@livequery/mongodb 2.0.152 → 2.0.154

package/README.md

@@ -4,17 +4,14 @@ Native MongoDB datasource adapter for the `@livequery` ecosystem.
 
 This package translates Livequery request shapes into MongoDB native driver operations. It is intended for projects that want to use `@livequery/core` with plain `mongodb` collections, without Mongoose models or schema introspection.
 
-The adapter supports two integration styles:
-
-- Core style: `new MongoDatasource(config)`, `init(routes)`, then `handle(ctx)`.
-- Legacy style: `new MongoDatasource()`, `init(config, routes)`, then direct `query(req, options)`.
+Integration with `@livequery/core`: `new MongoDatasource(config)`, `init(routes)`, then `handle(ctx)`. For imperative use you can also call `query(req, options)` directly.
 
 Reads are executed with MongoDB aggregation pipelines through `Collection.aggregate(...).toArray()`. Writes use native collection methods such as `insertOne`, `updateOne`, and `deleteOne`.
 
 ## Installation
 
 ```sh
-bun add @livequery/mongodb mongodb bson rxjs
+bun add @livequery/mongodb mongodb rxjs
 ```
 
 For local development in this workspace, `@livequery/core` is installed as a dev dependency from `file:../core`. Runtime JavaScript does not import `@livequery/core`; the generated declaration files use core types.
@@ -25,7 +22,7 @@ For local development in this workspace, `@livequery/core` is installed as a dev
 export * from './MongoDatasource.js'
 export * from './DataChangePayload.js'
 export * from './MongodbRealtime.js'
-export * from './types.js'
+export * from './MongodbCollection.js'
 ```
 
 ## Project Meaning
@@ -39,7 +36,7 @@ Typical request flow with `@livequery/core`:
 1. A framework adapter creates a `LivequeryContext`.
 2. `LivequeryRequestParser` reads `ctx.request` and writes `ctx.livequery`.
 3. `MongoDatasource.handle(ctx)` resolves route options from `ctx.request.method` and `ctx.request.ref`.
-4. `MongoDatasource` converts `ctx.livequery.query` into adapter `req.options`.
+4. `MongoDatasource` reads `ctx.livequery` (keys, query, body, method) as the adapter request.
 5. Reads are delegated to `MongoQuery`; writes go directly to the native collection.
 6. The result is assigned to `ctx.response`.
 
@@ -50,13 +47,13 @@ Typical request flow with `@livequery/core`:
 Main adapter class.
 
 ```ts
-class MongoDatasource extends Subject<WebsocketSyncPayload<LivequeryBaseEntity>>
+class MongoDatasource extends Subject<UpdatedData<LivequeryBaseEntity>>
 ```
 
 Responsibilities:
 
 - Store datasource config and route options.
-- Support core-style and legacy-style initialization.
+- Initialize from a list of routes.
 - Resolve connection, database, and collection for each request.
 - Normalize configured ObjectId fields.
 - Execute reads, inserts, updates, and deletes.
@@ -79,7 +76,7 @@ const datasource = new MongoDatasource({
 })
 ```
 
-If `config` is omitted, call `init(config, routes)` later.
+`config` is required before any request runs. Omit it here only if you assign `datasource.config` before the first `handle` / `query` call.
 
 #### `init(routes)`
 
