mongoose-killer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Thayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# Viper
+
+In a fight of Mongoose vs. Viper, only 1 in 10 Vipers come out on top. This is the 10th Viper.
+
+Viper is a drop-in Mongoose replacement built for speed.
+
+Under the hood, it uses the native MongoDB driver without any fluff for optimal performance while maintaining the same convenient API as Mongoose.
+
+## Quickstart
+
+```bash
+npm install mongoose-killer mongodb
+```
+```ts
+import { createGetModel } from "mongoose-killer";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient(process.env.MONGO_URI!);
+await client.connect();
+const db = client.db("app");
+
+const getModel = createGetModel({
+  db,
+  models: {
+    User: "users",
+    Post: "posts",
+  },
+  populates: {
+    Post: {
+      authorID: { collection: "users" },
+    },
+  },
+});
+
+const User = getModel("User");
+const Post = getModel("Post");
+
+await User.create({ name: "Alice" });
+
+const posts = await Post.find({ published: true })
+  .populate("authorID")
+  .sort({ createdAt: -1 })
+  .limit(10)
+  .lean();
+```
+
+## What it is
+
+- **A `Model` API, not an ODM.** No schemas, no validation, no hooks,
+  no virtuals. The native MongoDB driver does the work; Viper just
+  exposes it through the chainable, thenable, `.populate()`-aware
+  interface mongoose users already think in.
+- **Drop-in equivalence is enforced.** The test suite runs every test
+  against real Mongoose *and* Viper, asserting identical results. If a
+  call shape isn't covered by `tests/`, assume it isn't supported.
+- **TypeScript-first.** Source is TS, types ship with the package, ESM
+  and CJS both work.
+
+## What it isn't
+
+- A general-purpose ODM. The supported surface is whatever the test
+  suite covers — see "What's supported" below.
+- A schema layer. Documents are plain objects in and out. If you want
+  validation, do it before you call Viper.
+
+## Installing
+
+```bash
+npm install mongoose-killer mongodb
+# or
+yarn add mongoose-killer mongodb
+```
+
+`mongodb` is a peer dependency — Viper doesn't bundle a driver, so the
+client and Viper agree on driver version.
+
+## What's supported
+
+- **Standard calls**: `find`, `findOne`, `findById`, `findOneAndUpdate`,
+  `findByIdAndUpdate`, `findOneAndDelete`, `findByIdAndDelete`,
+  `updateOne`, `updateMany`, `deleteOne`, `deleteMany`, `create`,
+  `insertMany`, `bulkWrite`, `aggregate`, `countDocuments`, `distinct`,
+  `exists`.
+- **Populate**: string path, object spec with `select`/`match`, nested,
+  array-of-refs (`tags._id`), array of specs, static
+  `Model.populate(docs, spec)`. Always `$in`-batched, never N+1.
+- **Method chaining**: `lean`, `sort`, `limit`, `skip`, `select`, `hint`,
+  `comment`, `session`, `read`, `populate`, `where`, `or`, `and`,
+  `nor`, `option`.
+- **Sessions & Transactions**: `{ session }` threads through every op for transactions.
+- **Thenable API**: `await`, `.then`, `.catch`, `.finally`, `.exec()`.
+
+## What's *not* supported
+
+- Schemas, virtuals, hooks (`pre`/`post`), getters, setters, casting,
+  validation, defaults.
+- `new Model(doc)` / `doc.save()`. Use `Model.create(doc)`.
+- Mongoose-specific connection/event API. You own the `MongoClient`
+  and pass us a `Db`.
+- Mongoose's `Types` namespace — import `ObjectId` / `Decimal128`
+  straight from `bson`.
+
+## Compatibility Features
+
+### ObjectId Auto-casting
+
+Like Mongoose, Viper automatically casts 24-char hex strings to
+`ObjectId` in filter positions. **On by default** for drop-in parity.
+
+Since Viper doesn't know your schemas, this cast is applied to *every*
+24-hex string in a filter, not just the ones that should be IDs. If
+you have a field that stores 24-character hex strings that aren't IDs, 
+this behavior will be incorrect for your use case.
+
+You can easily opt out of this behavior by changing the global default
+or overriding per query.
+
+
+```ts
+// Default — on
+const getModel = createGetModel({ db, models });
+const getModel = createGetModel({ db, models, autoCastIds: true }); // Same but explicit
+
+// Opt out globally
+const getModel = createGetModel({ db, models, autoCastIds: false });
+
+// Override per query
+await User.findOne({ _id: hexId }).castIds();           // force on
+await User.findOne({ slug: hexLookingSlug }).skipCastIds(); // force off
+```
+
+If both `.castIds()` and `.skipCastIds()` get called on the same query
+(probably a bug), Viper throws by default. You can change that via
+`castIdsConflictPolicy: 'firstWins' | 'lastWins' | 'defaultWins'`.
+
+### `.id` field
+
+Like Mongoose, Viper exposes `.id` on non-lean documents as the
+stringified `_id`.
+
+```ts
+const post = await Post.findOne({ slug: "hello-world" });
+// post._id is an ObjectId, post.id is its string form
+
+console.log(post._id);       // ObjectId("507f1f77bcf86cd799439011")
+console.log(post.id);        // "507f1f77bcf86cd799439011"
+```
+
+If a document has no `_id`, `.id` returns `null` (matching Mongoose).
+The `.id` field will not be detected by `JSON.stringify`,  `Object.keys` 
+and other similar functions, so you won't end up with an id field when
+storing in Redis, for example.
+
+`.lean()` returns plain driver objects with no `.id` virtual, also
+matching Mongoose.
+
+## TypeScript and ESM
+
+Both TypeScript and ESM import syntax are supported by default.
+
+
+## Running the tests
+
+Requires a local MongoDB at `mongodb://localhost:27017`
+
+With docker-compose like this:
+```docker-compose
+services:
+  mongo:
+    image: mongo:7
+    ports:
+      - "27017:27017"
+    ulimits:
+      nofile:
+        soft: 64000
+        hard: 64000
+```
+
+With docker like this:
+```bash
+docker run --ulimit nofile=64000:64000 -p 27017:27017 mongo:7
+```
+
+If using replica set mode, you will need to include directConnection=true
+
+Setting ulimits is required because the internal socket limit default is low and running the tests create a lot of sockets.
+
+
+```bash
+yarn test            # default — runs against Viper
+yarn test:real       # against real mongoose
+yarn test:both       # back-to-back; the drop-in proof
+yarn typecheck       # tsc --noEmit
+```
+
+## License
+
+MIT.

