mongoose-killer 0.1.0

package/dist/esm/Query.js

@@ -0,0 +1,434 @@
+import { runPopulate, normalizePopulateArg } from "./populate.js";
+import { castFilter } from "./castFilter.js";
+import { CastIdsConflictError } from "./CastIdsConflictError.js";
+export class Query {
+    model;
+    op;
+    filter;
+    update;
+    pipeline;
+    distinctField;
+    // Chained options. We accumulate them and push to the driver at exec.
+    _sort;
+    _limit;
+    _skip;
+    _select;
+    _hint;
+    _comment;
+    _session;
+    _readPref;
+    _populates = [];
+    _lean = false;
+    // Ordered log of cast-id overrides on this chain.
+    //   "on"  — user called .castIds()
+    //   "off" — user called .skipCastIds()
+    // Empty = neither was called; use model's autoCastIds default.
+    // Both present at exec time = conflict, resolve per policy.
+    _castIdsOps = [];
+    // Options bag set by entry verb (e.g. { new, upsert, returnDocument }).
+    // Stays mostly opaque — we forward what the driver understands.
+    opOptions;
+    // Memoize result so a Query (like mongoose) can be awaited / .then'd
+    // exactly once and re-runs throw the mongoose error string.
+    _executed = false;
+    _execPromise = null;
+    constructor(init) {
+        this.model = init.model;
+        this.op = init.op;
+        this.filter = init.filter;
+        this.update = init.update;
+        this.pipeline = init.pipeline ?? [];
+        this.distinctField = init.distinctField;
+        this.opOptions = init.options ?? {};
+    }
+    // ---- chain methods ------------------------------------------------
+    lean(on = true) {
+        this._lean = on;
+        return this;
+    }
+    sort(spec) {
+        this._sort = spec;
+        return this;
+    }
+    limit(n) {
+        this._limit = n;
+        return this;
+    }
+    skip(n) {
+        this._skip = n;
+        return this;
+    }
+    select(spec) {
+        // Mongoose accepts strings ("name -_id") and objects ({ name: 1 }).
+        // The driver only takes objects, so normalize.
+        this._select = typeof spec === "string" ? parseSelectString(spec) : spec;
+        return this;
+    }
+    hint(h) {
+        this._hint = h;
+        return this;
+    }
+    comment(c) {
+        this._comment = c;
+        return this;
+    }
+    session(s) {
+        this._session = s ?? undefined;
+        return this;
+    }
+    read(pref) {
+        this._readPref = pref;
+        return this;
+    }
+    // Force ObjectId auto-cast ON for this query, regardless of the
+    // constructor's `autoCastIds` setting. See README + SECURITY.md.
+    castIds() {
+        this._castIdsOps.push("on");
+        return this;
+    }
+    // Force ObjectId auto-cast OFF for this query, regardless of the
+    // constructor's `autoCastIds` setting.
+    skipCastIds() {
+        this._castIdsOps.push("off");
+        return this;
+    }
+    populate(arg) {
+        // Mongoose semantics: bare `.populate()` populates every ref in the
+        // schema. We mirror that by populating every path in the model's
+        // populates map.
+        if (arg === undefined) {
+            const allPaths = Object.keys(this.model.populates);
+            this._populates.push(...allPaths.map((path) => ({ path })));
+            return this;
+        }
+        const specs = normalizePopulateArg(arg);
+        this._populates.push(...specs);
+        return this;
+    }
+    where(field, value) {
+        // Mongoose-style .where('foo').equals(bar) / .where('foo', bar).
+        // Inventory shows minimal usage; just support the two-arg form
+        // and merge into filter.
+        this.filter = this.filter ?? {};
+        if (arguments.length === 2) {
+            this.filter[field] = value;
+        }
+        return this;
+    }
+    // Mongoose-style filter combinators. Merge into the existing filter
+    // exactly the way mongoose does — push onto the existing $or/$and
+    // array if one exists, else create it.
+    or(conditions) {
+        this.filter = this.filter ?? {};
+        this.filter.$or = [...(this.filter.$or ?? []), ...conditions];
+        return this;
+    }
+    and(conditions) {
+        this.filter = this.filter ?? {};
+        this.filter.$and = [...(this.filter.$and ?? []), ...conditions];
+        return this;
+    }
+    nor(conditions) {
+        this.filter = this.filter ?? {};
+        this.filter.$nor = [...(this.filter.$nor ?? []), ...conditions];
+        return this;
+    }
+    // Aggregate-only: matches mongoose's Query.option (loose passthrough).
+    option(o) {
+        this.opOptions = { ...this.opOptions, ...o };
+        return this;
+    }
+    // ---- thenable terminus ---------------------------------------------
+    exec() {
+        if (this._executed) {
+            // Match mongoose's actual behavior on re-execution.
+            return Promise.reject(new Error("Query was already executed: re-run not supported"));
+        }
+        this._executed = true;
+        this._execPromise = this.run();
+        return this._execPromise;
+    }
+    then(onResolve, onReject) {
+        return this.exec().then(onResolve, onReject);
+    }
+    catch(onReject) {
+        return this.exec().catch(onReject);
+    }
+    finally(onFinally) {
+        return this.exec().finally(onFinally);
+    }
+    // ---- dispatch ------------------------------------------------------
+    async run() {
+        switch (this.op) {
+            case "find":
+                return this.runFind();
+            case "findOne":
+                return this.runFindOne();
+            case "findOneAndUpdate":
+                return this.runFindOneAndUpdate();
+            case "findOneAndDelete":
+                return this.runFindOneAndDelete();
+            case "updateOne":
+                return this.runUpdate("updateOne");
+            case "updateMany":
+                return this.runUpdate("updateMany");
+            case "deleteOne":
+                return this.runDelete("deleteOne");
+            case "deleteMany":
+                return this.runDelete("deleteMany");
+            case "countDocuments":
+                return this.runCount();
+            case "distinct":
+                return this.runDistinct();
+            case "exists":
+                return this.runExists();
+            case "aggregate":
+                return this.runAggregate();
+        }
+    }
+    // Apply 24-hex-string → ObjectId coercion, IF the resolved
+    // per-query setting says we should. Done once per exec, at the
+    // boundary just before handing the filter to the driver.
+    //
+    // The cast is on by default for Mongoose parity (Mongoose does the
+    // same silently from the schema). Opt out globally with
+    // `autoCastIds: false`, or per-query with `.skipCastIds()` when the
+    // filter value happens to look like a hex id but isn't.
+    castedFilter() {
+        const filter = this.filter ?? {};
+        return this.resolveCastIds() ? castFilter(filter) : filter;
+    }
+    // Resolve the per-query cast-id setting:
+    //   0 calls of either                 → constructor default
+    //   only .castIds()  was called       → true
+    //   only .skipCastIds() was called    → false
+    //   both were called                  → consult conflict policy
+    resolveCastIds() {
+        const ops = this._castIdsOps;
+        const hasOn = ops.includes("on");
+        const hasOff = ops.includes("off");
+        if (!hasOn && !hasOff)
+            return this.model.autoCastIds;
+        if (hasOn && !hasOff)
+            return true;
+        if (!hasOn && hasOff)
+            return false;
+        // Conflict: both were called at least once.
+        switch (this.model.castIdsConflictPolicy) {
+            case "throw":
+                throw new CastIdsConflictError({
+                    castIdsCallCount: ops.filter((o) => o === "on").length,
+                    skipCastIdsCallCount: ops.filter((o) => o === "off").length,
+                });
+            case "firstWins":
+                return ops[0] === "on";
+            case "lastWins":
+                return ops[ops.length - 1] === "on";
+            case "defaultWins":
+                return this.model.autoCastIds;
+        }
+    }
+    findOptions() {
+        const o = {};
+        if (this._sort)
+            o.sort = this._sort;
+        if (this._limit !== undefined)
+            o.limit = this._limit;
+        if (this._skip !== undefined)
+            o.skip = this._skip;
+        if (this._select)
+            o.projection = this._select;
+        if (this._hint)
+            o.hint = this._hint;
+        if (this._comment)
+            o.comment = this._comment;
+        if (this._session)
+            o.session = this._session;
+        if (this._readPref)
+            o.readPreference = this._readPref;
+        return o;
+    }
+    writeOptions() {
+        const o = { ...this.opOptions };
+        if (this._hint)
+            o.hint = this._hint;
+        if (this._comment)
+            o.comment = this._comment;
+        if (this._session)
+            o.session = this._session;
+        return o;
+    }
+    async runFind() {
+        const cursor = this.model.collection.find(this.castedFilter(), this.findOptions());
+        let docs = await cursor.toArray();
+        if (this._populates.length) {
+            docs = await runPopulate(docs, this._populates, {
+                ownerModel: this.model,
+                session: this._session,
+            });
+        }
+        if (!this._lean)
+            docs.forEach(addIdVirtual);
+        return docs;
+    }
+    async runFindOne() {
+        const doc = await this.model.collection.findOne(this.castedFilter(), this.findOptions());
+        if (!doc)
+            return null;
+        if (this._populates.length) {
+            const [populated] = await runPopulate([doc], this._populates, {
+                ownerModel: this.model,
+                session: this._session,
+            });
+            if (!this._lean)
+                addIdVirtual(populated);
+            return populated;
+        }
+        if (!this._lean)
+            addIdVirtual(doc);
+        return doc;
+    }
+    async runFindOneAndUpdate() {
+        // Mongoose default: { new: false, upsert: false }, returns the doc
+        // (pre-update unless new: true). Driver default in modern driver is
+        // returnDocument: 'before' which matches mongoose. We only translate
+        // { new: true } → returnDocument: 'after'.
+        const o = this.writeOptions();
+        if (o.new === true)
+            o.returnDocument = "after";
+        delete o.new;
+        if (this._select)
+            o.projection = this._select;
+        if (this._sort)
+            o.sort = this._sort;
+        const res = await this.model.collection.findOneAndUpdate(this.castedFilter(), wrapInSetIfPlain(this.update), o);
+        // Driver returns the document directly (not { value }) in modern
+        // versions. Mongoose unwraps to the doc too.
+        const doc = res && typeof res === "object" && "value" in res
+            ? res.value
+            : res;
+        if (!doc)
+            return null;
+        if (this._populates.length) {
+            const [populated] = await runPopulate([doc], this._populates, {
+                ownerModel: this.model,
+                session: this._session,
+            });
+            if (!this._lean)
+                addIdVirtual(populated);
+            return populated;
+        }
+        if (!this._lean)
+            addIdVirtual(doc);
+        return doc;
+    }
+    async runFindOneAndDelete() {
+        const o = this.writeOptions();
+        if (this._select)
+            o.projection = this._select;
+        if (this._sort)
+            o.sort = this._sort;
+        const res = await this.model.collection.findOneAndDelete(this.castedFilter(), o);
+        const doc = res && typeof res === "object" && "value" in res
+            ? res.value
+            : res;
+        if (doc && !this._lean)
+            addIdVirtual(doc);
+        return doc;
+    }
+    async runUpdate(kind) {
+        return this.model.collection[kind](this.castedFilter(), wrapInSetIfPlain(this.update), this.writeOptions());
+    }
+    async runDelete(kind) {
+        return this.model.collection[kind](this.castedFilter(), this.writeOptions());
+    }
+    async runCount() {
+        return this.model.collection.countDocuments(this.castedFilter(), this.findOptions());
+    }
+    async runDistinct() {
+        return this.model.collection.distinct(this.distinctField, this.castedFilter(), this.findOptions());
+    }
+    async runExists() {
+        const doc = await this.model.collection.findOne(this.castedFilter(), {
+            projection: { _id: 1 },
+            session: this._session,
+        });
+        return doc ? { _id: doc._id } : null;
+    }
+    async runAggregate() {
+        const opts = {};
+        if (this._session)
+            opts.session = this._session;
+        if (this._hint)
+            opts.hint = this._hint;
+        if (this._comment)
+            opts.comment = this._comment;
+        if (this.opOptions.allowDiskUse)
+            opts.allowDiskUse = this.opOptions.allowDiskUse;
+        // Cast hex strings in $match stages — but only if auto-cast is
+        // resolved-on for this query, same gating as the top-level
+        // filter. Other stages may contain expressions, but only $match
+        // is a true "filter" position.
+        const castOn = this.resolveCastIds();
+        const pipeline = this.pipeline.map((stage) => {
+            if (castOn && stage && typeof stage === "object" && "$match" in stage) {
+                return { ...stage, $match: castFilter(stage.$match) };
+            }
+            return stage;
+        });
+        return this.model.collection.aggregate(pipeline, opts).toArray();
+    }
+}
+// Mongoose silently wraps a plain object update in `$set`. The native
+// driver requires atomic operators or a pipeline. Pipeline updates are
+// Mongoose hydrated docs expose `.id` as a getter that returns
+// `this._id.toString()`. Lean docs don't (they're plain objects with
+// just _id). We mirror that: every non-lean return path runs each
+// doc through addIdVirtual to attach a non-enumerable `id` getter.
+//
+// Non-enumerable so JSON.stringify / spread / Object.keys see the
+// same shape as a lean doc. Idempotent: skip if `id` is already an
+// own property (already set, already populated, doc came from
+// somewhere else).
+export const addIdVirtual = (doc) => {
+    if (!doc || typeof doc !== "object")
+        return;
+    if (Object.prototype.hasOwnProperty.call(doc, "id"))
+        return;
+    Object.defineProperty(doc, "id", {
+        get() {
+            // Mongoose's `.id` returns `null` when `_id` is missing (rather
+            // than `undefined`). Matching that exactly — drop-in compat.
+            return this._id == null ? null : this._id.toString();
+        },
+        enumerable: false,
+        configurable: true,
+    });
+};
+// arrays — pass through. Updates that already have at least one
+// top-level `$`-key go through. Anything else gets wrapped.
+const wrapInSetIfPlain = (update) => {
+    if (update == null)
+        return update;
+    if (Array.isArray(update))
+        return update;
+    if (typeof update !== "object")
+        return update;
+    const keys = Object.keys(update);
+    if (keys.length === 0)
+        return update;
+    const hasOperator = keys.some((k) => k.startsWith("$"));
+    if (hasOperator)
+        return update;
+    return { $set: update };
+};
+const parseSelectString = (s) => {
+    const out = {};
+    for (const tok of s.split(/\s+/).filter(Boolean)) {
+        if (tok.startsWith("-"))
+            out[tok.slice(1)] = 0;
+        else
+            out[tok] = 1;
+    }
+    return out;
+};