@@ -103,35 +100,6 @@ await datasource.init([
 
 Route lookup uses `METHOD path`, for example `GET /products`. A path-only fallback is also stored for compatibility.
 
-#### `init(config, routes)`
-
-Legacy-style initialization.
-
-Parameters:
-
-- `config: MongoDatasourceConfig`: MongoDB connection configuration.
-- `routes: Array<{ method; path; options }>`: legacy route entries. The datasource options are nested under `options`.
-
-Example:
-
-```ts
-await datasource.init(
-  {
-    connections: { default: client },
-    databases: ['main'],
-  },
-  [
-    {
-      method: 'GET',
-      path: '/products',
-      options: {
-        collection: 'products',
-      },
-    },
-  ]
-)
-```
-
 #### `handle(ctx)`
 
 Core handler entry point.
@@ -164,7 +132,7 @@ Executes a parsed Livequery request against one MongoDB collection.
 
 Parameters:
 
-- `req: LivequeryRequest`: adapter request. Core requests use `query`; this adapter normalizes it to `options`. Legacy callers can pass `options` directly.
+- `req: LivequeryRequest`: parsed Livequery request. Reads `req.keys`, `req.query`, `req.method`, and `req.body`.
 - `options: RouteOptions`: route configuration that tells the adapter which collection, database, connection, and ObjectId fields to use.
 
 Supported `req.method` values:
@@ -192,7 +160,7 @@ const response = await datasource.query(
     ref: 'products',
     is_collection: true,
     keys: {},
-    options: { ':limit': 10 },
+    query: { ':limit': 10 },
   },
   {
     collection: 'products',
@@ -217,7 +185,7 @@ Responsibilities:
 
 Parameters:
 
-- `req: LivequeryRequest`: normalized adapter request. Reads `req.keys`, `req.options`, and `req.is_collection`.
+- `req: LivequeryRequest`: parsed adapter request. Reads `req.keys`, `req.query`, and `req.is_collection` (`req.query` is normalized to `{}` when absent).
 - `collection: Collection<T>`: native MongoDB collection.
 
 Behavior:
@@ -230,8 +198,8 @@ Known behavior:
 - `:limit` defaults to `10`.
 - Minimum `:limit` is `1`.
 - Maximum `:limit` is `100`.
-- Cursor paging is implemented.
-- Offset paging with `page` is not implemented yet.
+- Cursor paging (`:after` / `:before` / `:around`) is the default.
+- Offset paging is used when `:page` is provided.
 
 Filter examples:
 
@@ -267,7 +235,7 @@ Builds a cursor from a response item and active sort options.
 Parameters:
 
 - `item: LivequeryBaseEntity`: response item. Must contain `id`.
-- `options: QueryOption`: request options. Sort options ending with `:sort` are included in the cursor.
+- `options: Record<string, any>`: the request query (`req.query`). Sort options ending with `:sort` are included in the cursor.
 
 Returns:
 
@@ -386,6 +354,136 @@ An inserted `{ _id: 'post1', userId: 'user1', title: 'Hello' }` emits:
 }
 ```
 
+### `MongodbCollection`
+
+Lightweight imperative CRUD wrapper over a native MongoDB collection, with a Mongoose-`Model`-like surface. It is independent of the Livequery request flow and `LivequeryContext`: reach for it when application or service code needs to read and write documents directly, rather than through `MongoDatasource.handle(ctx)`.
+
+It is intentionally not an ODM. There are no schemas, validation, hooks, virtuals, or `populate()`. It only layers a few conveniences over the native driver: `id` / `_id` normalization, a collection-level defaults resolver, automatic timestamps, and flexible single-document filters.
+
+```ts
+class MongodbCollection<T = any>
+```
+
+Responsibilities:
+
+- Wrap one collection, resolved lazily from a provided `Db`.
+- Return documents with an enumerable `id: string` and a hidden `_id`.
+- Apply a defaults resolver plus `created_at` / `updated_at` on insert.
+- Bump `updated_at` on every update.
+- Accept a `string` id, an `ObjectId`, or a filter object for single-document operations.
+
+#### `defineCollection<T>(config)` and `constructor(db, config)`
+
+A collection is described once with `defineCollection`, then bound to a `Db` instance.
+
+`defineCollection<T>({ collection, defaults? })` returns a typed `CollectionDef<T>`:
+
+- `collection: string`: collection name. The handle is resolved lazily via `db.collection(name)`.
+- `defaults?: (input: Partial<T>) => Partial<T>`: optional default-field resolver, a replacement for Mongoose `@Prop({ default })`. It runs on every `create` / `insertMany` with the input document; the input always overrides the returned defaults.
+
+`new MongodbCollection<T>(db, config)`:
+
+- `db: Db`: a connected `mongodb` `Db`. It is passed in explicitly (no hidden module singleton), so one class works across databases and connections.
+- `config: CollectionDef<T>`: the definition returned by `defineCollection`. The generic `T` is inferred from it, so the instance is fully typed.
+
+Example:
+
+```ts
+import { MongoClient } from 'mongodb'
+import { MongodbCollection, defineCollection } from '@livequery/mongodb'
+
+const client = new MongoClient(process.env.MONGO_URL!)
+await client.connect()
+const db = client.db('main')
+
+type Order = { video_id: string; amount: number; started: boolean; running: boolean }
+type Video = { title: string }
+
+// With a defaults resolver (replaces Mongoose @Prop({ default })):
+const Orders = new MongodbCollection(db, defineCollection<Order>({
+  collection: 'orders',
+  defaults: () => ({ started: false, running: true }),
+}))
+
+// Without defaults:
+const Videos = new MongodbCollection(db, defineCollection<Video>({ collection: 'videos' }))
+```
+
+Define each collection once at composition time and reuse the instance across the app.
+
+#### Document shape: `MongoDoc<T>`
+
+```ts
+type MongoDoc<T> = T & { id: string; toJSON(): any }
+```
+
+Returned documents are hydrated:
+
+- `id` is an enumerable string (`_id.toString()`), so it appears in `JSON.stringify`, JSON responses, and `{ ...doc }`.
+- `_id` is non-enumerable, so it never leaks into output, yet `doc._id` is still readable as an `ObjectId` internally.
+- `toJSON()` returns the document without `_id` and `__v`.
+
+#### Methods
+
+| Method | Description |
+| --- | --- |
+| `find(filter?)` | Returns hydrated documents. |
+| `findOne(filter?)` | `filter` may be a `string` id, an `ObjectId`, or a filter object. |
+| `findById(id)` | Shorthand for `findOne` with a `string` id or `ObjectId`. |
+| `create(doc)` | Inserts one document; applies defaults + timestamps; strips any incoming `id` / `_id`. |
+| `insertMany(docs)` | Inserts many documents with the same preparation as `create`. |
+| `updateOne(filter, update, opts?)` | Wraps plain updates in `$set` and bumps `updated_at`; `filter` accepts string id / ObjectId / object. |
+| `updateMany(filter, update, opts?)` | Same update handling for many documents. |
+| `deleteOne(filter)` | Deletes one; `filter` accepts string id / ObjectId / object. |
+| `deleteMany(filter?)` | Deletes many documents. |
+| `countDocuments(filter?)` | Counts matching documents. |
+| `exists(filter?)` | `true` when at least one document matches. |
+| `aggregate(pipeline)` | Runs an aggregation pipeline and returns the array. |
+| `collection` | Getter for the raw native `Collection` (escape hatch). |
+
+Behavior:
+
+- Filter normalization: a 24-hex `string` becomes `{ _id: ObjectId }`; an `ObjectId` becomes `{ _id }`; any other string or object is used unchanged.
+- Update normalization: an update that already contains a `$`-operator (such as `$inc` or `$push`) is passed through; otherwise it is wrapped in `$set`. `updated_at` is always merged into the `$set` branch.
+- Inserts never persist an incoming `id` or `_id`.
+
+Example:
+
+```ts
+// create — applies defaults (started/running) + created_at/updated_at; strips any client id/_id
+const order = await Orders.create({ video_id: 'v1', amount: 50 })
+order.id              // '507f1f77bcf86cd799439011'
+order.started         // false — from the defaults resolver
+order._id             // ObjectId — still readable internally
+JSON.stringify(order) // contains "id", not "_id"
+
+// insertMany — same preparation as create, returns hydrated docs
+const [a, b] = await Orders.insertMany([{ video_id: 'v2', amount: 10 }, { video_id: 'v3', amount: 20 }])
+
+// reads — single-doc helpers accept a string id, an ObjectId, or a filter object
+await Orders.findOne('507f1f77bcf86cd799439011') // by string id (24-hex → _id)
+await Orders.findById(order._id)                 // by ObjectId
+await Orders.findOne({ video_id: 'v1' })         // by filter
+await Orders.find({ started: false })            // many
+
+// updates — plain bodies are wrapped in $set; operator bodies pass through; updated_at always bumped
+await Orders.updateOne(order.id, { amount: 80 })            // → { $set: { amount: 80, updated_at } }
+await Orders.updateOne(order.id, { $inc: { amount: 5 } })   // → { $inc, $set: { updated_at } }
+await Orders.updateMany({ started: false }, { running: true })
+
+// existence / counting
+await Orders.exists(order.id)                    // boolean
+await Orders.countDocuments({ video_id: 'v1' })  // number
+
+// delete
+await Orders.deleteOne(order.id)
+await Orders.deleteMany({ video_id: 'v3' })
+
+// escape hatches
+await Orders.aggregate([{ $group: { _id: '$video_id', total: { $sum: '$amount' } } }])
+Orders.collection                                // raw native Collection
+```
+
 ### `DataChangePayload<T>`
 
 Type-only realtime/change payload contract.
@@ -514,7 +612,9 @@ await datasource.handle(ctx)
 
 `LivequeryRequestParser` will set `ctx.livequery.document_id` and `ctx.livequery.keys.id`. The datasource converts `id` to Mongo `_id` for document reads and writes.
 
-## Legacy Usage Example
+## Direct Query Example
+
+For imperative use, call `query(req, options)` directly without going through `handle(ctx)`. Pass the config to the constructor; `init(routes)` is not required for this path since the collection is given in `options`.
 
 ```ts
 import { MongoClient } from 'mongodb'
@@ -523,33 +623,18 @@ import { MongoDatasource } from '@livequery/mongodb'
 const client = new MongoClient(process.env.MONGO_URL!)
 await client.connect()
 
-const datasource = new MongoDatasource()
-
-await datasource.init(
-  {
-    connections: { default: client },
-    databases: ['main'],
-  },
-  [
-    {
-      method: 'GET',
-      path: '/products',
-      options: {
-        collection: 'products',
-      },
-    },
-  ]
-)
+const datasource = new MongoDatasource({
+  connections: { default: client },
+  databases: ['main'],
+})
 
 const response = await datasource.query(
   {
     method: 'get',
     ref: 'products',
     is_collection: true,
-    collection_ref: 'products',
-    schema_collection_ref: 'products',
     keys: {},
-    options: { ':limit': 10 },
+    query: { ':limit': 10 },
   },
   {
     collection: 'products',

package/build/src/Cursor.d.ts

@@ -1,4 +1,4 @@
 export declare class Cursor {
-    static caculate(item: Record<string, any>, options: Record<string, any>): string;
+    static caculate(item: Record<string, any>, options: Record<string, any>): string | null;
     static parse(cursor: string): any;
 }

package/build/src/MongoDatasource.d.ts

@@ -46,6 +46,27 @@ export declare class MongoDatasource extends Subject<UpdatedData<LivequeryBaseEn
             total: number;
         };
     } | {
+        has: {
+            prev: boolean;
+            next: boolean;
+        };
+        count: {
+            prev: number;
+            next: number;
+            current: number;
+            total: number;
+        };
+        page: {
+            current: number;
+            total: number;
+        };
         item: any;
+        cursor: {
+            last: string | null;
+            first: string | null;
+        };
+        summary: any;
+    } | {
+        item: Record<string, any>;
     }>;
 }

package/build/src/MongoDatasource.js

@@ -111,8 +111,8 @@ export class MongoDatasource extends Subject {
         const total = current + count.next + count.prev;
         const paging = {
             cursor: {
-                last: Cursor.caculate(items[items.length - 1], req.query),
-                first: Cursor.caculate(items[0], req.query)
+                last: Cursor.caculate(items[items.length - 1], req.query || {}),
+                first: Cursor.caculate(items[0], req.query || {})
             },
             has,
             count: {
@@ -155,17 +155,18 @@ export class MongoDatasource extends Subject {
         };
     }
     async #post(req, collection) {
+        const { id: _bodyId, _id: _bodyRawId, ...cleanBody } = req.body || {};
         const merged = {
             ...req.keys,
-            ...req.body
+            ...cleanBody
         };
         const result = await collection.insertOne(merged);
         return {
-            item: {
+            item: this.#stringifyOids({
                 ...merged,
                 _id: undefined,
                 id: result.insertedId.toString()
-            }
+            })
         };
     }
     async #put(req, collection) {