package/dist/cjs/CastIdsConflictError.d.ts

@@ -0,0 +1,11 @@
+export declare class CastIdsConflictError extends Error {
+    readonly name = "CastIdsConflictError";
+    readonly castIdsCallCount: number;
+    readonly skipCastIdsCallCount: number;
+    constructor(opts: {
+        castIdsCallCount: number;
+        skipCastIdsCallCount: number;
+    });
+    static is(err: unknown): err is CastIdsConflictError;
+}
+//# sourceMappingURL=CastIdsConflictError.d.ts.map

package/dist/cjs/CastIdsConflictError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CastIdsConflictError.d.ts","sourceRoot":"","sources":["../../src/CastIdsConflictError.ts"],"names":[],"mappings":"AASA,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,0BAA0B;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;gBAE1B,IAAI,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAA;KAAE;IAS5E,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,oBAAoB;CAMrD"}

package/dist/cjs/CastIdsConflictError.js

@@ -0,0 +1,27 @@
+"use strict";
+// Thrown at query exec time when a single Query has had both
+// `.castIds()` and `.skipCastIds()` called on it AND the configured
+// conflict policy is "throw".
+//
+// Exported as a named class so callers can do `instanceof` in error
+// handlers. The static `is(err)` helper is here for callers that
+// receive errors across module-boundaries (different bundles can
+// produce instanceof-incompatible classes with the same name).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CastIdsConflictError = void 0;
+class CastIdsConflictError extends Error {
+    name = "CastIdsConflictError";
+    castIdsCallCount;
+    skipCastIdsCallCount;
+    constructor(opts) {
+        super(`Conflicting calls on the same Query: ${opts.castIdsCallCount}× .castIds() and ${opts.skipCastIdsCallCount}× .skipCastIds(). ` +
+            `The configured castIdsConflictPolicy is "throw" — pass createGetModel({ castIdsConflictPolicy: "lastWins" | "firstWins" | "defaultWins" }) to resolve conflicts automatically, or remove one of the calls.`);
+        this.castIdsCallCount = opts.castIdsCallCount;
+        this.skipCastIdsCallCount = opts.skipCastIdsCallCount;
+    }
+    static is(err) {
+        return (err instanceof Error &&
+            err.name === "CastIdsConflictError");
+    }
+}
+exports.CastIdsConflictError = CastIdsConflictError;

