typeferry 0.6.0

package/dist/mongodb/live/types.d.ts

@@ -0,0 +1,266 @@
+import type { Document, Filter, ObjectId } from 'mongodb';
+import type { z } from 'zod';
+import type { ClientNode } from '../../server/index.js';
+import type { MongoCollectionToken } from '../types.js';
+/** Reserved RPC used to create a connection-owned live subscription. */
+export declare const MONGO_LIVE_SUBSCRIBE_METHOD: "mongo:live:subscribe";
+/** Reserved RPC used to replace a stale live subscription snapshot. */
+export declare const MONGO_LIVE_RESYNC_METHOD: "mongo:live:resync";
+/** Reserved RPC used to stop a live subscription. */
+export declare const MONGO_LIVE_UNSUBSCRIBE_METHOD: "mongo:live:unsubscribe";
+/** Reserved event carrying live deltas and resynchronization controls. */
+export declare const MONGO_LIVE_EVENT: "mongo:live:delta";
+/** Client capability required before an ordered splice can be delivered. */
+export declare const MONGO_LIVE_ORDERED_WINDOW_CAPABILITY: "ordered-window-splice-v1";
+/** Client capability for collision-proof ObjectId materialization. */
+export declare const MONGO_LIVE_TYPED_OBJECT_ID_CAPABILITY: "typed-object-id-v1";
+/** Default maximum live subscriptions owned by one WebSocket connection. */
+export declare const MONGO_LIVE_MAX_SUBSCRIPTIONS_PER_CONNECTION = 32;
+/** Default maximum documents accepted in one initial snapshot. */
+export declare const MONGO_LIVE_MAX_SNAPSHOT_DOCUMENTS = 10000;
+/** Default native WebSocket queue size before a subscription becomes stale. */
+export declare const MONGO_LIVE_MAX_BUFFERED_BYTES: number;
+/** Time allowed for a slow consumer to recover before its socket is closed. */
+export declare const MONGO_LIVE_SLOW_CONSUMER_GRACE_MS = 30000;
+/** Delay between change-stream reconnect attempts. */
+export declare const MONGO_LIVE_SOURCE_RETRY_MS = 250;
+/** Default maximum number of documents skipped by an ordered window. */
+export declare const MONGO_LIVE_MAX_WINDOW_SKIP = 100000;
+/** MongoDB identifiers accepted by the server-side source. */
+export type MongoLiveSourceId = ObjectId | string | number;
+/** Collision-proof ObjectId representation produced on the client wire. */
+export interface MongoLiveObjectId {
+    /** Canonical MongoDB ObjectId hexadecimal value. */
+    readonly $objectId: string;
+}
+/** Identifiers produced by TypeFerry EJSON on the client wire. */
+export type MongoLiveId = MongoLiveObjectId | string | number;
+/** Removes source identity from fields returned by a publication projector. */
+export type MongoLiveProjectedFields<TFields extends object = object> = Readonly<Omit<TFields, '_id'>> & {
+    readonly _id?: never;
+};
+/** Client-visible live document with a source-owned stable identity. */
+export type MongoLiveClientDocument<TFields extends object = object> = Readonly<{
+    _id: MongoLiveId;
+} & Omit<TFields, '_id'>>;
+declare const MONGO_LIVE_ARGS: unique symbol;
+declare const MONGO_LIVE_DOCUMENT: unique symbol;
+/** Serializable client contract for one named live publication. */
+export interface MongoLivePublicationDescriptor<TName extends string, TArgs, TDocument extends {
+    readonly _id: MongoLiveId;
+}> {
+    /** Server-registered publication name. */
+    readonly name: TName;
+    /** Phantom argument type used by client inference. */
+    readonly [MONGO_LIVE_ARGS]?: TArgs;
+    /** Phantom result type used by client inference. */
+    readonly [MONGO_LIVE_DOCUMENT]?: TDocument;
+}
+/** Extracts the argument type carried by a publication descriptor. */
+export type MongoLiveArgsOf<TDescriptor> = TDescriptor extends MongoLivePublicationDescriptor<string, infer TArgs, {
+    readonly _id: MongoLiveId;
+}> ? TArgs : never;
+/** Extracts the client document type carried by a publication descriptor. */
+export type MongoLiveDocumentOf<TDescriptor> = TDescriptor extends MongoLivePublicationDescriptor<string, unknown, infer TDocument> ? TDocument : never;
+/** Creates a client-safe publication descriptor factory with inferred name. */
+export declare function mongoLivePublication<TArgs, TDocument extends {
+    readonly _id: MongoLiveId;
+}>(): <const TName extends string>(name: TName) => MongoLivePublicationDescriptor<TName, TArgs, TDocument>;
+/** Connection context available only while authorizing a subscription. */
+export interface MongoLiveAuthorizationContext {
+    /** Calling TypeFerry WebSocket node. */
+    readonly client: ClientNode;
+    /** Aborts when authorization or the owning connection is cancelled. */
+    readonly signal: AbortSignal;
+}
+/** Typed server implementation of a live publication. */
+export interface MongoLivePublicationConfig<TArgs, TScope, TStoredDocument extends Document, TFields extends object> {
+    /** Decorated collection token queried by the publication. */
+    readonly collection: MongoCollectionToken<TStoredDocument>;
+    /** Runtime argument validator. */
+    readonly args: z.ZodType<TArgs>;
+    /** Authentication is required unless explicitly disabled. */
+    readonly protected?: boolean;
+    /** Authorizes the caller and returns detached immutable query scope. */
+    readonly authorize: (context: MongoLiveAuthorizationContext, args: TArgs) => TScope | Promise<TScope>;
+    /** Builds the authoritative MongoDB selector. */
+    readonly filter: (scope: TScope, args: TArgs) => Filter<TStoredDocument>;
+    /**
+     * Builds one bounded ordered window. Omit for unordered set semantics.
+     *
+     * The runtime appends `_id`; application code must not declare it.
+     */
+    readonly window?: (scope: NoInfer<TScope>, args: NoInfer<TArgs>) => MongoLiveWindow<TStoredDocument>;
+    /** Projects stored data into client-visible fields without `_id`. */
+    readonly project: (document: TStoredDocument, scope: TScope) => MongoLiveProjectedFields<TFields> | Promise<MongoLiveProjectedFields<TFields>>;
+}
+/** Runtime-erased publication consumed by the live engine. */
+export interface MongoLiveRuntimePublication {
+    /** Public publication name. */
+    readonly name: string;
+    /** Decorated collection token. */
+    readonly collection: MongoCollectionToken<Document>;
+    /** Whether the caller must be authenticated. */
+    readonly protected: boolean;
+    /** Parses untrusted RPC arguments. */
+    parseArgs(value: unknown): unknown;
+    /** Authorizes a caller and returns detached query scope. */
+    authorize(context: MongoLiveAuthorizationContext, args: unknown): Promise<unknown>;
+    /** Builds the MongoDB selector from validated state. */
+    filter(scope: unknown, args: unknown): Filter<Document>;
+    /** Builds the optional server-owned ordered window. */
+    window?(scope: unknown, args: unknown): MongoLiveWindowInput | null;
+    /** Projects one stored document and injects no identity. */
+    project(document: Document, scope: unknown): Promise<MongoLiveProjectedFields<object>>;
+}
+/** Server registration retaining its typed client descriptor. */
+export interface MongoLivePublicationDefinition<TDescriptor extends MongoLivePublicationDescriptor<string, unknown, MongoLiveClientDocument>> extends MongoLiveRuntimePublication {
+    /** Client-safe descriptor corresponding to the server implementation. */
+    readonly descriptor: TDescriptor;
+}
+/** Untrusted request to start a live subscription. */
+export interface MongoLiveSubscribeRequest {
+    /** Stable client-generated subscription identifier. */
+    readonly subscriptionId: string;
+    /** Registered publication name. */
+    readonly publication: string;
+    /** Publication-specific arguments validated by the server. */
+    readonly args: unknown;
+    /** Optional wire extensions understood by the subscribing client. */
+    readonly capabilities?: readonly string[];
+}
+/** Request to replace a stale subscription generation. */
+export interface MongoLiveResyncRequest {
+    /** Existing connection-owned subscription identifier. */
+    readonly subscriptionId: string;
+    /** Generation observed by the requesting client. */
+    readonly staleGeneration: string;
+}
+/** Request to stop a connection-owned subscription. */
+export interface MongoLiveUnsubscribeRequest {
+    /** Existing connection-owned subscription identifier. */
+    readonly subscriptionId: string;
+}
+/** Complete authoritative state returned by subscribe and resync RPCs. */
+export interface MongoLiveSnapshot<TDocument extends MongoLiveClientDocument = MongoLiveClientDocument> {
+    /** Stable connection-owned subscription identifier. */
+    readonly subscriptionId: string;
+    /** Incarnation identifier replaced by every resnapshot. */
+    readonly generation: string;
+    /** Last sequence represented by the snapshot. */
+    readonly sequence: number;
+    /** Whether document order is part of the authoritative contract. */
+    readonly ordered?: boolean;
+    /** Complete authoritative result set or ordered window. */
+    readonly documents: readonly TDocument[];
+}
+/** Direction accepted for one ordered publication sort field. */
+export type MongoLiveSortDirection = 1 | -1;
+/** Top-level stored-document field accepted by an ordered publication. */
+type MongoLiveDeclaredDocumentKeys<TDocument extends Document> = keyof {
+    [TKey in keyof TDocument as string extends TKey ? never : number extends TKey ? never : TKey]: TDocument[TKey];
+};
+/** Top-level stored-document field accepted by an ordered publication. */
+export type MongoLiveSortField<TDocument extends Document> = Exclude<Extract<MongoLiveDeclaredDocumentKeys<TDocument>, string>, '_id'>;
+/** Stable application sort owned by an ordered publication. */
+export type MongoLiveSort<TDocument extends Document> = Readonly<Partial<Record<MongoLiveSortField<TDocument>, MongoLiveSortDirection>>> & {
+    readonly _id?: never;
+};
+/** Stable, bounded server-owned ordered MongoDB query window. */
+export interface MongoLiveWindow<TDocument extends Document = Document> {
+    /** Non-empty top-level sort fields; the runtime appends `_id: 1`. */
+    readonly sort: MongoLiveSort<TDocument>;
+    /** Number of matching documents omitted before the visible window. */
+    readonly skip?: number;
+    /** Maximum number of visible documents. */
+    readonly limit: number;
+}
+/** Runtime-erased ordered-window input awaiting capacity validation. */
+export interface MongoLiveWindowInput {
+    /** Application fields before the runtime identity tie-breaker. */
+    readonly sort: Readonly<Record<string, MongoLiveSortDirection>>;
+    /** Requested offset. */
+    readonly skip?: number;
+    /** Requested visible bound. */
+    readonly limit: number;
+}
+/** Runtime-erased and validated ordered window. */
+export interface MongoLiveRuntimeWindow {
+    /** Unique application fields followed by the runtime `_id` tie-breaker. */
+    readonly sort: readonly (readonly [string, MongoLiveSortDirection])[];
+    /** Validated non-negative offset. */
+    readonly skip: number;
+    /** Validated positive bound. */
+    readonly limit: number;
+}
+/** Atomic ordered-window replacement operation. */
+export interface MongoLiveWindowSpliceOperation<TDocument extends MongoLiveClientDocument = MongoLiveClientDocument> {
+    /** Positional operation discriminator. */
+    readonly type: 'window-splice';
+    /** Zero-based index in the current ordered array. */
+    readonly index: number;
+    /** Number of current documents removed at `index`. */
+    readonly deleteCount: number;
+    /** Authoritative replacement documents inserted at `index`. */
+    readonly documents: readonly TDocument[];
+}
+/** Semantic document operation following a snapshot. */
+export type MongoLiveOperation<TDocument extends MongoLiveClientDocument = MongoLiveClientDocument> = {
+    readonly type: 'added';
+    readonly document: TDocument;
+} | {
+    readonly type: 'changed';
+    readonly document: TDocument;
+} | {
+    readonly type: 'removed';
+    readonly id: MongoLiveId;
+} | MongoLiveWindowSpliceOperation<TDocument>;
+/** Ordered operation batch for one subscription generation. */
+export interface MongoLiveDelta<TDocument extends MongoLiveClientDocument = MongoLiveClientDocument> {
+    /** Discriminator for data messages. */
+    readonly type: 'delta';
+    /** Target subscription. */
+    readonly subscriptionId: string;
+    /** Target generation. */
+    readonly generation: string;
+    /** Monotonically increasing connection-local sequence. */
+    readonly sequence: number;
+    /** Semantic operations applied atomically by the client. */
+    readonly operations: readonly MongoLiveOperation<TDocument>[];
+}
+/** Control message requiring a complete authoritative replacement. */
+export interface MongoLiveResyncRequired {
+    /** Discriminator for control messages. */
+    readonly type: 'resync-required';
+    /** Target subscription. */
+    readonly subscriptionId: string;
+    /** Generation that must no longer be treated as ready. */
+    readonly staleGeneration: string;
+}
+/** Payload carried by the reserved live event. */
+export type MongoLiveEvent<TDocument extends MongoLiveClientDocument = MongoLiveClientDocument> = MongoLiveDelta<TDocument> | MongoLiveResyncRequired;
+/** Runtime capacity and slow-consumer controls. */
+export interface MongoLiveOptions {
+    /** Named server publications exposed by this registry. */
+    readonly publications: readonly MongoLiveRuntimePublication[];
+    /** Maximum subscriptions owned by one connection. */
+    readonly maxSubscriptionsPerConnection?: number;
+    /** Maximum documents accepted in one snapshot. */
+    readonly maxSnapshotDocuments?: number;
+    /** Maximum `skip` accepted from a server-owned ordered publication. */
+    readonly maxWindowSkip?: number;
+    /** Native WebSocket queue threshold before resync is required. */
+    readonly maxBufferedBytes?: number;
+    /** Slow-consumer recovery grace period. */
+    readonly slowConsumerGraceMs?: number;
+}
+/** Public client state for one live view. */
+export interface MongoLiveViewSnapshot<TDocument extends MongoLiveClientDocument> {
+    /** Current lifecycle state. */
+    readonly status: 'connecting' | 'ready' | 'resyncing' | 'stopped' | 'error';
+    /** Complete immutable result set in authoritative order when configured. */
+    readonly documents: readonly TDocument[];
+    /** Current failure, when status is `error`. */
+    readonly error: Error | null;
+}
+export {};