package/dist/esm/castFilter.js

@@ -0,0 +1,96 @@
+/**
+ * Auto-cast filter values that look like ObjectIds.
+ *
+ * Mongoose does this via schema knowledge ("this field is an ObjectId
+ * ref, so cast the string"). We don't have schemas, so we use the
+ * structurally atomic rule:
+ *
+ *   A 24-character hex string in a filter position is an ObjectId.
+ *
+ * This is the boundary where call sites stop having to remember to
+ * wrap with `new ObjectId(...)`. Without it, queries like
+ * `{ authorID: user.id }` silently match nothing because the stored
+ * value is an ObjectId but the filter is a string.
+ *
+ * Scope:
+ *   - Only the filter argument. Updates ($set/$push/$inc payloads) are
+ *     left alone — the user controls what gets written.
+ *   - Recursive into nested objects so $and/$or/$nor work, as do
+ *     positional operators like `{ items.0.ownerID: "..." }`.
+ *   - $in arrays: each element is cast individually.
+ *   - $regex / $text / $expr / $where / $jsonSchema / $where are
+ *     skipped — those operators take strings, not ObjectIds.
+ */
+import { ObjectId } from "bson";
+const HEX_24 = /^[a-f0-9]{24}$/i;
+// Operators whose values are intentional strings/expressions; never
+// cast their contents.
+const STRING_OPERATORS = new Set([
+    "$regex",
+    "$options",
+    "$text",
+    "$where",
+    "$expr",
+    "$jsonSchema",
+    "$comment",
+    "$search",
+    "$language",
+    "$caseSensitive",
+    "$diacriticSensitive",
+]);
+const isHex24 = (v) => typeof v === "string" && HEX_24.test(v);
+const toOidIfHex = (v) => (isHex24(v) ? new ObjectId(v) : v);
+export const castFilter = (filter) => {
+    if (filter == null)
+        return filter;
+    if (Array.isArray(filter))
+        return filter.map(castFilter);
+    if (typeof filter !== "object")
+        return filter;
+    // Leave ObjectId / Date / RegExp / etc. untouched.
+    if (isBsonLike(filter))
+        return filter;
+    const out = {};
+    for (const [key, value] of Object.entries(filter)) {
+        if (STRING_OPERATORS.has(key)) {
+            out[key] = value;
+            continue;
+        }
+        out[key] = castValue(value);
+    }
+    return out;
+};
+const castValue = (value) => {
+    if (isHex24(value))
+        return new ObjectId(value);
+    if (value == null)
+        return value;
+    if (Array.isArray(value))
+        return value.map(castValue);
+    if (typeof value !== "object")
+        return value;
+    if (isBsonLike(value))
+        return value;
+    // Object — could be an operator spec ({ $in: [...] }) or a nested
+    // subdocument. Either way, recurse with the same rules.
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (STRING_OPERATORS.has(k)) {
+            out[k] = v;
+            continue;
+        }
+        out[k] = castValue(v);
+    }
+    return out;
+};
+// True for values we should pass through untouched (ObjectId, Date,
+// Decimal128, Buffer, RegExp, etc.). Heuristic: non-plain objects.
+const isBsonLike = (v) => {
+    if (v instanceof Date)
+        return true;
+    if (v instanceof RegExp)
+        return true;
+    // bson types and similar — anything whose prototype isn't plain Object
+    const proto = Object.getPrototypeOf(v);
+    return proto !== Object.prototype && proto !== null;
+};

