@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/common/persistence/mongo/mongo-packages.ts

@@ -0,0 +1,130 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+import type * as NestMongoose from '@nestjs/mongoose';
+import type * as Mongodb from 'mongodb';
+import type * as Mongoose from 'mongoose';
+
+import { callerDirectory } from '../../helpers/module-location.helper.js';
+
+/**
+ * MongoDB's libraries — `mongoose`, `@nestjs/mongoose` and `mongodb` — are OPTIONAL peers since 12.1.0: a project that
+ * keeps its data in PostgreSQL installs none of them. Every module of the core that needs one at runtime takes it from
+ * here instead of importing it, because a static import of a package that is not installed fails the moment the
+ * barrel is loaded — long before anything could say which feature wanted it.
+ *
+ * Loaded synchronously: `@Prop()` and `@Schema()` run while a model class is DEFINED, and a project's own model file
+ * calls `SchemaFactory.createForClass()` right after — the decorators of the core's base classes must have reached
+ * Mongoose's metadata storage by then. `createRequire()` from this file's location resolves the packages the way a
+ * static import of the core would (the package's own peers in npm mode, the project's dependencies in vendor mode),
+ * and Node hands `require()` and `import` the same module instance: `mongoose` and `mongodb` are CommonJS, and
+ * `@nestjs/mongoose` (ESM only) is loaded through `require(esm)`, which shares the ESM loader's cache.
+ *
+ * Import-free leaf apart from the location helper — `import type` only — so it can sit below every module that needs
+ * it without joining an import cycle.
+ */
+
+/** The three packages, when installed */
+export interface MongoPackages {
+  /** The MongoDB driver: the project's own `mongodb`, else the one Mongoose ships (`mongoose.mongo`) */
+  mongodb: typeof Mongodb;
+  mongoose: typeof Mongoose;
+  nestMongoose: typeof NestMongoose;
+}
+
+/** MongoDB support was needed, and its libraries are not installed */
+export class MongoPackagesMissingError extends Error {
+  override readonly name = 'MongoPackagesMissingError';
+}
+
+const PACKAGE_SPECIFIERS = ['mongoose', '@nestjs/mongoose'] as const;
+
+/** Resolves like a static import of this module would */
+const requireHere = createRequire(join(callerDirectory(), 'mongo-packages.js'));
+
+/** `undefined` until the first look, `null` when the packages are not installed */
+let cached: MongoPackages | null | undefined;
+
+/**
+ * The packages when installed, else `undefined`. Throws when only one of `mongoose` / `@nestjs/mongoose` is installed:
+ * that is a broken installation, not a choice, and guessing either way would hide it.
+ */
+export function optionalMongoPackages(): MongoPackages | undefined {
+  if (cached === undefined) {
+    cached = loadMongoPackages() ?? null;
+  }
+  return cached ?? undefined;
+}
+
+/**
+ * The packages, or a named error saying which feature needed them and what to install.
+ *
+ * @param feature what needs MongoDB, in the words of the configuration ("the `mongoose` configuration", "GridFS")
+ */
+export function requireMongoPackages(feature: string): MongoPackages {
+  const packages = optionalMongoPackages();
+  if (!packages) {
+    throw new MongoPackagesMissingError(
+      `${feature} needs MongoDB, and its libraries are not installed. They are optional peer dependencies of ` +
+        '@lenne.tech/nest-server since 12.1.0 — add them to the project: `pnpm add mongoose @nestjs/mongoose mongodb` ' +
+        '(the versions in the migration guide 12.0.x → 12.1.x).',
+    );
+  }
+  return packages;
+}
+
+/**
+ * Better-Auth's MongoDB adapter — imported only where Better-Auth keeps its data in MongoDB, because it loads the
+ * MongoDB driver as it is evaluated
+ */
+export function requireBetterAuthMongoAdapter(): (db: unknown) => unknown {
+  requireMongoPackages('Better-Auth on MongoDB (the user model is not routed to a SQL source)');
+  return (requireHere('better-auth/adapters/mongodb') as { mongodbAdapter: (db: unknown) => unknown }).mongodbAdapter;
+}
+
+/** Whether MongoDB's libraries are installed */
+export function hasMongoPackages(): boolean {
+  return !!optionalMongoPackages();
+}
+
+function loadMongoPackages(): MongoPackages | undefined {
+  const [mongoose, nestMongoose] = PACKAGE_SPECIFIERS.map((specifier) => optionalRequire(specifier));
+  if (!mongoose && !nestMongoose) {
+    return undefined;
+  }
+  if (!mongoose || !nestMongoose) {
+    const missing = mongoose ? '@nestjs/mongoose' : 'mongoose';
+    throw new MongoPackagesMissingError(
+      `MongoDB support needs both mongoose and @nestjs/mongoose; ${missing} is not installed. Install it, or remove ` +
+        'the other one if the project keeps no data in MongoDB.',
+    );
+  }
+  const mongodb = optionalRequire('mongodb') ?? (mongoose as typeof Mongoose).mongo;
+  return {
+    mongodb: mongodb as typeof Mongodb,
+    mongoose: mongoose as typeof Mongoose,
+    nestMongoose: nestMongoose as typeof NestMongoose,
+  };
+}
+
+/** The package, or `undefined` when it is not installed — any other loading error is a real one and propagates */
+function optionalRequire(specifier: string): unknown {
+  try {
+    return requireHere(specifier);
+  } catch (error) {
+    if (isNotInstalled(error, specifier)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/** A "module not found" for the package itself — not for something the package failed to load */
+function isNotInstalled(error: unknown, specifier: string): boolean {
+  const { code, message } = (error ?? {}) as { code?: string; message?: string };
+  return (
+    (code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND') &&
+    typeof message === 'string' &&
+    (message.includes(`'${specifier}'`) || message.includes(`"${specifier}"`))
+  );
+}

package/src/core/common/persistence/mongo/mongoose-compat.ts

@@ -0,0 +1,129 @@
+import { Inject } from '@nestjs/common';
+import type { Query } from 'mongoose';
+
+import { HexObjectId } from './hex-object-id.js';
+import {
+  DeclaredSchema,
+  declaredSchema,
+  markRaw,
+  recordModelDeclaration,
+  recordPropDeclaration,
+} from './model-declarations.js';
+import { optionalMongoPackages, requireMongoPackages } from './mongo-packages.js';
+
+/**
+ * The parts of `@nestjs/mongoose` and `mongoose` the core declares its models, injections and ids with — usable
+ * whether or not MongoDB's libraries are installed (`mongo-packages.ts`). Since 12.1.0 the same names are exported for
+ * projects: a model file that imports `Prop`, `Schema` and `SchemaFactory` from `@lenne.tech/nest-server` works on
+ * MongoDB and on PostgreSQL alike, and installs nothing of MongoDB's where it is not used.
+ *
+ * - The decorators always RECORD what they declare (`model-declarations.ts`): that record is where a model's
+ *   descriptor comes from when Mongoose is not there to build a schema. With Mongoose installed they also apply the
+ *   real decorator, at the moment the original would have run — so a project's own `SchemaFactory.createForClass()`
+ *   sees the core's fields exactly as before.
+ * - The injection tokens are computed here, identically to `@nestjs/mongoose` (pinned by
+ *   `tests/unit/mongoose-compat.spec.ts`): a token is a string, and a service of the core must be constructible in a
+ *   project that has no MongoDB at all.
+ */
+
+/** `@nestjs/mongoose`'s name for the default connection */
+export const DEFAULT_CONNECTION_NAME = 'DatabaseConnection';
+
+/** The DI token of a connection — `getConnectionToken()` of `@nestjs/mongoose` */
+export function getConnectionToken(name?: string): string {
+  return name && name !== DEFAULT_CONNECTION_NAME ? `${name}Connection` : DEFAULT_CONNECTION_NAME;
+}
+
+/** The DI token of a model — `getModelToken()` of `@nestjs/mongoose` */
+export function getModelToken(model: string, connectionName?: string): string {
+  return connectionName === undefined ? `${model}Model` : `${getConnectionToken(connectionName)}/${model}Model`;
+}
+
+/**
+ * `@InjectModel()` — the model's Mongoose model where MongoDB is installed, else a stand-in that refuses data access;
+ * either way bound to the model's data store, which a `CrudService` follows (`CorePersistenceModule.forFeature()`)
+ */
+export function InjectModel(model: string, connectionName?: string): ParameterDecorator & PropertyDecorator {
+  return Inject(getModelToken(model, connectionName));
+}
+
+/** `@InjectConnection()` — the Mongoose connection, `null` where no MongoDB is configured */
+export function InjectConnection(name?: string): ParameterDecorator & PropertyDecorator {
+  return Inject(getConnectionToken(name));
+}
+
+/** `@Schema()` of `@nestjs/mongoose` */
+export function Schema(options?: Record<string, any>): ClassDecorator {
+  return (target) => {
+    recordModelDeclaration(target, options);
+    optionalMongoPackages()?.nestMongoose.Schema(options as any)(target);
+  };
+}
+
+/** `@Prop()` of `@nestjs/mongoose` */
+export function Prop(options?: Record<string, any>): PropertyDecorator {
+  return (target, propertyKey) => {
+    recordPropDeclaration(target, propertyKey, options);
+    optionalMongoPackages()?.nestMongoose.Prop(options as any)(target, propertyKey);
+  };
+}
+
+/** `raw()` of `@nestjs/mongoose` — an inline object definition, kept as written where Mongoose is not installed */
+export function raw(definition: Record<string, any>): Record<string, any> {
+  const packages = optionalMongoPackages();
+  return packages ? packages.nestMongoose.raw(definition) : markRaw(definition);
+}
+
+/**
+ * `SchemaFactory.createForClass()` of `@nestjs/mongoose` — the Mongoose schema, or the recorded declaration
+ * (`DeclaredSchema`) where Mongoose is not installed
+ */
+export const SchemaFactory = {
+  createForClass(target: abstract new (...args: any[]) => any): any {
+    const packages = optionalMongoPackages();
+    return packages ? packages.nestMongoose.SchemaFactory.createForClass(target as any) : declaredSchema(target);
+  },
+};
+
+/**
+ * `new Schema(definition, options)` of `mongoose` — for a model declared inline rather than through a class. A field
+ * whose shape is free-form is declared `{ type: Object }`, which Mongoose stores as `Mixed`.
+ */
+export function createSchema(definition: Record<string, any>, options: Record<string, any> = {}): any {
+  const packages = optionalMongoPackages();
+  return packages
+    ? new packages.mongoose.Schema(definition, options)
+    : new DeclaredSchema({ definition: { ...definition }, options: { ...options } });
+}
+
+/**
+ * The type to declare an ObjectId field with (`@Prop({ type: ObjectIdType, ref })`): Mongoose's `Schema.Types.ObjectId`
+ * where installed, else the class the descriptor recognises as an id
+ */
+export function objectIdType(): unknown {
+  return optionalMongoPackages()?.mongoose.Schema.Types.ObjectId ?? HexObjectId;
+}
+
+/** A new ObjectId, or one for the given hex string / ObjectId — `new Types.ObjectId(value)` */
+export function newObjectId(value?: { toHexString(): string } | string): any {
+  const packages = optionalMongoPackages();
+  return packages ? new packages.mongoose.Types.ObjectId(value as any) : new HexObjectId(value);
+}
+
+/** `Types.ObjectId.isValid()` — accepts what an ObjectId can be built from */
+export function isValidObjectId(value: unknown): boolean {
+  const packages = optionalMongoPackages();
+  return packages ? packages.mongoose.Types.ObjectId.isValid(value as any) : HexObjectId.isValid(value);
+}
+
+/** Whether a value is a Mongoose query (`instanceof Query`) — never where Mongoose is not installed */
+export function isMongooseQuery(value: unknown): value is Query<any, any> {
+  const Query = optionalMongoPackages()?.mongoose.Query;
+  return !!Query && value instanceof Query;
+}
+
+/** A GridFS bucket on a MongoDB database — GridFS IS MongoDB, so its absence is a configuration error, named as such */
+export function createGridFsBucket(db: unknown, options?: { bucketName?: string }): any {
+  const { mongodb } = requireMongoPackages('GridFS (file.storage: gridfs)');
+  return new mongodb.GridFSBucket(db as any, options);
+}

package/src/core/common/persistence/mongo/no-mongo-connection.module.ts

@@ -0,0 +1,18 @@
+import { Global, Module } from '@nestjs/common';
+
+import { getConnectionToken } from './mongoose-compat.js';
+
+/**
+ * The Mongoose connection token where no MongoDB is configured (`database` names no MongoDB source): `null`.
+ *
+ * Services of the core receive the connection through `@InjectConnection()` and use it only on their MongoDB path —
+ * on a SQL source they work through the data store. Without this provider every one of them would fail DI in a project
+ * that keeps its data in PostgreSQL alone; with it, a MongoDB path that is reached anyway fails with a named error
+ * (`CorePersistenceModule` stand-ins, `requireMongoPackages()`) instead of a missing-provider stack trace at boot.
+ */
+@Global()
+@Module({
+  exports: [getConnectionToken()],
+  providers: [{ provide: getConnectionToken(), useValue: null }],
+})
+export class NoMongoConnectionModule {}

package/src/core/common/persistence/mongo-lock-store.ts

@@ -0,0 +1,121 @@
+import type { Collection } from 'mongodb';
+
+import type { LockStore } from './lock-store.interface.js';
+
+/** The duplicate-key error code, decided by code rather than by matching message text. */
+const DUPLICATE_KEY = 11000;
+
+export interface MongoLockStoreOptions {
+  /**
+   * Field holding the lease key — `_id` by default. Any other field gets a unique index before the first claim: the
+   * claim's atomicity rests on it, exactly as it rests on `_id` otherwise.
+   */
+  keyField?: string;
+  /**
+   * A lock format older versions wrote: a timestamp and no `expiresAt`. Such a lock counts as expired once the
+   * timestamp is older than `staleAfterMs` — the rule those versions apply themselves — and every lock this store
+   * writes or renews carries the timestamp too, so an older replica applies its rule to it in a rolling deploy. Both
+   * sides then decide on one document, and a lease is never held twice.
+   */
+  legacyTimestamp?: { field: string; staleAfterMs: number };
+}
+
+/**
+ * Leases in a MongoDB collection: one document per key (`_id` by default), with `owner` and `expiresAt`.
+ *
+ * Works on the native collection on purpose — a lease collection has no Mongoose schema and no tenant,
+ * audit or password semantics a plugin could add. A TTL index on `expiresAt` may be added for garbage
+ * collection; correctness never depends on it, because every claim compares `expiresAt` itself.
+ */
+export class MongoLockStore implements LockStore {
+  protected readonly keyField: string;
+  private keyIndex?: Promise<unknown>;
+
+  constructor(
+    protected readonly collection: Collection<any>,
+    protected readonly options: MongoLockStoreOptions = {},
+  ) {
+    this.keyField = options.keyField ?? '_id';
+  }
+
+  async release(key: string, owner: string): Promise<boolean> {
+    const result = await this.collection.deleteOne({ [this.keyField]: key, owner });
+    return result.deletedCount === 1;
+  }
+
+  async renew(key: string, owner: string, ttlSeconds: number): Promise<boolean> {
+    const now = new Date();
+    const result = await this.collection.updateOne(
+      { [this.keyField]: key, expiresAt: { $gt: now }, owner },
+      { $set: { ...this.legacyStamp(now), expiresAt: new Date(now.getTime() + ttlSeconds * 1000) } },
+    );
+    return result.matchedCount === 1;
+  }
+
+  async tryAcquire(key: string, owner: string, ttlSeconds: number): Promise<boolean> {
+    await this.ensureKeyIndex();
+    const now = new Date();
+    const legacy = this.options.legacyTimestamp;
+    // Matches only an EXPIRED lease, which is taken over in one atomic step. A held lease does not
+    // match, so the upsert tries to insert the same key and fails with a duplicate key: lost. A missing
+    // lease is inserted: won. Two contenders for one expired lease cannot both match — the first update
+    // moves expiresAt into the future before the second is evaluated.
+    const expired = legacy
+      ? {
+          $or: [
+            { expiresAt: { $lte: now } },
+            {
+              expiresAt: { $exists: false },
+              [legacy.field]: { $lt: new Date(now.getTime() - legacy.staleAfterMs) },
+            },
+          ],
+        }
+      : { expiresAt: { $lte: now } };
+    try {
+      await this.collection.updateOne(
+        { [this.keyField]: key, ...expired },
+        {
+          $set: {
+            ...(this.keyField === '_id' ? {} : { [this.keyField]: key }),
+            ...this.legacyStamp(now),
+            acquiredAt: now,
+            expiresAt: new Date(now.getTime() + ttlSeconds * 1000),
+            owner,
+          },
+        },
+        { upsert: true },
+      );
+      return true;
+    } catch (error) {
+      if ((error as { code?: number })?.code !== DUPLICATE_KEY) {
+        throw error;
+      }
+      if (legacy) {
+        // A lock of a version that wrote no timestamp at all: start its clock now — as those versions did — rather
+        // than obeying it forever or breaking it at once (its holder may well be alive)
+        await this.collection.updateOne(
+          { [this.keyField]: key, expiresAt: { $exists: false }, [legacy.field]: { $exists: false } },
+          { $set: { [legacy.field]: now } },
+        );
+      }
+      return false;
+    }
+  }
+
+  /** The timestamp older versions read, refreshed with every claim and renewal */
+  private legacyStamp(now: Date): Record<string, Date> {
+    return this.options.legacyTimestamp ? { [this.options.legacyTimestamp.field]: now } : {};
+  }
+
+  private async ensureKeyIndex(): Promise<void> {
+    if (this.keyField === '_id') {
+      return;
+    }
+    this.keyIndex ??= this.collection.createIndex({ [this.keyField]: 1 }, { unique: true }).catch((error) => {
+      // Retried on the next claim: without the index a second contender could insert a second lock
+      this.keyIndex = undefined;
+      throw error;
+    });
+    await this.keyIndex;
+  }
+}

package/src/core/common/persistence/mongoose-data-store.ts

@@ -0,0 +1,232 @@
+import { Logger } from '@nestjs/common';
+import type { Model } from 'mongoose';
+
+import { getStringIds } from '../helpers/id.helper.js';
+import {
+  assertAccessReason,
+  assertArrayField,
+  assertProjection,
+  assertSampleSize,
+  assertSelectFields,
+} from './store-guards.js';
+import type {
+  DataStore,
+  DataStoreUpdate,
+  FindOptions,
+  PushOptions,
+  StoreCapabilities,
+  StoredRecord,
+  UpdateOptions,
+  Where,
+} from './data-store.interface.js';
+
+/** What MongoDB offers through Mongoose. Transactions need a replica set and are not assumed. */
+export const MONGOOSE_STORE_CAPABILITIES: Readonly<StoreCapabilities> = Object.freeze({
+  aggregatePipeline: true,
+  changeFeed: false,
+  gridfs: true,
+  idType: 'objectId',
+  mongoosePopulate: true,
+  rawFilterArm: true,
+  rls: false,
+  textSearch: true,
+  transactions: false,
+});
+
+/**
+ * The MongoDB data store: the neutral port over a Mongoose model.
+ *
+ * Every operation runs through a Model method, never the native collection, so the security plugins
+ * (tenant isolation before and after, audit fields, role guard, system roles, password hashing) fire
+ * exactly as for any other Mongoose call. Filters and updates pass through untouched — they already
+ * are the Mongo-operator form — except that the neutral `id` is addressed as `_id`.
+ */
+export class MongooseDataStore<T = Record<string, any>> implements DataStore<T> {
+  readonly capabilities = MONGOOSE_STORE_CAPABILITIES;
+  readonly driver = 'mongodb';
+  protected readonly logger = new Logger(MongooseDataStore.name);
+
+  constructor(protected readonly model: Model<any>) {}
+
+  get modelName(): string {
+    return this.model.modelName;
+  }
+
+  async count(where?: Where<T>): Promise<number> {
+    return this.model.countDocuments(toMongoFilter(where)).exec();
+  }
+
+  async sum(field: string, where?: Where<T>): Promise<{ count: number; sum: number }> {
+    assertSelectFields([field]);
+    // An aggregation's $match is not cast like a query: cast it through a query of the model first
+    const match = this.model.find().cast(this.model, toMongoFilter(where));
+    const [row] = await this.model
+      .aggregate<{ count: number; sum: number }>([
+        { $match: match },
+        { $group: { _id: null, count: { $sum: 1 }, sum: { $sum: { $ifNull: [`$${field}`, 0] } } } },
+      ])
+      .exec();
+    return { count: row?.count ?? 0, sum: row?.sum ?? 0 };
+  }
+
+  async deleteById(id: string): Promise<null | StoredRecord<T>> {
+    return toRecord<T>(await this.model.findByIdAndDelete(id).lean().exec());
+  }
+
+  async deleteMany(where: Where<T>): Promise<number> {
+    const result = await this.model.deleteMany(toMongoFilter(where)).exec();
+    return result.deletedCount;
+  }
+
+  async deleteOne(where: Where<T>): Promise<null | StoredRecord<T>> {
+    return toRecord<T>(await this.model.findOneAndDelete(toMongoFilter(where)).lean().exec());
+  }
+
+  async distinct(field: string, where?: Where<T>): Promise<unknown[]> {
+    return this.model.distinct(field, toMongoFilter(where)).exec();
+  }
+
+  async find(where?: Where<T>, options: FindOptions = {}): Promise<StoredRecord<T>[]> {
+    const sample = options.sample === undefined ? undefined : assertSampleSize(options.sample);
+    let query = this.model.find(toMongoFilter(where));
+    if (options.select || options.exclude) query = query.select(toProjection(options));
+    if (options.sort) query = query.sort(options.sort);
+    if (options.skip !== undefined) query = query.skip(options.skip);
+    if (options.limit !== undefined) query = query.limit(options.limit);
+    if (options.collation) query = query.collation(options.collation as any);
+    const docs = await query.lean().exec();
+    const records = (docs as unknown[]).map((doc) => toRecord<T>(doc));
+    // Drawn from the page this query returned, like `$sample` after `$limit`. CrudService.findAndCount() on MongoDB
+    // keeps its own aggregation; this path serves callers of the port.
+    return sample === undefined ? records : randomSample(records, sample);
+  }
+
+  async findById(id: string, options: Pick<FindOptions, 'exclude' | 'select'> = {}): Promise<null | StoredRecord<T>> {
+    let query = this.model.findById(id);
+    if (options.select || options.exclude) query = query.select(toProjection(options));
+    return toRecord<T>(await query.lean().exec());
+  }
+
+  async findOne(where: Where<T>, options: Omit<FindOptions, 'limit' | 'skip'> = {}): Promise<null | StoredRecord<T>> {
+    let query = this.model.findOne(toMongoFilter(where));
+    if (options.select || options.exclude) query = query.select(toProjection(options));
+    if (options.sort) query = query.sort(options.sort);
+    if (options.collation) query = query.collation(options.collation as any);
+    return toRecord<T>(await query.lean().exec());
+  }
+
+  async insert(record: Partial<T>): Promise<StoredRecord<T>> {
+    // `create()` runs the save hooks, so tenant stamping, audit fields and password hashing apply
+    const created = await this.model.create(record);
+    return toRecord<T>(created.toObject());
+  }
+
+  native<N = unknown>(reason: string): N {
+    assertAccessReason(reason, 'native');
+    this.logger.debug(`Native model access: ${reason} (Model: ${this.modelName})`);
+    return this.model as unknown as N;
+  }
+
+  async pullFromArray(id: string, field: string, condition: unknown): Promise<void> {
+    assertArrayField(field, 'pullFromArray');
+    await this.model
+      .findByIdAndUpdate(id, { $pull: { [field]: condition } } as any)
+      .lean()
+      .exec();
+  }
+
+  async pushToArray(id: string, field: string, items: readonly unknown[], options: PushOptions = {}): Promise<void> {
+    assertArrayField(field, 'pushToArray');
+    if (!items.length) {
+      return;
+    }
+    const push: Record<string, unknown> = { $each: [...items] };
+    if (options.slice !== undefined) push.$slice = options.slice;
+    if (options.position !== undefined) push.$position = options.position;
+    if (options.sort) push.$sort = options.sort;
+    await this.model
+      .findByIdAndUpdate(id, { $push: { [field]: push } } as any)
+      .lean()
+      .exec();
+  }
+
+  raw<N = unknown>(reason: string): N {
+    assertAccessReason(reason, 'raw');
+    this.logger.warn(`[SECURITY] Native collection access: ${reason} (Model: ${this.modelName})`);
+    return this.model.collection as unknown as N;
+  }
+
+  async updateById(
+    id: string,
+    update: DataStoreUpdate<T>,
+    options: UpdateOptions = {},
+  ): Promise<null | StoredRecord<T>> {
+    const updated = await this.model
+      .findByIdAndUpdate(id, update as any, {
+        returnDocument: 'after',
+        ...(options.timestamps === false ? { timestamps: false } : {}),
+      })
+      .lean()
+      .exec();
+    return toRecord<T>(updated);
+  }
+
+  async updateMany(where: Where<T>, update: DataStoreUpdate<T>): Promise<number> {
+    const result = await this.model.updateMany(toMongoFilter(where), update as any).exec();
+    return result.matchedCount;
+  }
+
+  async updateOne(where: Where<T>, update: DataStoreUpdate<T>): Promise<null | StoredRecord<T>> {
+    const updated = await this.model
+      .findOneAndUpdate(toMongoFilter(where), update as any, { returnDocument: 'after' })
+      .lean()
+      .exec();
+    return toRecord<T>(updated);
+  }
+}
+
+/** The neutral `id` is `_id` in MongoDB — at the top level and inside `$and` / `$or` / `$nor`. */
+export function toMongoFilter(where: undefined | Where<any>): Record<string, any> {
+  if (!where) {
+    return {};
+  }
+  const filter: Record<string, any> = {};
+  for (const [key, value] of Object.entries(where)) {
+    if (key === 'id') {
+      filter._id = value;
+    } else if ((key === '$and' || key === '$or' || key === '$nor') && Array.isArray(value)) {
+      filter[key] = value.map((entry) => toMongoFilter(entry));
+    } else {
+      filter[key] = value;
+    }
+  }
+  return filter;
+}
+
+/** A lean document as a neutral record: the id as a string under `id`, no `_id`, no version key. */
+function toRecord<T>(doc: unknown): StoredRecord<T> {
+  if (!doc) {
+    return null;
+  }
+  const { __v: _version, _id, ...fields } = doc as Record<string, any>;
+  return { ...fields, id: _id === undefined ? fields.id : getStringIds(_id) } as StoredRecord<T>;
+}
+
+function toProjection(options: Pick<FindOptions, 'exclude' | 'select'>): string {
+  assertProjection(options);
+  if (options.exclude?.length) {
+    return options.exclude.map((field) => `-${field}`).join(' ');
+  }
+  return (options.select ?? []).map((field) => (field === 'id' ? '_id' : field)).join(' ');
+}
+
+/** `size` items of `items` in random order (a partial Fisher–Yates shuffle) */
+function randomSample<I>(items: I[], size: number): I[] {
+  const pool = [...items];
+  const count = Math.min(size, pool.length);
+  for (let index = 0; index < count; index++) {
+    const pick = index + Math.floor(Math.random() * (pool.length - index));
+    [pool[index], pool[pick]] = [pool[pick], pool[index]];
+  }
+  return pool.slice(0, count);
+}