package/dist/mongodb/live/types.js

@@ -0,0 +1,29 @@
+/** Reserved RPC used to create a connection-owned live subscription. */
+export const MONGO_LIVE_SUBSCRIBE_METHOD = 'mongo:live:subscribe';
+/** Reserved RPC used to replace a stale live subscription snapshot. */
+export const MONGO_LIVE_RESYNC_METHOD = 'mongo:live:resync';
+/** Reserved RPC used to stop a live subscription. */
+export const MONGO_LIVE_UNSUBSCRIBE_METHOD = 'mongo:live:unsubscribe';
+/** Reserved event carrying live deltas and resynchronization controls. */
+export const MONGO_LIVE_EVENT = 'mongo:live:delta';
+/** Client capability required before an ordered splice can be delivered. */
+export const MONGO_LIVE_ORDERED_WINDOW_CAPABILITY = 'ordered-window-splice-v1';
+/** Client capability for collision-proof ObjectId materialization. */
+export const MONGO_LIVE_TYPED_OBJECT_ID_CAPABILITY = 'typed-object-id-v1';
+/** Default maximum live subscriptions owned by one WebSocket connection. */
+export const MONGO_LIVE_MAX_SUBSCRIPTIONS_PER_CONNECTION = 32;
+/** Default maximum documents accepted in one initial snapshot. */
+export const MONGO_LIVE_MAX_SNAPSHOT_DOCUMENTS = 10_000;
+/** Default native WebSocket queue size before a subscription becomes stale. */
+export const MONGO_LIVE_MAX_BUFFERED_BYTES = 2 * 1024 * 1024;
+/** Time allowed for a slow consumer to recover before its socket is closed. */
+export const MONGO_LIVE_SLOW_CONSUMER_GRACE_MS = 30_000;
+/** Delay between change-stream reconnect attempts. */
+export const MONGO_LIVE_SOURCE_RETRY_MS = 250;
+/** Default maximum number of documents skipped by an ordered window. */
+export const MONGO_LIVE_MAX_WINDOW_SKIP = 100_000;
+/** Creates a client-safe publication descriptor factory with inferred name. */
+export function mongoLivePublication() {
+    return (name) => ({ name });
+}
+//# sourceMappingURL=types.js.map

