ts-prorm-orm 1.1.0 → 1.2.0

package/dist/nosql/minio/index.d.ts

@@ -0,0 +1,122 @@
+import type { NoSqlStore } from '../store';
+/**
+ * A loosely-typed handle to a `minio` `Client`. Kept as an interface rather
+ * than the real driver type because `minio` is loaded lazily and may not be
+ * installed at type-check time; tests inject a mock matching this shape.
+ */
+export interface MinioClientLike {
+    putObject(bucket: string, key: string, data: unknown, ...rest: any[]): any;
+    getObject(bucket: string, key: string, ...rest: any[]): any;
+    removeObject(bucket: string, key: string, ...rest: any[]): any;
+    listObjects(bucket: string, prefix?: string, recursive?: boolean, ...rest: any[]): any;
+    statObject(bucket: string, key: string, ...rest: any[]): any;
+    makeBucket(bucket: string, ...rest: any[]): any;
+    bucketExists(bucket: string, ...rest: any[]): any;
+    [key: string]: any;
+}
+/** Connection options for `MinioStore`, mirroring `Minio.Client` construction. */
+export interface MinioStoreOptions {
+    /** Server hostname or IP, e.g. 'localhost' or 's3.example.com'. */
+    endPoint?: string;
+    /** TCP port the MinIO/S3 server listens on, e.g. 9000. */
+    port?: number;
+    /** Whether to use TLS (https). */
+    useSSL?: boolean;
+    /** Access key (username) for the server. */
+    accessKey?: string;
+    /** Secret key (password) for the server. */
+    secretKey?: string;
+    /**
+     * A pre-built `Minio.Client` (or compatible object). When provided,
+     * `connect()` uses it directly and does NOT require the driver — this is how
+     * tests inject a mock client, and how callers can supply a custom-configured
+     * client. When omitted, `connect()` builds a real `Minio.Client` from the
+     * options above.
+     */
+    client?: MinioClientLike;
+}
+/** Options for `putObject()`. */
+export interface PutObjectOptions {
+    /** Byte length of the object body, when known (some sources need it). */
+    size?: number;
+    /** Per-object metadata / headers (e.g. `{ 'Content-Type': 'application/json' }`). */
+    metadata?: Record<string, string>;
+}
+/** Result of `putObject()`. */
+export interface PutObjectResult {
+    etag?: string;
+    versionId?: string;
+}
+/** Result of `getObject()` — the fully-collected object body plus its stat metadata. */
+export interface GetObjectResult {
+    /** The complete object body, collected from the MinIO byte stream. */
+    body: Buffer;
+    /** Object metadata from a companion `statObject`, when available. */
+    stat?: StatObjectResult;
+}
+/** Result of `statObject()` — object metadata without the body. */
+export interface StatObjectResult {
+    size?: number;
+    etag?: string;
+    lastModified?: Date;
+    metaData?: Record<string, string>;
+}
+/**
+ * MinIO store, implementing the minimal `NoSqlStore` marker interface. Unlike
+ * the SQL dialects there is no `query(sql)` — MinIO's operations are
+ * object-shaped and that shape is preserved here rather than forced into a
+ * SQL string.
+ */
+export declare class MinioStore implements NoSqlStore {
+    readonly name = "minio";
+    readonly library = "minio";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: MinioStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `Minio.Client` (loosely typed) for anything not wrapped here. */
+    getClient(): MinioClientLike;
+    private requireClient;
+    /** Wraps a driver failure in a `DatabaseError`, preserving the original error. */
+    private wrapError;
+    /** `putObject` — store an object's body (and optional metadata) under `bucket`/`key`. */
+    putObject(bucket: string, key: string, data: unknown, options?: PutObjectOptions): Promise<PutObjectResult>;
+    /**
+     * `getObject` — fetch an object. `Minio.Client.getObject` resolves to a
+     * readable *byte stream*; this method collects that stream to completion
+     * into a single `Buffer` so callers get the whole body without wiring up
+     * stream plumbing. Optionally attaches a companion `statObject` result.
+     */
+    getObject(bucket: string, key: string): Promise<GetObjectResult>;
+    /** `removeObject` — delete an object. */
+    removeObject(bucket: string, key: string): Promise<void>;
+    /**
+     * `listObjects` — list objects in `bucket`, optionally restricted to those
+     * whose name starts with `prefix`. `Minio.Client.listObjects` returns an
+     * *object stream* that emits one item per object; this method collects that
+     * stream into an array of object *names* (`item.name`). Listing is recursive
+     * so nested "path"-style keys are all returned.
+     */
+    listObjects(bucket: string, prefix?: string): Promise<string[]>;
+    /** `statObject` — fetch an object's metadata without its body. */
+    statObject(bucket: string, key: string): Promise<StatObjectResult>;
+    /** `makeBucket` — create a bucket, optionally in a specific `region`. */
+    makeBucket(bucket: string, region?: string): Promise<void>;
+    /** `bucketExists` — whether a bucket exists. */
+    bucketExists(bucket: string): Promise<boolean>;
+    /**
+     * Collect a readable byte stream into a single `Buffer`. Supports both
+     * Node.js event-emitter streams (`.on('data'|'end'|'error')`) and async
+     * iterables (`for await`), so a test can inject either shape.
+     */
+    private collectStream;
+    /**
+     * Collect an object stream into an array of emitted items. Supports both
+     * Node.js event-emitter streams and async iterables.
+     */
+    private collectObjectStream;
+}
+export default MinioStore;

