@livequery/mongodb 2.0.151 → 2.0.153

package/README.md

@@ -25,6 +25,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 './MongodbCollection.js'
 export * from './types.js'
 ```
 
@@ -386,6 +387,100 @@ 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.
+
+#### `constructor(db, collectionName, resolveDefaults?)`
+
+Parameters:
+
+- `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.
+
+Example:
+
+```ts
+import { MongoClient } from 'mongodb'
+import { MongodbCollection } 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 }
+
+const Orders = new MongodbCollection<Order>(db, 'orders', () => ({ started: false, running: true }))
+const Videos = new MongodbCollection<Video>(db, 'videos') // no defaults
+```
+
+#### 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
+const order = await Orders.create({ video_id: 'v1', amount: 50 })
+order.id              // '507f1f77bcf86cd799439011'
+order._id             // ObjectId — still readable internally
+JSON.stringify(order) // contains "id", not "_id"
+
+await Orders.findOne('507f1f77bcf86cd799439011') // by string id
+await Orders.findById(order._id)                 // by ObjectId
+await Orders.findOne({ video_id: 'v1' })         // by filter
+
+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
+```
+
 ### `DataChangePayload<T>`
 
 Type-only realtime/change payload contract.

package/build/src/MongoDatasource.js

@@ -155,9 +155,10 @@ 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 {
@@ -212,7 +213,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

@@ -490,11 +490,12 @@ export class MongoQuery {
     }
     static async query(req, collection) {
         if (!req.is_collection) {
+            const { id, _id: _rawId, ...keysWithoutId } = req.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(),

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>;
+    readonly _type: T;
+    constructor(collection: string, defaults?: DefaultsResolver<T>);
+}
+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,113 @@
+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 });
+    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":"5.9.3"}

package/package.json

@@ -6,7 +6,7 @@
   "repository": {
     "url": "git@github.com:livequery/mongodb.git"
   },
-  "version": "2.0.151",
+  "version": "2.0.153",
   "description": "MongoDB datasource mapping for @livequery ecosystem",
   "main": "./build/src/index.js",
   "types": "./build/src/index.d.ts",
@@ -22,7 +22,7 @@
     }
   },
   "devDependencies": {
-    "@livequery/core": "^2.0.151",
+    "@livequery/core": "^2.0.152",
     "@types/node": "^18.11.9",
     "mongodb": "^6.20.0",
     "rxjs": "*",