@bhooai/nexus-data 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# @bhooai/nexus-data
+
+A from-scratch ODM built on the official `mongodb` driver (no mongoose).
+
+## Exports
+
+- `connect(uri, options)` / `getConnection()` — single connection + `ConnectionManager`.
+- `model<T>(name, schema, { collection })` — registers a model on the default connection.
+- `NexusSchema` (alias `Schema`) with field options: `{ type, required, default, enum,
+  min, max, match, validate, ref, refPath, select, immutable, expires, index, unique, transform }`.
+- `Model` — `find/findOne/findById/create/insertMany/updateOne/updateMany/
+  deleteOne/deleteMany/countDocuments/aggregate/bulkWrite/findOneAndUpdate`.
+- `DocumentInstance` — `save/remove/populate/validate` (+ `toObject()`).
+- `Query` — chainable + thenable: `where/gt/sort/limit/skip/select/populate/lean/session`.
+- `transaction(fn)` — driver `withTransaction`.
+- `pre`/`post` hooks for `save/validate/remove/updateOne/deleteOne/find`.
+- Batched multi-level `populate` (with `refPath`/`select`/`match`); auto-index creation at boot.
+
+## Usage
+
+```ts
+import { connect, model, Schema } from '@bhooai/nexus-data';
+
+connect('mongodb://localhost:27017/app');
+const User = model('User', new Schema({
+  email: { type: String, required: true, unique: true },
+  roles: { type: [String], default: ['user'] },
+}));
+const u = await User.findOne({ email: 'a@b.com' }).lean();
+```
+
+Tests run against real MongoDB via `.env` (`NEXUS_DB_URI`) — no embedded Mongo.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@bhooai/nexus-data",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "mongodb": "^6.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/connection/Connection.ts

@@ -0,0 +1,57 @@
+import { MongoClient, Db, type MongoClientOptions } from 'mongodb';
+import { NexusSchema } from '../schema/Schema.js';
+import { Model } from '../model/Model.js';
+import type { DocumentInstance } from '../model/Document.js';
+
+export interface ConnectOptions extends MongoClientOptions {
+  /** Database name override (otherwise taken from the URI). */
+  name?: string;
+  /** Auto-create indexes declared in schemas on connect. */
+  autoIndex?: boolean;
+}
+
+/**
+ * Wraps a `MongoClient` and lazily exposes a `Db`. Models are registered per
+ * connection. The default connection is created by the top-level `connect()`.
+ */
+export class Connection {
+  client: MongoClient;
+  dbPromise: Promise<Db>;
+  models = new Map<string, Model<any>>();
+  private dbName?: string;
+  autoIndex: boolean;
+
+  constructor(uri: string, options: ConnectOptions = {}) {
+    this.dbName = options.name;
+    this.autoIndex = options.autoIndex ?? true;
+    // Strip ODM-only options before handing the rest to the mongo driver.
+    const { name: _name, autoIndex: _autoIndex, ...driverOptions } = options;
+    this.client = new MongoClient(uri, driverOptions);
+    this.dbPromise = this.client.connect().then(() => this.client.db(this.dbName));
+  }
+
+  get db(): Promise<Db> {
+    return this.dbPromise;
+  }
+
+  /** Register a model on this connection and (optionally) create indexes. */
+  model<T extends DocumentInstance>(name: string, schema: NexusSchema, options: { collection?: string } = {}): Model<T> {
+    const existing = this.models.get(name);
+    if (existing) return existing as Model<T>;
+    const collectionName = options.collection ?? schema.options.collection ?? name.toLowerCase() + 's';
+    const model = new Model<T>(name, schema, this, collectionName);
+    this.models.set(name, model);
+    if (this.autoIndex) void model.createIndexes();
+    return model;
+  }
+
+  /** Start a session for transactions. */
+  async startSession() {
+    await this.dbPromise;
+    return this.client.startSession();
+  }
+
+  async close(): Promise<void> {
+    await this.client.close();
+  }
+}

package/src/connection/ConnectionManager.ts

