@brightchain/db 0.20.0

package/src/lib/headRegistry.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistentHeadRegistry = exports.InMemoryHeadRegistry = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+// Re-export InMemoryHeadRegistry from brightchain-lib for backward compatibility
+var inMemoryHeadRegistry_1 = require("@brightchain/brightchain-lib/lib/db/inMemoryHeadRegistry");
+Object.defineProperty(exports, "InMemoryHeadRegistry", { enumerable: true, get: function () { return inMemoryHeadRegistry_1.InMemoryHeadRegistry; } });
+/**
+ * Persistent HeadRegistry that writes through to a JSON file on disk.
+ *
+ * The in-memory Map is the primary read path; disk is the persistence layer.
+ * Every mutation (setHead, removeHead, clear) writes the full JSON to disk
+ * before returning, ensuring durability across process restarts.
+ *
+ * File-level locking via `fs.open` with exclusive create prevents concurrent
+ * write corruption when multiple processes share the same data directory.
+ *
+ * If the persisted file is missing or corrupt on load(), the registry starts
+ * empty and logs a warning rather than crashing.
+ */
+class PersistentHeadRegistry {
+    constructor(options) {
+        this.heads = new Map();
+        this.timestamps = new Map();
+        this.deferred = [];
+        this.filePath = (0, path_1.join)(options.dataDir, options.fileName ?? 'head-registry.json');
+        this.lockPath = this.filePath + '.lock';
+    }
+    makeKey(dbName, collectionName) {
+        return `${dbName}:${collectionName}`;
+    }
+    getHead(dbName, collectionName) {
+        return this.heads.get(this.makeKey(dbName, collectionName));
+    }
+    async setHead(dbName, collectionName, blockId) {
+        const key = this.makeKey(dbName, collectionName);
+        this.heads.set(key, blockId);
+        this.timestamps.set(key, new Date());
+        await this.writeToDisk();
+    }
+    async removeHead(dbName, collectionName) {
+        const key = this.makeKey(dbName, collectionName);
+        this.heads.delete(key);
+        this.timestamps.delete(key);
+        await this.writeToDisk();
+    }
+    async clear() {
+        this.heads.clear();
+        this.timestamps.clear();
+        this.deferred.length = 0;
+        await this.writeToDisk();
+    }
+    async load() {
+        try {
+            const content = await fs_1.promises.readFile(this.filePath, 'utf-8');
+            const parsed = JSON.parse(content);
+            if (parsed === null ||
+                typeof parsed !== 'object' ||
+                Array.isArray(parsed)) {
+                console.warn(`[PersistentHeadRegistry] Registry file is not a JSON object, starting empty: ${this.filePath}`);
+                this.heads.clear();
+                this.timestamps.clear();
+                return;
+            }
+            this.heads.clear();
+            this.timestamps.clear();
+            const record = parsed;
+            for (const [key, value] of Object.entries(record)) {
+                if (typeof value === 'string') {
+                    // Legacy format: plain blockId string, no timestamp
+                    this.heads.set(key, value);
+                }
+                else if (value !== null &&
+                    typeof value === 'object' &&
+                    'blockId' in value &&
+                    typeof value['blockId'] === 'string') {
+                    // New format: { blockId, timestamp }
+                    const entry = value;
+                    this.heads.set(key, entry['blockId']);
+                    if (typeof entry['timestamp'] === 'string') {
+                        this.timestamps.set(key, new Date(entry['timestamp']));
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const error = err;
+            if (error.code === 'ENOENT') {
+                // File doesn't exist yet — start empty (not a warning)
+                this.heads.clear();
+                this.timestamps.clear();
+                return;
+            }
+            console.warn(`[PersistentHeadRegistry] Failed to load registry file, starting empty: ${this.filePath}`, error.message ?? error);
+            this.heads.clear();
+            this.timestamps.clear();
+        }
+    }
+    getAllHeads() {
+        return new Map(this.heads);
+    }
+    getHeadTimestamp(dbName, collectionName) {
+        return this.timestamps.get(this.makeKey(dbName, collectionName));
+    }
+    async mergeHeadUpdate(dbName, collectionName, blockId, timestamp) {
+        const key = this.makeKey(dbName, collectionName);
+        const localTimestamp = this.timestamps.get(key);
+        // If no local head exists, or the remote timestamp is strictly newer, apply
+        if (!localTimestamp || timestamp.getTime() > localTimestamp.getTime()) {
+            this.heads.set(key, blockId);
+            this.timestamps.set(key, timestamp);
+            await this.writeToDisk();
+            return true;
+        }
+        // Local is same age or newer — reject
+        return false;
+    }
+    async deferHeadUpdate(dbName, collectionName, blockId, timestamp) {
+        this.deferred.push({ dbName, collectionName, blockId, timestamp });
+    }
+    async applyDeferredUpdates(blockId) {
+        let applied = 0;
+        const remaining = [];
+        for (const update of this.deferred) {
+            if (update.blockId === blockId) {
+                await this.mergeHeadUpdate(update.dbName, update.collectionName, update.blockId, update.timestamp);
+                applied++;
+            }
+            else {
+                remaining.push(update);
+            }
+        }
+        this.deferred.length = 0;
+        this.deferred.push(...remaining);
+        return applied;
+    }
+    getDeferredUpdates() {
+        return [...this.deferred];
+    }
+    /**
+     * Write the current in-memory state to disk with file-level locking.
+     *
+     * Locking strategy: create a `.lock` file with exclusive flag (`wx`).
+     * If the lock file already exists, retry with a short delay.
+     * The lock file is always removed after writing, even on error.
+     */
+    async writeToDisk() {
+        await this.acquireLock();
+        try {
+            const data = {};
+            for (const [key, value] of this.heads) {
+                const ts = this.timestamps.get(key);
+                data[key] = {
+                    blockId: value,
+                    ...(ts ? { timestamp: ts.toISOString() } : {}),
+                };
+            }
+            const json = JSON.stringify(data, null, 2);
+            // Write to a temp file then rename for atomicity
+            const tmpPath = this.filePath + '.tmp';
+            await fs_1.promises.writeFile(tmpPath, json, 'utf-8');
+            await fs_1.promises.rename(tmpPath, this.filePath);
+        }
+        finally {
+            await this.releaseLock();
+        }
+    }
+    async acquireLock(maxRetries = 50, retryDelayMs = 20) {
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                const handle = await fs_1.promises.open(this.lockPath, 'wx');
+                await handle.close();
+                return;
+            }
+            catch (err) {
+                const error = err;
+                if (error.code === 'EEXIST') {
+                    // Lock held by another writer — wait and retry
+                    await this.delay(retryDelayMs);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        // If we exhausted retries, force-remove stale lock and try once more
+        try {
+            await fs_1.promises.unlink(this.lockPath);
+        }
+        catch {
+            // Ignore — lock may have been released between check and unlink
+        }
+        const handle = await fs_1.promises.open(this.lockPath, 'wx');
+        await handle.close();
+    }
+    async releaseLock() {
+        try {
+            await fs_1.promises.unlink(this.lockPath);
+        }
+        catch {
+            // Ignore — lock file may already be gone
+        }
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Factory method that creates a PersistentHeadRegistry for the given directory.
+     * Useful for tests that need an isolated persistent registry.
+     */
+    static create(options) {
+        return new PersistentHeadRegistry(options);
+    }
+}
+exports.PersistentHeadRegistry = PersistentHeadRegistry;
+//# sourceMappingURL=headRegistry.js.map

package/src/lib/headRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headRegistry.js","sourceRoot":"","sources":["../../../../brightchain-db/src/lib/headRegistry.ts"],"names":[],"mappings":"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"}

package/src/lib/indexing.d.ts

@@ -0,0 +1,7 @@
+/**
+ * In-memory index engine for fast document lookups.
+ *
+ * This module has been relocated to @brightchain/brightchain-lib.
+ * Re-exported here for backward compatibility.
+ */
+export { CollectionIndex, DuplicateKeyError, IndexManager, } from '@brightchain/brightchain-lib/lib/db/indexing';

package/src/lib/indexing.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * In-memory index engine for fast document lookups.
+ *
+ * This module has been relocated to @brightchain/brightchain-lib.
+ * Re-exported here for backward compatibility.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexManager = exports.DuplicateKeyError = exports.CollectionIndex = void 0;
+var indexing_1 = require("@brightchain/brightchain-lib/lib/db/indexing");
+Object.defineProperty(exports, "CollectionIndex", { enumerable: true, get: function () { return indexing_1.CollectionIndex; } });
+Object.defineProperty(exports, "DuplicateKeyError", { enumerable: true, get: function () { return indexing_1.DuplicateKeyError; } });
+Object.defineProperty(exports, "IndexManager", { enumerable: true, get: function () { return indexing_1.IndexManager; } });
+//# sourceMappingURL=indexing.js.map

package/src/lib/indexing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexing.js","sourceRoot":"","sources":["../../../../brightchain-db/src/lib/indexing.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,yEAIsD;AAHpD,2GAAA,eAAe,OAAA;AACf,6GAAA,iBAAiB,OAAA;AACjB,wGAAA,YAAY,OAAA"}

package/src/lib/model.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Model — a typed wrapper around Collection that automatically
+ * serializes on writes and rehydrates on reads.
+ *
+ * Analogous to Mongoose's Model, but with explicit type boundaries:
+ *  - TStored: the shape of documents in the database (all strings, extends BsonDocument)
+ *  - TTyped: the shape your application code works with (typed IDs, Date objects, etc.)
+ *
+ * Conversion between the two is handled by an IHydrationSchema from brightchain-lib.
+ * Schema validation is applied automatically before every write.
+ *
+ * Usage:
+ *   const roleModel = new Model(db.collection<IStoredRole>('roles'), {
+ *     schema: ROLE_SCHEMA,
+ *     hydration: { hydrate: rehydrateRole, dehydrate: serializeRole },
+ *   });
+ *
+ *   // Reads return TTyped
+ *   const role = await roleModel.findOne({ name: 'Admin' });
+ *
+ *   // Writes accept TTyped, serialize automatically
+ *   await roleModel.insertOne(typedRoleObject);
+ */
+import type { IHydrationSchema } from '@brightchain/brightchain-lib';
+import type { Collection } from './collection';
+import { Cursor } from './cursor';
+import type { ValidationFieldError } from './errors';
+import type { CollectionSchema } from './schemaValidation';
+import type { AggregationStage, BsonDocument, DeleteResult, DocumentId, FilterQuery, FindOptions, InsertManyResult, InsertOneResult, ReplaceResult, SortSpec, UpdateOptions, UpdateQuery, UpdateResult, WriteOptions } from './types';
+/**
+ * A cursor that wraps a raw Cursor<TStored> and maps results through
+ * a hydration function, yielding TTyped documents.
+ *
+ * Preserves the chainable sort/skip/limit/project API of the underlying cursor.
+ */
+export declare class TypedCursor<TStored extends BsonDocument, TTyped> {
+    private readonly _inner;
+    private readonly _hydrate;
+    constructor(_inner: Cursor<TStored>, _hydrate: (stored: TStored) => TTyped);
+    sort(spec: SortSpec<TStored>): this;
+    skip(n: number): this;
+    limit(n: number): this;
+    toArray(): Promise<TTyped[]>;
+    count(): Promise<number>;
+    next(): Promise<TTyped | null>;
+    hasNext(): Promise<boolean>;
+    forEach(fn: (doc: TTyped) => void | Promise<void>): Promise<void>;
+    map<U>(fn: (doc: TTyped) => U): Promise<U[]>;
+    /** Make the cursor thenable so it can be awaited directly. */
+    then<TResult1 = TTyped[], TResult2 = never>(onfulfilled?: ((value: TTyped[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+export interface ModelOptions<TStored extends BsonDocument, TTyped> {
+    /** Collection schema for validation before writes. */
+    schema?: CollectionSchema;
+    /** Hydration schema for storage ↔ typed conversion. */
+    hydration: IHydrationSchema<TStored, TTyped>;
+    /**
+     * Collection name — used for validation error messages.
+     * Defaults to the schema name if a schema is provided.
+     */
+    collectionName?: string;
+}
+/**
+ * A typed model wrapping a raw Collection<TStored>.
+ *
+ * - Reads (find, findOne, findById) return TTyped after hydration.
+ * - Writes (insertOne, insertMany, updateOne, etc.) accept TTyped,
+ *   dehydrate to TStored, validate against the schema, then delegate
+ *   to the underlying collection.
+ * - The raw collection is accessible via `.collection` for escape-hatch
+ *   scenarios (bulk ops, aggregation, raw queries).
+ */
+export declare class Model<TStored extends BsonDocument, TTyped> {
+    /** The underlying raw collection. */
+    readonly collection: Collection<TStored>;
+    private readonly _hydrate;
+    private readonly _dehydrate;
+    private readonly _schema?;
+    private readonly _collectionName;
+    constructor(collection: Collection<TStored>, options: ModelOptions<TStored, TTyped>);
+    /**
+     * Validate a typed document against the schema.
+     * Returns an empty array if valid, or field errors if not.
+     */
+    validate(typed: TTyped): ValidationFieldError[];
+    /**
+     * Validate and throw if invalid.
+     */
+    private _validateOrThrow;
+    /**
+     * Find a single document matching the filter.
+     * The filter operates on stored field names/values.
+     */
+    findOne(filter?: FilterQuery<TStored>, options?: FindOptions<TStored>): Promise<TTyped | null>;
+    /**
+     * Find all documents matching the filter.
+     * Returns a TypedCursor that hydrates results lazily.
+     */
+    find(filter?: FilterQuery<TStored>, options?: FindOptions<TStored>): TypedCursor<TStored, TTyped>;
+    /**
+     * Find a document by its _id.
+     */
+    findById(id: DocumentId): Promise<TTyped | null>;
+    /**
+     * Insert a single typed document.
+     * Dehydrates to stored form, validates, then inserts.
+     */
+    insertOne(typed: TTyped, options?: WriteOptions): Promise<InsertOneResult>;
+    /**
+     * Insert multiple typed documents.
+     * Dehydrates and validates each before inserting.
+     */
+    insertMany(docs: TTyped[], options?: WriteOptions): Promise<InsertManyResult>;
+    /**
+     * Update the first document matching the filter.
+     * The filter and update operate on stored field names/values.
+     */
+    updateOne(filter: FilterQuery<TStored>, update: UpdateQuery<TStored>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Update all documents matching the filter.
+     */
+    updateMany(filter: FilterQuery<TStored>, update: UpdateQuery<TStored>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Delete the first document matching the filter.
+     */
+    deleteOne(filter: FilterQuery<TStored>, options?: WriteOptions): Promise<DeleteResult>;
+    /**
+     * Delete all documents matching the filter.
+     */
+    deleteMany(filter: FilterQuery<TStored>, options?: WriteOptions): Promise<DeleteResult>;
+    /**
+     * Replace a single document matching the filter with a typed replacement.
+     * Dehydrates the replacement to stored form, validates, then delegates.
+     */
+    replaceOne(filter: FilterQuery<TStored>, replacement: TTyped, options?: UpdateOptions): Promise<ReplaceResult>;
+    /**
+     * Run an aggregation pipeline on the underlying collection.
+     * Returns raw BsonDocument results (aggregation output shapes are
+     * typically different from the collection's document type).
+     */
+    aggregate(pipeline: AggregationStage[]): Promise<BsonDocument[]>;
+    /**
+     * Return distinct values for a stored field.
+     */
+    distinct<K extends keyof TStored>(field: K, filter?: FilterQuery<TStored>): Promise<Array<TStored[K]>>;
+    /**
+     * Count documents matching the filter.
+     */
+    countDocuments(filter?: FilterQuery<TStored>): Promise<number>;
+    /**
+     * Estimated total document count.
+     */
+    estimatedDocumentCount(): Promise<number>;
+    /**
+     * Check if a document matching the filter exists.
+     */
+    exists(filter: FilterQuery<TStored>): Promise<boolean>;
+    /** Convert a stored document to its typed form. */
+    hydrate(stored: TStored): TTyped;
+    /** Convert a typed document to its stored form. */
+    dehydrate(typed: TTyped): TStored;
+}

package/src/lib/model.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * @fileoverview Model — a typed wrapper around Collection that automatically
+ * serializes on writes and rehydrates on reads.
+ *
+ * Analogous to Mongoose's Model, but with explicit type boundaries:
+ *  - TStored: the shape of documents in the database (all strings, extends BsonDocument)
+ *  - TTyped: the shape your application code works with (typed IDs, Date objects, etc.)
+ *
+ * Conversion between the two is handled by an IHydrationSchema from brightchain-lib.
+ * Schema validation is applied automatically before every write.
+ *
+ * Usage:
+ *   const roleModel = new Model(db.collection<IStoredRole>('roles'), {
+ *     schema: ROLE_SCHEMA,
+ *     hydration: { hydrate: rehydrateRole, dehydrate: serializeRole },
+ *   });
+ *
+ *   // Reads return TTyped
+ *   const role = await roleModel.findOne({ name: 'Admin' });
+ *
+ *   // Writes accept TTyped, serialize automatically
+ *   await roleModel.insertOne(typedRoleObject);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Model = exports.TypedCursor = void 0;
+const errors_1 = require("./errors");
+const schemaValidation_1 = require("./schemaValidation");
+// ─── TypedCursor ─────────────────────────────────────────────────────────────
+/**
+ * A cursor that wraps a raw Cursor<TStored> and maps results through
+ * a hydration function, yielding TTyped documents.
+ *
+ * Preserves the chainable sort/skip/limit/project API of the underlying cursor.
+ */
+class TypedCursor {
+    constructor(_inner, _hydrate) {
+        this._inner = _inner;
+        this._hydrate = _hydrate;
+    }
+    sort(spec) {
+        this._inner.sort(spec);
+        return this;
+    }
+    skip(n) {
+        this._inner.skip(n);
+        return this;
+    }
+    limit(n) {
+        this._inner.limit(n);
+        return this;
+    }
+    async toArray() {
+        const docs = await this._inner.toArray();
+        return docs.map(this._hydrate);
+    }
+    async count() {
+        return this._inner.count();
+    }
+    async next() {
+        const doc = await this._inner.next();
+        return doc ? this._hydrate(doc) : null;
+    }
+    async hasNext() {
+        return this._inner.hasNext();
+    }
+    async forEach(fn) {
+        const docs = await this.toArray();
+        for (const doc of docs) {
+            await fn(doc);
+        }
+    }
+    async map(fn) {
+        const docs = await this.toArray();
+        return docs.map(fn);
+    }
+    /** Make the cursor thenable so it can be awaited directly. */
+    then(onfulfilled, onrejected) {
+        return this.toArray().then(onfulfilled, onrejected);
+    }
+}
+exports.TypedCursor = TypedCursor;
+// ─── Model ───────────────────────────────────────────────────────────────────
+/**
+ * A typed model wrapping a raw Collection<TStored>.
+ *
+ * - Reads (find, findOne, findById) return TTyped after hydration.
+ * - Writes (insertOne, insertMany, updateOne, etc.) accept TTyped,
+ *   dehydrate to TStored, validate against the schema, then delegate
+ *   to the underlying collection.
+ * - The raw collection is accessible via `.collection` for escape-hatch
+ *   scenarios (bulk ops, aggregation, raw queries).
+ */
+class Model {
+    constructor(collection, options) {
+        this.collection = collection;
+        this._hydrate = options.hydration.hydrate;
+        this._dehydrate = options.hydration.dehydrate;
+        this._schema = options.schema;
+        this._collectionName =
+            options.collectionName ?? options.schema?.name ?? 'unknown';
+        // Wire the schema into the collection for its own validation
+        if (this._schema) {
+            collection.setSchema(this._schema);
+        }
+    }
+    // ── Validation ──────────────────────────────────────────────────────────
+    /**
+     * Validate a typed document against the schema.
+     * Returns an empty array if valid, or field errors if not.
+     */
+    validate(typed) {
+        if (!this._schema)
+            return [];
+        const stored = this._dehydrate(typed);
+        try {
+            (0, schemaValidation_1.validateDocument)(stored, this._schema, this._collectionName);
+            return [];
+        }
+        catch (err) {
+            if (err instanceof errors_1.ValidationError) {
+                return err.validationErrors;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Validate and throw if invalid.
+     */
+    _validateOrThrow(stored) {
+        if (!this._schema)
+            return;
+        (0, schemaValidation_1.validateDocument)(stored, this._schema, this._collectionName);
+    }
+    // ── Reads (return TTyped) ───────────────────────────────────────────────
+    /**
+     * Find a single document matching the filter.
+     * The filter operates on stored field names/values.
+     */
+    async findOne(filter, options) {
+        const stored = await this.collection.findOne(filter, options);
+        return stored ? this._hydrate(stored) : null;
+    }
+    /**
+     * Find all documents matching the filter.
+     * Returns a TypedCursor that hydrates results lazily.
+     */
+    find(filter, options) {
+        const cursor = this.collection.find(filter, options);
+        return new TypedCursor(cursor, this._hydrate);
+    }
+    /**
+     * Find a document by its _id.
+     */
+    async findById(id) {
+        const stored = await this.collection.findById(id);
+        return stored ? this._hydrate(stored) : null;
+    }
+    // ── Writes (accept TTyped, serialize + validate automatically) ──────────
+    /**
+     * Insert a single typed document.
+     * Dehydrates to stored form, validates, then inserts.
+     */
+    async insertOne(typed, options) {
+        const stored = this._dehydrate(typed);
+        this._validateOrThrow(stored);
+        return this.collection.insertOne(stored, options);
+    }
+    /**
+     * Insert multiple typed documents.
+     * Dehydrates and validates each before inserting.
+     */
+    async insertMany(docs, options) {
+        const storedDocs = docs.map((d) => {
+            const stored = this._dehydrate(d);
+            this._validateOrThrow(stored);
+            return stored;
+        });
+        return this.collection.insertMany(storedDocs, options);
+    }
+    /**
+     * Update the first document matching the filter.
+     * The filter and update operate on stored field names/values.
+     */
+    async updateOne(filter, update, options) {
+        return this.collection.updateOne(filter, update, options);
+    }
+    /**
+     * Update all documents matching the filter.
+     */
+    async updateMany(filter, update, options) {
+        return this.collection.updateMany(filter, update, options);
+    }
+    /**
+     * Delete the first document matching the filter.
+     */
+    async deleteOne(filter, options) {
+        return this.collection.deleteOne(filter, options);
+    }
+    /**
+     * Delete all documents matching the filter.
+     */
+    async deleteMany(filter, options) {
+        return this.collection.deleteMany(filter, options);
+    }
+    // ── Convenience ─────────────────────────────────────────────────────────
+    /**
+     * Replace a single document matching the filter with a typed replacement.
+     * Dehydrates the replacement to stored form, validates, then delegates.
+     */
+    async replaceOne(filter, replacement, options) {
+        const stored = this._dehydrate(replacement);
+        this._validateOrThrow(stored);
+        return this.collection.replaceOne(filter, stored, options);
+    }
+    /**
+     * Run an aggregation pipeline on the underlying collection.
+     * Returns raw BsonDocument results (aggregation output shapes are
+     * typically different from the collection's document type).
+     */
+    async aggregate(pipeline) {
+        return this.collection.aggregate(pipeline);
+    }
+    /**
+     * Return distinct values for a stored field.
+     */
+    async distinct(field, filter) {
+        return this.collection.distinct(field, filter);
+    }
+    /**
+     * Count documents matching the filter.
+     */
+    async countDocuments(filter) {
+        return this.collection.countDocuments(filter);
+    }
+    /**
+     * Estimated total document count.
+     */
+    async estimatedDocumentCount() {
+        return this.collection.estimatedDocumentCount();
+    }
+    /**
+     * Check if a document matching the filter exists.
+     */
+    async exists(filter) {
+        const doc = await this.collection.findOne(filter);
+        return doc !== null;
+    }
+    // ── Conversion helpers (public for escape-hatch scenarios) ──────────────
+    /** Convert a stored document to its typed form. */
+    hydrate(stored) {
+        return this._hydrate(stored);
+    }
+    /** Convert a typed document to its stored form. */
+    dehydrate(typed) {
+        return this._dehydrate(typed);
+    }
+}
+exports.Model = Model;
+//# sourceMappingURL=model.js.map