package/dist/cjs/Model.d.ts

@@ -0,0 +1,51 @@
+import type { Collection, Db } from "mongodb";
+import { Query } from "./Query.js";
+import type { CastIdsConflictPolicy } from "./types.js";
+type ModelInit = {
+    name: string;
+    collection: Collection;
+    db: Db;
+    populates: Record<string, {
+        collection: string;
+    }>;
+    collectionToModelName: Map<string, string>;
+    getModelByName: (name: string) => any;
+    autoCastIds: boolean;
+    castIdsConflictPolicy: CastIdsConflictPolicy;
+};
+export declare class Model {
+    name: string;
+    collection: Collection;
+    populates: Record<string, {
+        collection: string;
+    }>;
+    collectionToModelName: Map<string, string>;
+    getModelByName: (name: string) => any;
+    autoCastIds: boolean;
+    castIdsConflictPolicy: CastIdsConflictPolicy;
+    db: {
+        db: Db;
+    };
+    constructor(init: ModelInit);
+    find(filter?: any, projection?: any, options?: any): Query;
+    findOne(filter?: any, projection?: any, options?: any): Query;
+    findById(id: any, projection?: any, options?: any): Query;
+    findOneAndUpdate(filter: any, update: any, options?: any): Query;
+    findByIdAndUpdate(id: any, update: any, options?: any): Query;
+    findOneAndDelete(filter: any, options?: any): Query;
+    findByIdAndDelete(id: any, options?: any): Query;
+    updateOne(filter: any, update: any, options?: any): Query;
+    updateMany(filter: any, update: any, options?: any): Query;
+    deleteOne(filter: any, options?: any): Query;
+    deleteMany(filter: any, options?: any): Query;
+    countDocuments(filter?: any, options?: any): Query;
+    distinct(field: string, filter?: any, options?: any): Query;
+    exists(filter: any, options?: any): Query;
+    aggregate(pipeline?: any[], options?: any): Query;
+    create(input: any, options?: any): Promise<any>;
+    insertMany(docs: any[], options?: any): Promise<any[]>;
+    bulkWrite(ops: any[], options?: any): Promise<any>;
+    populate(docs: any, arg: any): Promise<any>;
+}
+export {};
+//# sourceMappingURL=Model.d.ts.map

package/dist/cjs/Model.d.ts.map

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

