A modern JavaScript/TypeScript client library for WebCake database operations with MongoDB-like query interface
npm install webcake-dataA modern JavaScript/TypeScript client library for WebCake database operations with MongoDB-like query interface.
- š Modern ES6+ Module Support - Works with both Node.js and browsers
- š MongoDB-like Query Interface - Familiar query syntax for easy adoption
- šÆ TypeScript Support - Full TypeScript definitions included
- š Browser & Node.js Compatible - Works everywhere JavaScript runs
- š¦ Zero Dependencies - Lightweight with no external dependencies
- š Fluent API - Chainable query builder for complex operations
- ā” Minified Builds - Optimized and compressed for production use
``bash`
npm install webcake-data
`javascript
import { DBConnection } from 'webcake-data';
// Initialize connection
const db = new DBConnection({
// baseURL/siteId/token are preconfigured on WebCake-hosted sites;
// override only if you use a custom backend. Headers still need to be set.
baseURL: 'https://api.webcake.com/api/v1',
siteId: 'your-site-id',
token: 'your-auth-token',
headers: {
'x-cms-api-key': 'your-api-key' // For API permission checking
}
});
// Create a model
const User = db.model('users');
// Create a user
const user = await User.create({
name: 'John Doe',
email: 'john@example.com',
age: 30,
active: true
});
// Find users
const users = await User.find({ active: true }).exec();
`
`javascript`
const { DBConnection } = require('webcake-data');
Using CDN (Unpkg or JSDelivr):
`html`
Using JSDelivr:
`html`
Main connection class for database operations.
#### Constructor
`javascript`
new DBConnection(config)
Parameters:
- config.baseURL (string, optional): API base URLconfig.domain
- (string, optional): Domain base URL (overrides default relative path if provided)config.siteId
- (string, optional): Site ID (auto-detected from DOM if not provided)config.token
- (string, optional): Authentication tokenconfig.headers
- (object, optional): Additional headersconfig.headers['x-cms-api-key']
- (string, optional): API key for permission checking
Automatic Header Injection:
The library automatically monitors window.store_post and window.store_product. If present, it injects x-article-id and x-product-id headers respectively.
Example:
`javascript
const db = new DBConnection({
baseURL: 'https://api.webcake.com/api/v1', // Optional: defaults to /api/v1
domain: 'https://api.webcake.com', // Optional: Base domain to prepend to baseURL
siteId: 'your-site-id',
token: 'your-auth-token',
headers: {
'x-cms-api-key': 'your-api-key' // For API permission checking
}
});
// Automatic Header Injection:
// If window.store_post or window.store_product are present,
// the library will automatically inject 'x-article-id' and 'x-product-id' headers.
`
#### Methods
- model(collectionName) - Create a model for a collectioninsertOne(tableName, fields)
- - Insert a single recordinsertMany(tableName, records)
- - Insert multiple recordsquery(tableName, queryParams)
- - Query recordsupdateById(tableName, id, fields)
- - Update record by IDupdateOne(tableName, filters, fields)
- - Update one recordupdateMany(tableName, filters, fields)
- - Update multiple recordsdeleteById(tableName, id)
- - Delete record by IDdeleteOne(tableName, filters)
- - Delete one recorddeleteMany(tableName, filters)
- - Delete multiple recordscount(tableName, filters)
- - Count recordsexists(tableName, filters)
- - Check if records exist
Model class for collection operations.
#### Methods
- create(data) - Create a new documentinsertMany(dataArray)
- - Create multiple documentsfind(filters)
- - Find documents (returns QueryBuilder)findOne(filters, options)
- - Find one document with optional select/sort/populatefindById(id, options)
- - Find document by ID with optional select/sort/populateupdateOne(filters, updateData)
- - Update one documentfindByIdAndUpdate(id, updateData, options)
- - Update document by IDfindOneAndUpdate(filters, updateData)
- - Find and update one documentupdateMany(filters, updateData)
- - Update multiple documentsdeleteOne(filters)
- - Delete one documentfindByIdAndDelete(id)
- - Delete document by IDfindOneAndDelete(filters)
- - Find and delete one documentdeleteMany(filters)
- - Delete multiple documentscountDocuments(filters)
- - Count documentsexists(filters)
- - Check if documents exist
findOne/findById options:
- select (string | string[]): Fields to returnsort
- (object): Sort order applied before taking the first recordpopulate
- (object | object[]): Populate configuration(s) identical to QueryBuilder.populate()
Fluent query builder for complex database queries.
#### Methods
- where(field, operator, value) - Add filter condition (supports: where(obj), where(field, value), or where(field, operator, value))eq(field, value)
- - Equality filtergt(field, value)
- - Greater than filtergte(field, value)
- - Greater than or equal filterlt(field, value)
- - Less than filterlte(field, value)
- - Less than or equal filterin(field, values)
- - In array filternin(field, values)
- - Not in array filterne(field, value)
- - Not equal filterbetween(field, value1, value2)
- - Between values filterlike(field, pattern)
- - Pattern matching filtersort(sortObj)
- - Sort resultslimit(n)
- - Limit number of resultsskip(n)
- - Skip number of resultsselect(fields)
- - Select specific fieldspopulate(config)
- - Populate related dataexec()
- - Execute query
`javascript
import { DBConnection } from 'webcake-data';
const db = new DBConnection({
baseURL: 'https://api.webcake.com/api/v1',
siteId: 'your-site-id',
token: 'your-auth-token',
headers: {
'x-cms-api-key': 'your-api-key' // For API permission checking
}
});
const User = db.model('users');
// Create
const user = await User.create({
name: 'John Doe',
email: 'john@example.com',
age: 30,
active: true
});
// Read
const users = await User.find({ active: true }).exec();
const user = await User.findOne(
{ email: 'john@example.com' },
{
select: ['id', 'name', 'email'],
populate: {
field: 'profile',
table: 'profiles',
referenceField: 'user_id',
select: 'avatar bio'
}
}
);
const userById = await User.findById('user-id', {
select: 'id name email',
sort: { inserted_at: -1 }
});
// Update
await User.updateOne(
{ email: 'john@example.com' },
{ age: 31, active: false }
);
await User.findByIdAndUpdate('user-id', { age: 32 }, { new: true });
// Delete
await User.deleteOne({ email: 'john@example.com' });
await User.findByIdAndDelete('user-id');
`
`javascript
// Using where with object
const results1 = await User.find()
.where({ active: true, age: { $gte: 25 } })
.exec();
// Complex query with multiple conditions
const results = await User.find()
.where('age').gte(25).lte(40)
.where('active', true)
.in('name', ['John', 'Jane', 'Bob'])
.like('email', '%@example.com')
.sort({ age: -1, name: 1 })
.limit(20)
.skip(10)
.select('name email age')
.exec();
// Population (joins) with object-based where and sort
const usersWithPosts = await User.find()
.populate({
field: 'posts',
table: 'posts',
referenceField: 'user_id',
select: 'title content',
where: { published: true },
sort: { inserted_at: -1 },
limit: 5
})
.exec();
// Count and exists
const activeUserCount = await User.countDocuments({ active: true });
const userExists = await User.exists({ email: 'john@example.com' });
`
`javascript
// Insert multiple records
await User.insertMany([
{ name: 'Jane', email: 'jane@example.com', age: 25, active: true },
{ name: 'Bob', email: 'bob@example.com', age: 35, active: false }
]);
// Update multiple records
await User.updateMany({ active: false }, { active: true });
// Delete multiple records
await User.deleteMany({ active: false });
`
`javascript`
try {
const user = await User.create({
name: 'John Doe',
email: 'john@example.com'
});
} catch (error) {
console.error('Failed to create user:', error.message);
}
The library includes full TypeScript definitions:
`typescript
import { DBConnection, DBModel, QueryBuilder } from 'webcake-data';
interface User {
id: string;
name: string;
email: string;
age: number;
active: boolean;
}
const db = new DBConnection({
baseURL: 'https://api.webcake.com/api/v1',
siteId: 'your-site-id',
headers: {
'x-cms-api-key': 'your-api-key' // For API permission checking
}
});
const UserModel: DBModel = db.model
`
The library automatically detects the site ID from DOM attributes:
`html`
Or you can provide it explicitly:
`javascript`
const db = new DBConnection({
siteId: 'your-site-id'
});
The library uses Rollup for bundling and minification. Build scripts are available:
`bashBuild minified and unminified versions for all formats
npm run build
Build outputs are generated in the
dist/ directory:-
webcake-data.esm.min.js - ES Module (minified, ~7.4KB)
- webcake-data.umd.min.js - UMD format (minified, ~7.6KB) - for browsers
- webcake-data.esm.js - ES Module (unminified)
- webcake-data.umd.js - UMD format (unminified)$3
The minified builds are optimized for production use:
- ESM Minified: ~7.4KB
- UMD Minified: ~7.6KB (includes browser global export)
$3
The library is minified using Terser with the following optimizations:
- Variable name mangling
- Dead code elimination
- Whitespace and comment removal
- Property access optimization
- 2-pass compression for maximum size reduction
$3
To contribute to the library:
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run the build: npm run build
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull RequestLicense
MIT License - see LICENSE file for details.
Support
For support, please open an issue on GitHub.
AI Helper Prompt
Users can copy this prompt into ChatGPT, Gemini, Claude, or any AI assistant to get high-quality help with WebCake Data. For best results, share it together with the raw code bundle (
https://raw.githubusercontent.com/vuluu2k/webcake-data/main/repomix-output.txt) so the AI can read the entire library context:`
You are a senior full-stack engineer specializing in the WebCake Data JavaScript/TypeScript library - a modern MongoDB-like query interface for WebCake database operations.Context & Documentation
- Read the full repository context from: https://raw.githubusercontent.com/vuluu2k/webcake-data/main/repomix-output.txt
- Official documentation: https://github.com/vuluu2k/webcake-data
- The library provides three main classes: DBConnection, DBModel, and QueryBuilder
- Supports both browser (UMD) and Node.js (ESM/CommonJS) environmentsCore Principles
1. Database Field Convention: Use inserted_at for timestamp fields, NOT created_at
2. Query Builder Pattern: Leverage fluent API for complex queries with method chaining
3. Population (Joins): Use populate() for relational data with proper referenceField configuration
4. Error Handling: Always wrap database operations in try-catch blocks
5. Performance: Use select() to limit fields, limit/skip for pagination, and indexes for sortingYour Task Workflow
When helping users with WebCake Data:$3
Ask about:
- Collection/table names and their relationships
- Filter conditions and query complexity
- Fields to select/return (use select() for performance)
- Pagination needs (limit/skip values)
- Population requirements (which related data to join)
- Sorting preferences (use inserted_at for chronological sorting)
- Environment (browser vs Node.js, TypeScript vs JavaScript)
- Authentication setup (baseURL, siteId, token, headers)$3
- Identify which API methods to use (find, findOne, findById, create, update, delete)
- Plan query builder chain for complex conditions
- Design population strategy for relational data
- Consider performance optimizations (field selection, pagination)$3
Follow these patterns:Connection Setup:
`javascript
import { DBConnection } from 'webcake-data';const db = new DBConnection({
baseURL: 'https://api.webcake.com/api/v1',
siteId: 'your-site-id',
token: 'your-auth-token',
headers: {
'x-cms-api-key': 'your-api-key'
}
});
`CRUD Operations:
`javascript
const User = db.model('users');// Create with inserted_at
const user = await User.create({
name: 'John Doe',
email: 'john@example.com',
inserted_at: new Date()
});
// Query with filters
const users = await User.find({ active: true })
.where('age').gte(18).lte(65)
.select('name email age')
.sort({ inserted_at: -1 })
.limit(20)
.skip(0)
.exec();
// Update
await User.findByIdAndUpdate(userId, { age: 31 }, { new: true });
// Delete
await User.findByIdAndDelete(userId);
`Population (Joins):
`javascript
const usersWithPosts = await User.find()
.populate({
field: 'posts',
table: 'posts',
referenceField: 'user_id',
select: 'title content',
where: { published: true },
sort: { inserted_at: -1 },
limit: 5
})
.exec();
`Error Handling:
`javascript
try {
const result = await User.create(userData);
return { success: true, data: result };
} catch (error) {
console.error('Database operation failed:', error.message);
return { success: false, error: error.message };
}
`$3
- Describe why each method/operator was chosen
- Explain how populate() creates the join relationship
- Clarify pagination behavior (skip/limit)
- Note performance implications (indexes, field selection)
- Highlight error handling strategy$3
- Call out any assumptions made
- Suggest alternative approaches when applicable
- Mention testing strategies
- Note any environment-specific considerationsCritical Rules
ā
DO:
- Use inserted_at for all timestamp fields
- Use async/await for all database operations
- Wrap operations in try-catch blocks
- Use select() to limit returned fields
- Use populate() for relational data
- Follow the fluent API pattern for queries
- Use object-based where() for complex filters: .where({ field: value, age: { $gte: 25 } })
- Provide self-contained, runnable code examplesā DON'T:
- Use
created_at (use inserted_at instead)
- Use undocumented or private APIs
- Forget error handling
- Return all fields when only some are needed
- Use synchronous patterns
- Make assumptions about schema without asking
- Provide incomplete code snippetsExample Response Format
1. Requirements Summary: Briefly restate what the user needs
2. Solution Plan: List the APIs and approach
3. Code Implementation: Provide complete, runnable code
4. Explanation: Explain key decisions and patterns
5. Next Steps: Suggest testing approach or improvementsAdditional Resources
- MongoDB-like operators: $gte, $lte, $gt, $lt, $in, $nin, $ne, $like
- Query methods: where(), eq(), gt(), gte(), lt(), lte(), in(), nin(), ne(), between(), like()
- Options: select, sort, limit, skip, populate
- findOne/findById support options: { select, sort, populate }Remember: Clarity, correctness, and production-readiness are paramount. Always provide code that follows best practices and can be used immediately.
``