@lossless.org/client 0.1.0

package/dist_ts/nosqldb/classes.collection.d.ts

@@ -0,0 +1,302 @@
+import * as plugins from './plugins.js';
+import { type ISmartdataCollectionPreparationOptions } from './classes.collectionpreparation.js';
+import { type IOrdinaryPersistencePolicy } from './classes.ordinarypersistence.js';
+import { SmartdataDb } from './classes.db.js';
+import { SmartdataDbCursor } from './classes.cursor.js';
+import { SmartDataDbDoc, type IIndexOptions, type TSmartdataNumericDocumentPath, type TSmartdataIdentityValueType } from './classes.doc.js';
+import { SmartdataDbWatcher } from './classes.watcher.js';
+import { type TSmartdataOrdinarySession } from './classes.session.js';
+export interface IFindOptions {
+    limit?: number;
+}
+/**
+ *
+ */
+export interface IDocValidationFunc<T> {
+    (doc: T): boolean;
+}
+export type TDelayed<TDelayedArg> = () => TDelayedArg;
+export interface ICollectionBindingOptions {
+    /**
+     * Explicit persisted collection name. Use this to bind a renamed model to
+     * its legacy collection without changing stored data.
+     */
+    collectionName?: string;
+}
+export type TCollectionModelIndexDirection = 1 | -1 | 'text';
+export interface ICollectionModelIndexOptions {
+    background?: boolean;
+    unique?: boolean;
+    sparse?: boolean;
+    expireAfterSeconds?: number;
+}
+export interface ICollectionModelIndex {
+    name: string;
+    key: Record<string, TCollectionModelIndexDirection>;
+    options?: ICollectionModelIndexOptions;
+}
+/** Named index on one or more paths rooted in the model's persisted fields. */
+export interface INamedIndexDefinition extends ICollectionModelIndex {
+}
+export type TStringFieldKey<TModel extends object> = {
+    [TKey in keyof TModel]-?: NonNullable<TModel[TKey]> extends string ? TKey : never;
+}[keyof TModel] & string;
+export interface ICollectionModelConfig<TModel extends object = any> {
+    /**
+     * The persisted collection name. Programmatic model binding never derives
+     * this value from a constructor name.
+     */
+    collectionName: string;
+    /**
+     * Top-level model fields that SmartData may persist.
+     */
+    persistedFields: ReadonlyArray<keyof TModel & string>;
+    /**
+     * Persisted top-level numeric fields that strict atomic expressions may
+     * reference. This explicit runtime declaration complements the TypeScript
+     * numeric-field constraint.
+     */
+    numericFields?: ReadonlyArray<TSmartdataNumericDocumentPath<TModel>>;
+    /**
+     * Persisted string identity fields with @unI()-equivalent selector and
+     * immutability semantics. Each field requires an explicit single-field,
+     * ascending unique index in `indexes`.
+     */
+    identityFields?: ReadonlyArray<TStringFieldKey<TModel>>;
+    /**
+     * Persisted fields used by SmartData's search helpers.
+     */
+    searchableFields?: ReadonlyArray<keyof TModel & string>;
+    /**
+     * Stable named MongoDB indexes. Object property order defines key order.
+     */
+    indexes?: ReadonlyArray<ICollectionModelIndex>;
+}
+export interface INormalizedCollectionModelSchema {
+    readonly ordinaryPersistence?: IOrdinaryPersistencePolicy;
+    readonly collectionName: string;
+    readonly persistedFields: readonly string[];
+    readonly numericFields: readonly string[];
+    readonly identityFields: readonly string[];
+    readonly identityValueTypes: Readonly<Record<string, TSmartdataIdentityValueType>>;
+    readonly searchableFields: readonly string[];
+    readonly indexes: ReadonlyArray<{
+        readonly name: string;
+        readonly key: ReadonlyArray<readonly [string, TCollectionModelIndexDirection]>;
+        readonly options: Readonly<IIndexOptions>;
+    }>;
+    readonly fingerprint: string;
+}
+export type TCompoundIndexDirection = 1 | -1;
+export interface ICompoundIndexDefinition {
+    /** Stable MongoDB index name. */
+    name: string;
+    /** Ordered fields and their ascending/descending directions. */
+    key: Record<string, TCompoundIndexDirection>;
+    /** MongoDB create-index options other than `name`. */
+    options?: Omit<plugins.mongodb.CreateIndexesOptions, 'name'>;
+}
+export interface ISmartdataIndexInfo {
+    name: string;
+    fields: Array<{
+        path: string;
+        direction: 1 | -1 | 'text';
+    }>;
+    unique: boolean;
+    sparse: boolean;
+    expireAfterSeconds?: number;
+}
+type TCollectionModelConstructor<TModel extends SmartDataDbDoc<any, any>> = {
+    new (...args: any[]): TModel;
+    name: string;
+    prototype: TModel;
+};
+/**
+ * Programmatically declares and binds an ordinary SmartData model.
+ *
+ * Repeating an equivalent declaration is safe. Divergent declarations for
+ * the same constructor, database and collection fail before database work.
+ */
+export declare function defineCollectionModel<TModel extends SmartDataDbDoc<any, any>>(modelArg: TCollectionModelConstructor<TModel>, dbArg: SmartdataDb | TDelayed<SmartdataDb>, configArg: ICollectionModelConfig<TModel>): TCollectionModelConstructor<TModel>;
+/**
+ * Declares a stable named compound index owned by a SmartData model.
+ */
+export declare function compoundIndex(definitionArg: ICompoundIndexDefinition): (value: Function, context: ClassDecoratorContext) => any;
+/** Declares an inherited named index without implicitly declaring persisted fields. */
+export declare function namedIndex(definitionArg: INamedIndexDefinition): (value: Function, context: ClassDecoratorContext) => any;
+/**
+ * This is a decorator that will tell the decorated class what dbTable to use
+ * @param dbArg
+ */
+export declare function Collection(dbArg: SmartdataDb | TDelayed<SmartdataDb>, optionsArg?: ICollectionBindingOptions): (value: Function, context: ClassDecoratorContext) => any;
+export interface IManager {
+    db: SmartdataDb;
+}
+export declare const setDefaultManagerForDoc: <T>(managerArg: IManager, dbDocArg: T) => T;
+/**
+ * This is a decorator that will tell the decorated class what dbTable to use
+ * @param dbArg
+ */
+export declare function managed<TManager extends IManager>(managerOrOptionsArg?: TManager | TDelayed<TManager> | ICollectionBindingOptions, optionsArg?: ICollectionBindingOptions): (value: Function, context: ClassDecoratorContext) => any;
+/**
+ * @dpecrecated use @managed instead
+ */
+export declare const Manager: typeof managed;
+export declare class SmartdataCollection<T> {
+    /**
+     * the collection that is used
+     */
+    mongoDbCollection: plugins.mongodb.Collection;
+    objectValidation: IDocValidationFunc<T> | null;
+    collectionName: string;
+    smartdataDb: SmartdataDb;
+    uniqueIndexes: string[];
+    regularIndexes: Array<{
+        field: string;
+        options: IIndexOptions;
+    }>;
+    compoundIndexes: ICompoundIndexDefinition[];
+    private modelSchema?;
+    private initializationPromise?;
+    private initializationGeneration;
+    private initialized;
+    constructor(classNameArg: string, smartDataDbArg: SmartdataDb);
+    private runWithOrdinarySession;
+    /**
+     * Returns the deep-frozen normalized model schema bound to this collection,
+     * or undefined when no model schema has been bound yet. The schema exposes
+     * declared fields and named index definitions only, never raw driver access.
+     */
+    getBoundModelSchema(): INormalizedCollectionModelSchema | undefined;
+    bindModelSchema(schemaArg: INormalizedCollectionModelSchema): void;
+    resetForDatabaseReconnect(): void;
+    /**
+     * makes sure a collection exists within MongoDb that maps to the SmartdataCollection
+     */
+    init(): Promise<void>;
+    ensureInitialized(): Promise<void>;
+    /** Explicit bounded preparation of the bound model's exact declared topology. */
+    prepareCollection(opts: ISmartdataCollectionPreparationOptions): Promise<void>;
+    isInitializedForCurrentDatabase(): boolean;
+    private initializeOnce;
+    private publishModelIndexes;
+    /**
+     * mark unique index
+     */
+    markUniqueIndexes(keyArrayArg?: string[]): Promise<void>;
+    /**
+     * creates regular indexes for the collection
+     */
+    createRegularIndexes(indexesArg?: Array<{
+        field: string;
+        options: IIndexOptions;
+    }>): Promise<void>;
+    /**
+     * Logs duplicate values for a field to help diagnose unique index creation failures.
+     */
+    private logDuplicatesForField;
+    /**
+     * adds a validation function that all newly inserted and updated objects have to pass
+     */
+    addDocValidation(funcArg: IDocValidationFunc<T>): void;
+    /**
+     * finds an object in the DbCollection
+     */
+    findOne(filterObject: any, opts?: {
+        projection?: plugins.mongodb.Document;
+        maxTimeMS?: number;
+        session?: TSmartdataOrdinarySession;
+    }): Promise<any>;
+    getCursor(filterObjectArg: any, dbDocArg: typeof SmartDataDbDoc, opts?: {
+        session?: plugins.mongodb.ClientSession;
+    }): Promise<SmartdataDbCursor<any>>;
+    /**
+     * finds an object in the DbCollection
+     */
+    findAll(filterObject: any, opts?: {
+        session?: TSmartdataOrdinarySession;
+    }): Promise<any[]>;
+    /**
+     * Watches the collection, returning a SmartdataDbWatcher with RxJS and EventEmitter support.
+     * @param filterObject match filter for change stream
+     * @param opts optional MongoDB ChangeStreamOptions & { bufferTimeMs } to buffer events
+     * @param smartdataDbDocArg document class for instance creation
+     */
+    watch(filterObject: any, opts?: (plugins.mongodb.ChangeStreamOptions & {
+        bufferTimeMs?: number;
+    }), smartdataDbDocArg?: typeof SmartDataDbDoc): Promise<SmartdataDbWatcher>;
+    /**
+     * create an object in the database
+     */
+    private prepareOrdinaryInsert;
+    insert(dbDocArg: T & SmartDataDbDoc<T, unknown>, opts?: {
+        session?: TSmartdataOrdinarySession;
+    }): Promise<any>;
+    /**
+     * Executes a bounded grouped-totals aggregation over already-validated
+     * stages and never exposes the aggregation cursor. Prefer the validated
+     * static `SmartDataDbDoc.getGroupedTotals()`, which owns input validation
+     * before this raw persistence boundary.
+     */
+    aggregateGroupedTotals(matchArg: plugins.mongodb.Filter<plugins.mongodb.Document> | undefined, groupArg: plugins.mongodb.Document, limitArg: number, opts?: {
+        session?: TSmartdataOrdinarySession;
+        maxTimeMS?: number;
+        timeoutMS?: number;
+        signal?: AbortSignal;
+    }): Promise<plugins.mongodb.Document[]>;
+    insertMany(dbDocsArg: Array<T & SmartDataDbDoc<T, unknown>>, opts?: {
+        session?: TSmartdataOrdinarySession;
+        ordered?: boolean;
+    }): Promise<plugins.mongodb.InsertManyResult>;
+    /** Model.insertManyIfAbsent owns identity and new-instance validation. */
+    insertManyIfAbsent(documentsArg: Array<T & SmartDataDbDoc<T, unknown>>, identityFieldArg: string, optsArg: {
+        session?: TSmartdataOrdinarySession;
+        timeoutMS?: number;
+    }): Promise<{
+        insertedCount: number;
+        matchedCount: number;
+    }>;
+    /**
+     * inserts object into the DbCollection
+     */
+    update(dbDocArg: T & SmartDataDbDoc<T, unknown>, opts?: {
+        session?: TSmartdataOrdinarySession;
+    }): Promise<any>;
+    delete(dbDocArg: T & SmartDataDbDoc<T, unknown>, opts?: {
+        session?: TSmartdataOrdinarySession;
+    }): Promise<any>;
+    /**
+     * Rejects instance-level document targeting when the model declares no
+     * identity fields. An empty identity filter would otherwise address an
+     * arbitrary document in the collection.
+     */
+    private assertConstrainingIdentifiableObject;
+    getCount(filterObject: any, opts?: {
+        limit?: number;
+        hint?: string;
+        maxTimeMS?: number;
+        timeoutMS?: number;
+        signal?: AbortSignal;
+        session?: TSmartdataOrdinarySession;
+    }): Promise<number>;
+    getIndexInfo(): Promise<ISmartdataIndexInfo[]>;
+    /**
+     * Runs an integrity check on the collection.
+     * Compares estimated vs actual document count and checks for duplicates on unique index fields.
+     */
+    checkCollectionIntegrity(): Promise<{
+        ok: boolean;
+        estimatedCount: number;
+        actualCount: number;
+        duplicateFields: Array<{
+            field: string;
+            duplicateValues: number;
+        }>;
+    }>;
+    /**
+     * checks a Doc for constraints
+     * if this.objectValidation is not set it passes.
+     */
+    private checkDoc;
+}
+export {};