anchordb 0.2.0

package/dist/cjs/model/model.js

@@ -0,0 +1,823 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.castValue = exports.Model = void 0;
+exports.hydrateDoc = hydrateDoc;
+exports.serialise = serialise;
+exports.pluralize = pluralize;
+const errors_ts_1 = require("../core/errors.js");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_ts_1.ValidationError; } });
+const object_id_ts_1 = require("../core/object-id.js");
+const cast_ts_1 = require("../schema/cast.js");
+Object.defineProperty(exports, "castValue", { enumerable: true, get: function () { return cast_ts_1.castValue; } });
+const validate_ts_1 = require("../schema/validate.js");
+const filter_ts_1 = require("../query/filter.js");
+const update_ts_1 = require("../query/update.js");
+const path_ts_1 = require("../query/path.js");
+const query_ts_1 = require("../query/builder/query.js");
+const keys_ts_1 = require("../index/keys.js");
+const pipeline_ts_1 = require("../query/aggregation/pipeline.js");
+const source_ts_1 = require("../query/aggregation/source.js");
+/**
+ * Mongoose's `Model`.
+ *
+ * Every mutation funnels through `persist()`, which is the single place that stamps timestamps,
+ * assigns HLC values and (in synced mode) records a mutation. Having one path is what makes
+ * "Lens edits behave exactly like app edits" true by construction rather than by discipline.
+ */
+class Model {
+    constructor(name, schema, runtime, options = {}) {
+        this.indexesReady = null;
+        /** Set by createModelConstructor so query results can be hydrated into Documents. */
+        this.documentFactory = null;
+        this.modelName = name;
+        this.schema = schema;
+        this.runtime = runtime;
+        this.collectionName = options.collection ?? schema.options.collection ?? pluralize(name);
+        // Statics declared on the schema become methods on the model, as in Mongoose.
+        for (const [key, fn] of Object.entries(schema.statics)) {
+            this[key] = fn.bind(this);
+        }
+    }
+    /** Wired by the model constructor; keeps Model free of an import cycle with Document. */
+    _setDocumentFactory(factory) {
+        this.documentFactory = factory;
+    }
+    get adapter() {
+        return this.runtime.adapter;
+    }
+    // ---- index bootstrap -----------------------------------------------------
+    /**
+     * Creates schema-declared indexes on first use, mirroring Mongoose's `autoIndex`.
+     * Memoised, so concurrent first queries do not race to build the same index.
+     */
+    async ensureIndexes() {
+        this.indexesReady ??= (async () => {
+            await this.runtime.ready();
+            await this.adapter.ensureCollection(this.collectionName);
+            for (const declared of this.schema.indexes()) {
+                const spec = {
+                    name: declared.name,
+                    key: declared.key,
+                    ...(declared.options.unique !== undefined ? { unique: declared.options.unique } : {}),
+                    ...(declared.options.sparse !== undefined ? { sparse: declared.options.sparse } : {}),
+                    ...(declared.options.partialFilterExpression
+                        ? { partialFilterExpression: declared.options.partialFilterExpression }
+                        : {}),
+                    ...(declared.options.expireAfterSeconds !== undefined
+                        ? { expireAfterSeconds: declared.options.expireAfterSeconds }
+                        : {}),
+                };
+                await this.adapter.createIndex(this.collectionName, spec);
+            }
+        })();
+        return this.indexesReady;
+    }
+    async createIndex(key, options = {}) {
+        await this.runtime.ready();
+        await this.adapter.ensureCollection(this.collectionName);
+        const entries = Object.entries(key);
+        const name = options.name ?? (0, keys_ts_1.defaultIndexName)(entries);
+        await this.adapter.createIndex(this.collectionName, { ...options, name, key: entries });
+        return name;
+    }
+    async createIndexes(specs) {
+        const out = [];
+        for (const spec of specs)
+            out.push(await this.createIndex(spec.key, spec.options ?? {}));
+        return out;
+    }
+    async listIndexes() {
+        await this.ensureIndexes();
+        const explicit = await this.adapter.listIndexes(this.collectionName);
+        // `_id` always has an implicit unique index and is never droppable.
+        return [{ name: "_id_", key: [["_id", 1]], unique: true }, ...explicit];
+    }
+    async dropIndex(name) {
+        if (name === "_id_") {
+            throw new errors_ts_1.MongoServerError({ message: "cannot drop _id index", code: 72 });
+        }
+        await this.adapter.dropIndex(this.collectionName, name);
+    }
+    async dropIndexes() {
+        await this.runtime.ready();
+        for (const idx of await this.adapter.listIndexes(this.collectionName)) {
+            await this.adapter.dropIndex(this.collectionName, idx.name);
+        }
+    }
+    // ---- reads ---------------------------------------------------------------
+    find(filter = {}) {
+        return new query_ts_1.Query(this, { op: "find", filter });
+    }
+    findOne(filter = {}) {
+        return new query_ts_1.Query(this, { op: "findOne", filter });
+    }
+    findById(id) {
+        return new query_ts_1.Query(this, { op: "findOne", filter: { _id: normaliseId(id) } });
+    }
+    countDocuments(filter = {}) {
+        return new query_ts_1.Query(this, { op: "count", filter });
+    }
+    async estimatedDocumentCount() {
+        await this.ensureIndexes();
+        const n = await this.adapter.count({ collection: this.collectionName, constraints: [] });
+        return n ?? (await this.find({}).count());
+    }
+    async exists(filter) {
+        const doc = await this.findOne(filter).select("_id").exec();
+        return doc ? { _id: doc._id } : null;
+    }
+    distinct(field, filter = {}) {
+        const q = new query_ts_1.Query(this, { op: "distinct", filter, distinctField: field });
+        return q;
+    }
+    /**
+     * MongoDB aggregation pipeline.
+     *
+     * The pipeline array is plain MongoDB syntax, so the identical value can be handed to
+     * `Model.aggregate()` on a Mongoose backend. Pass `{ mongoCompatible: true }` to have any
+     * non-portable construct rejected at development time rather than discovered in production.
+     */
+    async aggregate(pipeline, options = {}) {
+        await this.ensureIndexes();
+        await this.runPreHooks("aggregate", { modelName: this.modelName, op: "aggregate" });
+        const result = await (0, pipeline_ts_1.runPipeline)(pipeline, this.aggregationSource(), {
+            ...(this.runtime.time.serverTimeZone ? { timezone: options.timezone } : { timezone: options.timezone }),
+            ...options,
+        });
+        await this.runPostHooks("aggregate", result.documents, { modelName: this.modelName, op: "aggregate" });
+        return result.documents;
+    }
+    /** Same pipeline, but reports what was pushed into storage and what ran in JS. */
+    async explainAggregate(pipeline, options = {}) {
+        await this.ensureIndexes();
+        const result = await (0, pipeline_ts_1.runPipeline)(pipeline, this.aggregationSource(), { ...options, explain: true });
+        return result.explain;
+    }
+    aggregationSource() {
+        return new source_ts_1.StorageAggregationSource({
+            adapter: this.adapter,
+            collection: this.collectionName,
+            schema: this.schema,
+            // $lookup names a COLLECTION, so resolve it to a registered model when one exists — that is
+            // what lets the joined documents be hydrated with their own schema types.
+            resolveCollection: (name) => {
+                const model = this.runtime.getModelByCollection?.(name);
+                if (model)
+                    return { collection: model.collectionName, schema: model.schema };
+                return { collection: name, schema: this.schema };
+            },
+        });
+    }
+    /**
+     * Bulk write, mirroring Mongoose. Operations are applied in order and reported per type.
+     */
+    async bulkWrite(operations) {
+        const summary = { insertedCount: 0, matchedCount: 0, modifiedCount: 0, deletedCount: 0, upsertedCount: 0 };
+        for (const op of operations) {
+            const kind = Object.keys(op)[0];
+            const spec = op[kind];
+            switch (kind) {
+                case "insertOne": {
+                    await this.insertOne(spec.document);
+                    summary.insertedCount++;
+                    break;
+                }
+                case "updateOne":
+                case "updateMany": {
+                    const s = spec;
+                    const res = await (kind === "updateOne" ? this.updateOne : this.updateMany).call(this, s.filter, s.update, s.upsert ? { upsert: true } : {});
+                    summary.matchedCount += res.matchedCount;
+                    summary.modifiedCount += res.modifiedCount;
+                    summary.upsertedCount += res.upsertedCount;
+                    break;
+                }
+                case "replaceOne": {
+                    const s = spec;
+                    const res = await this.replaceOne(s.filter, s.replacement);
+                    summary.matchedCount += res.matchedCount;
+                    summary.modifiedCount += res.modifiedCount;
+                    break;
+                }
+                case "deleteOne":
+                case "deleteMany": {
+                    const s = spec;
+                    const res = await (kind === "deleteOne" ? this.deleteOne : this.deleteMany).call(this, s.filter);
+                    summary.deletedCount += res.deletedCount;
+                    break;
+                }
+                default:
+                    throw new errors_ts_1.MongoServerError({ message: `Unknown bulkWrite operation "${String(kind)}"`, code: 9 });
+            }
+        }
+        return summary;
+    }
+    // ---- writes --------------------------------------------------------------
+    async create(input) {
+        if (Array.isArray(input))
+            return this.insertMany(input);
+        return this.insertOne(input);
+    }
+    async insertOne(input) {
+        await this.ensureIndexes();
+        const row = await this.prepareInsert(input);
+        await this.persist([{ type: "insert", collection: this.collectionName, _id: row.doc._id, row }], "save", {
+            doc: row.doc,
+        });
+        return this.hydrate(row);
+    }
+    /**
+     * `ordered: true` (the default) stops at the first error; `ordered: false` attempts every
+     * document and reports all failures in a BulkWriteError — matching MongoDB, including the
+     * accurate `insertedCount`.
+     */
+    async insertMany(inputs, options = {}) {
+        await this.ensureIndexes();
+        const ordered = options.ordered ?? true;
+        if (ordered) {
+            const rows = [];
+            for (const input of inputs)
+                rows.push(await this.prepareInsert(input));
+            await this.persist(rows.map((row) => ({ type: "insert", collection: this.collectionName, _id: row.doc._id, row })), "insertMany", {});
+            return rows.map((r) => this.hydrate(r));
+        }
+        const inserted = [];
+        const insertedIds = {};
+        const writeErrors = [];
+        for (let i = 0; i < inputs.length; i++) {
+            try {
+                const row = await this.prepareInsert(inputs[i]);
+                await this.persist([{ type: "insert", collection: this.collectionName, _id: row.doc._id, row }], "save", {
+                    doc: row.doc,
+                });
+                inserted.push(row);
+                insertedIds[i] = row.doc._id;
+            }
+            catch (err) {
+                const e = err;
+                writeErrors.push({ index: i, code: e.code ?? 0, errmsg: e.message, err: e });
+            }
+        }
+        if (writeErrors.length > 0) {
+            throw new errors_ts_1.BulkWriteError({ writeErrors, insertedCount: inserted.length, insertedIds });
+        }
+        return inserted.map((r) => this.hydrate(r));
+    }
+    async updateOne(filter, update, options = {}) {
+        return this.runUpdate(filter, update, { ...options, multi: false });
+    }
+    async updateMany(filter, update, options = {}) {
+        return this.runUpdate(filter, update, { ...options, multi: true });
+    }
+    async replaceOne(filter, replacement, options = {}) {
+        return this.runUpdate(filter, replacement, { ...options, multi: false, replace: true });
+    }
+    async findOneAndUpdate(filter, update, options = {}) {
+        const before = await this.findOne(filter).exec();
+        if (!before) {
+            if (options.upsert) {
+                await this.runUpdate(filter, update, { ...options, multi: false });
+                return this.findOne(filter).exec();
+            }
+            return null;
+        }
+        await this.runUpdate({ _id: before._id }, update, { ...options, multi: false });
+        // Mongoose returns the pre-update document unless `new: true`.
+        return options.new ? this.findById(before._id).exec() : before;
+    }
+    async findByIdAndUpdate(id, update, options = {}) {
+        return this.findOneAndUpdate({ _id: normaliseId(id) }, update, options);
+    }
+    async findOneAndDelete(filter) {
+        const doc = await this.findOne(filter).exec();
+        if (!doc)
+            return null;
+        await this.deleteOne({ _id: doc._id });
+        return doc;
+    }
+    async findByIdAndDelete(id) {
+        return this.findOneAndDelete({ _id: normaliseId(id) });
+    }
+    async deleteOne(filter) {
+        return this.runDelete(filter, false);
+    }
+    async deleteMany(filter) {
+        return this.runDelete(filter, true);
+    }
+    // ---- internals -----------------------------------------------------------
+    async prepareInsert(input) {
+        const now = this.runtime.time.now();
+        const raw = (0, path_ts_1.deepClone)(input);
+        const id = raw._id !== undefined ? normaliseId(raw._id) : new object_id_ts_1.ObjectId().toHexString();
+        delete raw._id;
+        const { doc } = (0, cast_ts_1.castDocument)(raw, this.schema, { applyDefaults: true });
+        doc._id = id;
+        const { createdAt, updatedAt } = this.schema.timestampFields;
+        if (createdAt)
+            doc[createdAt] = now;
+        if (updatedAt)
+            doc[updatedAt] = now;
+        if (this.schema.versionKey)
+            doc[this.schema.versionKey] = 0;
+        await this.runPreHooks("validate", { modelName: this.modelName, op: "validate", doc });
+        await (0, validate_ts_1.validateDocument)(doc, this.schema, { modelName: this.modelName });
+        await this.runPostHooks("validate", doc, { modelName: this.modelName, op: "validate", doc });
+        return {
+            doc: serialise(doc),
+            meta: {
+                version: 0,
+                hlc: this.runtime.clock.tickStamp(),
+                dirty: this.runtime.syncEnabled,
+                deleted: false,
+                createdAt: now,
+                updatedAt: now,
+            },
+        };
+    }
+    async runUpdate(filter, update, options) {
+        await this.ensureIndexes();
+        await this.runPreHooks(options.multi ? "updateMany" : "updateOne", {
+            modelName: this.modelName,
+            op: options.multi ? "updateMany" : "updateOne",
+            filter,
+            update,
+        });
+        const matches = await this.loadMatching(filter, options.multi ? undefined : 1);
+        if (matches.length === 0 && options.upsert) {
+            const seed = buildUpsertSeed(filter, update);
+            const created = await this.insertOne(seed);
+            return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedCount: 1, upsertedId: created._id };
+        }
+        const now = this.runtime.time.now();
+        const ops = [];
+        let modified = 0;
+        for (const row of matches) {
+            const currentDoc = hydrateDoc(row, this.schema);
+            const replace = options.replace ?? (0, update_ts_1.isReplacement)(update);
+            let nextDoc;
+            if (replace) {
+                const { doc: castReplacement } = (0, cast_ts_1.castDocument)(stripImmutable(update, this.schema), this.schema, { applyDefaults: true });
+                nextDoc = castReplacement;
+                nextDoc._id = currentDoc._id;
+                // createdAt survives a replace unless explicitly overridden (§26.4).
+                const createdField = this.schema.timestampFields.createdAt;
+                if (createdField)
+                    nextDoc[createdField] = currentDoc[createdField] ?? row.meta.createdAt;
+            }
+            else {
+                const applied = (0, update_ts_1.applyUpdate)(currentDoc, update);
+                const { doc: recast } = (0, cast_ts_1.castDocument)(applied, this.schema, { applyDefaults: false });
+                nextDoc = recast;
+                nextDoc._id = currentDoc._id;
+                const createdField = this.schema.timestampFields.createdAt;
+                if (createdField)
+                    nextDoc[createdField] = currentDoc[createdField];
+            }
+            if (options.runValidators !== false) {
+                const paths = replace ? undefined : (0, update_ts_1.updatedPaths)(update);
+                await (0, validate_ts_1.validateDocument)(nextDoc, this.schema, {
+                    modelName: this.modelName,
+                    ...(paths ? { pathsToValidate: paths.filter((p) => this.schema.paths.has(p)) } : {}),
+                });
+            }
+            // Did this update actually change anything? Compare with updatedAt and the version key
+            // excluded on both sides: those are stamped below precisely because the cast above drops them,
+            // so including them would guarantee a difference and modifiedCount could never be 0.
+            //
+            // Mongo treats a no-op update as exactly that — matched, not modified, updatedAt untouched.
+            // Skipping the write is what makes that true here, and it is what stops a bulk
+            // "set status to active" over 10,000 documents queueing 10,000 mutations when only a few
+            // hundred needed changing.
+            if (sameContent(serialise(nextDoc), row.doc, this.schema))
+                continue;
+            modified++;
+            const updatedField = this.schema.timestampFields.updatedAt;
+            if (updatedField)
+                nextDoc[updatedField] = now;
+            if (this.schema.versionKey) {
+                nextDoc[this.schema.versionKey] = Number(currentDoc[this.schema.versionKey] ?? 0) + 1;
+            }
+            const serialised = serialise(nextDoc);
+            ops.push({
+                type: replace ? "replace" : "update",
+                collection: this.collectionName,
+                _id: row.doc._id,
+                row: {
+                    doc: serialised,
+                    meta: { ...row.meta, updatedAt: now, hlc: this.runtime.clock.tickStamp(), dirty: this.runtime.syncEnabled },
+                },
+            });
+        }
+        if (ops.length > 0)
+            await this.persist(ops, options.multi ? "updateMany" : "updateOne", { filter, update });
+        return {
+            acknowledged: true,
+            matchedCount: matches.length,
+            modifiedCount: modified,
+            upsertedCount: 0,
+            upsertedId: null,
+        };
+    }
+    async runDelete(filter, multi) {
+        await this.ensureIndexes();
+        await this.runPreHooks(multi ? "deleteMany" : "deleteOne", {
+            modelName: this.modelName,
+            op: multi ? "deleteMany" : "deleteOne",
+            filter,
+        });
+        const matches = await this.loadMatching(filter, multi ? undefined : 1);
+        if (matches.length === 0)
+            return { acknowledged: true, deletedCount: 0 };
+        const now = this.runtime.time.now();
+        const ops = matches.map((row) => this.runtime.syncEnabled
+            ? // Synced mode keeps a tombstone: the deletion itself has to be replayable to the server.
+                {
+                    type: "delete",
+                    collection: this.collectionName,
+                    _id: row.doc._id,
+                    row: {
+                        doc: row.doc,
+                        meta: {
+                            ...row.meta,
+                            deleted: true,
+                            deletedAt: now,
+                            updatedAt: now,
+                            dirty: true,
+                            hlc: this.runtime.clock.tickStamp(),
+                        },
+                    },
+                }
+            : // Local-only mode has nobody to tell, so the row simply goes.
+                { type: "hardDelete", collection: this.collectionName, _id: row.doc._id });
+        await this.persist(ops, multi ? "deleteMany" : "deleteOne", { filter });
+        return { acknowledged: true, deletedCount: matches.length };
+    }
+    /** The single write path: storage, then mutation queue, then events. */
+    async persist(ops, hook, ctx) {
+        await this.adapter.write(ops);
+        if (this.runtime.syncEnabled) {
+            await this.runtime.recordMutations(this.collectionName, ops);
+        }
+        for (const op of ops) {
+            this.runtime.events.emit("change", {
+                collection: this.collectionName,
+                modelName: this.modelName,
+                operation: op.type === "hardDelete" ? "delete" : op.type,
+                documentId: op._id,
+                document: op.row ? hydrateDoc(op.row, this.schema) : null,
+            });
+        }
+        await this.runPostHooks(hook, ops, { modelName: this.modelName, op: hook, ...ctx });
+    }
+    async loadMatching(rawFilter, limit) {
+        const filter = (0, cast_ts_1.castFilter)(rawFilter, this.schema);
+        const result = await this.adapter.find({
+            collection: this.collectionName,
+            constraints: (0, filter_ts_1.extractConstraints)(filter),
+        });
+        // The adapter narrows; the JS matcher decides. Same reasoning as run(): extracted constraints
+        // are not the whole filter, so matching is never skipped.
+        const out = [];
+        for (const row of result.rows) {
+            if (!(0, filter_ts_1.matchesFilter)(hydrateDoc(row, this.schema), filter))
+                continue;
+            out.push(row);
+            if (limit !== undefined && out.length >= limit)
+                break;
+        }
+        return out;
+    }
+    async runPreHooks(name, ctx) {
+        for (const fn of this.schema.preHooks.get(name) ?? []) {
+            await fn.call(ctx.doc ?? this, ctx);
+        }
+    }
+    async runPostHooks(name, result, ctx) {
+        for (const fn of this.schema.postHooks.get(name) ?? []) {
+            await fn.call(ctx.doc ?? this, result, ctx);
+        }
+    }
+    /**
+     * Return a Document, matching what queries return.
+     *
+     * Mongoose's create()/insertMany() hand back Documents, so `(await User.create(...)).save()`
+     * works. Returning a plain object here while find() returned a Document would be an inconsistency
+     * a user would hit immediately and could not explain.
+     */
+    hydrate(row) {
+        const doc = hydrateDoc(row, this.schema);
+        return (this.documentFactory ? this.documentFactory(doc) : doc);
+    }
+    // ---- query execution -----------------------------------------------------
+    /** Entry point for every `Query`. This is where the whole chain becomes one storage plan. */
+    async run(state) {
+        await this.ensureIndexes();
+        await this.runPreHooks(state.op === "findOne" ? "findOne" : "find", {
+            modelName: this.modelName,
+            op: state.op === "findOne" ? "findOne" : "find",
+            filter: state.filter,
+        });
+        // Cast filter values through the schema first, so a hex string reaches the matcher as the
+        // ObjectId the document actually holds.
+        state = { ...state, filter: (0, cast_ts_1.castFilter)(state.filter, this.schema) };
+        const constraints = (0, filter_ts_1.extractConstraints)(state.filter);
+        const wantsOne = state.op === "findOne";
+        const effectiveLimit = wantsOne ? 1 : state.limit;
+        /**
+         * `extractConstraints` drops whatever it cannot express — a `$regex`, an `$or`, an
+         * `$elemMatch`. The adapter therefore reports it "applied all constraints" while conditions
+         * remain unevaluated. Trusting that flag as "the filter is satisfied" would return rows that do
+         * not match, so:
+         *
+         *   - the JS matcher below always runs and is the sole authority on correctness;
+         *   - the storage engine may apply skip/limit ONLY when extraction was lossless, because paging
+         *     over a row set that still needs filtering pages over the wrong rows.
+         */
+        const lossless = (0, filter_ts_1.isFullyExtractable)(state.filter);
+        const canPushPaging = lossless;
+        const result = await this.adapter.find({
+            collection: this.collectionName,
+            constraints,
+            ...(state.sort ? { sort: state.sort } : {}),
+            ...(canPushPaging && state.skip !== undefined ? { skip: state.skip } : {}),
+            ...(canPushPaging && effectiveLimit !== undefined ? { limit: effectiveLimit } : {}),
+        });
+        let docs = result.rows.map((row) => hydrateDoc(row, this.schema));
+        const examined = docs.length;
+        // Always filter. Cheap on an already-narrowed set, and the only way the answer is guaranteed.
+        docs = docs.filter((d) => (0, filter_ts_1.matchesFilter)(d, state.filter));
+        if (state.sort && !result.applied.sort)
+            docs = sortDocs(docs, state.sort);
+        if (state.skip !== undefined && !(canPushPaging && result.applied.skip))
+            docs = docs.slice(state.skip);
+        if (effectiveLimit !== undefined && !(canPushPaging && result.applied.limit)) {
+            docs = docs.slice(0, effectiveLimit);
+        }
+        if (state.op === "count")
+            return docs.length;
+        if (state.op === "distinct") {
+            const field = state.distinctField;
+            const seen = [];
+            for (const doc of docs) {
+                const value = (0, path_ts_1.getPath)(doc, field);
+                const values = Array.isArray(value) ? value : [value];
+                for (const v of values) {
+                    if (v !== undefined && !seen.some((s) => (0, path_ts_1.compareValues)(s, v) === 0))
+                        seen.push(v);
+                }
+            }
+            return seen;
+        }
+        if (state.populate.length > 0) {
+            await this.applyPopulate(docs, state.populate);
+        }
+        if (state.projection)
+            docs = docs.map((d) => project(d, state.projection));
+        if (state.explain) {
+            const explain = {
+                op: state.op,
+                filter: state.filter,
+                stage: result.indexUsed ? "IXSCAN" : "COLLSCAN",
+                indexUsed: result.indexUsed ?? null,
+                pushedDown: result.applied,
+                documentsExamined: examined,
+                documentsReturned: docs.length,
+                populatedPaths: state.populate.map((p) => p.path),
+                ...(state.sort ? { sort: state.sort } : {}),
+            };
+            return explain;
+        }
+        // Mongoose returns Documents (with .save(), .isModified()) unless .lean() is used. Matching
+        // that is what lets a loaded document be edited and saved without re-learning anything.
+        const output = state.lean || !this.documentFactory
+            ? docs.map(stripUndefined)
+            : docs.map((d) => this.documentFactory(d));
+        await this.runPostHooks(wantsOne ? "findOne" : "find", output, {
+            modelName: this.modelName,
+            op: wantsOne ? "findOne" : "find",
+            filter: state.filter,
+        });
+        if (wantsOne)
+            return output[0] ?? null;
+        return output;
+    }
+    /**
+     * Batched population: every referenced id across the whole page is collected and fetched with one
+     * query per target collection. The naive alternative is one query per document per path, which
+     * turns a 50-row page into 50 round trips.
+     */
+    async applyPopulate(docs, specs) {
+        for (const spec of specs) {
+            const refName = spec.model ?? this.schema.refs().get(spec.path);
+            if (!refName) {
+                throw new Error(`Cannot populate "${spec.path}" on model "${this.modelName}": no ref is declared for that path. ` +
+                    `Add \`ref\` to the schema, or pass \`{ path, model }\`.`);
+            }
+            const target = this.runtime.getModel(refName);
+            const ids = [];
+            for (const doc of docs) {
+                const value = (0, path_ts_1.getPath)(doc, spec.path);
+                if (value === undefined || value === null)
+                    continue;
+                for (const v of Array.isArray(value) ? value : [value])
+                    ids.push(String(v));
+            }
+            if (ids.length === 0)
+                continue;
+            const uniqueIds = [...new Set(ids.map(String))];
+            const query = target.find({ _id: { $in: uniqueIds }, ...(spec.match ?? {}) });
+            if (spec.select)
+                query.select(spec.select);
+            if (spec.options?.sort)
+                query.sort(spec.options.sort);
+            if (spec.options?.limit !== undefined)
+                query.limit(spec.options.limit);
+            if (spec.options?.skip !== undefined)
+                query.skip(spec.options.skip);
+            if (spec.populate)
+                query.populate(spec.populate);
+            const found = (await query.exec());
+            const byId = new Map(found.map((d) => [String(d._id), d]));
+            const onMissing = this.runtime.onMissingRef;
+            for (const doc of docs) {
+                const value = (0, path_ts_1.getPath)(doc, spec.path);
+                if (value === undefined || value === null)
+                    continue;
+                if (Array.isArray(value)) {
+                    const resolved = value
+                        .map((v) => byId.get(String(v)) ?? missingRef(v, onMissing, spec.path, this.modelName))
+                        .filter((v) => v !== undefined);
+                    (0, path_ts_1.setPath)(doc, spec.path, resolved);
+                }
+                else {
+                    const hit = byId.get(String(value));
+                    (0, path_ts_1.setPath)(doc, spec.path, hit ?? missingRef(value, onMissing, spec.path, this.modelName));
+                }
+            }
+        }
+    }
+}
+exports.Model = Model;
+/**
+ * A ref with no local target. Offline-first makes this ordinary rather than exceptional: the
+ * referenced document may simply not have synced down yet, so the behaviour is configurable and
+ * defaults to Mongoose's (null).
+ */
+function missingRef(id, mode, path, modelName) {
+    if (mode === "keep-id")
+        return id;
+    if (mode === "throw") {
+        throw new errors_ts_1.DocumentNotFoundError({ _id: id }, `${modelName}.${path} — the referenced document is not present locally. ` +
+            `It may not have synced yet; use onMissingRef: "null" or "keep-id" to tolerate this.`);
+    }
+    return null;
+}
+/**
+ * Content equality for an update, ignoring the fields an update always rewrites.
+ *
+ * `updatedAt` and the version key are stamped on every write, so a straight comparison would report
+ * every matched document as modified. Everything else is compared exactly.
+ */
+function sameContent(next, stored, schema) {
+    const volatileKeys = [schema.timestampFields.updatedAt, schema.versionKey].filter(Boolean);
+    const strip = (doc) => {
+        if (doc === null || typeof doc !== "object")
+            return doc;
+        const copy = {};
+        for (const [key, value] of Object.entries(doc)) {
+            if (!volatileKeys.includes(key))
+                copy[key] = value;
+        }
+        return copy;
+    };
+    return JSON.stringify(strip(next)) === JSON.stringify(strip(stored));
+}
+function buildUpsertSeed(filter, update) {
+    const seed = {};
+    // Equality conditions in the filter seed the new document, as Mongo does.
+    for (const [key, value] of Object.entries(filter)) {
+        if (key.startsWith("$"))
+            continue;
+        if (value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date))
+            continue;
+        (0, path_ts_1.setPath)(seed, key, value);
+    }
+    return (0, update_ts_1.applyUpdate)(seed, update, { isInsert: true });
+}
+function stripImmutable(doc, schema) {
+    const out = { ...doc };
+    for (const [path, def] of schema.paths) {
+        if (def.immutable)
+            delete out[path];
+    }
+    return out;
+}
+function sortDocs(docs, sort) {
+    return [...docs].sort((a, b) => {
+        for (const [path, dir] of sort) {
+            const c = (0, path_ts_1.compareValues)((0, path_ts_1.getPath)(a, path), (0, path_ts_1.getPath)(b, path));
+            if (c !== 0)
+                return dir === 1 ? c : -c;
+        }
+        return 0;
+    });
+}
+function project(doc, projection) {
+    const entries = Object.entries(projection).filter(([k]) => k !== "_id");
+    const including = entries.some(([, v]) => v === 1);
+    const out = {};
+    if (including) {
+        for (const [path, flag] of entries) {
+            if (flag === 1) {
+                const value = (0, path_ts_1.getPath)(doc, path);
+                if (value !== undefined)
+                    (0, path_ts_1.setPath)(out, path, value);
+            }
+        }
+        if (projection._id !== 0)
+            out._id = doc._id;
+        return out;
+    }
+    Object.assign(out, (0, path_ts_1.deepClone)(doc));
+    for (const [path] of entries)
+        delete out[path];
+    if (projection._id === 0)
+        delete out._id;
+    return out;
+}
+function stripUndefined(doc) {
+    const out = {};
+    for (const [k, v] of Object.entries(doc))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** Storage holds JSON; typed values (ObjectId, Date) are rebuilt on read. */
+function hydrateDoc(row, schema) {
+    const doc = (0, path_ts_1.deepClone)(row.doc);
+    // Mongoose exposes _id as an ObjectId, so code doing doc._id.equals(...) or .toHexString()
+    // works unchanged. Storage keeps the hex string; the conversion happens here on read.
+    if (typeof doc._id === "string" && object_id_ts_1.ObjectId.isValid(doc._id))
+        doc._id = new object_id_ts_1.ObjectId(doc._id);
+    for (const [path, def] of schema.paths) {
+        if (path === "_id")
+            continue;
+        const value = (0, path_ts_1.getPath)(doc, path);
+        if (value === undefined || value === null)
+            continue;
+        if (def.instance === "Date" && typeof value === "string")
+            (0, path_ts_1.setPath)(doc, path, new Date(value));
+        else if (def.instance === "ObjectId" && typeof value === "string" && object_id_ts_1.ObjectId.isValid(value)) {
+            (0, path_ts_1.setPath)(doc, path, new object_id_ts_1.ObjectId(value));
+        }
+        else if (def.instance === "Array" && def.arrayType && Array.isArray(value)) {
+            if (def.arrayType.instance === "Date")
+                (0, path_ts_1.setPath)(doc, path, value.map((v) => (typeof v === "string" ? new Date(v) : v)));
+            else if (def.arrayType.instance === "ObjectId") {
+                (0, path_ts_1.setPath)(doc, path, value.map((v) => (typeof v === "string" && object_id_ts_1.ObjectId.isValid(v) ? new object_id_ts_1.ObjectId(v) : v)));
+            }
+        }
+    }
+    return doc;
+}
+/** Inverse of hydrate: typed values become their JSON forms for storage and the wire. */
+function serialise(doc) {
+    if (doc === null || typeof doc !== "object")
+        return doc;
+    const out = {};
+    for (const [key, value] of Object.entries(doc)) {
+        out[key] = serialiseValue(value);
+    }
+    return out;
+}
+function serialiseValue(value) {
+    if (value instanceof object_id_ts_1.ObjectId)
+        return value.toHexString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(serialiseValue);
+    if (value !== null && typeof value === "object" && !(value instanceof Uint8Array)) {
+        return serialise(value);
+    }
+    return value;
+}
+function normaliseId(id) {
+    if (id instanceof object_id_ts_1.ObjectId)
+        return id.toHexString();
+    if (typeof id === "string")
+        return id;
+    if (id && typeof id.toHexString === "function") {
+        return id.toHexString();
+    }
+    return String(id);
+}
+/** Mongoose's collection naming: lowercase and pluralise the model name. */
+function pluralize(name) {
+    const lower = name.toLowerCase();
+    if (/(s|x|z|ch|sh)$/.test(lower))
+        return `${lower}es`;
+    if (/[^aeiou]y$/.test(lower))
+        return `${lower.slice(0, -1)}ies`;
+    return `${lower}s`;
+}
+//# sourceMappingURL=model.js.map