package/dist/cjs/Model.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Model = void 0;
+const bson_1 = require("bson");
+const Query_js_1 = require("./Query.js");
+const populate_js_1 = require("./populate.js");
+// Mongoose `Model` is half class, half magic. We mimic the surface the
+// codebase actually uses (per inventory): the static entry verbs.
+// Instances are not a thing — call sites never `new Model()`.
+class Model {
+    name;
+    collection;
+    populates;
+    collectionToModelName;
+    getModelByName;
+    autoCastIds;
+    castIdsConflictPolicy;
+    // Mongoose exposes Model.db as a Connection-like object, and
+    // Connection.db is the native Db handle. Some libraries reach
+    // through `Model.db.db` to grab the native Db and issue a raw
+    // `db.collection(name).findOne({})` — bypassing the ODM (often
+    // to avoid lossy type handling like mongoose's historical
+    // Decimal128 quirks).
+    //
+    // We mimic that two-hop shape: `model.db` is a wrapper object whose
+    // `.db` is the native Db. Anything else hanging off Connection is
+    // not currently used by any call site, so we leave it unset.
+    db;
+    constructor(init) {
+        this.name = init.name;
+        this.collection = init.collection;
+        this.populates = init.populates;
+        this.collectionToModelName = init.collectionToModelName;
+        this.getModelByName = init.getModelByName;
+        this.autoCastIds = init.autoCastIds;
+        this.castIdsConflictPolicy = init.castIdsConflictPolicy;
+        this.db = { db: init.db };
+    }
+    // ---- query entry verbs --------------------------------------------
+    find(filter = {}, projection, options) {
+        const q = new Query_js_1.Query({ model: this, op: "find", filter, options });
+        if (projection)
+            q.select(projection);
+        if (options?.sort)
+            q.sort(options.sort);
+        if (options?.limit !== undefined)
+            q.limit(options.limit);
+        if (options?.skip !== undefined)
+            q.skip(options.skip);
+        return q;
+    }
+    findOne(filter = {}, projection, options) {
+        const q = new Query_js_1.Query({ model: this, op: "findOne", filter, options });
+        if (projection)
+            q.select(projection);
+        return q;
+    }
+    findById(id, projection, options) {
+        return this.findOne({ _id: coerceId(id) }, projection, options);
+    }
+    findOneAndUpdate(filter, update, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "findOneAndUpdate",
+            filter,
+            update,
+            options,
+        });
+    }
+    findByIdAndUpdate(id, update, options) {
+        return this.findOneAndUpdate({ _id: coerceId(id) }, update, options);
+    }
+    findOneAndDelete(filter, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "findOneAndDelete",
+            filter,
+            options,
+        });
+    }
+    findByIdAndDelete(id, options) {
+        return this.findOneAndDelete({ _id: coerceId(id) }, options);
+    }
+    updateOne(filter, update, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "updateOne",
+            filter,
+            update,
+            options,
+        });
+    }
+    updateMany(filter, update, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "updateMany",
+            filter,
+            update,
+            options,
+        });
+    }
+    deleteOne(filter, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "deleteOne",
+            filter,
+            options,
+        });
+    }
+    deleteMany(filter, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "deleteMany",
+            filter,
+            options,
+        });
+    }
+    countDocuments(filter = {}, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "countDocuments",
+            filter,
+            options,
+        });
+    }
+    distinct(field, filter = {}, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "distinct",
+            filter,
+            distinctField: field,
+            options,
+        });
+    }
+    exists(filter, options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "exists",
+            filter,
+            options,
+        });
+    }
+    aggregate(pipeline = [], options) {
+        return new Query_js_1.Query({
+            model: this,
+            op: "aggregate",
+            pipeline,
+            options,
+        });
+    }
+    // ---- writes that aren't chains ------------------------------------
+    // Mongoose's create returns the inserted doc(s) with _id set.
+    // Inventory uses both forms: create(doc) and create([docs], options).
+    async create(input, options) {
+        if (Array.isArray(input)) {
+            const docs = input.map(prepInsert);
+            if (docs.length === 0)
+                return [];
+            await this.collection.insertMany(docs, options ?? {});
+            return docs;
+        }
+        const doc = prepInsert(input);
+        await this.collection.insertOne(doc, options ?? {});
+        return doc;
+    }
+    async insertMany(docs, options) {
+        const prepared = docs.map(prepInsert);
+        if (prepared.length === 0)
+            return [];
+        await this.collection.insertMany(prepared, options ?? {});
+        return prepared;
+    }
+    async bulkWrite(ops, options) {
+        return this.collection.bulkWrite(ops, options ?? {});
+    }
+    // Static populate: takes pre-fetched doc(s) and decorates them.
+    // Used in a handful of inventory sites for ad-hoc populate after
+    // a custom aggregation.
+    async populate(docs, arg) {
+        const isArr = Array.isArray(docs);
+        const arr = isArr ? docs : [docs];
+        if (arr.length === 0)
+            return docs;
+        const specs = (0, populate_js_1.normalizePopulateArg)(arg);
+        const populated = await (0, populate_js_1.runPopulate)(arr, specs, {
+            ownerModel: this,
+            session: undefined,
+        });
+        return isArr ? populated : populated[0];
+    }
+}
+exports.Model = Model;
+// Mongoose auto-assigns _id on insert; the driver does the same, but
+// only if _id is missing. We let the driver handle it — no work here.
+// Kept as a hook in case we ever need to deep-clone or strip Mongoose-
+// only fields.
+const prepInsert = (doc) => doc;
+const coerceId = (id) => {
+    if (id instanceof bson_1.ObjectId)
+        return id;
+    if (typeof id === "string" && /^[0-9a-fA-F]{24}$/.test(id)) {
+        return new bson_1.ObjectId(id);
+    }
+    return id;
+};