package/dist/esm/createGetModel.js

@@ -0,0 +1,43 @@
+import { Model } from "./Model.js";
+// Build a registry of Model instances keyed by name. The returned
+// getModel is the only thing call sites see; they never touch Model
+// directly.
+export const createGetModel = (opts) => {
+    const registry = new Map();
+    // collection name -> model name, so populate can resolve refs by
+    // collection (matches how the test fixtures express them).
+    const collectionToModelName = new Map();
+    for (const [name, collection] of Object.entries(opts.models)) {
+        collectionToModelName.set(collection, name);
+    }
+    const getModelByName = (name) => {
+        const m = registry.get(name);
+        if (!m)
+            throw new Error(`Unknown model: ${name}`);
+        return m;
+    };
+    // Resolve defaults once, here, so each Model gets a frozen copy.
+    // autoCastIds defaults to ON for Mongoose-parity — Mongoose silently
+    // coerces 24-char hex strings to ObjectId, and viper is a drop-in
+    // replacement. Set autoCastIds: false to opt out.
+    const autoCastIds = opts.autoCastIds !== false;
+    // Conflict resolution defaults to "throw" so .castIds() and
+    // .skipCastIds() colliding on the same query surfaces the bug
+    // instead of silently picking one.
+    const castIdsConflictPolicy = opts.castIdsConflictPolicy ?? "throw";
+    for (const [name, collection] of Object.entries(opts.models)) {
+        const populates = opts.populates?.[name];
+        const model = new Model({
+            name,
+            collection: opts.db.collection(collection),
+            db: opts.db,
+            populates: populates ?? {},
+            collectionToModelName,
+            getModelByName,
+            autoCastIds,
+            castIdsConflictPolicy,
+        });
+        registry.set(name, model);
+    }
+    return (name) => getModelByName(name);
+};

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+// Public surface. Just createGetModel — no Schema, no Types, no
+// connection management, no Model export. The caller wires up the
+// MongoClient + Db themselves and hands us the Db.
+//
+// See README.md for the full design rationale.
+export { createGetModel } from "./createGetModel.js";
+export { CastIdsConflictError } from "./CastIdsConflictError.js";

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}