package/dist/nosql/momento/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Momento Cache store implementation.
+ *
+ * Momento is a serverless, globally-available cache accessed through the
+ * `@gomomento/sdk` `CacheClient`. Every operation is scoped to a named
+ * cache. Momento has no SQL surface and no arbitrary key enumeration, so
+ * this class implements the minimal `NoSqlStore` marker interface and
+ * exposes an edge-KV `get`/`set`/`del`/`list`/`incr` surface mapped onto the
+ * Momento client.
+ *
+ * ## Driver
+ *
+ * Uses `@gomomento/sdk` (`CacheClient`). The driver is loaded lazily inside
+ * `connect()` (or supplied pre-built via the `client` option) so importing
+ * this module never requires `@gomomento/sdk` to be installed unless a store
+ * is actually connected. Tests inject a mock `client`.
+ *
+ * ## Method mapping
+ *
+ * - `get(key)`       -> `client.get(cacheName, key)`
+ * - `set(k,v,opts)`  -> `client.set(cacheName, key, value, { ttl })`
+ * - `del(key)`       -> `client.delete(cacheName, key)`
+ * - `list(name?)`    -> `client.listFetch(cacheName, listName)`. Momento has
+ *   no key-scan, so `list()` fetches the elements of a Momento *list*
+ *   (`name` is the list name, defaulting to `defaultListName`) rather than
+ *   enumerating cache keys.
+ * - `incr(k,by?)`    -> `client.increment(cacheName, key, by)`
+ *
+ * ## Serialization
+ *
+ * String values are stored verbatim; every other value is `JSON.stringify`'d
+ * before being written.
+ */
+import { NoSqlStore } from '../store';
+/** Options for `set()`. */
+export interface MomentoSetOptions {
+    /** Time-to-live in seconds for this item (Momento `ttl`). */
+    ttl?: number;
+}
+/** The subset of the Momento `CacheClient` surface this store drives. */
+export interface MomentoCacheClient {
+    get(cacheName: string, key: string): Promise<any>;
+    set(cacheName: string, key: string, value: string, options?: Record<string, unknown>): Promise<any>;
+    delete(cacheName: string, key: string): Promise<any>;
+    increment(cacheName: string, key: string, amount?: number, options?: Record<string, unknown>): Promise<any>;
+    listFetch(cacheName: string, listName: string): Promise<any>;
+}
+/** Connection options for `MomentoStore`. */
+export interface MomentoStoreOptions {
+    /** Name of the Momento cache every operation targets (required). */
+    cacheName?: string;
+    /** Default list name used by `list()` when none is passed. */
+    defaultListName?: string;
+    /** Momento SDK `Configuration` (used only when building a real client). */
+    configuration?: unknown;
+    /** Momento `CredentialProvider` (used only when building a real client). */
+    credentialProvider?: unknown;
+    /** Default TTL (seconds) for the constructed client. */
+    defaultTtlSeconds?: number;
+    /** Pre-built `CacheClient`; when given `connect()` uses it and skips `require('@gomomento/sdk')`. */
+    client?: MomentoCacheClient;
+}
+/**
+ * `MomentoStore` wraps a Momento `CacheClient` behind the `NoSqlStore`
+ * lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr` surface.
+ */
+export declare class MomentoStore implements NoSqlStore {
+    readonly name = "momento";
+    readonly library = "@gomomento/sdk";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: MomentoStoreOptions);
+    private get cacheName();
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying Momento `CacheClient` for anything not wrapped here. */
+    getClient(): MomentoCacheClient;
+    private requireClient;
+    /** Read a key from the configured cache. Returns the Momento response object. */
+    get(key: string): Promise<any>;
+    /**
+     * Write `value` under `key`. Strings are stored verbatim; other values are
+     * JSON-serialized. `options.ttl` sets a per-item TTL in seconds.
+     */
+    set(key: string, value: unknown, options?: MomentoSetOptions): Promise<any>;
+    /** Delete a key from the configured cache. */
+    del(key: string): Promise<any>;
+    /**
+     * Fetch the elements of a Momento list. Momento cannot enumerate cache
+     * keys, so `prefix`/`listName` names a list; defaults to
+     * `defaultListName`.
+     */
+    list(listName?: string): Promise<any>;
+    /** Atomically increment the numeric value at `key` by `by` (default `1`). */
+    incr(key: string, by?: number): Promise<any>;
+}
+export default MomentoStore;