package/dist/cjs/Query.d.ts

@@ -0,0 +1,85 @@
+import type { Collection, ClientSession } from "mongodb";
+import type { CastIdsConflictPolicy } from "./types.js";
+type Op = "find" | "findOne" | "findOneAndUpdate" | "findOneAndDelete" | "updateOne" | "updateMany" | "deleteOne" | "deleteMany" | "countDocuments" | "distinct" | "exists" | "aggregate";
+type ModelLike = {
+    name: string;
+    collection: Collection;
+    populates: Record<string, {
+        collection: string;
+    }>;
+    collectionToModelName: Map<string, string>;
+    getModelByName: (name: string) => any;
+    autoCastIds: boolean;
+    castIdsConflictPolicy: CastIdsConflictPolicy;
+};
+type QueryInit = {
+    model: ModelLike;
+    op: Op;
+    filter?: any;
+    update?: any;
+    pipeline?: any[];
+    distinctField?: string;
+    options?: any;
+};
+export declare class Query implements PromiseLike<any> {
+    private model;
+    private op;
+    private filter;
+    private update;
+    private pipeline;
+    private distinctField;
+    private _sort;
+    private _limit;
+    private _skip;
+    private _select;
+    private _hint;
+    private _comment;
+    private _session;
+    private _readPref;
+    private _populates;
+    private _lean;
+    private _castIdsOps;
+    private opOptions;
+    private _executed;
+    private _execPromise;
+    constructor(init: QueryInit);
+    lean(on?: boolean): this;
+    sort(spec: any): this;
+    limit(n: number): this;
+    skip(n: number): this;
+    select(spec: any): this;
+    hint(h: any): this;
+    comment(c: string): this;
+    session(s: ClientSession | null | undefined): this;
+    read(pref: any): this;
+    castIds(): this;
+    skipCastIds(): this;
+    populate(arg?: any): this;
+    where(field: string, value?: any): this;
+    or(conditions: any[]): this;
+    and(conditions: any[]): this;
+    nor(conditions: any[]): this;
+    option(o: any): this;
+    exec(): Promise<any>;
+    then<TResolve = any, TReject = never>(onResolve?: ((v: any) => TResolve | PromiseLike<TResolve>) | null, onReject?: ((e: any) => TReject | PromiseLike<TReject>) | null): Promise<TResolve | TReject>;
+    catch<T = never>(onReject?: ((e: any) => T | PromiseLike<T>) | null): Promise<any | T>;
+    finally(onFinally?: (() => void) | null): Promise<any>;
+    private run;
+    private castedFilter;
+    private resolveCastIds;
+    private findOptions;
+    private writeOptions;
+    private runFind;
+    private runFindOne;
+    private runFindOneAndUpdate;
+    private runFindOneAndDelete;
+    private runUpdate;
+    private runDelete;
+    private runCount;
+    private runDistinct;
+    private runExists;
+    private runAggregate;
+}
+export declare const addIdVirtual: (doc: any) => void;
+export {};
+//# sourceMappingURL=Query.d.ts.map

package/dist/cjs/Query.d.ts.map

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