package/dist/mongodb/live/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/mongodb/live/types.ts"],"names":[],"mappings":"AAUA,wEAAwE;AACxE,MAAM,CAAC,MAAM,2BAA2B,GAAG,sBAA+B,CAAA;AAE1E,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG,mBAA4B,CAAA;AAEpE,qDAAqD;AACrD,MAAM,CAAC,MAAM,6BAA6B,GAAG,wBAAiC,CAAA;AAE9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAA2B,CAAA;AAE3D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oCAAoC,GAC/C,0BAAmC,CAAA;AAErC,sEAAsE;AACtE,MAAM,CAAC,MAAM,qCAAqC,GAChD,oBAA6B,CAAA;AAE/B,4EAA4E;AAC5E,MAAM,CAAC,MAAM,2CAA2C,GAAG,EAAE,CAAA;AAE7D,kEAAkE;AAClE,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAA;AAEvD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;AAE5D,+EAA+E;AAC/E,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAA;AAEvD,sDAAsD;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAA;AAE7C,wEAAwE;AACxE,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAA;AAoDjD,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB;IAMlC,OAAO,CACL,IAAW,EAC8C,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AAC1E,CAAC"}

package/dist/mongodb/live/window.d.ts

@@ -0,0 +1,7 @@
+import { type MongoLiveClientDocument, type MongoLiveRuntimeWindow, type MongoLiveWindowInput, type MongoLiveWindowSpliceOperation } from './types.js';
+/** Validates and normalizes one server-owned ordered window. */
+export declare function normalizeMongoLiveWindow(window: MongoLiveWindowInput, maxDocuments: number, maxSkip: number): MongoLiveRuntimeWindow;
+/** Derives one atomic splice between two authoritative ordered windows. */
+export declare function createMongoLiveWindowSplice<TDocument extends MongoLiveClientDocument>(previous: readonly TDocument[], current: readonly TDocument[]): MongoLiveWindowSpliceOperation<TDocument> | null;
+/** Applies one splice after validating indices and unique materialized identity. */
+export declare function applyMongoLiveWindowSplice<TDocument extends MongoLiveClientDocument>(previous: readonly TDocument[], operation: MongoLiveWindowSpliceOperation<TDocument>): readonly TDocument[] | null;