@@ -0,0 +1,37 @@
+import { Connection, type ConnectOptions } from './Connection.js';
+
+/**
+ * Manages multiple named connections (e.g. a primary app DB plus an analytics
+ * DB). The default connection is registered under the name `'default'` and is
+ * what the top-level `connect()`/`model()` helpers use.
+ */
+export class ConnectionManager {
+  private connections = new Map<string, Connection>();
+
+  connect(name: string, uri: string, options: ConnectOptions = {}): Connection {
+    const existing = this.connections.get(name);
+    if (existing) return existing;
+    const conn = new Connection(uri, options);
+    this.connections.set(name, conn);
+    return conn;
+  }
+
+  get(name = 'default'): Connection {
+    const conn = this.connections.get(name);
+    if (!conn) throw new Error(`Connection '${name}' is not registered.`);
+    return conn;
+  }
+
+  has(name: string): boolean {
+    return this.connections.has(name);
+  }
+
+  /** Close all managed connections. */
+  async closeAll(): Promise<void> {
+    await Promise.all([...this.connections.values()].map((c) => c.close()));
+    this.connections.clear();
+  }
+}
+
+/** A process-wide connection manager for multi-DB setups. */
+export const connectionManager = new ConnectionManager();

package/src/errors.ts

@@ -0,0 +1,17 @@
+import { ValidationError as CoreValidationError } from '../../nexus-core/src/index.js';
+
+export { CoreValidationError as ValidationError };
+
+export class DocumentNotFoundError extends Error {
+  constructor(message = 'No document found') {
+    super(message);
+    this.name = 'DocumentNotFoundError';
+  }
+}
+
+export class VersionError extends Error {
+  constructor(message = 'Document version mismatch') {
+    super(message);
+    this.name = 'VersionError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+import { Connection, type ConnectOptions } from './connection/Connection.js';
+import { NexusSchema } from './schema/Schema.js';
+import { Model } from './model/Model.js';
+import type { DocumentInstance } from './model/Document.js';
+
+export * from './schema/SchemaType.js';
+export * from './schema/validators.js';
+export { NexusSchema as Schema } from './schema/Schema.js';
+export { Model } from './model/Model.js';
+export { DocumentInstance } from './model/Document.js';
+export { Query } from './query/Query.js';
+export { Connection } from './connection/Connection.js';
+export { ConnectionManager, connectionManager } from './connection/ConnectionManager.js';
+export * from './errors.js';
+export {
+  PROJECT_INFO_DB,
+  sanitizeDbName,
+  resolveProjectInfo,
+  connectProjectInfo,
+  getProjectInfoCollection,
+  upsertProjectInfo,
+  listProjectInfo,
+  getProjectInfo,
+  deleteProjectInfo,
+  dropProjectDatabase,
+  closeProjectInfo,
+  type ProjectInfo,
+  type ClusterNodeRecord,
+  getClusterNodesCollection,
+  upsertClusterNode,
+  deleteClusterNode,
+  listClusterNodes,
+  syncClusterNodes,
+} from './projects.js';
+
+let defaultConnection: Connection | undefined;
+
+/** Connect to MongoDB and establish the default connection. */
+export function connect(uri: string, options: ConnectOptions = {}): Connection {
+  defaultConnection = new Connection(uri, options);
+  return defaultConnection;
+}
+
+/** The default connection (set by `connect`). */
+export function getConnection(): Connection {
+  if (!defaultConnection) throw new Error('Not connected — call connect(uri) first.');
+  return defaultConnection;
+}
+
+/** Register a model on the default connection. */
+export function model<T extends DocumentInstance>(name: string, schema: NexusSchema, options?: { collection?: string }): Model<T> {
+  return getConnection().model<T>(name, schema, options);
+}
+
+/** Run a transaction on the default connection. */
+export async function transaction<T>(fn: (session: import('mongodb').ClientSession) => Promise<T>): Promise<T> {
+  const conn = getConnection();
+  const session = await conn.startSession();
+  try {
+    return await session.withTransaction(() => fn(session));
+  } finally {
+    await session.endSession();
+  }
+}
+
+export { ObjectId, Decimal128 } from 'mongodb';

package/src/model/Document.ts

@@ -0,0 +1,126 @@
+import type { NexusSchema } from '../schema/Schema.js';
+import type { Model } from './Model.js';
+import type { ObjectId } from 'mongodb';
+
+/** A hydrated document instance wrapping a plain Mongo object. */
+export class DocumentInstance {
+  _doc: Record<string, unknown> = {};
+  _schema: NexusSchema;
+  _model: Model<this>;
+  _isNew = true;
+  _modified = new Set<string>();
+
+  constructor(schema: NexusSchema, model: Model<DocumentInstance>, data: Record<string, unknown>, isNew = true) {
+    this._schema = schema;
+    this._model = model as Model<this>;
+    this._isNew = isNew;
+    this._doc = { ...data };
+    // New documents consider all initial fields modified (matches mongoose isNew semantics),
+    // so pre('save') hooks using isModified() fire for first inserts.
+    if (isNew) for (const k of Object.keys(this._doc)) this._modified.add(k);
+
+    // Proxy property access to _doc so `doc.email` reads/writes the stored value.
+    return new Proxy(this, {
+      get(target, prop: string) {
+        if (prop in target || typeof prop !== 'string') return (target as unknown as Record<string, unknown>)[prop];
+        return target._doc[prop];
+      },
+      set(target, prop: string, value: unknown) {
+        if (prop in target && typeof (target as unknown as Record<string, unknown>)[prop] !== 'undefined' && prop.startsWith('_')) {
+          (target as unknown as Record<string, unknown>)[prop] = value;
+          return true;
+        }
+        if (prop === '_doc' || prop.startsWith('_')) {
+          (target as unknown as Record<string, unknown>)[prop] = value;
+          return true;
+        }
+        target._doc[prop] = value;
+        target._modified.add(prop);
+        return true;
+      },
+    });
+  }
+
+  isModified(path?: string): boolean {
+    if (path) return this._modified.has(path);
+    return this._modified.size > 0;
+  }
+
+  toObject(): Record<string, unknown> {
+    const out = { ...this._doc };
+    // Apply virtual getters (bound to the instance so they can read other fields).
+    for (const [name, virt] of this._schema.virtuals) {
+      if (virt.get) {
+        try { out[name] = virt.get.call(this); } catch { /* virtual getters must not break serialization */ }
+      }
+    }
+    return out;
+  }
+
+  toJSON(): Record<string, unknown> {
+    return this.toObject();
+  }
+
+  async validate(): Promise<void> {
+    await runHooks(this._schema.preHooks, 'validate', this);
+    this._schema.validate(this._doc);
+    await runHooks(this._schema.postHooks, 'validate', this);
+  }
+
+  async populate(path: string): Promise<this> {
+    const { populate } = await import('../populate/populate.js');
+    await populate(this._model.connection, [this], path);
+    return this;
+  }
+
+  async save(): Promise<this> {
+    await runHooks(this._schema.preHooks, 'save', this);
+    if (this._schema.options.timestamps) {
+      const now = new Date();
+      const ts = this._schema.options.timestamps === true ? { createdAt: 'createdAt', updatedAt: 'updatedAt' } : this._schema.options.timestamps;
+      if (ts?.createdAt && this._isNew) this._doc[ts.createdAt] = now;
+      if (ts?.updatedAt) this._doc[ts.updatedAt] = now;
+    }
+    if (this._isNew) {
+      this._schema.applyDefaults(this._doc);
+      await this.validate();
+      const result = await this._model.collection.then((c) => c.insertOne(this._doc));
+      if (result.acknowledged) this._doc._id = result.insertedId;
+      this._isNew = false;
+    } else {
+      await this.validate();
+      const update = this._modified.size ? this._buildUpdate() : { $set: this._doc };
+      await this._model.collection.then((c) => c.updateOne({ _id: this._doc._id as ObjectId }, update));
+    }
+    this._modified.clear();
+    await runHooks(this._schema.postHooks, 'save', this);
+    return this;
+  }
+
+  async remove(): Promise<void> {
+    await runHooks(this._schema.preHooks, 'remove', this);
+    await this._model.collection.then((c) => c.deleteOne({ _id: this._doc._id as ObjectId }));
+    await runHooks(this._schema.postHooks, 'remove', this);
+  }
+
+  private _buildUpdate(): Record<string, unknown> {
+    const $set: Record<string, unknown> = {};
+    for (const path of this._modified) {
+      // Immutable fields cannot be written after the initial insert.
+      const field = this._schema.compiledPaths.get(path);
+      if (field?.immutable && !this._isNew) continue;
+      $set[path] = this._doc[path];
+    }
+    return { $set };
+  }
+}
+
+async function runHooks(
+  hooks: Map<string, Array<(ctx: unknown) => unknown | Promise<unknown>>>,
+  event: string,
+  ctx: unknown,
+): Promise<void> {
+  const list = hooks.get(event);
+  if (!list) return;
+  for (const fn of list) await fn.call(ctx, ctx);
+}

package/src/model/Model.ts

@@ -0,0 +1,189 @@
+import type { Collection, Db } from 'mongodb';
+import { ObjectId } from 'mongodb';
+import { NexusSchema } from '../schema/Schema.js';
+import { Connection } from '../connection/Connection.js';
+import { DocumentInstance } from './Document.js';
+import { hydrate } from './hydrate.js';
+import { Query } from '../query/Query.js';
+
+/** Build a NEW (not-yet-persisted) document instance from input data. */
+export function newInstance<T extends DocumentInstance>(
+  schema: NexusSchema,
+  model: Model<T>,
+  data: Record<string, unknown>,
+): T {
+  return new DocumentInstance(schema, model, data, true) as T;
+}
+
+export class Model<T extends DocumentInstance> {
+  collection: Promise<Collection>;
+  schema: NexusSchema;
+  connection: Connection;
+  collectionName: string;
+  name: string;
+
+  constructor(name: string, schema: NexusSchema, connection: Connection, collectionName: string) {
+    this.name = name;
+    this.schema = schema;
+    this.connection = connection;
+    this.collectionName = collectionName;
+    this.collection = connection.db.then((db: Db) => db.collection(collectionName));
+
+    // Attach static methods declared on the schema.
+    for (const [key, fn] of Object.entries(schema.statics)) {
+      (this as unknown as Record<string, unknown>)[key] = fn.bind(this);
+    }
+  }
+
+  /** Hydrate a raw mongo doc into a Document instance. */
+  hydrate(doc: Record<string, unknown>): T {
+    return hydrate<T>(this.schema, this, doc) as T;
+  }
+
+  // ── Query builders ──────────────────────────────────────────────────────
+  find(filter: Record<string, unknown> = {}): Query<T> {
+    return new Query<T>(this, 'find', castFilterId(filter));
+  }
+
+  findOne(filter: Record<string, unknown> = {}): Query<T> {
+    return new Query<T>(this, 'findOne', castFilterId(filter));
+  }
+
+  findById(id: unknown): Query<T> {
+    return new Query<T>(this, 'findOne', { _id: castId(id) });
+  }
+
+  // ── Writes ──────────────────────────────────────────────────────────────
+  async create(docs: Record<string, unknown> | Record<string, unknown>[]): Promise<T[]> {
+    const input = Array.isArray(docs) ? docs : [docs];
+    const out: T[] = [];
+    for (const data of input) {
+      const instance = newInstance(this.schema, this, data);
+      await instance.save();
+      out.push(instance);
+    }
+    return out;
+  }
+
+  async insertMany(docs: Record<string, unknown>[]): Promise<T[]> {
+    const prepared = docs.map((d) => {
+      const copy = { ...d };
+      this.schema.applyDefaults(copy);
+      this.schema.validate(copy);
+      return copy;
+    });
+    const coll = await this.collection;
+    const result = await coll.insertMany(prepared);
+    return prepared.map((d, i) => {
+      d._id = result.insertedIds[i];
+      return this.hydrate(d);
+    });
+  }
+
+  async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<number> {
+    await runSchemaHooks(this.schema, 'updateOne', { filter, update, model: this });
+    const coll = await this.collection;
+    const result = await coll.updateOne(castFilterId(filter), update);
+    return result.modifiedCount;
+  }
+
+  async updateMany(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<number> {
+    const coll = await this.collection;
+    const result = await coll.updateMany(castFilterId(filter), update);
+    return result.modifiedCount;
+  }
+
+  async deleteOne(filter: Record<string, unknown>): Promise<number> {
+    const coll = await this.collection;
+    const result = await coll.deleteOne(castFilterId(filter));
+    return result.deletedCount;
+  }
+
+  async deleteMany(filter: Record<string, unknown>): Promise<number> {
+    await runSchemaHooks(this.schema, 'deleteMany', { filter, model: this });
+    const coll = await this.collection;
+    const result = await coll.deleteMany(castFilterId(filter));
+    return result.deletedCount;
+  }
+
+  /** Find a doc and apply an update in one round-trip; returns the updated (or original) hydrated doc. */
+  async findOneAndUpdate(
+    filter: Record<string, unknown>,
+    update: Record<string, unknown>,
+    opts: { returnDocument?: 'before' | 'after'; upsert?: boolean } = {},
+  ): Promise<T | null> {
+    const coll = await this.collection;
+    const result = await coll.findOneAndUpdate(castFilterId(filter), update, {
+      returnDocument: opts.returnDocument === 'before' ? 'before' : 'after',
+      upsert: opts.upsert ?? false,
+      includeResultMetadata: true,
+    });
+    if (!result || !result.value) return null;
+    return this.hydrate(result.value as Record<string, unknown>);
+  }
+
+  /** Find a doc and remove it; returns the deleted hydrated doc (or null). */
+  async findOneAndDelete(filter: Record<string, unknown>): Promise<T | null> {
+    const coll = await this.collection;
+    const result = await coll.findOneAndDelete(castFilterId(filter), { includeResultMetadata: true });
+    if (!result || !result.value) return null;
+    return this.hydrate(result.value as Record<string, unknown>);
+  }
+
+  /** Run a bulk write of mixed operations; returns the driver result summary. */
+  async bulkWrite(ops: Record<string, unknown>[]): Promise<{ insertedCount: number; modifiedCount: number; deletedCount: number }> {
+    const coll = await this.collection;
+    const result = await coll.bulkWrite(ops as never);
+    return {
+      insertedCount: result.insertedCount,
+      modifiedCount: result.modifiedCount,
+      deletedCount: result.deletedCount,
+    };
+  }
+
+  async countDocuments(filter: Record<string, unknown> = {}): Promise<number> {
+    const coll = await this.collection;
+    return coll.countDocuments(filter);
+  }
+
+  async aggregate(pipeline: Record<string, unknown>[]): Promise<unknown[]> {
+    const coll = await this.collection;
+    return coll.aggregate(pipeline).toArray();
+  }
+
+  /** Create indexes declared in the schema. Called automatically on connect. */
+  async createIndexes(): Promise<void> {
+    if (this.schema.indexes.length === 0) return;
+    const coll = await this.collection;
+    for (const { spec, options } of this.schema.indexes) {
+      await coll.createIndex(spec, options);
+    }
+  }
+}
+
+/** Run pre/post hooks for a write event on a schema (best-effort, used by updateOne/deleteMany). */
+async function runSchemaHooks(schema: NexusSchema, event: string, ctx: Record<string, unknown>): Promise<void> {
+  const pre = schema.preHooks.get(event);
+  if (pre) for (const fn of pre) await fn.call(ctx, ctx);
+  const post = schema.postHooks.get(event);
+  if (post) for (const fn of post) await fn.call(ctx, ctx);
+}
+
+/** Cast a 24-char hex string (or any ObjectId-like) to ObjectId; pass through otherwise. */
+export function castId(id: unknown): unknown {
+  if (id instanceof ObjectId) return id;
+  if (typeof id === 'string' && /^[0-9a-fA-F]{24}$/.test(id)) return new ObjectId(id);
+  return id;
+}
+
+/** Cast a top-level scalar `_id` in a filter (Mongoose-style); leaves operator/array filters untouched. */
+function castFilterId(filter: Record<string, unknown>): Record<string, unknown> {
+  if (filter && typeof filter === 'object' && '_id' in filter) {
+    const v = filter._id;
+    if (typeof v === 'string' || v instanceof ObjectId) {
+      const cast = castId(v);
+      if (cast !== v) filter._id = cast;
+    }
+  }
+  return filter;
+}

package/src/model/hydrate.ts

@@ -0,0 +1,12 @@
+import type { NexusSchema } from '../schema/Schema.js';
+import type { Model } from './Model.js';
+import { DocumentInstance } from './Document.js';
+
+/** Build a Document instance from a raw Mongo doc (not new). */
+export function hydrate<T extends DocumentInstance>(
+  schema: NexusSchema,
+  model: Model<T>,
+  doc: Record<string, unknown>,
+): T {
+  return new DocumentInstance(schema, model, doc, false) as T;
+}

package/src/populate/populate.ts

@@ -0,0 +1,114 @@
+import type { Connection } from '../connection/Connection.js';
+import { DocumentInstance } from '../model/Document.js';
+import type { ObjectId } from 'mongodb';
+
+interface PopulatePath {
+  path: string;
+  select?: string;
+  match?: Record<string, unknown>;
+}
+
+/**
+ * Resolve `ref` fields across documents in batched lookups (one query per
+ * path, not one per document). Supports nested paths ("a.b"), array refs, and
+ * `refPath` (dynamic model per document). Populated docs are hydrated and
+ * assigned back onto the parent.
+ */
+export async function populate(
+  connection: Connection,
+  docs: DocumentInstance[],
+  paths: string | PopulatePath[],
+): Promise<void> {
+  if (docs.length === 0) return;
+  const list = typeof paths === 'string' ? [{ path: paths }] : paths;
+  for (const p of list) await populateOne(connection, docs, p);
+}
+
+async function populateOne(
+  connection: Connection,
+  docs: DocumentInstance[],
+  p: PopulatePath,
+): Promise<void> {
+  const segments = p.path.split('.');
+  const head = segments[0]!;
+  const rest = segments.slice(1).join('.');
+
+  // Determine the ref model for this path. The field may use a static `ref`
+  // (found on the schema of any doc) or a dynamic `refPath`.
+  const sampleField = docs[0]?._schema.compiledPaths.get(head);
+  if (!sampleField || (!sampleField.ref && !sampleField.refPath)) {
+    throw new Error(`Path \`${head}\` is not a reference and cannot be populated.`);
+  }
+
+  // Collect ids (supporting arrays of refs).
+  const ids = new Set<unknown>();
+  for (const doc of docs) {
+    const value = doc._doc[head];
+    if (Array.isArray(value)) for (const v of value) ids.add(v);
+    else if (value !== undefined && value !== null) ids.add(value);
+  }
+  if (ids.size === 0) return;
+
+  // Group docs by target model name (for refPath) and resolve each group.
+  const byModel = new Map<string, { model: string; ids: Set<unknown> }>();
+  for (const doc of docs) {
+    const field = doc._schema.compiledPaths.get(head)!;
+    const modelName = field.refPath ? String(doc._doc[field.refPath]) : field.ref!;
+    const entry = byModel.get(modelName) ?? { model: modelName, ids: new Set() };
+    const value = doc._doc[head];
+    if (Array.isArray(value)) for (const v of value) entry.ids.add(v);
+    else if (value !== undefined && value !== null) entry.ids.add(value);
+    byModel.set(modelName, entry);
+  }
+
+  for (const { model: modelName, ids: modelIds } of byModel.values()) {
+    const targetModel = connection.models.get(modelName);
+    if (!targetModel) throw new Error(`Model \`${modelName}\` is not registered.`);
+    const projection = p.select ? buildProjection(p.select) : undefined;
+    const found = await targetModel.collection.then((c) =>
+       c.find({ _id: { $in: [...modelIds] as ObjectId[] }, ...(p.match ?? {}) }, projection ? { projection } : {}).toArray(),
+    );
+    const byId = new Map(found.map((d) => [String(d._id), d]));
+
+    for (const doc of docs) {
+      const field = doc._schema.compiledPaths.get(head)!;
+      const targetName = field.refPath ? String(doc._doc[field.refPath]) : field.ref!;
+      if (targetName !== modelName) continue;
+      const value = doc._doc[head];
+      if (Array.isArray(value)) {
+        doc._doc[head] = value.map((id) => byId.get(String(id)) ?? id).filter((v) => v !== undefined);
+        for (const child of doc._doc[head] as unknown[]) {
+          if (child && typeof child === 'object' && '_doc' in (child as object)) continue;
+        }
+        // hydrate populated children
+        doc._doc[head] = (doc._doc[head] as unknown[]).map((raw) =>
+          raw && typeof raw === 'object' && !('_doc' in raw) ? targetModel.hydrate(raw as Record<string, unknown>) : raw,
+        );
+      } else {
+        const raw = byId.get(String(value));
+        if (raw) doc._doc[head] = targetModel.hydrate(raw);
+      }
+    }
+  }
+
+  // Recurse into nested populate paths.
+  if (rest) {
+    const children: DocumentInstance[] = [];
+    for (const doc of docs) {
+      const value = doc._doc[head];
+      if (Array.isArray(value)) for (const v of value) if (v instanceof DocumentInstance) children.push(v);
+      else if (value instanceof DocumentInstance) children.push(value);
+    }
+    if (children.length) await populateOne(connection, children, { path: rest, select: p.select, match: p.match });
+  }
+}
+
+function buildProjection(select: string): Record<string, 0 | 1> {
+  const proj: Record<string, 0 | 1> = {};
+  for (const part of select.split(' ')) {
+    if (!part) continue;
+    const exclude = part.startsWith('-');
+    proj[exclude ? part.slice(1) : part] = exclude ? 0 : 1;
+  }
+  return proj;
+}