package/dist/nosql/mongodb/index.d.ts

@@ -0,0 +1,265 @@
+/**
+ * MongoDB store implementation for the Prorm NoSQL layer.
+ *
+ * MongoDB is a document store, not a SQL engine, so this class does not
+ * implement the SQL-shaped `Dialect` interface (see src/dialects/dialect.ts).
+ * It implements the minimal `NoSqlStore` marker interface (src/nosql/store.ts)
+ * for connection lifecycle, and otherwise exposes MongoDB's real API shape
+ * directly: filters, projections, aggregation pipelines, sessions/
+ * transactions, and typed collections - rather than forcing everything
+ * through a `query(sql)` method that doesn't make sense for a document
+ * database.
+ */
+import { MongoClient, Db, Collection, Document, Filter, FindOptions, OptionalUnlessRequiredId, InsertOneOptions, BulkWriteOptions, UpdateFilter, UpdateOptions, DeleteOptions, CountDocumentsOptions, AggregateOptions, IndexSpecification, CreateIndexesOptions, ListIndexesOptions, DropCollectionOptions, EstimatedDocumentCountOptions, CreateCollectionOptions, ListCollectionsOptions, CollectionInfo, RenameOptions, MongoClientOptions, ClientSession, ClientSessionOptions, TransactionOptions, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, AnyBulkWriteOperation, BulkWriteResult, FindOneAndUpdateOptions, FindOneAndDeleteOptions, DistinctOptions, WithId, FindCursor, ChangeStream, ChangeStreamDocument, ChangeStreamOptions } from 'mongodb';
+import { NoSqlStore } from '../store';
+/** One `[field, direction]` ordering term, e.g. `['createdAt', 'DESC']`. */
+export type OrderTerm = [string, 'ASC' | 'DESC'] | string;
+/** Options for {@link MongoStore.findAll}/{@link MongoStore.findOneWhere}. */
+export interface OrmFindOptions {
+    /** Ordering terms applied in sequence. A bare string sorts ascending. */
+    order?: OrderTerm | OrderTerm[];
+    /** Maximum number of documents to return. */
+    limit?: number;
+    /** Number of leading documents to skip (offset). */
+    offset?: number;
+    /** Projection: fields to include/exclude. */
+    projection?: Document;
+}
+/** A group-aggregation request for {@link MongoStore.aggregateGroup}. */
+export interface OrmAggregateOptions {
+    /** ORM `where` filter applied before grouping (`$match`). */
+    where?: Record<string | symbol, unknown>;
+    /** Field(s) to group by. Omit for a single whole-collection group. */
+    groupBy?: string | string[];
+    /** Emit a `count` per group. */
+    count?: boolean;
+    /** Fields to `sum` per group, keyed by output name → source field. */
+    sum?: Record<string, string>;
+    /** Fields to `avg` per group, keyed by output name → source field. */
+    avg?: Record<string, string>;
+    /** Fields to `min` per group, keyed by output name → source field. */
+    min?: Record<string, string>;
+    /** Fields to `max` per group, keyed by output name → source field. */
+    max?: Record<string, string>;
+}
+/** Describes an association to eager-load via `$lookup` in {@link MongoStore.findWithInclude}. */
+export interface MongoInclude {
+    /** The collection to join to (the associated model's collection). */
+    from: string;
+    /** Field on the local documents used as the join key. */
+    localField: string;
+    /** Field on the `from` documents matched against `localField`. Defaults to `_id`. */
+    foreignField?: string;
+    /** Property name under which matched documents are attached. */
+    as: string;
+    /** When true, unwind to a single associated document (belongsTo/hasOne) instead of an array. */
+    single?: boolean;
+}
+/**
+ * Options for constructing a `MongoStore`.
+ *
+ * `uri` is the standard MongoDB connection string
+ * (`mongodb://...` / `mongodb+srv://...`). `database` selects the database
+ * to operate against once connected. Any additional standard
+ * `MongoClientOptions` (pool size, TLS, auth, timeouts, etc.) can be passed
+ * through via `clientOptions`.
+ */
+export interface MongoStoreOptions {
+    /** MongoDB connection string, e.g. `mongodb://localhost:27017` */
+    uri: string;
+    /** Name of the database to use */
+    database: string;
+    /** Additional options passed straight through to the native `MongoClient` */
+    clientOptions?: MongoClientOptions;
+}
+/** Options accepted by {@link MongoStore.find}. */
+export interface MongoFindOptions<T extends Document = Document> extends Omit<FindOptions<T>, 'sort' | 'limit' | 'skip' | 'projection'> {
+    projection?: FindOptions<T>['projection'];
+    sort?: FindOptions<T>['sort'];
+    limit?: number;
+    skip?: number;
+}
+/**
+ * `MongoStore` wraps the official `mongodb` driver's `MongoClient`/`Db`/
+ * `Collection` API in a small, typed convenience layer.
+ */
+export declare class MongoStore implements NoSqlStore {
+    readonly name = "mongodb";
+    readonly library = "mongodb";
+    private readonly options;
+    private client;
+    private db;
+    private _isConnected;
+    constructor(options: MongoStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying native `MongoClient`. */
+    getClient(): MongoClient;
+    /** Returns the underlying native `Db` handle for the configured database. */
+    getDb(): Db;
+    private requireClient;
+    private requireDb;
+    /** Typed collection accessor, e.g. `store.collection<User>('users')`. */
+    collection<T extends Document = Document>(name: string): Collection<T>;
+    private wrapError;
+    /**
+     * Maps a raw MongoDB driver error to one of our well-known `ErrorCodes`.
+     *
+     * MongoDB surfaces most server-side failures as a numeric `code` (and a
+     * human-readable `codeName`) on the error object itself - unlike some SQL
+     * drivers, this is not tucked away behind `.parent`/`.metadata.original`.
+     * We sniff those fields here so callers get a meaningful, dialect-
+     * agnostic error code (e.g. `UNIQUE_CONSTRAINT_ERROR` for duplicate key
+     * violations) instead of a generic `QUERY_ERROR` for everything.
+     */
+    private mapErrorCode;
+    findOne<T extends Document = Document>(collectionName: string, filter?: Filter<T>, options?: FindOptions<T>): Promise<T | null>;
+    find<T extends Document = Document>(collectionName: string, filter?: Filter<T>, options?: MongoFindOptions<T>): Promise<T[]>;
+    /**
+     * Like {@link find}, but returns the native `FindCursor` instead of
+     * materializing the results with `toArray()`. Use this for large result
+     * sets that shouldn't be pulled fully into memory - iterate with
+     * `for await (const doc of cursor)` or use `cursor.next()`/`cursor.forEach()`.
+     */
+    findCursor<T extends Document = Document>(collectionName: string, filter?: Filter<T>, options?: MongoFindOptions<T>): FindCursor<WithId<T>>;
+    countDocuments<T extends Document = Document>(collectionName: string, filter?: Filter<T>, options?: CountDocumentsOptions): Promise<number>;
+    /**
+     * Returns a fast, metadata-based approximate count of all documents in
+     * `collectionName`. Unlike {@link countDocuments}, this does not accept a
+     * filter and does not scan the collection - it reads the collection's
+     * cached document count, so it's cheap but can be stale/approximate
+     * (e.g. immediately after bulk writes, or on a sharded cluster).
+     */
+    estimatedDocumentCount(collectionName: string, options?: EstimatedDocumentCountOptions): Promise<number>;
+    aggregate<T extends Document = Document, R extends Document = Document>(collectionName: string, pipeline: Document[], options?: AggregateOptions): Promise<R[]>;
+    /** Returns the distinct values for `field` across documents matching `filter`. */
+    distinct<T extends Document = Document>(collectionName: string, field: string, filter?: Filter<T>, options?: DistinctOptions): Promise<unknown[]>;
+    /**
+     * Translate an ORM `where` object (with `Op.*` operators and
+     * `Op.and`/`Op.or`/`Op.not`) into a native MongoDB filter document. Exposed
+     * for callers that want to feed the translated filter into other native
+     * operations (e.g. `aggregate`, `watch`).
+     */
+    translateWhere<T extends Document = Document>(where: Record<string | symbol, unknown>): Filter<T>;
+    /**
+     * Fetch all documents in `collectionName` matching an ORM `where` clause,
+     * with optional ordering, offset, limit, and projection. The `where` object
+     * accepts the full ORM operator surface (`Op.gt`, `Op.in`, `Op.between`,
+     * `Op.like`, `Op.and`/`Op.or`, ...), translated to a native MongoDB filter -
+     * so standard queries never require hand-written `$`-filters.
+     */
+    findAll<T extends Document = Document>(collectionName: string, where?: Record<string | symbol, unknown>, options?: OrmFindOptions): Promise<T[]>;
+    /** Fetch the first document in `collectionName` matching an ORM `where` clause (respecting `order`), or `null`. */
+    findOneWhere<T extends Document = Document>(collectionName: string, where?: Record<string | symbol, unknown>, options?: Omit<OrmFindOptions, 'limit'>): Promise<T | null>;
+    /** Count documents in `collectionName` matching an ORM `where` clause. */
+    countWhere<T extends Document = Document>(collectionName: string, where?: Record<string | symbol, unknown>): Promise<number>;
+    /**
+     * Update every document in `collectionName` matching an ORM `where` clause,
+     * applying `patch` (a raw `$`-update, or a plain object which is wrapped in
+     * `$set`).
+     */
+    updateWhere<T extends Document = Document>(collectionName: string, where: Record<string | symbol, unknown>, patch: UpdateFilter<T> | Partial<T>, options?: UpdateOptions): Promise<Document | UpdateResult<T>>;
+    /** Delete every document in `collectionName` matching an ORM `where` clause. */
+    deleteWhere<T extends Document = Document>(collectionName: string, where: Record<string | symbol, unknown>, options?: DeleteOptions): Promise<DeleteResult>;
+    /**
+     * Insert-or-update by an ORM `where` clause: applies `patch` to a matching
+     * document, inserting one (with the patch merged over the filter's implied
+     * fields) if none matches. Thin wrapper over `updateOne` with `upsert: true`.
+     */
+    upsert<T extends Document = Document>(collectionName: string, where: Record<string | symbol, unknown>, patch: UpdateFilter<T> | Partial<T>, options?: Omit<UpdateOptions, 'upsert'>): Promise<UpdateResult<T>>;
+    /**
+     * Grouped aggregation over `collectionName` using a native
+     * `$match`/`$group` pipeline (`count`/`sum`/`avg`/`min`/`max`), with an
+     * optional ORM `where` pre-filter. Returns one entry per group:
+     * `{ group, ...aggregates }` (`group` is `null` when no `groupBy` is given).
+     */
+    aggregateGroup(collectionName: string, options?: OrmAggregateOptions): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Fetch documents from `collectionName` matching an ORM `where` clause, with
+     * one or more associations eager-loaded via native `$lookup` (the MongoDB
+     * equivalent of a SQL join / ORM `include`). Each {@link MongoInclude}
+     * attaches matched documents under its `as` key; `single: true` unwinds to a
+     * single document for to-one associations.
+     */
+    findWithInclude<T extends Document = Document, R extends Document = Document>(collectionName: string, where?: Record<string | symbol, unknown>, includes?: MongoInclude[], options?: OrmFindOptions): Promise<R[]>;
+    insertOne<T extends Document = Document>(collectionName: string, doc: OptionalUnlessRequiredId<T>, options?: InsertOneOptions): Promise<InsertOneResult<T>>;
+    insertMany<T extends Document = Document>(collectionName: string, docs: OptionalUnlessRequiredId<T>[], options?: BulkWriteOptions): Promise<InsertManyResult<T>>;
+    /**
+     * Executes a mix of insert/update/delete/upsert operations against a
+     * single collection in one round trip. Thin passthrough to the native
+     * driver's `Collection.bulkWrite()`.
+     */
+    bulkWrite<T extends Document = Document>(collectionName: string, operations: AnyBulkWriteOperation<T>[], options?: BulkWriteOptions): Promise<BulkWriteResult>;
+    updateOne<T extends Document = Document>(collectionName: string, filter: Filter<T>, update: UpdateFilter<T> | Partial<T>, options?: UpdateOptions): Promise<UpdateResult<T>>;
+    updateMany<T extends Document = Document>(collectionName: string, filter: Filter<T>, update: UpdateFilter<T> | Partial<T>, options?: UpdateOptions): Promise<Document | UpdateResult<T>>;
+    /** Atomically finds a document matching `filter` and updates it, returning it (or `null`). */
+    findOneAndUpdate<T extends Document = Document>(collectionName: string, filter: Filter<T>, update: UpdateFilter<T> | Document[], options?: FindOneAndUpdateOptions): Promise<WithId<T> | null>;
+    deleteOne<T extends Document = Document>(collectionName: string, filter: Filter<T>, options?: DeleteOptions): Promise<DeleteResult>;
+    deleteMany<T extends Document = Document>(collectionName: string, filter: Filter<T>, options?: DeleteOptions): Promise<DeleteResult>;
+    /** Atomically finds a document matching `filter` and deletes it, returning it (or `null`). */
+    findOneAndDelete<T extends Document = Document>(collectionName: string, filter: Filter<T>, options?: FindOneAndDeleteOptions): Promise<WithId<T> | null>;
+    createIndex(collectionName: string, indexSpec: IndexSpecification, options?: CreateIndexesOptions): Promise<string>;
+    dropIndex(collectionName: string, indexName: string): Promise<Document>;
+    /**
+     * Lists the indexes defined on `collectionName`. Fills the asymmetry with
+     * {@link createIndex}/{@link dropIndex}, which have no built-in way to
+     * inspect what indexes already exist. Thin passthrough to the native
+     * driver's `Collection.listIndexes().toArray()`.
+     */
+    listIndexes(collectionName: string, options?: ListIndexesOptions): Promise<Document[]>;
+    /**
+     * Explicitly creates `collectionName`, rather than relying on MongoDB's
+     * implicit creation of a collection on first write. This is the only way
+     * to create a **timeseries collection** (`options.timeseries: { timeField,
+     * metaField?, granularity? }`) or a **view** (`options.viewOn` +
+     * `options.pipeline`), since both must be declared at creation time -
+     * previously this required dropping down to `getDb().createCollection(...)`
+     * directly.
+     */
+    createCollection<T extends Document = Document>(collectionName: string, options?: CreateCollectionOptions): Promise<Collection<T>>;
+    /**
+     * Lists the collections (and views) defined in the configured database.
+     * Thin passthrough to the native driver's `Db.listCollections().toArray()`.
+     */
+    listCollections(filter?: Document, options?: ListCollectionsOptions): Promise<CollectionInfo[]>;
+    /**
+     * Renames `oldName` to `newName`. Uses `Db.renameCollection()` (rather
+     * than `Collection.rename()`) because it's the driver API that stays
+     * generic over the document type, matching the rest of this class's
+     * typed-collection conventions.
+     */
+    renameCollection<T extends Document = Document>(oldName: string, newName: string, options?: RenameOptions): Promise<Collection<T>>;
+    /** Drops `collectionName` entirely. Thin passthrough to `Collection.drop()`. */
+    dropCollection(collectionName: string, options?: DropCollectionOptions): Promise<boolean>;
+    /**
+     * Opens a change stream on `collectionName`, delivering real-time
+     * notifications of insert/update/replace/delete operations. Thin
+     * passthrough to the native driver's `Collection.watch()`.
+     *
+     * Like {@link withTransaction}, this requires a replica set / sharded
+     * cluster deployment - a standalone `mongod` does not support change
+     * streams (see README "Known limitations").
+     *
+     * Returns the native `ChangeStream`, which is itself an async iterable
+     * and event emitter (`on('change', ...)`, `on('error', ...)`, `close()`).
+     *
+     * ```typescript
+     * const stream = store.watch<User>('users', [{ $match: { operationType: 'insert' } }]);
+     * stream.on('change', (change) => {
+     *   // change.operationType, change.fullDocument, ...
+     * });
+     * // later: await stream.close();
+     * ```
+     */
+    watch<T extends Document = Document>(collectionName: string, pipeline?: Document[], options?: ChangeStreamOptions): ChangeStream<T, ChangeStreamDocument<T>>;
+    /** Starts a new client session (for multi-document transactions). */
+    startSession(options?: ClientSessionOptions): ClientSession;
+    /**
+     * Runs `fn` inside a MongoDB multi-document transaction. Requires a
+     * replica set / mongos deployment - standalone servers do not support
+     * transactions (see README "Known limitations").
+     */
+    withTransaction<T>(fn: (session: ClientSession) => Promise<T>, options?: TransactionOptions): Promise<T>;
+}
+export default MongoStore;

package/dist/nosql/mongodb/index.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MongoStore = void 0;
 const mongodb_1 = require("mongodb");
 const index_1 = require("../../errors/index");
+const where_1 = require("./where");
 /**
  * `MongoStore` wraps the official `mongodb` driver's `MongoClient`/`Db`/
  * `Collection` API in a small, typed convenience layer.
@@ -228,6 +229,134 @@ class MongoStore {
         }
     }
     // ---------------------------------------------------------------------
+    // ORM-shaped queries (Op-based where clauses, no hand-written filters)
+    // ---------------------------------------------------------------------
+    /**
+     * Translate an ORM `where` object (with `Op.*` operators and
+     * `Op.and`/`Op.or`/`Op.not`) into a native MongoDB filter document. Exposed
+     * for callers that want to feed the translated filter into other native
+     * operations (e.g. `aggregate`, `watch`).
+     */
+    translateWhere(where) {
+        return (0, where_1.translateWhereToMongo)(where);
+    }
+    /**
+     * Fetch all documents in `collectionName` matching an ORM `where` clause,
+     * with optional ordering, offset, limit, and projection. The `where` object
+     * accepts the full ORM operator surface (`Op.gt`, `Op.in`, `Op.between`,
+     * `Op.like`, `Op.and`/`Op.or`, ...), translated to a native MongoDB filter -
+     * so standard queries never require hand-written `$`-filters.
+     */
+    async findAll(collectionName, where = {}, options = {}) {
+        return this.find(collectionName, this.translateWhere(where), {
+            sort: (0, where_1.translateOrderToMongo)(options.order),
+            skip: options.offset,
+            limit: options.limit,
+            projection: options.projection,
+        });
+    }
+    /** Fetch the first document in `collectionName` matching an ORM `where` clause (respecting `order`), or `null`. */
+    async findOneWhere(collectionName, where = {}, options = {}) {
+        const rows = await this.findAll(collectionName, where, { ...options, limit: 1 });
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /** Count documents in `collectionName` matching an ORM `where` clause. */
+    async countWhere(collectionName, where = {}) {
+        return this.countDocuments(collectionName, this.translateWhere(where));
+    }
+    /**
+     * Update every document in `collectionName` matching an ORM `where` clause,
+     * applying `patch` (a raw `$`-update, or a plain object which is wrapped in
+     * `$set`).
+     */
+    async updateWhere(collectionName, where, patch, options) {
+        const update = isRawUpdate(patch) ? patch : { $set: patch };
+        return this.updateMany(collectionName, this.translateWhere(where), update, options);
+    }
+    /** Delete every document in `collectionName` matching an ORM `where` clause. */
+    async deleteWhere(collectionName, where, options) {
+        return this.deleteMany(collectionName, this.translateWhere(where), options);
+    }
+    /**
+     * Insert-or-update by an ORM `where` clause: applies `patch` to a matching
+     * document, inserting one (with the patch merged over the filter's implied
+     * fields) if none matches. Thin wrapper over `updateOne` with `upsert: true`.
+     */
+    async upsert(collectionName, where, patch, options) {
+        const update = isRawUpdate(patch) ? patch : { $set: patch };
+        return this.updateOne(collectionName, this.translateWhere(where), update, { ...options, upsert: true });
+    }
+    /**
+     * Grouped aggregation over `collectionName` using a native
+     * `$match`/`$group` pipeline (`count`/`sum`/`avg`/`min`/`max`), with an
+     * optional ORM `where` pre-filter. Returns one entry per group:
+     * `{ group, ...aggregates }` (`group` is `null` when no `groupBy` is given).
+     */
+    async aggregateGroup(collectionName, options = {}) {
+        const pipeline = [];
+        if (options.where)
+            pipeline.push({ $match: (0, where_1.translateWhereToMongo)(options.where) });
+        const groupFields = options.groupBy
+            ? Array.isArray(options.groupBy)
+                ? options.groupBy
+                : [options.groupBy]
+            : [];
+        const id = groupFields.length === 0
+            ? null
+            : groupFields.length === 1
+                ? `$${groupFields[0]}`
+                : Object.fromEntries(groupFields.map((f) => [f.replace(/\./g, '_'), `$${f}`]));
+        const group = { _id: id };
+        const hasOtherAgg = !!(options.sum || options.avg || options.min || options.max);
+        if (options.count || !hasOtherAgg)
+            group.count = { $sum: 1 };
+        for (const [out, src] of Object.entries(options.sum ?? {}))
+            group[out] = { $sum: `$${src}` };
+        for (const [out, src] of Object.entries(options.avg ?? {}))
+            group[out] = { $avg: `$${src}` };
+        for (const [out, src] of Object.entries(options.min ?? {}))
+            group[out] = { $min: `$${src}` };
+        for (const [out, src] of Object.entries(options.max ?? {}))
+            group[out] = { $max: `$${src}` };
+        pipeline.push({ $group: group });
+        pipeline.push({ $addFields: { group: '$_id' } });
+        pipeline.push({ $project: { _id: 0 } });
+        return this.aggregate(collectionName, pipeline);
+    }
+    /**
+     * Fetch documents from `collectionName` matching an ORM `where` clause, with
+     * one or more associations eager-loaded via native `$lookup` (the MongoDB
+     * equivalent of a SQL join / ORM `include`). Each {@link MongoInclude}
+     * attaches matched documents under its `as` key; `single: true` unwinds to a
+     * single document for to-one associations.
+     */
+    async findWithInclude(collectionName, where = {}, includes = [], options = {}) {
+        const pipeline = [{ $match: (0, where_1.translateWhereToMongo)(where) }];
+        const sort = (0, where_1.translateOrderToMongo)(options.order);
+        if (sort)
+            pipeline.push({ $sort: sort });
+        if (typeof options.offset === 'number')
+            pipeline.push({ $skip: options.offset });
+        if (typeof options.limit === 'number')
+            pipeline.push({ $limit: options.limit });
+        for (const inc of includes) {
+            pipeline.push({
+                $lookup: {
+                    from: inc.from,
+                    localField: inc.localField,
+                    foreignField: inc.foreignField ?? '_id',
+                    as: inc.as,
+                },
+            });
+            if (inc.single) {
+                pipeline.push({ $unwind: { path: `$${inc.as}`, preserveNullAndEmptyArrays: true } });
+            }
+        }
+        if (options.projection)
+            pipeline.push({ $project: options.projection });
+        return this.aggregate(collectionName, pipeline);
+    }
+    // ---------------------------------------------------------------------
     // Writes
     // ---------------------------------------------------------------------
     async insertOne(collectionName, doc, options) {
@@ -458,4 +587,14 @@ class MongoStore {
     }
 }
 exports.MongoStore = MongoStore;
+/**
+ * Whether `patch` is already a raw MongoDB update document (uses `$`-prefixed
+ * operators like `$set`/`$inc`) rather than a plain field object that should
+ * be wrapped in `$set`.
+ */
+function isRawUpdate(patch) {
+    return (patch !== null &&
+        typeof patch === 'object' &&
+        Object.keys(patch).some((k) => k.startsWith('$')));
+}
 exports.default = MongoStore;

package/dist/nosql/mongodb/where.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Translate an ORM `where` object into a native MongoDB filter document.
+ * A bare `{ field: value }` maps to equality, an array value to `$in`, and
+ * `Op.and`/`Op.or`/`Op.not` to `$and`/`$or`/`$nor`.
+ */
+export declare function translateWhereToMongo(where: Record<string | symbol, unknown> | undefined | null): Record<string, unknown>;
+/** Build a MongoDB `sort` document from ORM ordering terms. */
+export declare function translateOrderToMongo(order: Array<[string, 'ASC' | 'DESC'] | string> | [string, 'ASC' | 'DESC'] | string | undefined): Record<string, 1 | -1> | undefined;