package/dist/mongodb/live/window.js

@@ -0,0 +1,93 @@
+import { EJSON } from '../../ejson/index.js';
+import {} from './types.js';
+/** Validates and normalizes one server-owned ordered window. */
+export function normalizeMongoLiveWindow(window, maxDocuments, maxSkip) {
+    const entries = Object.entries(window.sort);
+    if (entries.length === 0) {
+        throw new Error('MongoDB live ordered windows require at least one sort field.');
+    }
+    if (!Number.isSafeInteger(window.limit) || window.limit < 1) {
+        throw new Error('MongoDB live ordered window "limit" must be a positive integer.');
+    }
+    if (window.limit > maxDocuments) {
+        throw new Error(`MongoDB live ordered window "limit" exceeds ${maxDocuments} documents.`);
+    }
+    const skip = window.skip ?? 0;
+    if (!Number.isSafeInteger(skip) || skip < 0) {
+        throw new Error('MongoDB live ordered window "skip" must be a non-negative integer.');
+    }
+    if (skip > maxSkip) {
+        throw new Error(`MongoDB live ordered window "skip" exceeds ${maxSkip} documents.`);
+    }
+    const fields = new Set();
+    const sort = [];
+    for (const [field, direction] of entries) {
+        if (typeof field !== 'string' ||
+            field.length === 0 ||
+            field === '_id' ||
+            field.startsWith('$') ||
+            field.includes('.')) {
+            throw new Error('MongoDB live ordered window sort fields must be unique top-level fields other than "_id".');
+        }
+        if (fields.has(field)) {
+            throw new Error(`MongoDB live ordered window sort field "${field}" is duplicated.`);
+        }
+        if (direction !== 1 && direction !== -1) {
+            throw new Error(`MongoDB live ordered window sort direction for "${field}" must be 1 or -1.`);
+        }
+        fields.add(field);
+        sort.push([field, direction]);
+    }
+    sort.push(['_id', 1]);
+    return { sort, skip, limit: window.limit };
+}
+/** Derives one atomic splice between two authoritative ordered windows. */
+export function createMongoLiveWindowSplice(previous, current) {
+    let prefix = 0;
+    while (prefix < previous.length &&
+        prefix < current.length &&
+        EJSON.equals(previous[prefix], current[prefix])) {
+        prefix += 1;
+    }
+    if (prefix === previous.length && prefix === current.length)
+        return null;
+    let suffix = 0;
+    while (suffix < previous.length - prefix &&
+        suffix < current.length - prefix &&
+        EJSON.equals(previous[previous.length - 1 - suffix], current[current.length - 1 - suffix])) {
+        suffix += 1;
+    }
+    const operation = {
+        type: 'window-splice',
+        index: prefix,
+        deleteCount: previous.length - prefix - suffix,
+        documents: current.slice(prefix, current.length - suffix),
+    };
+    const applied = applyMongoLiveWindowSplice(previous, operation);
+    if (!applied || !EJSON.equals(applied, current)) {
+        throw new Error('MongoDB live ordered window splice invariant failed.');
+    }
+    return operation;
+}
+/** Applies one splice after validating indices and unique materialized identity. */
+export function applyMongoLiveWindowSplice(previous, operation) {
+    if (!Number.isSafeInteger(operation.index) ||
+        !Number.isSafeInteger(operation.deleteCount) ||
+        operation.index < 0 ||
+        operation.deleteCount < 0 ||
+        operation.index > previous.length ||
+        operation.index + operation.deleteCount > previous.length) {
+        return null;
+    }
+    const current = [...previous];
+    current.splice(operation.index, operation.deleteCount, ...operation.documents);
+    const identities = new Set();
+    for (const document of current) {
+        const identity = EJSON.stringify(document._id, { canonical: true });
+        if (identities.has(identity))
+            return null;
+        identities.add(identity);
+    }
+    return current;
+}
+//# sourceMappingURL=window.js.map