@@ -185,11 +186,16 @@ export class MongoDatasource extends Subject {
         const isPlainBody = req.body && typeof req.body === 'object'
             && !Object.keys(req.body).some(k => k.startsWith('$'));
         const id = keys.id ?? req.document_id;
-        return {
+        return this.#stringifyOids({
             ...keys,
             ...isPlainBody ? req.body : {},
             ...id ? { id } : {}
-        };
+        });
+    }
+    #stringifyOids(item) {
+        return Object.entries(item).reduce((p, [k, v]) => {
+            return { ...p, [k]: v instanceof ObjectId ? v.toString() : v };
+        }, {});
     }
     #keys(req) {
         return Object.entries(req.keys).reduce((p, [k, c]) => {
@@ -212,7 +218,8 @@ export class MongoDatasource extends Subject {
     #update(body) {
         if (!body || Object.keys(body).some(key => key.startsWith('$')))
             return body;
-        return { $set: body };
+        const { id: _id, _id: _rawId, ...cleanBody } = body;
+        return { $set: cleanBody };
     }
     #convert(obj, fields) {
         return {

package/build/src/MongoQuery.js

@@ -159,7 +159,7 @@ export class MongoQuery {
                 }
             }).filter(Boolean);
             const is_distinc_count = `${v}`.includes('distinc');
-            const simple = is_distinc_count ? key : (exprs.length == 1 ? fns[0].key : false);
+            const simple = is_distinc_count ? key : (exprs.length == 1 && fns[0] ? fns[0].key : false);
             const pipelines = [
                 ...$match.length > 0 ? [{ $match }] : [],
                 {
@@ -238,34 +238,14 @@ export class MongoQuery {
             if (k.endsWith(':like'))
                 return p;
             const [key, expression] = k.split(':');
-            const map = {
-                eq: () => ({ $eq: value }),
-                lt: () => ({ $lt: !isNaN(Number(value)) ? Number(value) : 0 }),
-                lte: () => ({ $lte: !isNaN(Number(value)) ? Number(value) : 0 }),
-                gt: () => ({ $gt: !isNaN(Number(value)) ? Number(value) : 0 }),
-                gte: () => ({ $gte: !isNaN(Number(value)) ? Number(value) : 0 }),
-                ne: () => {
-                    return { $ne: value };
-                },
-                in: () => ({ $in: this.#parse_array(value) }),
-                nin: () => ({ $nin: this.#parse_array(value) }),
-                'eq-number': () => ({ $eq: !isNaN(Number(value)) ? Number(value) : 0 }),
-                'neq-number': () => ({ $ne: !isNaN(Number(value)) ? Number(value) : 0 }),
-                'eq-boolean': () => ({ $eq: `${value}`.toLowerCase() == 'true' ? true : false }),
-                'neq-boolean': () => ({ $ne: `${value}`.toLowerCase() == 'false' ? false : true }),
-                'eq-null': () => ({ $eq: null }),
-                'neq-null': () => ({ $ne: null }),
-                'eq-oid': () => ({ $eq: ObjectId.isValid(value) ? new ObjectId(value) : value }),
-                'neq-oid': () => ({ $ne: ObjectId.isValid(value) ? new ObjectId(value) : value }),
-            };
-            const fn = map[expression || 'eq'];
-            if (!fn)
+            const clause = this.#operator_clause(expression, value);
+            if (!clause)
                 return p;
             return {
                 ...p,
                 [key]: {
                     ...p[key] || {},
-                    ...fn()
+                    ...clause
                 }
             };
         }, {});
@@ -277,20 +257,75 @@ export class MongoQuery {
         const andMatch = and ? this.#build_match(and) : {};
         if (Object.keys(andMatch).length > 0)
             clauses.push(andMatch);
-        const orMatch = or ? this.#build_match(or) : {};
-        if (Object.keys(orMatch).length > 0) {
-            clauses.push({ $or: Object.entries(orMatch).map(([k, v]) => ({ [k]: v })) });
-        }
-        const notMatch = not ? this.#build_match(not) : {};
-        if (Object.keys(notMatch).length > 0) {
-            clauses.push({ $nor: Object.entries(notMatch).map(([k, v]) => ({ [k]: v })) });
-        }
+        const orBranches = or ? this.#branches(or) : [];
+        if (orBranches.length > 0)
+            clauses.push({ $or: orBranches });
+        const notBranches = not ? this.#branches(not) : [];
+        if (notBranches.length > 0)
+            clauses.push({ $nor: notBranches });
         if (clauses.length === 0)
             return {};
         if (clauses.length === 1)
             return clauses[0];
         return { $and: clauses };
     }
+    static #operator_clause(expression, value) {
+        const map = {
+            eq: () => ({ $eq: value }),
+            lt: () => ({ $lt: !isNaN(Number(value)) ? Number(value) : 0 }),
+            lte: () => ({ $lte: !isNaN(Number(value)) ? Number(value) : 0 }),
+            gt: () => ({ $gt: !isNaN(Number(value)) ? Number(value) : 0 }),
+            gte: () => ({ $gte: !isNaN(Number(value)) ? Number(value) : 0 }),
+            ne: () => ({ $ne: value }),
+            in: () => ({ $in: this.#parse_array(value) }),
+            nin: () => ({ $nin: this.#parse_array(value) }),
+            'eq-number': () => ({ $eq: !isNaN(Number(value)) ? Number(value) : 0 }),
+            'neq-number': () => ({ $ne: !isNaN(Number(value)) ? Number(value) : 0 }),
+            'eq-boolean': () => ({ $eq: `${value}`.toLowerCase() == 'true' ? true : false }),
+            'neq-boolean': () => ({ $ne: `${value}`.toLowerCase() == 'false' ? false : true }),
+            'eq-null': () => ({ $eq: null }),
+            'neq-null': () => ({ $ne: null }),
+            'eq-oid': () => ({ $eq: ObjectId.isValid(value) ? new ObjectId(value) : value }),
+            'neq-oid': () => ({ $ne: ObjectId.isValid(value) ? new ObjectId(value) : value }),
+        };
+        const fn = map[expression || 'eq'];
+        return fn ? fn() : null;
+    }
+    static #branches(filters) {
+        if (!filters)
+            return [];
+        const { ':and': and, ':or': or, ':not': not, ...rest } = filters;
+        const branches = [];
+        for (const [k, value] of Object.entries(rest)) {
+            if (k.startsWith('::'))
+                continue;
+            if (k.endsWith(':like')) {
+                const key = k.split(':like')[0];
+                branches.push({ [key]: { $regex: this.#escape_regex(`${value}`), $options: 'i' } });
+                continue;
+            }
+            const [key, expression] = k.split(':');
+            const clause = this.#operator_clause(expression, value);
+            if (clause)
+                branches.push({ [key]: clause });
+        }
+        if (and) {
+            const m = this.#build_match(and);
+            if (Object.keys(m).length > 0)
+                branches.push(m);
+        }
+        if (or) {
+            const m = this.#build_match({ ':or': or });
+            if (Object.keys(m).length > 0)
+                branches.push(m);
+        }
+        if (not) {
+            const m = this.#build_match({ ':not': not });
+            if (Object.keys(m).length > 0)
+                branches.push(m);
+        }
+        return branches;
+    }
     static #build_search_query(req) {
         const search = req.query[":search"];
         return search ? [{ $match: { $text: { $search: `${search}` } } }] : [];
@@ -489,12 +524,14 @@ export class MongoQuery {
         return $sort;
     }
     static async query(req, collection) {
-        if (!req.is_collection) {
+        const request = { ...req, keys: req.keys ?? {}, query: req.query ?? {} };
+        if (!request.is_collection) {
+            const { id, _id: _rawId, ...keysWithoutId } = request.keys;
             const aggregates = [
                 {
                     $match: {
-                        ...req.keys,
-                        ...req.keys.id ? { id: undefined, _id: this.#objectId('id', req.keys.id) } : {}
+                        ...keysWithoutId,
+                        ...id ? { _id: this.#objectId('id', id) } : {}
                     }
                 },
                 ...this.#rename_id(),
@@ -513,19 +550,19 @@ export class MongoQuery {
                 summary: {}
             };
         }
-        const is_cursor_paging = req.query[':after'] || req.query[':before'] || req.query[':around'] || !req.query[':page'];
-        const $sort = this.#get_sorter(req);
+        const is_cursor_paging = request.query[':after'] || request.query[':before'] || request.query[':around'] || !request.query[':page'];
+        const $sort = this.#get_sorter(request);
         const pipelines = [
             { $sort },
-            ...this.#build_query_filter(req),
-            ...this.#build_search_query(req),
+            ...this.#build_query_filter(request),
+            ...this.#build_search_query(request),
             ...this.#rename_id(),
-            ...is_cursor_paging ? this.#build_cursor_paging($sort, req) : this.#build_offset_paging(req)
+            ...is_cursor_paging ? this.#build_cursor_paging($sort, request) : this.#build_offset_paging(request)
         ];
         const response = await collection.aggregate(pipelines).toArray();
         return {
             ...response[0],
-            limit: this.#get_limit(req)
+            limit: this.#get_limit(request)
         };
     }
 }

package/build/src/MongodbCollection.d.ts

@@ -0,0 +1,37 @@
+import { ObjectId } from 'mongodb';
+import type { Collection, Db, Filter } from 'mongodb';
+export type MongoDoc<T> = T & {
+    id: string;
+    toJSON(): any;
+};
+export type DefaultsResolver<T> = (input: Partial<T>) => Partial<T>;
+export declare class CollectionDef<T> {
+    readonly collection: string;
+    readonly defaults?: DefaultsResolver<T> | undefined;
+    readonly _type: T;
+    constructor(collection: string, defaults?: DefaultsResolver<T> | undefined);
+}
+export declare function defineCollection<T>(config: {
+    collection: string;
+    defaults?: DefaultsResolver<T>;
+}): CollectionDef<T>;
+export declare class MongodbCollection<T = any> {
+    private readonly db;
+    private readonly collectionName;
+    private readonly resolveDefaults?;
+    constructor(db: Db, config: CollectionDef<T>);
+    get collection(): Collection<any>;
+    private prepareInsert;
+    find(filter?: Filter<any>): Promise<MongoDoc<T>[]>;
+    findOne(filter?: string | ObjectId | Filter<any>): Promise<MongoDoc<T> | null>;
+    findById(id: string | ObjectId): Promise<MongoDoc<T> | null>;
+    create(doc: Partial<T>): Promise<MongoDoc<T>>;
+    insertMany(docs: Partial<T>[]): Promise<MongoDoc<T>[]>;
+    updateOne(filter: string | ObjectId | Filter<any>, update: any, opts?: any): Promise<import("mongodb").UpdateResult<any>>;
+    updateMany(filter: Filter<any>, update: any, opts?: any): Promise<import("mongodb").UpdateResult<any>>;
+    deleteOne(filter: string | ObjectId | Filter<any>): Promise<import("mongodb").DeleteResult>;
+    deleteMany(filter?: Filter<any>): Promise<import("mongodb").DeleteResult>;
+    countDocuments(filter?: Filter<any>): Promise<number>;
+    exists(filter?: string | ObjectId | Filter<any>): Promise<boolean>;
+    aggregate<R = any>(pipeline: any[]): Promise<R[]>;
+}

package/build/src/MongodbCollection.js

@@ -0,0 +1,116 @@
+import { ObjectId } from 'mongodb';
+function hydrate(doc) {
+    if (!doc)
+        return null;
+    const oid = doc._id;
+    Object.defineProperty(doc, '_id', { value: oid, enumerable: false, configurable: true, writable: true });
+    if (Object.prototype.hasOwnProperty.call(doc, '__v')) {
+        Object.defineProperty(doc, '__v', { value: doc.__v, enumerable: false, configurable: true, writable: true });
+    }
+    Object.defineProperty(doc, 'id', {
+        value: oid ? oid.toString() : undefined,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+    Object.defineProperty(doc, 'toJSON', {
+        value() {
+            const { _id: _omitId, __v: _omitV, ...rest } = this;
+            return rest;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+    return doc;
+}
+function withSet(update) {
+    const hasOperator = Object.keys(update || {}).some((k) => k.startsWith('$'));
+    return hasOperator ? update : { $set: update };
+}
+function withTouch(update) {
+    const base = withSet(update);
+    return { ...base, $set: { ...(base.$set ?? {}), updated_at: Date.now() } };
+}
+function isHex24(s) {
+    return /^[a-f\d]{24}$/i.test(s);
+}
+function toFilter(filter = {}) {
+    if (typeof filter === 'string')
+        return { _id: isHex24(filter) ? ObjectId.createFromHexString(filter) : filter };
+    if (filter instanceof ObjectId)
+        return { _id: filter };
+    return filter;
+}
+export class CollectionDef {
+    collection;
+    defaults;
+    constructor(collection, defaults) {
+        this.collection = collection;
+        this.defaults = defaults;
+    }
+}
+export function defineCollection(config) {
+    return new CollectionDef(config.collection, config.defaults);
+}
+export class MongodbCollection {
+    db;
+    collectionName;
+    resolveDefaults;
+    constructor(db, config) {
+        this.db = db;
+        this.collectionName = config.collection;
+        this.resolveDefaults = config.defaults;
+    }
+    get collection() {
+        return this.db.collection(this.collectionName);
+    }
+    prepareInsert(input) {
+        const now = Date.now();
+        const { id: _gid, _id: _moid, ...clean } = (input ?? {});
+        const defaults = this.resolveDefaults ? this.resolveDefaults((input ?? {})) : {};
+        return { created_at: now, updated_at: now, ...defaults, ...clean };
+    }
+    async find(filter = {}) {
+        const docs = await this.collection.find(filter).toArray();
+        return docs.map((d) => hydrate(d));
+    }
+    async findOne(filter = {}) {
+        return hydrate(await this.collection.findOne(toFilter(filter)));
+    }
+    findById(id) {
+        return this.findOne(id);
+    }
+    async create(doc) {
+        const record = this.prepareInsert(doc);
+        const r = await this.collection.insertOne(record);
+        record._id = r.insertedId;
+        return hydrate(record);
+    }
+    async insertMany(docs) {
+        const records = docs.map((d) => this.prepareInsert(d));
+        const r = await this.collection.insertMany(records);
+        records.forEach((d, i) => (d._id = r.insertedIds[i]));
+        return records.map((d) => hydrate(d));
+    }
+    updateOne(filter, update, opts) {
+        return this.collection.updateOne(toFilter(filter), withTouch(update), opts);
+    }
+    updateMany(filter, update, opts) {
+        return this.collection.updateMany(filter, withTouch(update), opts);
+    }
+    deleteOne(filter) {
+        return this.collection.deleteOne(toFilter(filter));
+    }
+    deleteMany(filter = {}) {
+        return this.collection.deleteMany(filter);
+    }
+    countDocuments(filter = {}) {
+        return this.collection.countDocuments(filter);
+    }
+    exists(filter = {}) {
+        return this.collection.findOne(toFilter(filter), { projection: { _id: 1 } }).then((d) => !!d);
+    }
+    aggregate(pipeline) {
+        return this.collection.aggregate(pipeline).toArray();
+    }
+}

package/build/src/index.d.ts

@@ -1,3 +1,4 @@
 export * from './MongoDatasource.js';
 export * from './DataChangePayload.js';
 export * from './MongodbRealtime.js';
+export * from './MongodbCollection.js';

package/build/src/index.js

@@ -1,3 +1,4 @@
 export * from './MongoDatasource.js';
 export * from './DataChangePayload.js';
 export * from './MongodbRealtime.js';
+export * from './MongodbCollection.js';

package/build/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/cursor.ts","../src/datachangepayload.ts","../src/mongodatasource.ts","../src/mongoquery.ts","../src/mongodbrealtime.ts","../src/smartcache.ts","../src/index.ts"],"version":"5.9.3"}
+{"root":["../src/cursor.ts","../src/datachangepayload.ts","../src/mongodatasource.ts","../src/mongoquery.ts","../src/mongodbcollection.ts","../src/mongodbrealtime.ts","../src/smartcache.ts","../src/index.ts"],"version":"6.0.3"}

package/package.json

@@ -6,7 +6,7 @@
   "repository": {
     "url": "git@github.com:livequery/mongodb.git"
   },
-  "version": "2.0.152",
+  "version": "2.0.154",
   "description": "MongoDB datasource mapping for @livequery ecosystem",
   "main": "./build/src/index.js",
   "types": "./build/src/index.d.ts",
@@ -30,8 +30,8 @@
   },
   "scripts": {
     "test": "bun test",
-    "build": "rm -rf build; tsc -b .",
-    "deploy": "rm -rf build && yarn build; git add .; git commit -m \"Update\"; git push origin master; npm publish --access public"
+    "build": "rm -rf build && tsc -b .",
+    "deploy": "rm -rf build && yarn build && git add . && git commit -m \"Update\" && git push origin main && npm publish --access public"
   },
   "peerDependencies": {
     "mongodb": "^6.20.0"