WebCake Data

A modern JavaScript/TypeScript client library for WebCake database operations with MongoDB-like query interface.

Features

- 🚀 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

Installation

``bash
npm install webcake-data
`

Quick Start

$3

`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();
`

$3

`javascript
const { DBConnection } = require('webcake-data');
`

$3

Using CDN (Unpkg or JSDelivr):

`html



`

Using JSDelivr:

`html

`

API Reference

$3

Main connection class for database operations.

#### Constructor

`javascript
new DBConnection(config)
`

Parameters:
- config.baseURL (string, optional): API base URL
- config.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 token
- config.headers (object, optional): Additional headers
- config.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 collection
- insertOne(tableName, fields) - Insert a single record
- insertMany(tableName, records) - Insert multiple records
- query(tableName, queryParams) - Query records
- updateById(tableName, id, fields) - Update record by ID
- updateOne(tableName, filters, fields) - Update one record
- updateMany(tableName, filters, fields) - Update multiple records
- deleteById(tableName, id) - Delete record by ID
- deleteOne(tableName, filters) - Delete one record
- deleteMany(tableName, filters) - Delete multiple records
- count(tableName, filters) - Count records
- exists(tableName, filters) - Check if records exist

$3

Model class for collection operations.

#### Methods

- create(data) - Create a new document
- insertMany(dataArray) - Create multiple documents
- find(filters) - Find documents (returns QueryBuilder)
- findOne(filters, options) - Find one document with optional select/sort/populate
- findById(id, options) - Find document by ID with optional select/sort/populate
- updateOne(filters, updateData) - Update one document
- findByIdAndUpdate(id, updateData, options) - Update document by ID
- findOneAndUpdate(filters, updateData) - Find and update one document
- updateMany(filters, updateData) - Update multiple documents
- deleteOne(filters) - Delete one document
- findByIdAndDelete(id) - Delete document by ID
- findOneAndDelete(filters) - Find and delete one document
- deleteMany(filters) - Delete multiple documents
- countDocuments(filters) - Count documents
- exists(filters) - Check if documents exist

findOne/findById options:
- select (string | string[]): Fields to return
- sort (object): Sort order applied before taking the first record
- populate (object | object[]): Populate configuration(s) identical to QueryBuilder.populate()

$3

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 filter
- gt(field, value) - Greater than filter
- gte(field, value) - Greater than or equal filter
- lt(field, value) - Less than filter
- lte(field, value) - Less than or equal filter
- in(field, values) - In array filter
- nin(field, values) - Not in array filter
- ne(field, value) - Not equal filter
- between(field, value1, value2) - Between values filter
- like(field, pattern) - Pattern matching filter
- sort(sortObj) - Sort results
- limit(n) - Limit number of results
- skip(n) - Skip number of results
- select(fields) - Select specific fields
- populate(config) - Populate related data
- exec() - Execute query

Usage Examples

$3

`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');
`

$3

`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' });
`

$3

`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 });
`

$3

`javascript
try {
const user = await User.create({
name: 'John Doe',
email: 'john@example.com'
});
} catch (error) {
console.error('Failed to create user:', error.message);
}
`

TypeScript Support

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('users');
`

Browser Integration

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'
});
`

Development

$3

The library uses Rollup for bundling and minification. Build scripts are available:

`bash


Build minified and unminified versions for all formats

npm run build

Production build with optimizations

npm run build:prod
`

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 Request

License

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) environments

Core 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 sorting

Your 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 considerations

Critical 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 snippets

Example 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 improvements

Additional 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.
``