package/dist/mongodb/live/window.js.map

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

package/dist/mongodb/registry.d.ts

@@ -0,0 +1,35 @@
+import type { Collection, Db, Document, MongoClient } from 'mongodb';
+import type { TypeFerryMongo, TypeFerryMongoOptions, MongoCollectionClass, MongoCollectionDefinition, MongoCollectionTarget, MongoCollectionToken, MongoDocumentOf } from './types.js';
+/** Extracts a decorated collection class from a raw class or typed token. */
+export declare function mongoCollectionClass(target: MongoCollectionTarget): MongoCollectionClass;
+/** Runtime registry for decorated MongoDB collections and native driver handles. */
+export declare class TypeFerryMongoRegistry implements TypeFerryMongo {
+    /** Native database handle used by registered collections. */
+    readonly db: Db;
+    /** Native client when one is known; `null` when constructed from an external `Db`. */
+    readonly client: MongoClient | null;
+    private readonly closeClient;
+    private readonly definitions;
+    private readonly collections;
+    private readonly watchHandles;
+    private readonly liveEngine;
+    /** Creates a registry from resolved MongoDB handles. */
+    constructor(options: TypeFerryMongoOptions, connection: {
+        readonly db: Db;
+        readonly client: MongoClient | null;
+        readonly ownsClient: boolean;
+    });
+    /** Returns a native driver collection inferred from a typed collection token. */
+    collection<TToken extends MongoCollectionToken<Document>>(token: TToken): Collection<MongoDocumentOf<TToken>>;
+    /** Returns a native driver collection by name when no typed token is available. */
+    collectionByName<TDocument extends Document = Document>(name: string): Collection<TDocument>;
+    /** Returns decorator metadata for a registered collection. */
+    meta(target: MongoCollectionTarget): MongoCollectionDefinition;
+    /** Creates all declared indexes without dropping or reconciling existing indexes. */
+    ensureIndexes(): Promise<void>;
+    /** Closes change streams and the owned MongoDB client when applicable. */
+    close(): Promise<void>;
+    private startWatches;
+}
+/** Creates a TypeFerry MongoDB registry around native MongoDB driver handles. */
+export declare function createTypeFerryMongo(options: TypeFerryMongoOptions): Promise<TypeFerryMongo>;

