@lossless.org/client 0.1.0

package/.smartconfig.json

@@ -0,0 +1,37 @@
+{
+  "@git.zone/cli": {
+    "schemaVersion": 2,
+    "projectType": "npm",
+    "module": {
+      "githost": "code.foss.global",
+      "gitscope": "lossless.org",
+      "gitrepo": "client",
+      "npmPackagename": "@lossless.org/client",
+      "description": "One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.",
+      "license": "MIT"
+    },
+    "release": {
+      "preflight": {
+        "test": true,
+        "build": true
+      },
+      "targets": {
+        "git": {
+          "enabled": true,
+          "remote": "origin",
+          "pushBranch": true,
+          "pushTags": true
+        },
+        "npm": {
+          "enabled": true,
+          "registries": [
+            "https://verdaccio.lossless.digital",
+            "https://registry.npmjs.org"
+          ],
+          "accessLevel": "public",
+          "alreadyPublished": "success"
+        }
+      }
+    }
+  }
+}

package/dist_ts/00_commitinfo_data.d.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export declare const commitinfo: {
+    name: string;
+    version: string;
+    description: string;
+};

package/dist_ts/00_commitinfo_data.js

@@ -0,0 +1,9 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+    name: '@lossless.org/client',
+    version: '0.1.0',
+    description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxzQkFBc0I7SUFDNUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLDBGQUEwRjtDQUN4RyxDQUFBIn0=

package/dist_ts/classes.losslessorgclient.d.ts

@@ -0,0 +1,32 @@
+import type { NoSqlConnection, INoSqlConnectionOptions } from './nosqldb/classes.connection.js';
+import type { ObjectStorageConnection, IObjectStorageConnectionOptions } from './objectstorage/classes.connection.js';
+import type { SqlConnection } from './sqldb/classes.sqlconnection.js';
+import type { ClickHouseConnection } from './sqldb/classes.clickhouseconnection.js';
+import type { ISqlConnectionOptions, IClickHouseConnectionOptions } from './sqldb/interfaces.js';
+import type { IOperationOptions, IReadiness } from './core/interfaces.js';
+export interface ILosslessOrgClientOptions {
+    nosqldb?: Record<string, INoSqlConnectionOptions>;
+    sqldb?: Record<string, ISqlConnectionOptions | IClickHouseConnectionOptions>;
+    objectstorage?: Record<string, IObjectStorageConnectionOptions>;
+}
+type TSqlFor<Options> = Options extends {
+    backend: 'clickhouse';
+} ? ClickHouseConnection : SqlConnection;
+/** Named connections with one lifecycle; engines and persisted domain semantics stay separate. */
+export declare class LosslessOrgClient<const Options extends ILosslessOrgClientOptions = ILosslessOrgClientOptions> {
+    readonly options: Options;
+    private readonly resources;
+    private connecting?;
+    private closing?;
+    private connectOperation?;
+    private state;
+    constructor(options: Options);
+    connect(options?: IOperationOptions): Promise<void>;
+    private get;
+    nosqldb<Name extends keyof NonNullable<Options['nosqldb']> & string>(name: Name): NoSqlConnection;
+    sqldb<Name extends keyof NonNullable<Options['sqldb']> & string>(name: Name): TSqlFor<NonNullable<Options['sqldb']>[Name]>;
+    objectstorage<Name extends keyof NonNullable<Options['objectstorage']> & string>(name: Name): ObjectStorageConnection;
+    ready(options?: IOperationOptions): Promise<Record<string, IReadiness>>;
+    close(): Promise<void>;
+}
+export {};

package/dist_ts/classes.losslessorgclient.js

