@lossless.org/client 0.1.0

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

@@ -0,0 +1,722 @@
+import * as plugins from './plugins.js';
+import { SmartdataDb } from './classes.db.js';
+import { SmartdataDbCursor } from './classes.cursor.js';
+import { type ISmartdataBootstrapRecordOptions, type ISmartdataBootstrapRecordResult } from './classes.bootstraprecord.js';
+import { type ISmartdataCollectionPreparationOptions } from './classes.collectionpreparation.js';
+import { type ISmartdataStoredInspectionOptions, type ISmartdataStoredInspection, type ISmartdataStoredEvidenceInspection } from './classes.storedinspection.js';
+import { type IManager, type ISmartdataIndexInfo, SmartdataCollection } from './classes.collection.js';
+import { SmartdataDbWatcher } from './classes.watcher.js';
+import { type TSmartdataOrdinarySession } from './classes.session.js';
+import { type ISmartdataCollectionTopologyInspection, type ISmartdataExpectedCollectionTopology } from './classes.collectiontopology.js';
+/**
+ * Search options for `.search()`:
+ * - filter: additional MongoDB query to AND-merge
+ * - validate: post-fetch validator, return true to keep a doc
+ */
+export interface SearchOptions<T> {
+    /**
+     * Additional MongoDB filter to AND‐merge into the query
+     */
+    filter?: Record<string, any>;
+    /**
+     * Post‐fetch validator; return true to keep each doc
+     */
+    validate?: (doc: T) => Promise<boolean> | boolean;
+    /**
+     * Optional MongoDB session for transactional operations
+     */
+    session?: TSmartdataOrdinarySession;
+}
+export type TDocCreation = 'db' | 'new' | 'mixed';
+export type TSmartdataPrimaryId<T> = T extends {
+    _id: infer TId;
+} ? Extract<TId, string | plugins.mongodb.ObjectId> : plugins.mongodb.ObjectId;
+export type TSmartdataIdentityValueType = 'string' | 'positiveSafeInteger';
+export interface IUnIOptions {
+    /**
+     * Runtime value contract for this identity field. The default remains a
+     * non-empty string. Numeric identities require an explicit opt-in.
+     */
+    valueType?: TSmartdataIdentityValueType;
+}
+export declare function globalSvDb(): (value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * Options for custom serialization/deserialization of a field.
+ */
+export interface SvDbOptions {
+    /** Function to serialize the field value before saving to DB */
+    serialize?: (value: any) => any;
+    /** Function to deserialize the field value after reading from DB */
+    deserialize?: (value: any) => any;
+    /**
+     * Explicit relative nested paths that atomic filters and updates may target
+     * below this persisted field.
+     */
+    atomicPaths?: readonly string[];
+    /**
+     * Declares this persisted top-level field as numeric for strict atomic
+     * expression references.
+     */
+    numeric?: boolean;
+}
+/**
+ * saveable - saveable decorator to be used on class properties
+ */
+export declare function svDb(options?: SvDbOptions): (value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * searchable - marks a property as searchable with Lucene query syntax
+ */
+export declare function searchable(): (value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * unique index - decorator to mark a unique index
+ */
+export declare function unI(optionsArg?: IUnIOptions): (value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * Options for MongoDB indexes
+ */
+export interface IIndexOptions {
+    background?: boolean;
+    unique?: boolean;
+    sparse?: boolean;
+    expireAfterSeconds?: number;
+    [key: string]: any;
+}
+/**
+ * index - decorator to mark a field for regular indexing
+ */
+export declare function index(options?: IIndexOptions): (value: undefined, context: ClassFieldDecoratorContext) => void;
+type ElementOf<T> = T extends ReadonlyArray<infer U> ? U : T;
+type InValues<T> = ReadonlyArray<ElementOf<T>>;
+export type MongoFilterCondition<T> = T | {
+    $eq?: T;
+    $ne?: T;
+    $gt?: T;
+    $gte?: T;
+    $lt?: T;
+    $lte?: T;
+    $in?: InValues<T>;
+    $nin?: InValues<T>;
+    $exists?: boolean;
+    $type?: string | number;
+    $regex?: string | RegExp;
+    $options?: string;
+    $all?: T extends ReadonlyArray<infer U> ? ReadonlyArray<U> : never;
+    $elemMatch?: T extends ReadonlyArray<infer U> ? MongoFilter<U> : never;
+    $size?: T extends ReadonlyArray<any> ? number : never;
+    $not?: MongoFilterCondition<T>;
+};
+export type MongoFilter<T> = {
+    [K in keyof T]?: T[K] extends object ? T[K] extends any[] ? MongoFilterCondition<T[K]> : MongoFilter<T[K]> | MongoFilterCondition<T[K]> : MongoFilterCondition<T[K]>;
+} & {
+    $and?: MongoFilter<T>[];
+    $or?: MongoFilter<T>[];
+    $nor?: MongoFilter<T>[];
+    $not?: MongoFilter<T>;
+    [key: string]: any;
+};
+export type TSmartdataDocumentPath<T> = keyof T & string;
+export type TSmartdataAtomicNestedDocumentPath<T> = `${TSmartdataDocumentPath<T>}.${string}`;
+export type TSmartdataAtomicDocumentPath<T> = TSmartdataDocumentPath<T> | TSmartdataAtomicNestedDocumentPath<T>;
+export type TSmartdataProjection<T> = Partial<Record<TSmartdataAtomicDocumentPath<T> | '_id', 0 | 1>>;
+export type TSmartdataSort<T> = Partial<Record<TSmartdataAtomicDocumentPath<T> | '_id', 1 | -1>>;
+export interface ISmartdataCursorOptions<T> {
+    projection?: TSmartdataProjection<T>;
+    /**
+     * Callers are responsible for including a unique final tiebreaker when
+     * deterministic pagination across equal values matters.
+     */
+    sort?: TSmartdataSort<T>;
+    batchSize?: number;
+    limit?: number;
+    /** Zero-based offset. Requires an explicit sort and bounded limit. */
+    skip?: number;
+    /** Model-declared index name, or MongoDB's built-in `_id_` index. */
+    hint?: string;
+    maxTimeMS?: number;
+    session?: plugins.mongodb.ClientSession;
+    /**
+     * @deprecated Prefer the structured cursor options. The modifier runs last
+     * for backward compatibility.
+     */
+    modifier?: (cursorArg: plugins.mongodb.FindCursor<plugins.mongodb.WithId<plugins.mongodb.BSON.Document>>) => plugins.mongodb.FindCursor<plugins.mongodb.WithId<plugins.mongodb.BSON.Document>>;
+}
+export interface ISmartdataCountOptions {
+    limit?: number;
+    /** Model-declared index name, or MongoDB's built-in `_id_` index. */
+    hint?: string;
+    maxTimeMS?: number;
+    /** Client-side operation deadline, including server selection and pool waits. */
+    timeoutMS?: number;
+    signal?: AbortSignal;
+    session?: TSmartdataOrdinarySession;
+}
+export interface ISmartdataOffsetPageOptions<T> {
+    skip: number;
+    limit: number;
+    /** Include a unique final tiebreaker to order equal preceding values. */
+    sort: TSmartdataSort<T>;
+    projection?: TSmartdataProjection<T>;
+    hint?: string;
+    maxTimeMS?: number;
+    /** Defaults to 5000ms; maximum 120000ms. Covers the cursor's entire lifetime. */
+    timeoutMS?: number;
+    signal?: AbortSignal;
+    session?: TSmartdataOrdinarySession;
+}
+export interface ISmartdataFindOneOptions<T> {
+    projection?: TSmartdataProjection<T>;
+    maxTimeMS?: number;
+    session?: TSmartdataOrdinarySession;
+}
+type TSmartdataAtomicSet<T> = Partial<Pick<T, TSmartdataDocumentPath<T>>> & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, unknown>>;
+type TSmartdataAtomicIncrement<T> = Partial<Record<{
+    [TKey in TSmartdataDocumentPath<T>]: NonNullable<T[TKey]> extends number ? TKey : never;
+}[TSmartdataDocumentPath<T>], number>> & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, number>>;
+export type TSmartdataNumericDocumentPath<T> = {
+    [TKey in TSmartdataDocumentPath<T>]: NonNullable<T[TKey]> extends number ? TKey : never;
+}[TSmartdataDocumentPath<T>];
+export type TSmartdataAtomicNumericFieldReference<T> = `$${TSmartdataNumericDocumentPath<T>}`;
+export type TSmartdataAtomicNumericExpressionOperand<T> = number | TSmartdataAtomicNumericFieldReference<T> | {
+    $add: readonly [
+        TSmartdataAtomicNumericExpressionOperand<T>,
+        TSmartdataAtomicNumericExpressionOperand<T>,
+        ...TSmartdataAtomicNumericExpressionOperand<T>[]
+    ];
+};
+export interface ISmartdataAtomicNumericExpression<T> {
+    $lte: readonly [
+        TSmartdataAtomicNumericExpressionOperand<T>,
+        TSmartdataAtomicNumericExpressionOperand<T>
+    ];
+}
+export interface ISmartdataGroupedTotalsOptions<T> {
+    /**
+     * One or two declared top-level fields whose distinct value combinations
+     * form the groups.
+     */
+    groupBy: ReadonlyArray<TSmartdataDocumentPath<T>>;
+    /**
+     * Declared numeric top-level fields to sum per group.
+     */
+    sums?: ReadonlyArray<TSmartdataNumericDocumentPath<T>>;
+    filter?: MongoFilter<T>;
+    /**
+     * Required bound on the number of returned groups (1..10000). The group
+     * stage is not sorted, so when more groups exist than the limit the
+     * returned subset is arbitrary. Use `getGroupedTotalsPage()` when the
+     * caller must detect overflow at the 10000-group boundary.
+     */
+    limit: number;
+    maxTimeMS?: number;
+    /** Client-side deadline for the complete aggregation cursor lifetime. */
+    timeoutMS?: number;
+    signal?: AbortSignal;
+    session?: TSmartdataOrdinarySession;
+}
+export interface ISmartdataGroupedTotalsRow<T> {
+    /**
+     * The group's key values. Documents missing a group field and documents
+     * holding an explicit null merge into one group reported as null.
+     */
+    group: {
+        [TKey in TSmartdataDocumentPath<T>]?: T[TKey] | null;
+    };
+    count: number;
+    sums: Partial<Record<TSmartdataNumericDocumentPath<T>, number>>;
+}
+export interface ISmartdataGroupedTotalsPage<T> {
+    rows: Array<ISmartdataGroupedTotalsRow<T>>;
+    hasMore: boolean;
+}
+export type TSmartdataAtomicArrayPath<T> = {
+    [TKey in TSmartdataDocumentPath<T>]: NonNullable<T[TKey]> extends ReadonlyArray<unknown> ? TKey : never;
+}[TSmartdataDocumentPath<T>];
+type TSmartdataAtomicArrayElement<TValue> = NonNullable<TValue> extends ReadonlyArray<infer TElement> ? TElement : never;
+type TSmartdataAtomicArrayOperation<T> = Partial<{
+    [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicArrayElement<T[TKey]>;
+}>;
+type TSmartdataAtomicPullScalar<TValue> = Extract<TValue, string | number | boolean | null | Date | plugins.mongodb.ObjectId | plugins.mongodb.Binary | plugins.mongodb.Decimal128 | plugins.mongodb.Long | plugins.mongodb.Int32 | plugins.mongodb.Double | plugins.mongodb.Timestamp>;
+type TSmartdataAtomicArrayPullOperation<T> = Partial<{
+    [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicPullScalar<TSmartdataAtomicArrayElement<T[TKey]>>;
+}>;
+export interface ISmartdataAtomicUpdate<T> {
+    $set?: TSmartdataAtomicSet<T>;
+    $unset?: Partial<Record<TSmartdataAtomicDocumentPath<T>, '' | true | 1>>;
+    $inc?: TSmartdataAtomicIncrement<T>;
+    $setOnInsert?: TSmartdataAtomicSet<T>;
+    /**
+     * Appends one element to a declared top-level array field. Modifier
+     * documents ($each, $position, $slice, $sort) are rejected.
+     */
+    $push?: TSmartdataAtomicArrayOperation<T>;
+    /**
+     * Adds one element to a declared top-level array field unless an equal
+     * element is already present. Modifier documents are rejected.
+     */
+    $addToSet?: TSmartdataAtomicArrayOperation<T>;
+    /**
+     * Removes every element equal to a scalar operand from a declared
+     * top-level array field. Operator documents, plain objects, arrays, and
+     * regular expressions are rejected.
+     */
+    $pull?: TSmartdataAtomicArrayPullOperation<T>;
+}
+type TSmartdataAtomicDirectEquality<TValue> = TValue extends ReadonlyArray<infer TEntry> ? ReadonlyArray<TSmartdataAtomicDirectEquality<TEntry>> : TValue extends object ? TValue extends Date | ArrayBufferView | plugins.mongodb.ObjectId | plugins.mongodb.Binary | plugins.mongodb.Decimal128 | plugins.mongodb.Long | plugins.mongodb.Int32 | plugins.mongodb.Double | plugins.mongodb.Timestamp | plugins.mongodb.MinKey | plugins.mongodb.MaxKey ? TValue : never : Exclude<TValue, undefined>;
+type TSmartdataAtomicInValue<TValue> = TValue extends ReadonlyArray<infer TEntry> ? TSmartdataAtomicDirectEquality<TEntry> : TSmartdataAtomicDirectEquality<TValue>;
+export type TSmartdataAtomicFilterCondition<TValue> = TSmartdataAtomicDirectEquality<TValue> | {
+    $eq?: TValue;
+    $ne?: TSmartdataAtomicDirectEquality<TValue>;
+    $gt?: TSmartdataAtomicDirectEquality<TValue>;
+    $gte?: TSmartdataAtomicDirectEquality<TValue>;
+    $lt?: TSmartdataAtomicDirectEquality<TValue>;
+    $lte?: TSmartdataAtomicDirectEquality<TValue>;
+    $in?: ReadonlyArray<TSmartdataAtomicInValue<TValue>>;
+    $nin?: ReadonlyArray<TSmartdataAtomicInValue<TValue>>;
+    $exists?: boolean;
+    $type?: plugins.mongodb.BSONType | plugins.mongodb.BSONTypeAlias;
+    $regex?: string | RegExp;
+    $options?: string;
+    $not?: TSmartdataAtomicFilterCondition<TValue>;
+};
+type TSmartdataAtomicTopLevelFilter<T> = {
+    [TKey in TSmartdataDocumentPath<T>]?: TSmartdataAtomicFilterCondition<T[TKey]>;
+};
+type TSmartdataAtomicNestedFilter<T> = Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, TSmartdataAtomicFilterCondition<unknown>>>;
+type TSmartdataAtomicFilterBranch<T> = TSmartdataAtomicTopLevelFilter<T> & TSmartdataAtomicNestedFilter<T> & {
+    $and?: Array<TSmartdataAtomicFilterBranch<T>>;
+    $or?: Array<TSmartdataAtomicFilterBranch<T>>;
+    $nor?: Array<TSmartdataAtomicFilterBranch<T>>;
+};
+export type TSmartdataAtomicFilter<T> = TSmartdataAtomicFilterBranch<T> & {
+    /**
+     * A root-only, fail-closed numeric expression. This predicate never
+     * counts as the equality anchor required by atomic writes.
+     */
+    $expr?: ISmartdataAtomicNumericExpression<T>;
+};
+export interface ISmartdataAtomicUpdateOptions {
+    upsert?: boolean;
+    session?: TSmartdataOrdinarySession;
+}
+export interface ISmartdataAtomicUpdateResult {
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+    upsertedId: plugins.mongodb.ObjectId | null;
+}
+export type TSmartdataAtomicReturnDocument = 'before' | 'after';
+export interface ISmartdataAtomicFindOneAndUpdateOptions<TReturnDocument extends TSmartdataAtomicReturnDocument, TModel = any> {
+    returnDocument: TReturnDocument;
+    upsert?: boolean;
+    /**
+     * Optional sort applied before MongoDB selects the single document to
+     * update. Accepts the same paths as cursor sorts: declared top-level fields,
+     * nested paths declared through `@svDb({ atomicPaths })` or a model index,
+     * and `_id`. Callers wanting deterministic claim ordering should include a
+     * unique tiebreaker field.
+     */
+    sort?: TSmartdataSort<TModel>;
+    session?: TSmartdataOrdinarySession;
+}
+export type TSmartdataAtomicFindOneAndUpdateResult<T, TReturnDocument extends TSmartdataAtomicReturnDocument> = {
+    status: 'matched';
+    document: T;
+} | {
+    status: 'upserted';
+    document: TReturnDocument extends 'after' ? T : null;
+} | {
+    status: 'not_matched';
+    document: null;
+};
+export interface ISmartdataAtomicDeleteOptions {
+    session?: TSmartdataOrdinarySession;
+    /** Client-side operation deadline, including server selection and pool waits. */
+    timeoutMS?: number;
+}
+export interface ISmartdataInsertManyIfAbsentOptions<T> {
+    /** A declared, non-serialized @unI identity field. */
+    identityField: TSmartdataDocumentPath<T>;
+    /** Client-side bulk operation deadline, including server selection and pool waits. */
+    timeoutMS?: number;
+    session?: TSmartdataOrdinarySession;
+}
+export interface ISmartdataInsertManyIfAbsentResult {
+    insertedCount: number;
+    matchedCount: number;
+}
+export interface ISmartdataAtomicDeleteResult {
+    acknowledged: boolean;
+    deletedCount: number;
+}
+export interface ISmartdataAtomicUpdateManyOptions {
+    session?: TSmartdataOrdinarySession;
+}
+export interface ISmartdataAtomicUpdateManyResult {
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+}
+export declare const convertFilterForMongoDb: (filterArg: {
+    [key: string]: any;
+}) => {
+    [key: string]: any;
+};
+export declare class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends IManager = any> {
+    /**
+     * the collection object an Doc belongs to
+     */
+    static collection: SmartdataCollection<any>;
+    static get exact(): unknown;
+    collection: SmartdataCollection<any>;
+    static defaultManager: any;
+    static manager: any;
+    manager: TManager;
+    /**
+     * Helper to get collection with fallback to static for Deno compatibility
+     */
+    private getCollectionSafe;
+    /** Insert a strict primary-only bootstrap record without separate collection/index DDL. */
+    static insertBootstrapRecord(dbArg: SmartdataDb, recordArg: unknown, optionsArg?: ISmartdataBootstrapRecordOptions): Promise<ISmartdataBootstrapRecordResult>;
+    /** Inspect bounded stored BSON without initializing or hydrating the model. */
+    static inspectStoredDocuments(dbArg: SmartdataDb, optionsArg?: ISmartdataStoredInspectionOptions): Promise<ISmartdataStoredInspection>;
+    /** Diagnose stored BSON with explicit ordinary validation evidence, without hydration. */
+    static inspectStoredDocumentEvidence(dbArg: SmartdataDb, optionsArg?: ISmartdataStoredInspectionOptions): Promise<ISmartdataStoredEvidenceInspection>;
+    static createInstanceFromMongoDbNativeDoc<T>(this: plugins.tsclass.typeFest.Class<T>, mongoDbNativeDocArg: any): T;
+    private static getDeclaredPersistedRoots;
+    private static getDeclaredUniqueRoots;
+    private static getDeclaredIdentityValueTypes;
+    private static getDeclaredNumericRoots;
+    /**
+     * Returns every equality key set that globally constrains a single document
+     * of this model: each declared identity field on its own, plus the full key
+     * set of every declared unqualified unique index. Unique indexes that carry
+     * any option beyond `unique` (sparse, partial, or otherwise uninterpretable)
+     * or a non-numeric key direction do not qualify — such indexes do not
+     * guarantee at most one matching document for an equality filter.
+     */
+    private static getGloballyConstrainingKeySets;
+    private static getDeclaredAtomicPaths;
+    private static getSerializedPersistedRoots;
+    private static getDeclaredQueryPaths;
+    private static assertHydratedProjection;
+    /**
+     * Initializes the model collection and all model-owned indexes. Failed
+     * initialization is retryable after the underlying conflict is repaired.
+     */
+    static init(): Promise<void>;
+    static ensureInitialized(): Promise<void>;
+    /** Verify or install the model's exact topology within one explicit deadline. */
+    static prepareCollection(opts: ISmartdataCollectionPreparationOptions): Promise<void>;
+    /**
+     * Returns a sanitized view of the indexes installed for this model.
+     */
+    static getIndexInfo(): Promise<ISmartdataIndexInfo[]>;
+    /**
+     * Returns the model's immutable collection and index contract without
+     * resolving a manager, database, or SmartdataCollection.
+     */
+    static getExpectedCollectionTopology(): ISmartdataExpectedCollectionTopology;
+    /**
+     * Inspects an explicitly supplied connected database without initializing or
+     * mutating the model collection.
+     */
+    static inspectCollectionTopology(dbArg: SmartdataDb): Promise<ISmartdataCollectionTopologyInspection>;
+    /**
+     * Inserts a newly constructed ordinary model through SmartData.
+     */
+    static insert<T extends SmartDataDbDoc<any, any>>(this: plugins.tsclass.typeFest.Class<T>, documentArg: T, opts?: {
+        session?: TSmartdataOrdinarySession;
+    }): Promise<plugins.mongodb.InsertOneResult<{
+        _id: TSmartdataPrimaryId<T>;
+    }>>;
+    /**
+     * Inserts a batch of newly constructed ordinary models through SmartData.
+     * Each document inserts atomically; the batch as a whole is not isolated
+     * unless the caller supplies a transaction session. With ordered semantics
+     * (the default) MongoDB stops at the first failure; documents MongoDB
+     * reports as inserted are marked database-backed even when the batch fails
+     * part-way, so callers can compensate precisely.
+     */
+    static insertMany<T extends SmartDataDbDoc<any, any>>(this: plugins.tsclass.typeFest.Class<T>, documentsArg: T[], opts?: {
+        session?: TSmartdataOrdinarySession;
+        ordered?: boolean;
+    }): Promise<plugins.mongodb.InsertManyResult<{
+        _id: TSmartdataPrimaryId<T>;
+    }>>;
+    /**
+     * Inserts absent identities without changing existing documents, including
+     * their timestamps. The unordered batch is bounded to 1000 documents and
+     * 16 MiB of serialized BSON. New-model timestamps are preserved. Inputs stay
+     * new so the same batch can be retried after an ambiguous result; read a
+     * stored instance before updating it because an existing body may differ.
+     */
+    static insertManyIfAbsent<T extends SmartDataDbDoc<any, any>>(this: plugins.tsclass.typeFest.Class<T>, documentsArg: T[], opts: ISmartdataInsertManyIfAbsentOptions<T>): Promise<ISmartdataInsertManyIfAbsentResult>;
+    /**
+     * Atomically updates one ordinary model document using a strict selector
+     * and a bounded set of MongoDB update operators.
+     */
+    static atomicUpdate<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: TSmartdataAtomicFilter<T>, updateArg: ISmartdataAtomicUpdate<T>, opts?: ISmartdataAtomicUpdateOptions): Promise<ISmartdataAtomicUpdateResult>;
+    /**
+     * Atomically updates one ordinary model document and returns a hydrated
+     * before or after image with a sanitized persistence outcome.
+     */
+    static atomicFindOneAndUpdate<T, TReturnDocument extends TSmartdataAtomicReturnDocument>(this: plugins.tsclass.typeFest.Class<T>, filterArg: TSmartdataAtomicFilter<T>, updateArg: ISmartdataAtomicUpdate<T>, optionsArg: ISmartdataAtomicFindOneAndUpdateOptions<TReturnDocument, T>): Promise<TSmartdataAtomicFindOneAndUpdateResult<T, TReturnDocument>>;
+    /**
+     * Atomically deletes one ordinary model document using a strict selector.
+     *
+     * This static operation intentionally does not hydrate an instance or run
+     * instance deletion hooks. Callers that require those hooks must use the
+     * instance `delete()` method instead.
+     */
+    static atomicDelete<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: TSmartdataAtomicFilter<T>, opts?: ISmartdataAtomicDeleteOptions): Promise<ISmartdataAtomicDeleteResult>;
+    /**
+     * Atomically deletes every ordinary model document matching a strict
+     * selector. Each matched document is deleted atomically; the batch as a
+     * whole is not isolated. Unlike `atomicDelete()`, the filter does not need
+     * to pin a unique index — plural intent is explicit in this API — but it
+     * still requires declared fields and at least one top-level equality
+     * anchor.
+     */
+    static atomicDeleteMany<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: TSmartdataAtomicFilter<T>, opts?: ISmartdataAtomicDeleteOptions): Promise<ISmartdataAtomicDeleteResult>;
+    /**
+     * Atomically updates every ordinary model document matching a strict
+     * selector. Each matched document is updated atomically; the batch as a
+     * whole is not isolated. No upsert is possible, so `$setOnInsert` is
+     * rejected.
+     */
+    static atomicUpdateMany<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: TSmartdataAtomicFilter<T>, updateArg: Omit<ISmartdataAtomicUpdate<T>, '$setOnInsert'>, opts?: ISmartdataAtomicUpdateManyOptions): Promise<ISmartdataAtomicUpdateManyResult>;
+    /**
+     * Computes bounded grouped counts and optional numeric sums server-side.
+     * Groups by one or two declared top-level fields, always returns a `count`
+     * per group, and sums only declared numeric fields. The `$limit` follows
+     * the group stage without a sort, so when more groups exist than the limit
+     * the returned subset is arbitrary. Use `getGroupedTotalsPage()` when the
+     * caller must detect overflow. The aggregation cursor never leaves SmartData.
+     */
+    static getGroupedTotals<T>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T>): Promise<Array<ISmartdataGroupedTotalsRow<T>>>;
+    /**
+     * Computes the same bounded grouped totals as `getGroupedTotals()` and
+     * reports whether at least one additional group exists beyond the requested
+     * row limit.
+     */
+    static getGroupedTotalsPage<T>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T>): Promise<ISmartdataGroupedTotalsPage<T>>;
+    /**
+     * gets all instances as array
+     * @param this
+     * @param filterArg - Type-safe MongoDB filter with nested object support and operators
+     * @returns
+     */
+    static getInstances<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: MongoFilter<T>, opts?: {
+        session?: TSmartdataOrdinarySession;
+    }): Promise<T[]>;
+    /**
+     * Cursor-paged query with stable seek pagination — the org-standard way to
+     * list unbounded collections. Orders by a comparable (ideally indexed)
+     * sort field with a unique tiebreaker, returns one page plus the cursor
+     * for the next, and never materializes the full result set.
+     * Owned sessions require a prepared model and remain leased through optional
+     * counting, model hydration and cursor cleanup.
+     */
+    static getPagedInstances<T>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: {
+        filter?: MongoFilter<T>;
+        /** Comparable, ideally indexed field that orders the pages (e.g. a numeric timestamp). */
+        sortField: string;
+        sortDirection?: 'asc' | 'desc';
+        /** Unique tiebreaker field present on every document. Defaults to 'id'. */
+        uniqueField?: string;
+        /** Page size, default 100, capped at 1000. */
+        limit?: number;
+        /** Seek position returned as nextCursor by the previous page. */
+        cursor?: {
+            sortValue: number | string;
+            uniqueValue: string;
+        };
+        /** Also count all filter matches (extra query). */
+        withTotal?: boolean;
+        session?: TSmartdataOrdinarySession;
+    }): Promise<{
+        documents: T[];
+        nextCursor?: {
+            sortValue: number | string;
+            uniqueValue: string;
+        };
+        total?: number;
+    }>;
+    /**
+     * gets the first matching instance
+     * @param this
+     * @param filterArg
+     * @returns
+     */
+    static getInstance<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: MongoFilter<T>, opts?: ISmartdataFindOneOptions<T>): Promise<T>;
+    static exists<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: MongoFilter<T>, opts?: {
+        maxTimeMS?: number;
+        session?: TSmartdataOrdinarySession;
+    }): Promise<boolean>;
+    /**
+     * get a unique id prefixed with the class name
+     */
+    static getNewId<T = any>(this: plugins.tsclass.typeFest.Class<T>, lengthArg?: number): Promise<string>;
+    /**
+     * Stream results using model-declared projections, sorts and index hints.
+     * Offset pages require an explicit sort and limit. Include a unique final
+     * tiebreaker; concurrent writes can still move rows between offset pages.
+     */
+    static getCursor<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: MongoFilter<T>, opts?: ISmartdataCursorOptions<T>): Promise<SmartdataDbCursor<T>>;
+    /**
+     * Read a bounded offset page while retaining an owned session through cursor
+     * cleanup. Initialize the model before calling; this operation never creates
+     * collections or indexes. Count separately with the same filter and hint.
+     */
+    static getOffsetPage<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: MongoFilter<T>, opts: ISmartdataOffsetPageOptions<T>): Promise<T[]>;
+    /**
+     * watch the collection
+     * @param this
+     * @param filterArg
+     * @param forEachFunction
+     */
+    /**
+     * Watch the collection for changes, with optional buffering and change stream options.
+     * @param filterArg MongoDB filter to select which changes to observe
+     * @param opts optional ChangeStreamOptions plus bufferTimeMs
+     */
+    static watch<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: MongoFilter<T>, opts?: plugins.mongodb.ChangeStreamOptions & {
+        bufferTimeMs?: number;
+    }): Promise<SmartdataDbWatcher<T>>;
+    /**
+     * run a function for all instances
+     * @returns
+     */
+    static forEach<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: MongoFilter<T>, forEachFunction: (itemArg: T) => Promise<any>): Promise<void>;
+    /**
+     * returns a count of the documents in the collection
+     */
+    static getCount<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg?: MongoFilter<T>, opts?: ISmartdataCountOptions): Promise<number>;
+    /**
+     * Runs an integrity check on this collection.
+     * Returns a summary with estimated vs actual counts and any duplicate unique fields.
+     */
+    static checkCollectionIntegrity<T>(this: plugins.tsclass.typeFest.Class<T>): Promise<{
+        ok: boolean;
+        estimatedCount: number;
+        actualCount: number;
+        duplicateFields: Array<{
+            field: string;
+            duplicateValues: number;
+        }>;
+    }>;
+    /**
+     * Create a MongoDB filter from a Lucene query string
+     * @param luceneQuery Lucene query string
+     * @returns MongoDB query object
+     */
+    static createSearchFilter<T>(this: plugins.tsclass.typeFest.Class<T>, luceneQuery: string): any;
+    /**
+     * List all searchable fields defined on this class
+     */
+    static getSearchableFields(): string[];
+    /**
+     * Execute a query with optional hard filter and post-fetch validation
+     */
+    private static execQuery;
+    /**
+     * Search documents by text or field:value syntax, with safe regex fallback
+     * Supports additional filtering and post-fetch validation via opts
+     * @param query A search term or field:value expression
+     * @param opts Optional filter and validate hooks
+     * @returns Array of matching documents
+     */
+    static search<T>(this: plugins.tsclass.typeFest.Class<T>, query: string, opts?: SearchOptions<T>): Promise<T[]>;
+    /**
+     * how the Doc in memory was created, may prove useful later.
+     */
+    creationStatus: TDocCreation;
+    /**
+     * updated from db in any case where doc comes from db
+     */
+    _createdAt: string;
+    /**
+     * will be updated everytime the doc is saved
+     */
+    _updatedAt: string;
+    /**
+     * an array of saveable properties of ALL doc
+     * Note: Set by decorators on prototype - NOT declared as instance property to avoid shadowing in Deno
+     * Declared with definite assignment assertion to satisfy TypeScript without creating instance property
+     */
+    globalSaveableProperties: string[];
+    /**
+     * unique indexes
+     * Note: Set by decorators on prototype - NOT declared as instance property to avoid shadowing in Deno
+     */
+    uniqueIndexes: string[];
+    /** Runtime value contracts for fields declared with @unI(). */
+    identityValueTypes: Record<string, TSmartdataIdentityValueType>;
+    /**
+     * regular indexes with their options
+     * Note: Set by decorators on prototype - NOT declared as instance property to avoid shadowing in Deno
+     */
+    regularIndexes: Array<{
+        field: string;
+        options: IIndexOptions;
+    }>;
+    /**
+     * named compound indexes declared by @compoundIndex
+     */
+    compoundIndexes: Array<{
+        name: string;
+        key: Record<string, 1 | -1>;
+        options?: Omit<plugins.mongodb.CreateIndexesOptions, 'name'>;
+    }>;
+    /**
+     * an array of saveable properties of a specific doc
+     * Note: Set by decorators on prototype - NOT declared as instance property to avoid shadowing in Deno
+     */
+    saveableProperties: string[];
+    /**
+     * name
+     */
+    name: string;
+    /**
+     * primary id in the database
+     */
+    dbDocUniqueId: string;
+    /**
+     * class constructor
+     */
+    constructor();
+    /**
+     * saves this instance (optionally within a transaction)
+     */
+    save(opts?: {
+        session?: plugins.mongodb.ClientSession;
+    }): Promise<any>;
+    /**
+     * deletes a document from the database (optionally within a transaction)
+     */
+    delete(opts?: {
+        session?: plugins.mongodb.ClientSession;
+    }): Promise<any>;
+    /**
+     * also store any referenced objects to DB
+     * better for data consistency
+     */
+    saveDeep(savedMapArg?: plugins.lik.ObjectMap<SmartDataDbDoc<any, any>>): void;
+    /**
+     * updates an object from db
+     */
+    updateFromDb(): Promise<boolean>;
+    /**
+     * creates a saveable object so the instance can be persisted as json in the database
+     *
+     * Properties whose value is `undefined` are omitted entirely rather than
+     * written as BSON null, so "absent" stays representable. Explicit `null` is
+     * untouched and remains storable wherever the field type allows it.
+     */
+    createSavableObject(): Promise<TImplements>;
+    /**
+     * creates an identifiable object for operations that require filtering
+     */
+    createIdentifiableObject(): Promise<any>;
+}
+export {};