package/dist/mongodb/registry.js

@@ -0,0 +1,129 @@
+import { startMongoWatch } from './change-streams.js';
+import { resolveMongoConnection } from './client.js';
+import { getMongoCollectionDefinition } from './decorators/index.js';
+import { MongoLiveEngine } from './live/engine.js';
+/** Extracts a decorated collection class from a raw class or typed token. */
+export function mongoCollectionClass(target) {
+    return 'Class' in target ? target.Class : target;
+}
+/** Runtime registry for decorated MongoDB collections and native driver handles. */
+export class TypeFerryMongoRegistry {
+    /** Native database handle used by registered collections. */
+    db;
+    /** Native client when one is known; `null` when constructed from an external `Db`. */
+    client;
+    closeClient;
+    definitions = new Map();
+    collections = new Map();
+    watchHandles = [];
+    liveEngine;
+    /** Creates a registry from resolved MongoDB handles. */
+    constructor(options, connection) {
+        this.db = connection.db;
+        this.client = connection.client;
+        this.closeClient = connection.ownsClient || Boolean(options.closeExternalClient);
+        for (const target of options.collections) {
+            const Class = mongoCollectionClass(target);
+            const definition = getMongoCollectionDefinition(Class);
+            this.definitions.set(Class, definition);
+            this.collections.set(definition.name, this.db.collection(definition.name));
+        }
+        if (options.live && !options.server) {
+            throw new Error('MongoDB live publications require a TypeFerry server.');
+        }
+        if (options.live) {
+            for (const publication of options.live.publications) {
+                this.meta(publication.collection);
+            }
+        }
+        this.liveEngine =
+            options.server && options.live
+                ? new MongoLiveEngine({
+                    server: options.server,
+                    options: options.live,
+                    resolveCollection: publication => this.collection(publication.collection),
+                    collectionName: publication => this.meta(publication.collection).name,
+                })
+                : null;
+        if (options.server) {
+            this.startWatches(options);
+        }
+    }
+    /** Returns a native driver collection inferred from a typed collection token. */
+    collection(token) {
+        const definition = this.meta(token);
+        return this.collectionByName(definition.name);
+    }
+    /** Returns a native driver collection by name when no typed token is available. */
+    collectionByName(name) {
+        const registered = this.collections.get(name);
+        if (registered)
+            return registered;
+        return this.db.collection(name);
+    }
+    /** Returns decorator metadata for a registered collection. */
+    meta(target) {
+        const Class = mongoCollectionClass(target);
+        const definition = this.definitions.get(Class);
+        if (!definition) {
+            throw new Error(`MongoDB collection "${Class.name}" is not registered.`);
+        }
+        return definition;
+    }
+    /** Creates all declared indexes without dropping or reconciling existing indexes. */
+    async ensureIndexes() {
+        for (const definition of this.definitions.values()) {
+            const collection = this.collectionByName(definition.name);
+            for (const index of definition.indexes) {
+                await collection.createIndex(index.spec, index.options);
+            }
+        }
+    }
+    /** Closes change streams and the owned MongoDB client when applicable. */
+    async close() {
+        await this.liveEngine?.close();
+        await Promise.all(this.watchHandles.map(handle => handle.close()));
+        this.watchHandles.length = 0;
+        if (this.closeClient) {
+            await this.client?.close();
+        }
+    }
+    startWatches(options) {
+        const server = options.server;
+        if (!server)
+            return;
+        for (const definition of this.definitions.values()) {
+            const collection = this.collectionByName(definition.name);
+            for (const watch of definition.watches) {
+                this.watchHandles.push(startMongoWatch({
+                    collection,
+                    definition,
+                    watch,
+                    server,
+                }));
+            }
+        }
+    }
+}
+/** Creates a TypeFerry MongoDB registry around native MongoDB driver handles. */
+export async function createTypeFerryMongo(options) {
+    const connection = await resolveMongoConnection(options);
+    let registry = null;
+    try {
+        registry = new TypeFerryMongoRegistry(options, connection);
+        if (options.ensureIndexes) {
+            await registry.ensureIndexes();
+        }
+        return registry;
+    }
+    catch (error) {
+        if (registry) {
+            await registry.close();
+        }
+        else if (connection.ownsClient) {
+            await connection.client?.close();
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/mongodb/registry.js.map

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

package/dist/mongodb/schema.d.ts

@@ -0,0 +1,16 @@
+import { ObjectId, type Document } from 'mongodb';
+import { z } from 'zod';
+/** Zod schema that accepts only native MongoDB `ObjectId` values. */
+export declare function objectId(): z.ZodType<ObjectId>;
+/** Zod schema that coerces valid hex strings into native MongoDB `ObjectId`s. */
+export declare function coerceObjectId(): z.ZodType<ObjectId>;
+/** Converts a hex string or native `ObjectId` into a native `ObjectId`. */
+export declare function toObjectId(value: string | ObjectId): ObjectId;
+/** Converts a hex string or native `ObjectId` into a stable lowercase hex id. */
+export declare function objectIdHex(value: string | ObjectId): string;
+/** Parses an insert document through an explicit Zod schema. */
+export declare function parseInsert<TDocument extends Document>(schema: z.ZodType<TDocument>, value: unknown): TDocument;
+/** Parses a replacement document through an explicit Zod schema. */
+export declare function parseReplacement<TDocument extends Document>(schema: z.ZodType<TDocument>, value: unknown): TDocument;
+/** Parses a `$set` payload through an explicit Zod schema for that payload. */
+export declare function parseSet<TSet extends Document>(schema: z.ZodType<TSet>, value: unknown): TSet;

package/dist/mongodb/schema.js

@@ -0,0 +1,43 @@
+import { ObjectId } from 'mongodb';
+import { z } from 'zod';
+/** Zod schema that accepts only native MongoDB `ObjectId` values. */
+export function objectId() {
+    return z.custom((value) => value instanceof ObjectId, 'Expected MongoDB ObjectId');
+}
+/** Zod schema that coerces valid hex strings into native MongoDB `ObjectId`s. */
+export function coerceObjectId() {
+    return z.preprocess(value => {
+        if (value instanceof ObjectId)
+            return value;
+        if (typeof value === 'string' && ObjectId.isValid(value)) {
+            return new ObjectId(value);
+        }
+        return value;
+    }, objectId());
+}
+/** Converts a hex string or native `ObjectId` into a native `ObjectId`. */
+export function toObjectId(value) {
+    if (value instanceof ObjectId)
+        return value;
+    if (!ObjectId.isValid(value)) {
+        throw new Error(`Invalid MongoDB ObjectId "${value}".`);
+    }
+    return new ObjectId(value);
+}
+/** Converts a hex string or native `ObjectId` into a stable lowercase hex id. */
+export function objectIdHex(value) {
+    return toObjectId(value).toHexString();
+}
+/** Parses an insert document through an explicit Zod schema. */
+export function parseInsert(schema, value) {
+    return schema.parse(value);
+}
+/** Parses a replacement document through an explicit Zod schema. */
+export function parseReplacement(schema, value) {
+    return schema.parse(value);
+}
+/** Parses a `$set` payload through an explicit Zod schema for that payload. */
+export function parseSet(schema, value) {
+    return schema.parse(value);
+}
+//# sourceMappingURL=schema.js.map

package/dist/mongodb/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/mongodb/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAiB,MAAM,SAAS,CAAA;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,qEAAqE;AACrE,MAAM,UAAU,QAAQ;IACtB,OAAO,CAAC,CAAC,MAAM,CACb,CAAC,KAAK,EAAqB,EAAE,CAAC,KAAK,YAAY,QAAQ,EACvD,2BAA2B,CAC5B,CAAA;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc;IAC5B,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE;QAC1B,IAAI,KAAK,YAAY,QAAQ;YAAE,OAAO,KAAK,CAAA;QAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAA;QAC5B,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAA;AAChB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,UAAU,CAAC,KAAwB;IACjD,IAAI,KAAK,YAAY,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,6BAA6B,KAAK,IAAI,CAAC,CAAA;IACzD,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAC,KAAwB;IAClD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;AACxC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,WAAW,CACzB,MAA4B,EAC5B,KAAc;IAEd,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAC9B,MAA4B,EAC5B,KAAc;IAEd,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,QAAQ,CACtB,MAAuB,EACvB,KAAc;IAEd,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC"}