@@ -0,0 +1,103 @@
+import * as plugins from './plugins.js';
+import { LosslessClientError } from './core/classes.error.js';
+import { Operation } from './core/classes.operation.js';
+/** Named connections with one lifecycle; engines and persisted domain semantics stay separate. */
+export class LosslessOrgClient {
+    options;
+    resources = new Map();
+    connecting;
+    closing;
+    connectOperation;
+    state = 'initial';
+    constructor(options) {
+        this.options = options;
+    }
+    connect(options = {}) {
+        if (this.state === 'connected')
+            return Promise.resolve();
+        if (this.state === 'connecting' && this.connecting)
+            return this.connecting;
+        if (this.state !== 'initial')
+            return Promise.reject(new LosslessClientError('closed', 'Create a new client after failure or close.'));
+        this.connectOperation = new Operation(options);
+        this.state = 'connecting';
+        const operation = this.connectOperation;
+        this.connecting = (async () => {
+            try {
+                for (const [name, config] of Object.entries(this.options.nosqldb ?? {})) {
+                    operation.check();
+                    const { NoSqlConnection } = await plugins.loadNoSql();
+                    const connection = new NoSqlConnection(config);
+                    this.resources.set(`nosqldb:${name}`, connection);
+                    await connection.connect({ signal: operation.signal });
+                }
+                for (const [name, config] of Object.entries(this.options.sqldb ?? {})) {
+                    operation.check();
+                    const connection = config.backend === 'clickhouse'
+                        ? new (await plugins.loadClickHouse()).ClickHouseConnection(config)
+                        : new (await plugins.loadSql()).SqlConnection(config);
+                    this.resources.set(`sqldb:${name}`, connection);
+                    await connection.connect({ signal: operation.signal });
+                    operation.check();
+                }
+                for (const [name, config] of Object.entries(this.options.objectstorage ?? {})) {
+                    operation.check();
+                    const { ObjectStorageConnection } = await plugins.loadObjects();
+                    this.resources.set(`objectstorage:${name}`, new ObjectStorageConnection(config));
+                }
+                operation.check();
+                this.state = 'connected';
+            }
+            catch (error) {
+                const cleanup = await Promise.allSettled([...this.resources.values()].map(resource => resource.close()));
+                this.state = 'failed';
+                const errors = cleanup.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+                if (errors.length)
+                    throw new AggregateError([error, ...errors], 'Client connection and cleanup failed.');
+                throw error;
+            }
+            finally {
+                operation.dispose();
+                this.connectOperation = undefined;
+            }
+        })();
+        void this.connecting.finally(() => { this.connecting = undefined; }).catch(() => { });
+        return this.connecting;
+    }
+    get(family, name) {
+        if (this.state !== 'connected')
+            throw new LosslessClientError('not_connected', 'Call and await client.connect() first.');
+        const resource = this.resources.get(`${family}:${name}`);
+        if (!resource)
+            throw new LosslessClientError('invalid_argument', `Unknown ${family} connection: ${name}`);
+        return resource;
+    }
+    nosqldb(name) {
+        return this.get('nosqldb', name);
+    }
+    sqldb(name) {
+        return this.get('sqldb', name);
+    }
+    objectstorage(name) {
+        return this.get('objectstorage', name);
+    }
+    async ready(options = {}) {
+        if (this.state !== 'connected')
+            throw new LosslessClientError('not_connected', 'Client is not connected.');
+        return Object.fromEntries(await Promise.all([...this.resources].map(async ([name, resource]) => [name, await resource.ready(options)])));
+    }
+    close() {
+        return this.closing ??= (async () => {
+            this.state = 'closing';
+            this.connectOperation?.cancel();
+            await this.connecting?.catch(() => { });
+            const result = await Promise.allSettled([...this.resources.values()].map(resource => resource.close()));
+            const errors = result.flatMap(item => item.status === 'rejected' ? [item.reason] : []);
+            if (errors.length)
+                throw new AggregateError(errors, 'Client cleanup failed.');
+            this.resources.clear();
+            this.state = 'closed';
+        })();
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5sb3NzbGVzc29yZ2NsaWVudC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2NsYXNzZXMubG9zc2xlc3NvcmdjbGllbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFPeEMsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDOUQsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBVXhELGtHQUFrRztBQUNsRyxNQUFNLE9BQU8saUJBQWlCO0lBT0E7SUFOWCxTQUFTLEdBQUcsSUFBSSxHQUFHLEVBQXFCLENBQUM7SUFDbEQsVUFBVSxDQUFpQjtJQUMzQixPQUFPLENBQWlCO0lBQ3hCLGdCQUFnQixDQUFhO0lBQzdCLEtBQUssR0FBNkUsU0FBUyxDQUFDO0lBRXBHLFlBQTRCLE9BQWdCO1FBQWhCLFlBQU8sR0FBUCxPQUFPLENBQVM7SUFBRyxDQUFDO0lBRXpDLE9BQU8sQ0FBQyxVQUE2QixFQUFFO1FBQzVDLElBQUksSUFBSSxDQUFDLEtBQUssS0FBSyxXQUFXO1lBQUUsT0FBTyxPQUFPLENBQUMsT0FBTyxFQUFFLENBQUM7UUFDekQsSUFBSSxJQUFJLENBQUMsS0FBSyxLQUFLLFlBQVksSUFBSSxJQUFJLENBQUMsVUFBVTtZQUFFLE9BQU8sSUFBSSxDQUFDLFVBQVUsQ0FBQztRQUMzRSxJQUFJLElBQUksQ0FBQyxLQUFLLEtBQUssU0FBUztZQUFFLE9BQU8sT0FBTyxDQUFDLE1BQU0sQ0FBQyxJQUFJLG1CQUFtQixDQUFDLFFBQVEsRUFBRSw2Q0FBNkMsQ0FBQyxDQUFDLENBQUM7UUFDdEksSUFBSSxDQUFDLGdCQUFnQixHQUFHLElBQUksU0FBUyxDQUFDLE9BQU8sQ0FBQyxDQUFDO1FBQy9DLElBQUksQ0FBQyxLQUFLLEdBQUcsWUFBWSxDQUFDO1FBQzFCLE1BQU0sU0FBUyxHQUFHLElBQUksQ0FBQyxnQkFB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

package/dist_ts/core/classes.error.d.ts

@@ -0,0 +1,16 @@
+import type { TClientErrorCode } from './interfaces.js';
+export declare class LosslessClientError extends Error {
+    readonly code: TClientErrorCode;
+    readonly backendCode?: string;
+    /** A transient cause is a hint, never permission to retry an ambiguous mutation. */
+    readonly retryability: 'transient' | 'permanent' | 'unknown';
+    readonly outcome: 'unknown' | 'partial' | undefined;
+    readonly acknowledgedRows?: number;
+    constructor(code: TClientErrorCode, message: string, options?: ErrorOptions & {
+        backendCode?: string;
+        retryability?: 'transient' | 'permanent' | 'unknown';
+        acknowledgedRows?: number;
+    });
+}
+/** Safe outer message; the original backend error remains available explicitly through cause. */
+export declare const backendError: (error: unknown) => LosslessClientError;

package/dist_ts/core/classes.error.js

@@ -0,0 +1,29 @@
+export class LosslessClientError extends Error {
+    code;
+    backendCode;
+    /** A transient cause is a hint, never permission to retry an ambiguous mutation. */
+    retryability;
+    outcome;
+    acknowledgedRows;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'LosslessClientError';
+        this.backendCode = options?.backendCode;
+        this.retryability = options?.retryability ?? 'unknown';
+        this.outcome = code === 'ambiguous_write' ? 'unknown' : code === 'partial_write' ? 'partial' : undefined;
+        this.acknowledgedRows = options?.acknowledgedRows;
+    }
+}
+/** Safe outer message; the original backend error remains available explicitly through cause. */
+export const backendError = (error) => {
+    if (error instanceof LosslessClientError)
+        return error;
+    const details = error && typeof error === 'object' ? error : {};
+    const code = String(details.code ?? details.errno ?? '');
+    const authentication = ['ER_ACCESS_DENIED_ERROR', 'ER_DBACCESS_DENIED_ERROR', '1045', '1044', '516'].includes(code);
+    const conflict = ['ER_DUP_ENTRY', 'ER_LOCK_DEADLOCK', 'ER_LOCK_WAIT_TIMEOUT', '1062', '1213', '1205'].includes(code);
+    const transient = ['ER_LOCK_DEADLOCK', 'ER_LOCK_WAIT_TIMEOUT', '1213', '1205', 'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT'].includes(code);
+    return new LosslessClientError(authentication ? 'authentication' : conflict ? 'conflict' : 'backend_error', authentication ? 'Backend authentication failed.' : conflict ? 'Backend operation conflicted.' : 'Backend operation failed.', { cause: error, backendCode: code || undefined, retryability: transient ? 'transient' : authentication ? 'permanent' : 'unknown' });
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5lcnJvci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2NvcmUvY2xhc3Nlcy5lcnJvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFFQSxNQUFNLE9BQU8sbUJBQW9CLFNBQVEsS0FBSztJQU1oQjtJQUxaLFdBQVcsQ0FBVTtJQUNyQyxvRkFBb0Y7SUFDcEUsWUFBWSxDQUF3QztJQUNwRCxPQUFPLENBQW9DO0lBQzNDLGdCQUFnQixDQUFVO0lBQzFDLFlBQTRCLElBQXNCLEVBQUUsT0FBZSxFQUNqRSxPQUFrSTtRQUNsSSxLQUFLLENBQUMsT0FBTyxFQUFFLE9BQU8sQ0FBQyxDQUFDO1FBRkUsU0FBSSxHQUFKLElBQUksQ0FBa0I7UUFHaEQsSUFBSSxDQUFDLElBQUksR0FBRyxxQkFBcUIsQ0FBQztRQUNsQyxJQUFJLENBQUMsV0FBVyxHQUFHLE9BQU8sRUFBRSxXQUFXLENBQUM7UUFDeEMsSUFBSSxDQUFDLFlBQVksR0FBRyxPQUFPLEVBQUUsWUFBWSxJQUFJLFNBQVMsQ0FBQztRQUN2RCxJQUFJLENBQUMsT0FBTyxHQUFHLElBQUksS0FBSyxpQkFBaUIsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxJQUFJLEtBQUssZUFBZSxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQztRQUN6RyxJQUFJLENBQUMsZ0JBQWdCLEdBQUcsT0FBTyxFQUFFLGdCQUFnQixDQUFDO0lBQ3BELENBQUM7Q0FDRjtBQUVELGlHQUFpRztBQUNqRyxNQUFNLENBQUMsTUFBTSxZQUFZLEdBQUcsQ0FBQyxLQUFjLEVBQXVCLEVBQUU7SUFDbEUsSUFBSSxLQUFLLFlBQVksbUJBQW1CO1FBQUUsT0FBTyxLQUFLLENBQUM7SUFDdkQsTUFBTSxPQUFPLEdBQUcsS0FBSyxJQUFJLE9BQU8sS0FBSyxLQUFLLFFBQVEsQ0FBQyxDQUFDLENBQUMsS0FBZ0MsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0lBQzNGLE1BQU0sSUFBSSxHQUFHLE1BQU0sQ0FBQyxPQUFPLENBQUMsSUFBSSxJQUFJLE9BQU8sQ0FBQyxLQUFLLElBQUksRUFBRSxDQUFDLENBQUM7SUFDekQsTUFBTSxjQUFjLEdBQUcsQ0FBQyx3QkFBd0IsRUFBRSwwQkFBMEIsRUFBRSxNQUFNLEVBQUUsTUFBTSxFQUFFLEtBQUssQ0FBQyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUNwSCxNQUFNLFFBQVEsR0FBRyxDQUFDLGNBQWMsRUFBRSxrQkFBa0IsRUFBRSxzQkFBc0IsRUFBRSxNQUFNLEVBQUUsTUFBTSxFQUFFLE1BQU0sQ0FBQyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUNySCxNQUFNLFNBQVMsR0FBRyxDQUFDLGtCQUFrQixFQUFFLHNCQUFzQixFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsWUFBWSxFQUFFLGNBQWMsRUFBRSxXQUFXLENBQUMsQ0FBQyxRQUFRLENBQUMsSUFBSSxDQUFDLENBQUM7SUFDekksT0FBTyxJQUFJLG1CQUFtQixDQUFDLGNBQWMsQ0FBQyxDQUFDLENBQUMsZ0JBQWdCLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsVUFBVSxDQUFDLENBQUMsQ0FBQyxlQUFlLEVBQ3hHLGNBQWMsQ0FBQyxDQUFDLENBQUMsZ0NBQWdDLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsK0JBQStCLENBQUMsQ0FBQyxDQUFDLDJCQUEyQixFQUM1SCxFQUFFLEtBQUssRUFBRSxLQUFLLEVBQUUsV0FBVyxFQUFFLElBQUksSUFBSSxTQUFTLEVBQUUsWUFBWSxFQUFFLFNBQVMsQ0FBQyxDQUFDLENBQUMsV0FBVyxDQUFDLENBQUMsQ0FBQyxjQUFjLENBQUMsQ0FBQyxDQUFDLFdBQVcsQ0FBQyxDQUFDLENBQUMsU0FBUyxFQUFFLENBQUMsQ0FBQztBQUN4SSxDQUFDLENBQUMifQ==

package/dist_ts/core/classes.operation.d.ts

@@ -0,0 +1,17 @@
+import { LosslessClientError } from './classes.error.js';
+import type { IOperationOptions } from './interfaces.js';
+/** Owns one deadline and abort listener; callers join resource cleanup before disposal. */
+export declare class Operation {
+    readonly controller: AbortController;
+    get signal(): AbortSignal;
+    private readonly timer;
+    private readonly upstream?;
+    private readonly onAbort;
+    constructor(options?: IOperationOptions, defaultTimeoutMs?: number);
+    check(): void;
+    /** Revoke admission while waiting for caller code. This cannot interrupt arbitrary JavaScript. */
+    wait<Result>(task: PromiseLike<Result>): Promise<Result>;
+    iterate<Row>(rows: AsyncIterable<Row> | Iterable<Row>): AsyncGenerator<Row>;
+    cancel(reason?: LosslessClientError): void;
+    dispose(): void;
+}

package/dist_ts/core/classes.operation.js

@@ -0,0 +1,70 @@
+import { LosslessClientError } from './classes.error.js';
+/** Owns one deadline and abort listener; callers join resource cleanup before disposal. */
+export class Operation {
+    controller = new AbortController();
+    get signal() { return this.controller.signal; }
+    timer;
+    upstream;
+    onAbort = () => this.cancel(new LosslessClientError('cancelled', 'Operation cancelled.'));
+    constructor(options = {}, defaultTimeoutMs = 30_000) {
+        const timeout = options.timeoutMs ?? defaultTimeoutMs;
+        if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 86_400_000) {
+            throw new LosslessClientError('invalid_argument', 'timeoutMs must be an integer between 1 and 86400000.');
+        }
+        this.upstream = options.signal;
+        this.upstream?.addEventListener('abort', this.onAbort, { once: true });
+        this.timer = setTimeout(() => this.cancel(new LosslessClientError('timeout', 'Operation deadline exceeded.')), timeout);
+        this.timer.unref();
+        if (this.upstream?.aborted)
+            this.onAbort();
+    }
+    check() { if (this.signal.aborted)
+        throw this.signal.reason; }
+    /** Revoke admission while waiting for caller code. This cannot interrupt arbitrary JavaScript. */
+    async wait(task) {
+        const aborted = Promise.withResolvers();
+        const abort = () => aborted.reject(this.signal.reason);
+        this.signal.addEventListener('abort', abort, { once: true });
+        if (this.signal.aborted)
+            abort();
+        try {
+            return await Promise.race([task, aborted.promise]);
+        }
+        finally {
+            this.signal.removeEventListener('abort', abort);
+        }
+    }
+    async *iterate(rows) {
+        const asyncRows = rows;
+        const iterator = asyncRows[Symbol.asyncIterator]?.() ?? rows[Symbol.iterator]?.();
+        if (!iterator)
+            throw new LosslessClientError('invalid_argument', 'Insert input must be iterable.');
+        let completed = false;
+        try {
+            while (true) {
+                this.check();
+                const result = await this.wait(Promise.resolve(iterator.next()));
+                if (result.done) {
+                    completed = true;
+                    return;
+                }
+                this.check();
+                yield result.value;
+            }
+        }
+        finally {
+            // Request source cleanup even after cancellation. A caller-owned producer must cooperate
+            // with the supplied signal to stop its own pending I/O; no backend lease remains attached.
+            if (!completed && iterator.return)
+                await this.wait(Promise.resolve(iterator.return()));
+        }
+    }
+    cancel(reason = new LosslessClientError('closed', 'Connection closed.')) {
+        this.controller.abort(reason);
+    }
+    dispose() {
+        clearTimeout(this.timer);
+        this.upstream?.removeEventListener('abort', this.onAbort);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5vcGVyYXRpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9jb3JlL2NsYXNzZXMub3BlcmF0aW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBR3pELDJGQUEyRjtBQUMzRixNQUFNLE9BQU8sU0FBUztJQUNKLFVBQVUsR0FBRyxJQUFJLGVBQWUsRUFBRSxDQUFDO0lBQ25ELElBQVcsTUFBTSxLQUFrQixPQUFPLElBQUksQ0FBQyxVQUFVLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQztJQUNsRCxLQUFLLENBQWdDO0lBQ3JDLFFBQVEsQ0FBZTtJQUN2QixPQUFPLEdBQUcsR0FBRyxFQUFFLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxJQUFJLG1CQUFtQixDQUFDLFdBQVcsRUFBRSxzQkFBc0IsQ0FBQyxDQUFDLENBQUM7SUFFM0csWUFBWSxVQUE2QixFQUFFLEVBQUUsZ0JBQWdCLEdBQUcsTUFBTTtRQUNwRSxNQUFNLE9BQU8sR0FBRyxPQUFPLENBQUMsU0FBUyxJQUFJLGdCQUFnQixDQUFDO1FBQ3RELElBQUksQ0FBQyxNQUFNLENBQUMsYUFBYSxDQUFDLE9BQU8sQ0FBQyxJQUFJLE9BQU8sR0FBRyxDQUFDLElBQUksT0FBTyxHQUFHLFVBQVUsRUFBRSxDQUFDO1lBQzFFLE1BQU0sSUFBSSxtQkFBbUIsQ0FBQyxrQkFBa0IsRUFBRSxzREFBc0QsQ0FBQyxDQUFDO1FBQzVHLENBQUM7UUFDRCxJQUFJLENBQUMsUUFBUSxHQUFHLE9BQU8sQ0FBQyxNQUFNLENBQUM7UUFDL0IsSUFBSSxDQUFDLFFBQVEsRUFBRSxnQkFBZ0IsQ0FBQyxPQUFPLEVBQUUsSUFBSSxDQUFDLE9BQU8sRUFBRSxFQUFFLElBQUksRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDO1FBQ3ZFLElBQUksQ0FBQyxLQUFLLEdBQUcsVUFBVSxDQUFDLEdBQUcsRUFBRSxD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

package/dist_ts/core/interfaces.d.ts

@@ -0,0 +1,18 @@
+export type TBackend = 'nosqldb' | 'mongodb' | 'sqldb' | 'mariadb' | 'clickhouse' | 'objectstorage' | 's3';
+export type TCapability = 'available' | 'unsupported' | 'unknown';
+export interface ICapabilities {
+    readonly backend: TBackend;
+    readonly transactions: TCapability;
+    readonly changeStreams: TCapability;
+    readonly objectMetrics: TCapability;
+    readonly diskResidentScans: TCapability;
+}
+export interface IOperationOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface IReadiness {
+    ready: boolean;
+    reason?: string;
+}
+export type TClientErrorCode = 'invalid_argument' | 'unsupported_capability' | 'not_connected' | 'closed' | 'timeout' | 'cancelled' | 'result_limit' | 'authentication' | 'conflict' | 'backend_error' | 'ambiguous_write' | 'partial_write';

package/dist_ts/core/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2NvcmUvaW50ZXJmYWNlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist_ts/index.d.ts

@@ -0,0 +1,4 @@
+export { LosslessOrgClient } from './classes.losslessorgclient.js';
+export type { ILosslessOrgClientOptions } from './classes.losslessorgclient.js';
+export { LosslessClientError } from './core/classes.error.js';
+export type { ICapabilities, IOperationOptions, IReadiness, TBackend, TCapability, TClientErrorCode } from './core/interfaces.js';

package/dist_ts/index.js

@@ -0,0 +1,3 @@
+export { LosslessOrgClient } from './classes.losslessorgclient.js';
+export { LosslessClientError } from './core/classes.error.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUVuRSxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQyJ9

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

@@ -0,0 +1,26 @@
+import * as plugins from './plugins.js';
+import type { SmartdataCollection } from './classes.collection.js';
+import { type TSmartdataOrdinarySession } from './classes.session.js';
+/**
+ * Executes a model-validated atomic delete against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicDelete()` owns the
+ * public API and must validate every filter before calling this raw persistence
+ * boundary.
+ */
+export declare const executeAtomicDelete: <T>(collectionArg: SmartdataCollection<T>, filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>, optsArg?: {
+    session?: TSmartdataOrdinarySession;
+    timeoutMS?: number;
+}) => Promise<plugins.mongodb.DeleteResult>;
+/**
+ * Executes a model-validated atomic delete-many against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicDeleteMany()` owns
+ * the public API and must validate every filter before calling this raw
+ * persistence boundary. Each matched document is deleted atomically; the
+ * batch as a whole is not isolated.
+ */
+export declare const executeAtomicDeleteMany: <T>(collectionArg: SmartdataCollection<T>, filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>, optsArg?: {
+    session?: TSmartdataOrdinarySession;
+    timeoutMS?: number;
+}) => Promise<plugins.mongodb.DeleteResult>;

package/dist_ts/nosqldb/classes.atomicdelete.js

@@ -0,0 +1,44 @@
+import * as plugins from './plugins.js';
+import { runWithOrdinarySmartdataSession, } from './classes.session.js';
+/**
+ * Executes a model-validated atomic delete against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicDelete()` owns the
+ * public API and must validate every filter before calling this raw persistence
+ * boundary.
+ */
+export const executeAtomicDelete = async (collectionArg, filterArg, optsArg) => {
+    return runWithOrdinarySmartdataSession(optsArg?.session, collectionArg.smartdataDb, {
+        ordinaryWrite: true,
+        prepared: collectionArg.isInitializedForCurrentDatabase(),
+        preparationMessage: `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    }, async (rawSessionArg) => {
+        await collectionArg.init();
+        return collectionArg.mongoDbCollection.deleteOne(filterArg, {
+            session: rawSessionArg,
+            timeoutMS: optsArg?.timeoutMS,
+        });
+    });
+};
+/**
+ * Executes a model-validated atomic delete-many against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicDeleteMany()` owns
+ * the public API and must validate every filter before calling this raw
+ * persistence boundary. Each matched document is deleted atomically; the
+ * batch as a whole is not isolated.
+ */
+export const executeAtomicDeleteMany = async (collectionArg, filterArg, optsArg) => {
+    return runWithOrdinarySmartdataSession(optsArg?.session, collectionArg.smartdataDb, {
+        ordinaryWrite: true,
+        prepared: collectionArg.isInitializedForCurrentDatabase(),
+        preparationMessage: `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    }, async (rawSessionArg) => {
+        await collectionArg.init();
+        return collectionArg.mongoDbCollection.deleteMany(filterArg, {
+            session: rawSessionArg,
+            timeoutMS: optsArg?.timeoutMS,
+        });
+    });
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5hdG9taWNkZWxldGUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9ub3NxbGRiL2NsYXNzZXMuYXRvbWljZGVsZXRlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBRXhDLE9BQU8sRUFDTCwrQkFBK0IsR0FFaEMsTUFBTSxzQkFBc0IsQ0FBQztBQUU5Qjs7Ozs7O0dBTUc7QUFDSCxNQUFNLENBQUMsTUFBTSxtQkFBbUIsR0FBRyxLQUFLLEVBQ3RDLGFBQXFDLEVBQ3JDLFNBQTJELEVBQzNELE9BR0MsRUFDc0MsRUFBRTtJQUN6QyxPQUFPLCtCQUErQixDQUNwQyxPQUFPLEVBQUUsT0FBTyxFQUNoQixhQUFhLENBQUMsV0FBVyxFQUN6QjtRQUNFLGFBQWEsRUFBRSxJQUFJO1FBQ25CLFFBQVEsRUFBRSxhQUFhLENBQUMsK0JBQStCLEVBQUU7UUFDekQsa0JBQWtCLEVBQ2hCLDBCQUEwQixhQUFhLENBQUMsY0FBYyw0Q0FBNEM7S0FDckcsRUFDRCxLQUFLLEVBQUUsYUFBYSxFQUFFLEVBQUU7UUFDdEIsTUFBTSxhQUFhLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDM0IsT0FBTyxhQUFhLENBQUMsaUJBQWlCLENBQUMsU0FBUyxDQUM5QyxTQUFTLEVBQ1Q7WUFDRSxPQUFPLEVBQUUsYUFBYTtZQUN0QixTQUFTLEVBQUUsT0FBTyxFQUFFLFNBQVM7U0FDOUIsQ0FDRixDQUFDO0lBQ0osQ0FBQyxDQUNGLENBQUM7QUFDSixDQUFDLENBQUM7QUFFRjs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQUcsS0FBSyxFQUMxQyxhQUFxQyxFQUNyQyxTQUEyRCxFQUMzRCxPQUdDLEVBQ3NDLEVBQUU7SUFDekMsT0FBTywrQkFBK0IsQ0FDcEMsT0FBTyxFQUFFLE9BQU8sRUFDaEIsYUFBYSxDQUFDLFdBQVcsRUFDekI7UUFDRSxhQUFhLEVBQUUsSUFBSTtRQUNuQixRQUFRLEVBQUUsYUFBYSxDQUFDLCtCQUErQixFQUFFO1FBQ3pELGtCQUFrQixFQUNoQiwwQkFBMEIsYUFBYSxDQUFDLGNBQWMsNENBQTRDO0tBQ3JHLEVBQ0QsS0FBSyxFQUFFLGFBQWEsRUFBRSxFQUFFO1FBQ3RCLE1BQU0sYUFBYSxDQUFDLElBQUksRUFBRSxDQUFDO1FBQzNCLE9BQU8sYUFBYSxDQUFDLGlCQUFpQixDQUFDLFVBQVUsQ0FDL0MsU0FBUyxFQUNUO1lBQ0UsT0FBTyxFQUFFLGFBQWE7WUFDdEIsU0FBUyxFQUFFLE9BQU8sRUFBRSxTQUFTO1NBQzlCLENBQ0YsQ0FBQztJQUNKLENBQUMsQ0FDRixDQUFDO0FBQ0osQ0FBQyxDQUFDIn0=

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

@@ -0,0 +1,27 @@
+import * as plugins from './plugins.js';
+import type { SmartdataCollection } from './classes.collection.js';
+import { type TSmartdataOrdinarySession } from './classes.session.js';
+type TRawDocument = plugins.mongodb.WithId<plugins.mongodb.Document>;
+export type TAtomicFindOneAndUpdateExecutionResult = {
+    status: 'matched';
+    document: TRawDocument;
+} | {
+    status: 'upserted';
+    document: TRawDocument | null;
+} | {
+    status: 'not_matched';
+    document: null;
+};
+/**
+ * Executes a model-validated atomic find-one-and-update against MongoDB.
+ *
+ * This helper is package-internal. It classifies driver metadata before
+ * returning and never exposes a MongoDB ModifyResult to the public model API.
+ */
+export declare const executeAtomicFindOneAndUpdate: <T>(collectionArg: SmartdataCollection<T>, filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>, updateArg: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>, optionsArg: {
+    returnDocument: "before" | "after";
+    upsert: boolean;
+    sort?: Record<string, 1 | -1>;
+    session?: TSmartdataOrdinarySession;
+}) => Promise<TAtomicFindOneAndUpdateExecutionResult>;
+export {};

package/dist_ts/nosqldb/classes.atomicfindoneandupdate.js

@@ -0,0 +1,86 @@
+import * as plugins from './plugins.js';
+import { normalizeOrdinaryPersistenceError, SmartdataPersistenceError, } from './classes.persistence.js';
+import { runWithOrdinarySmartdataSession, isSmartdataSession, failSmartdataTransaction, } from './classes.session.js';
+import { validateOrdinaryStoredDocument } from './classes.ordinarypersistence.js';
+const unsupportedResult = () => {
+    throw new SmartdataPersistenceError('unsupported_operation', 'MongoDB returned unsupported atomic find-one-and-update metadata.');
+};
+const classifyResult = (resultArg, optionsArg) => {
+    const metadata = resultArg.lastErrorObject;
+    if (resultArg.ok !== 1 || !metadata)
+        return unsupportedResult();
+    const hasUpserted = Object.prototype.hasOwnProperty.call(metadata, 'upserted');
+    const upserted = metadata.upserted;
+    if (metadata.n === 1
+        && metadata.updatedExisting === true
+        && !hasUpserted
+        && resultArg.value !== null) {
+        return { status: 'matched', document: resultArg.value };
+    }
+    if (optionsArg.upsert
+        && metadata.n === 1
+        && metadata.updatedExisting === false
+        && hasUpserted
+        && upserted !== undefined
+        && upserted !== null
+        && ((optionsArg.returnDocument === 'before' && resultArg.value === null)
+            || (optionsArg.returnDocument === 'after' && resultArg.value !== null))) {
+        return { status: 'upserted', document: resultArg.value };
+    }
+    if (!optionsArg.upsert
+        && metadata.n === 0
+        && metadata.updatedExisting === false
+        && !hasUpserted
+        && resultArg.value === null) {
+        return { status: 'not_matched', document: null };
+    }
+    return unsupportedResult();
+};
+/**
+ * Executes a model-validated atomic find-one-and-update against MongoDB.
+ *
+ * This helper is package-internal. It classifies driver metadata before
+ * returning and never exposes a MongoDB ModifyResult to the public model API.
+ */
+export const executeAtomicFindOneAndUpdate = async (collectionArg, filterArg, updateArg, optionsArg) => {
+    const policy = collectionArg.getBoundModelSchema()?.ordinaryPersistence;
+    if (policy && (!isSmartdataSession(optionsArg.session) || optionsArg.returnDocument !== 'after')) {
+        throw new SmartdataPersistenceError('unsupported_operation', 'Validated ordinary updates require an owned transaction and an after image.');
+    }
+    return runWithOrdinarySmartdataSession(optionsArg.session, collectionArg.smartdataDb, {
+        ordinaryWrite: true,
+        prepared: collectionArg.isInitializedForCurrentDatabase(),
+        preparationMessage: `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    }, async (rawSessionArg) => {
+        if (policy && !rawSessionArg?.inTransaction()) {
+            throw new SmartdataPersistenceError('unsupported_operation', 'Validated ordinary updates require an active owned transaction.');
+        }
+        await collectionArg.init();
+        try {
+            const result = await collectionArg.mongoDbCollection.findOneAndUpdate(filterArg, updateArg, {
+                includeResultMetadata: true,
+                returnDocument: optionsArg.returnDocument,
+                upsert: optionsArg.upsert,
+                ...(optionsArg.sort ? { sort: optionsArg.sort } : {}),
+                session: rawSessionArg,
+            });
+            try {
+                const classified = classifyResult(result, optionsArg);
+                if (policy && classified.document) {
+                    classified.document = validateOrdinaryStoredDocument(classified.document, policy, collectionArg.getBoundModelSchema().persistedFields);
+                }
+                return classified;
+            }
+            catch (errorArg) {
+                if (policy) {
+                    failSmartdataTransaction(optionsArg.session, collectionArg.smartdataDb, errorArg);
+                }
+                throw errorArg;
+            }
+        }
+        catch (errorArg) {
+            return normalizeOrdinaryPersistenceError(errorArg, `Atomic find-one-and-update conflicts with a unique index in collection "${collectionArg.collectionName}".`);
+        }
+    });
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5hdG9taWNmaW5kb25lYW5kdXBkYXRlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvbm9zcWxkYi9jbGFzc2VzLmF0b21pY2ZpbmRvbmVhbmR1cGRhdGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFFeEMsT0FBTyxFQUNMLGlDQUFpQyxFQUNqQyx5QkFBeUIsR0FDMUIsTUFBTSwwQkFBMEIsQ0FBQztBQUNsQyxPQUFPLEVBQ0wsK0JBQStCLEVBQy9CLGtCQUFrQixFQUNsQix3QkFBd0IsR0FHekIsTUFBTSxzQkFBc0IsQ0FBQztBQUM5QixPQUFPLEVBQUUsOEJBQThCLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQVNsRixNQUFNLGlCQUFpQixHQUFHLEdBQVUsRUFBRTtJQUNwQyxNQUFNLElBQUkseUJBQXlCLENBQ2pDLHVCQUF1QixFQUN2QixtRUFBbUUsQ0FDcEUsQ0FBQztBQUNKLENBQUMsQ0FBQztBQUVGLE1BQU0sY0FBYyxHQUFHLENBQ3JCLFNBQWlFLEVBQ2pFLFVBR0MsRUFDdUMsRUFBRTtJQUMxQyxNQUFNLFFBQVEsR0FBRyxTQUFTLENBQUMsZUFBZSxDQUFDO0lBQzNDLElBQUksU0FBUyxDQUFDLEVBQUUsS0FBSyxDQUFDLElBQUksQ0FBQyxRQUFRO1FBQUUsT0FBTyxpQkFBaUIsRUFBRSxDQUFDO0lBQ2hFLE1BQU0sV0FBVyxHQUFHLE1BQU0sQ0FBQyxTQUFTLENBQUMsY0FBYyxDQUFDLElBQUksQ0FBQyxRQUFRLEVBQUUsVUFBVSxDQUFDLENBQUM7SUFDL0UsTUFBTSxRQUFRLEdBQUcsUUFBUSxDQUFDLFFBQVEsQ0FBQztJQUVuQyxJQUNFLFFBQVEsQ0FBQyxDQUFDLEtBQUssQ0FBQztXQUNiLFFBQVEsQ0FBQyxlQUFlLEtBQUssSUFBSTtXQUNqQyxDQUFDLFdBQVc7V0FDWixTQUFTLENBQUMsS0FBSyxLQUFLLElBQUksRUFDM0IsQ0FBQztRQUNELE9BQU8sRUFBRSxNQUFNLEVBQUUsU0FBUyxFQUFFLFFBQVEsRUFBRSxTQUFTLENBQUMsS0FBSyxFQUFFLENBQUM7SUFDMUQsQ0FBQztJQUVELElBQ0UsVUFBVSxDQUFDLE1BQU07V0FDZCxRQUFRLENBQUMsQ0FBQyxLQUFLLENBQUM7V0FDaEIsUUFBUSxDQUFDLGVBQWUsS0FBSyxLQUFLO1dBQ2xDLFdBQVc7V0FDWCxRQUFRLEtBQUssU0FBUztXQUN0QixRQUFRLEtBQUssSUFBSTtXQUNqQixDQUNELENBQUMsVUFBVSxDQUFDLGNBQWMsS0FBSyxRQUFRLElBQUksU0FBUyxDQUFDLEtBQUssS0FBSyxJQUFJLENBQUM7ZUFDakUsQ0FBQyxVQUFVLENBQUMsY0FBYyxLQUFLLE9BQU8sSUFBSSxTQUFTLENBQUMsS0FBSyxLQUFLLElBQUksQ0FBQyxDQUN2RSxFQUNELENBQUM7UUFDRCxPQUFPLEVBQUUsTUFBTSxFQUFFLFVBQVUsRUFBRSxRQUFRLEVBQUUsU0FBUyxDQUFDLEtBQUssRUFBRSxDQUFDO0lBQzNELENBQUM7SUFFRCxJQUNFLENBQUMsVUFBVSxDQUFDLE1BQU07V0FDZixRQUFRLENBQUMsQ0FBQyxLQUFLLENBQUM7V0FDaEIsUUFBUSxDQUFDLGVBQWUsS0FBSyxLQUFLO1dBQ2xDLENBQUMsV0FBVztXQUNaLFNBQVMsQ0FBQyxLQUFLLEtBQUssSUFBSSxFQUMzQixDQUFDO1FBQ0QsT0FBTyxFQUFFLE1BQU0sRUFBRSxhQUFhLEVBQUUsUUFBUSxFQUFFLElBQUksRUFBRSxDQUFDO0lBQ25ELENBQUM7SUFFRCxPQUFPLGlCQUFpQixFQUFFLENBQUM7QUFDN0IsQ0FBQyxDQUFDO0FBRUY7Ozs7O0dBS0c7QUFDSCxNQUFNLENBQUMsTUFBTSw2QkFBNkIsR0FBRyxLQUFLLEVBQ2hELGFBQXFDLEVBQ3JDLFNBQTJELEVBQzNELFNBQWlFLEVBQ2pFLFVBS0MsRUFDZ0QsRUFBRTtJQUNuRCxNQUFNLE1BQU0sR0FBRyxhQUFhLENBQUMsbUJBQW1CLEVBQUUsRUFBRSxtQkFBbUIsQ0FBQztJQUN4RSxJQUFJLE1BQU0sSUFBSSxDQUFDLENBQUMsa0JBQWtCLENBQUMsVUFBVSxDQUFDLE9BQU8sQ0FBQyxJQUFJLFVBQVUsQ0FBQyxjQUFjLEtBQUssT0FBTyxDQUFDLEVBQUUsQ0FBQztRQUNqRyxNQUFNLElBQUkseUJBQXlCLENBQUMsdUJBQXVCLEVBQ3pELDZFQUE2RSxDQUFDLENBQUM7SUFDbkYsQ0FBQztJQUNELE9BQU8sK0JBQStCLENBQ3BDLFVBQVUsQ0FBQyxPQUFPLEVBQ2xCLGFBQWEsQ0FBQyxXQUFXLEVBQ3pCO1FBQ0UsYUFBYSxFQUFFLElBQUk7UUFDbkIsUUFBUSxFQUFFLGFBQWEsQ0FBQywrQkFBK0IsRUFBRTtRQUN6RCxrQkFBa0IsRUFDaEIsMEJBQTBCLGFBQWEsQ0FBQyxjQUFjLDRDQUE0QztLQUNyRyxFQUNELEtBQUssRUFBRSxhQUFhLEVBQUUsRUFBRTtRQUN0QixJQUFJLE1BQU0sSUFBSSxDQUFDLGFBQWEsRUFBRSxhQUFhLEVBQUUsRUFBRSxDQUFDO1lBQzlDLE1BQU0sSUFBSSx5QkFBeUIsQ0FBQyx1QkFBdUIsRUFDekQsaUVBQWlFLENBQUMsQ0FBQztRQUN2RSxDQUFDO1FBQ0QsTUFBTSxhQUFhLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDM0IsSUFBSSxDQUFDO1lBQ0gsTUFBTSxNQUFNLEdBQUcsTUFBTSxhQUFhLENBQUMsaUJBQWlCLENBQUMsZ0JBQWdCLENBQ25FLFNBQVMsRUFDVCxTQUFTLEVBQ1Q7Z0JBQ0UscUJBQXFCLEVBQUUsSUFBSTtnQkFDM0IsY0FBYyxFQUFFLFVBQVUsQ0FBQyxjQUFjO2dCQUN6QyxNQUFNLEVBQUUsVUFBVSxDQUFDLE1BQU07Z0JBQ3pCLEdBQUcsQ0FBQyxVQUFVLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxFQUFFLElBQUksRUFBRSxVQUFVLENBQUMsSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztnQkFDckQsT0FBTyxFQUFFLGFBQWE7YUFDdkIsQ0FDRixDQUFDO1lBQ0YsSUFBSSxDQUFDO2dCQUNILE1BQU0sVUFBVSxHQUFHLGNBQWMsQ0FBQyxNQUFNLEVBQUUsVUFBVSxDQUFDLENBQUM7Z0JBQ3RELElBQUksTUFBTSxJQUFJLFVBQVUsQ0FBQyxRQUFRLEVBQUUsQ0FBQztvQkFDbEMsVUFBVSxDQUFDLFFBQVEsR0FBRyw4QkFBOEIsQ0FDbEQsVUFBVSxDQUFDLFFBQVEsRUFBRSxNQUFNLEVBQUUsYUFBYSxDQUFDLG1CQUFtQixFQUFHLENBQUMsZUFBZSxDQUNsRSxDQUFDO2dCQUNwQixDQUFDO2dCQUNELE9BQU8sVUFBVSxDQUFDO1lBQ3BCLENBQUM7WUFBQyxPQUFPLFFBQVEsRUFBRSxDQUFDO2dCQUNsQixJQUFJLE1BQU0sRUFBRSxDQUFDO29CQUNYLHdCQUF3QixDQUN0QixVQUFVLENBQUMsT0FBMkIsRUFBRSxhQUFhLENBQUMsV0FBVyxFQUFFLFFBQVEsQ0FDNUUsQ0FBQztnQkFDSixDQUFDO2dCQUNELE1BQU0sUUFBUSxDQUFDO1lBQ2pCLENBQUM7UUFDSCxDQUFDO1FBQUMsT0FBTyxRQUFRLEVBQUUsQ0FBQztZQUNsQixPQUFPLGlDQUFpQyxDQUN0QyxRQUFRLEVBQ1IsMkVBQTJFLGFBQWEsQ0FBQyxjQUFjLElBQUksQ0FDNUcsQ0FBQztRQUNKLENBQUM7SUFDSCxDQUFDLENBQ0YsQ0FBQztBQUNKLENBQUMsQ0FBQyJ9

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

@@ -0,0 +1,26 @@
+import * as plugins from './plugins.js';
+import type { SmartdataCollection } from './classes.collection.js';
+import { type TSmartdataOrdinarySession } from './classes.session.js';
+/**
+ * Executes a model-validated atomic update against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicUpdate()` owns the
+ * public API and must validate and normalize every filter and update before
+ * calling this raw persistence boundary.
+ */
+export declare const executeAtomicUpdate: <T>(collectionArg: SmartdataCollection<T>, filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>, updateArg: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>, optsArg?: {
+    upsert?: boolean;
+    session?: TSmartdataOrdinarySession;
+}) => Promise<plugins.mongodb.UpdateResult>;
+/**
+ * Executes a model-validated atomic update-many against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicUpdateMany()` owns
+ * the public API and must validate and normalize every filter and update
+ * before calling this raw persistence boundary. Each matched document is
+ * updated atomically; the batch as a whole is not isolated and no upsert is
+ * possible.
+ */
+export declare const executeAtomicUpdateMany: <T>(collectionArg: SmartdataCollection<T>, filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>, updateArg: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>, optsArg?: {
+    session?: TSmartdataOrdinarySession;
+}) => Promise<plugins.mongodb.UpdateResult>;