@livequery/mongodb 2.0.153 → 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.
@@ -26,7 +23,6 @@ export * from './MongoDatasource.js'
 export * from './DataChangePayload.js'
 export * from './MongodbRealtime.js'
 export * from './MongodbCollection.js'
-export * from './types.js'
 ```
 
 ## Project Meaning
@@ -40,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`.
 
@@ -51,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.
@@ -80,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)`
 
@@ -104,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.
@@ -165,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:
@@ -193,7 +160,7 @@ const response = await datasource.query(
     ref: 'products',
     is_collection: true,
     keys: {},
-    options: { ':limit': 10 },
+    query: { ':limit': 10 },
   },
   {
     collection: 'products',
@@ -218,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:
@@ -231,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:
 
@@ -268,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:
 
@@ -405,30 +372,45 @@ Responsibilities:
 - Bump `updated_at` on every update.
 - Accept a `string` id, an `ObjectId`, or a filter object for single-document operations.
 
-#### `constructor(db, collectionName, resolveDefaults?)`
+#### `defineCollection<T>(config)` and `constructor(db, config)`
 
-Parameters:
+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.
-- `collectionName: string`: collection name. The handle is resolved lazily via `db.collection(name)`.
-- `resolveDefaults?: (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.
+- `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 } from '@livequery/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 }),
+}))
 
-const Orders = new MongodbCollection<Order>(db, 'orders', () => ({ started: false, running: true }))
-const Videos = new MongodbCollection<Video>(db, 'videos') // no defaults
+// 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
@@ -468,17 +450,38 @@ Behavior:
 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"
 
-await Orders.findOne('507f1f77bcf86cd799439011') // by string 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 })
 
-await Orders.updateOne(order.id, { amount: 80 })          // wrapped in $set, bumps updated_at
-await Orders.updateOne(order.id, { $inc: { amount: 5 } }) // operator preserved, still bumps updated_at
+// 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>`
@@ -609,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'
@@ -618,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: {
@@ -162,11 +162,11 @@ export class MongoDatasource extends Subject {
         };
         const result = await collection.insertOne(merged);
         return {
-            item: {
+            item: this.#stringifyOids({
                 ...merged,
                 _id: undefined,
                 id: result.insertedId.toString()
-            }
+            })
         };
     }
     async #put(req, collection) {
@@ -186,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]) => {

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,8 +524,9 @@ export class MongoQuery {
         return $sort;
     }
     static async query(req, collection) {
-        if (!req.is_collection) {
-            const { id, _id: _rawId, ...keysWithoutId } = req.keys;
+        const request = { ...req, keys: req.keys ?? {}, query: req.query ?? {} };
+        if (!request.is_collection) {
+            const { id, _id: _rawId, ...keysWithoutId } = request.keys;
             const aggregates = [
                 {
                     $match: {
@@ -514,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

@@ -7,9 +7,9 @@ export type MongoDoc<T> = T & {
 export type DefaultsResolver<T> = (input: Partial<T>) => Partial<T>;
 export declare class CollectionDef<T> {
     readonly collection: string;
-    readonly defaults?: DefaultsResolver<T>;
+    readonly defaults?: DefaultsResolver<T> | undefined;
     readonly _type: T;
-    constructor(collection: string, defaults?: DefaultsResolver<T>);
+    constructor(collection: string, defaults?: DefaultsResolver<T> | undefined);
 }
 export declare function defineCollection<T>(config: {
     collection: string;

package/build/src/MongodbCollection.js

@@ -4,6 +4,9 @@ function hydrate(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,

package/build/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"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":"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.153",
+  "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"