@lossless.org/client 0.1.1 → 1.1.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@lossless.org/client',
-    version: '0.1.1',
+    version: '1.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/core/drivers.d.ts

@@ -0,0 +1,17 @@
+import type { TBackend } from './interfaces.js';
+/** Backends whose driver package ships as an optional peer dependency instead of a dependency. */
+export type TOptionalDriverBackend = Extract<TBackend, 'mariadb' | 'clickhouse' | 's3'>;
+export interface IOptionalDriver {
+    /** npm package the consumer installs. */
+    readonly package: string;
+    /** Entry point that needs it, so the refusal names the import the consumer already wrote. */
+    readonly subpath: string;
+    /** Connections the driver enables, phrased as the aggregate client configuration names them. */
+    readonly usage: string;
+}
+export declare const optionalDrivers: Readonly<Record<TOptionalDriverBackend, IOptionalDriver>>;
+/**
+ * Rejection handler for a lazy family import. An absent optional driver becomes an instruction naming the package and
+ * the entry point; every other failure keeps its original identity so real load errors stay visible.
+ */
+export declare const requireDriver: (backend: TOptionalDriverBackend) => (error: unknown) => never;

package/dist_ts/core/drivers.js

@@ -0,0 +1,27 @@
+import { LosslessClientError } from './classes.error.js';
+export const optionalDrivers = Object.freeze({
+    mariadb: { package: 'mariadb', subpath: '@lossless.org/client/sqldb',
+        usage: 'sqldb connections with backend "sqldb" or "mariadb"' },
+    clickhouse: { package: '@clickhouse/client', subpath: '@lossless.org/client/sqldb',
+        usage: 'sqldb connections with backend "clickhouse"' },
+    s3: { package: '@aws-sdk/client-s3', subpath: '@lossless.org/client/objectstorage',
+        usage: 'objectstorage connections with backend "s3"' },
+});
+/** Node names the unresolved package in its message; anything else is a defect of this package, not a missing install. */
+const isUninstalled = (error, packageName) => {
+    const details = error;
+    return !!details && details.code === 'ERR_MODULE_NOT_FOUND' &&
+        typeof details.message === 'string' && details.message.includes(`'${packageName}'`);
+};
+/**
+ * Rejection handler for a lazy family import. An absent optional driver becomes an instruction naming the package and
+ * the entry point; every other failure keeps its original identity so real load errors stay visible.
+ */
+export const requireDriver = (backend) => (error) => {
+    const driver = optionalDrivers[backend];
+    if (!isUninstalled(error, driver.package))
+        throw error;
+    throw new LosslessClientError('driver_missing', `Install the optional peer dependency "${driver.package}" to use ${driver.usage} (${driver.subpath}). ` +
+        `Run: pnpm add ${driver.package}`, { cause: error, retryability: 'permanent' });
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZHJpdmVycy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2NvcmUvZHJpdmVycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQWV6RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQThELE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDdEcsT0FBTyxFQUFFLEVBQUUsT0FBTyxFQUFFLFNBQVMsRUFBRSxPQUFPLEVBQUUsNEJBQTRCO1FBQ2xFLEtBQUssRUFBRSxxREFBcUQsRUFBRTtJQUNoRSxVQUFVLEVBQUUsRUFBRSxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsT0FBTyxFQUFFLDRCQUE0QjtRQUNoRixLQUFLLEVBQUUsNkNBQTZDLEVBQUU7SUFDeEQsRUFBRSxFQUFFLEVBQUUsT0FBTyxFQUFFLG9CQUFvQixFQUFFLE9BQU8sRUFBRSxvQ0FBb0M7UUFDaEYsS0FBSyxFQUFFLDZDQUE2QyxFQUFFO0NBQ3pELENBQUMsQ0FBQztBQUVILDBIQUEwSDtBQUMxSCxNQUFNLGFBQWEsR0FBRyxDQUFDLEtBQWMsRUFBRSxXQUFtQixFQUFXLEVBQUU7SUFDckUsTUFBTSxPQUFPLEdBQUcsS0FBaUUsQ0FBQztJQUNsRixPQUFPLENBQUMsQ0FBQyxPQUFPLElBQUksT0FBTyxDQUFDLElBQUksS0FBSyxzQkFBc0I7UUFDekQsT0FBTyxPQUFPLENBQUMsT0FBTyxLQUFLLFFBQVEsSUFBSSxPQUFPLENBQUMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJLFdBQVcsR0FBRyxDQUFDLENBQUM7QUFDeEYsQ0FBQyxDQUFDO0FBRUY7OztHQUdHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLENBQUMsT0FBK0IsRUFBRSxFQUFFLENBQUMsQ0FBQyxLQUFjLEVBQVMsRUFBRTtJQUMxRixNQUFNLE1BQU0sR0FBRyxlQUFlLENBQUMsT0FBTyxDQUFDLENBQUM7SUFDeEMsSUFBSSxDQUFDLGFBQWEsQ0FBQyxLQUFLLEVBQUUsTUFBTSxDQUFDLE9BQU8sQ0FBQztRQUFFLE1BQU0sS0FBSyxDQUFDO0lBQ3ZELE1BQU0sSUFBSSxtQkFBbUIsQ0FBQyxnQkFBZ0IsRUFDNUMseUNBQXlDLE1BQU0sQ0FBQyxPQUFPLFlBQVksTUFBTSxDQUFDLEtBQUssS0FBSyxNQUFNLENBQUMsT0FBTyxLQUFLO1FBQ3ZHLGlCQUFpQixNQUFNLENBQUMsT0FBTyxFQUFFLEVBQ2pDLEVBQUUsS0FBSyxFQUFFLEtBQUssRUFBRSxZQUFZLEVBQUUsV0FBVyxFQUFFLENBQUMsQ0FBQztBQUNqRCxDQUFDLENBQUMifQ==

package/dist_ts/core/interfaces.d.ts

@@ -15,4 +15,4 @@ 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';
+export type TClientErrorCode = 'invalid_argument' | 'unsupported_capability' | 'driver_missing' | 'not_connected' | 'closed' | 'timeout' | 'cancelled' | 'result_limit' | 'authentication' | 'conflict' | 'backend_error' | 'ambiguous_write' | 'partial_write';

package/dist_ts/index.d.ts

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

package/dist_ts/index.js

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

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

@@ -12,6 +12,27 @@ export declare const executeAtomicUpdate: <T>(collectionArg: SmartdataCollection
     upsert?: boolean;
     session?: TSmartdataOrdinarySession;
 }) => Promise<plugins.mongodb.UpdateResult>;
+/**
+ * Executes a bounded batch of model-validated atomic upserts against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicUpsertMany()` owns the
+ * public API and must validate and normalize every filter and update before
+ * calling this raw persistence boundary. Each entry applies atomically; the
+ * batch as a whole is not isolated unless the caller supplies a transaction
+ * session.
+ */
+export declare const executeAtomicUpsertMany: <T>(collectionArg: SmartdataCollection<T>, operationsArg: ReadonlyArray<{
+    filter: plugins.mongodb.Filter<plugins.mongodb.Document>;
+    update: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>;
+}>, optsArg?: {
+    session?: TSmartdataOrdinarySession;
+    timeoutMS?: number;
+}) => Promise<{
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+    upsertedCount: number;
+}>;
 /**
  * Executes a model-validated atomic update-many against MongoDB.
  *

package/dist_ts/nosqldb/classes.atomicupdate.js

@@ -26,6 +26,46 @@ export const executeAtomicUpdate = async (collectionArg, filterArg, updateArg, o
         }
     });
 };
+/**
+ * Executes a bounded batch of model-validated atomic upserts against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicUpsertMany()` owns the
+ * public API and must validate and normalize every filter and update before
+ * calling this raw persistence boundary. Each entry applies atomically; the
+ * batch as a whole is not isolated unless the caller supplies a transaction
+ * session.
+ */
+export const executeAtomicUpsertMany = async (collectionArg, operationsArg, 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();
+        try {
+            const result = await collectionArg.mongoDbCollection.bulkWrite(operationsArg.map((operationArg) => ({
+                updateOne: {
+                    filter: operationArg.filter,
+                    update: operationArg.update,
+                    upsert: true,
+                },
+            })), {
+                ordered: false,
+                session: rawSessionArg,
+                timeoutMS: optsArg?.timeoutMS,
+            });
+            return {
+                acknowledged: result.isOk(),
+                matchedCount: result.matchedCount,
+                modifiedCount: result.modifiedCount,
+                upsertedCount: result.upsertedCount,
+            };
+        }
+        catch (errorArg) {
+            return normalizeOrdinaryPersistenceError(errorArg, `Atomic upsert-many conflicts with a unique index in collection "${collectionArg.collectionName}".`);
+        }
+    });
+};
 /**
  * Executes a model-validated atomic update-many against MongoDB.
  *
@@ -52,4 +92,4 @@ export const executeAtomicUpdateMany = async (collectionArg, filterArg, updateAr
         }
     });
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5hdG9taWN1cGRhdGUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9ub3NxbGRiL2NsYXNzZXMuYXRvbWljdXBkYXRlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBRXhDLE9BQU8sRUFBRSxpQ0FBaUMsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBQzdFLE9BQU8sRUFDTCwrQkFBK0IsR0FFaEMsTUFBTSxzQkFBc0IsQ0FBQztBQUU5Qjs7Ozs7O0dBTUc7QUFDSCxNQUFNLENBQUMsTUFBTSxtQkFBbUIsR0FBRyxLQUFLLEVBQ3RDLGFBQXFDLEVBQ3JDLFNBQTJELEVBQzNELFNBQWlFLEVBQ2pFLE9BR0MsRUFDc0MsRUFBRTtJQUN6QyxPQUFPLCtCQUErQixDQUNwQyxPQUFPLEVBQUUsT0FBTyxFQUNoQixhQUFhLENBQUMsV0FBVyxFQUN6QjtRQUNFLGFBQWEsRUFBRSxJQUFJO1FBQ25CLFFBQVEsRUFBRSxhQUFhLENBQUMsK0JBQStCLEVBQUU7UUFDekQsa0JBQWtCLEVBQ2hCLDBCQUEwQixhQUFhLENBQUMsY0FBYyw0Q0FBNEM7S0FDckcsRUFDRCxLQUFLLEVBQUUsYUFBYSxFQUFFLEVBQUU7UUFDdEIsTUFBTSxhQUFhLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDM0IsSUFBSSxDQUFDO1lBQ0gsT0FBTyxNQUFNLGFBQWEsQ0FBQyxpQkFBaUIsQ0FBQyxTQUFTLENBQ3BELFNBQVMsRUFDVCxTQUFTLEVBQ1Q7Z0JBQ0UsTUFBTSxFQUFFLE9BQU8sRUFBRSxNQUFNLEtBQUssSUFBSTtnQkFDaEMsT0FBTyxFQUFFLGFBQWE7YUFDdkIsQ0FDRixDQUFDO1FBQ0osQ0FBQztRQUFDLE9BQU8sUUFBUSxFQUFFLENBQUM7WUFDbEIsT0FBTyxpQ0FBaUMsQ0FDdEMsUUFBUSxFQUNSLDhEQUE4RCxhQUFhLENBQUMsY0FBYyxJQUFJLENBQy9GLENBQUM7UUFDSixDQUFDO0lBQ0gsQ0FBQyxDQUNGLENBQUM7QUFDSixDQUFDLENBQUM7QUFFRjs7Ozs7Ozs7R0FRRztBQUNILE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLEtBQUssRUFDMUMsYUFBcUMsRUFDckMsU0FBMkQsRUFDM0QsU0FBaUUsRUFDakUsT0FFQyxFQUNzQyxFQUFFO0lBQ3pDLE9BQU8sK0JBQStCLENBQ3BDLE9BQU8sRUFBRSxPQUFPLEVBQ2hCLGFBQWEsQ0FBQyxXQUFXLEVBQ3pCO1FBQ0UsYUFBYSxFQUFFLElBQUk7UUFDbkIsUUFBUSxFQUFFLGFBQWEsQ0FBQywrQkFBK0IsRUFBRTtRQUN6RCxrQkFBa0IsRUFDaEIsMEJBQTBCLGFBQWEsQ0FBQyxjQUFjLDRDQUE0QztLQUNyRyxFQUNELEtBQUssRUFBRSxhQUFhLEVBQUUsRUFBRTtRQUN0QixNQUFNLGFBQWEsQ0FBQyxJQUFJLEVBQUUsQ0FBQztRQUMzQixJQUFJLENBQUM7WUFDSCxPQUFPLE1BQU0sYUFBYSxDQUFDLGlCQUFpQixDQUFDLFVBQVUsQ0FDckQsU0FBUyxFQUNULFNBQVMsRUFDVDtnQkFDRSxPQUFPLEVBQUUsYUFBYTthQUN2QixDQUNGLENBQUM7UUFDSixDQUFDO1FBQUMsT0FBTyxRQUFRLEVBQUUsQ0FBQztZQUNsQixPQUFPLGlDQUFpQyxDQUN0QyxRQUFRLEVBQ1IsbUVBQW1FLGFBQWEsQ0FBQyxjQUFjLElBQUksQ0FDcEcsQ0FBQztRQUNKLENBQUM7SUFDSCxDQUFDLENBQ0YsQ0FBQztBQUNKLENBQUMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5hdG9taWN1cGRhdGUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9ub3NxbGRiL2NsYXNzZXMuYXRvbWljdXBkYXRlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBRXhDLE9BQU8sRUFBRSxpQ0FBaUMsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBQzdFLE9BQU8sRUFDTCwrQkFBK0IsR0FFaEMsTUFBTSxzQkFBc0IsQ0FBQztBQUU5Qjs7Ozs7O0dBTUc7QUFDSCxNQUFNLENBQUMsTUFBTSxtQkFBbUIsR0FBRyxLQUFLLEVBQ3RDLGFBQXFDLEVBQ3JDLFNBQTJELEVBQzNELFNBQWlFLEVBQ2pFLE9BR0MsRUFDc0MsRUFBRTtJQUN6QyxPQUFPLCtCQUErQixDQUNwQyxPQUFPLEVBQUUsT0FBTyxFQUNoQixhQUFhLENBQUMsV0FBVyxFQUN6QjtRQUNFLGFBQWEsRUFBRSxJQUFJO1FBQ25CLFFBQVEsRUFBRSxhQUFhLENBQUMsK0JBQStCLEVBQUU7UUFDekQsa0JBQWtCLEVBQ2hCLDBCQUEwQixhQUFhLENBQUMsY0FBYyw0Q0FBNEM7S0FDckcsRUFDRCxLQUFLLEVBQUUsYUFBYSxFQUFFLEVBQUU7UUFDdEIsTUFBTSxhQUFhLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDM0IsSUFBSSxDQUFDO1lBQ0gsT0FBTyxNQUFNLGFBQWEsQ0FBQyxpQkFBaUIsQ0FBQyxTQUFTLENBQ3BELFNBQVMsRUFDVCxTQUFTLEVBQ1Q7Z0JBQ0UsTUFBTSxFQUFFLE9BQU8sRUFBRSxNQUFNLEtBQUssSUFBSTtnQkFDaEMsT0FBTyxFQUFFLGFBQWE7YUFDdkIsQ0FDRixDQUFDO1FBQ0osQ0FBQztRQUFDLE9BQU8sUUFBUSxFQUFFLENBQUM7WUFDbEIsT0FBTyxpQ0FBaUMsQ0FDdEMsUUFBUSxFQUNSLDhEQUE4RCxhQUFhLENBQUMsY0FBYyxJQUFJLENBQy9GLENBQUM7UUFDSixDQUFD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

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

@@ -22,6 +22,14 @@ export interface ICollectionBindingOptions {
      * its legacy collection without changing stored data.
      */
     collectionName?: string;
+    /**
+     * Stores one declared `@unI()` string identity as the document `_id`, making
+     * the primary key itself the uniqueness authority. The field keeps its own
+     * stored value and receives no separate unique index. Irreversible for an
+     * existing collection: every stored document must already satisfy
+     * `_id === document[field]`.
+     */
+    identityAsDocumentId?: string;
 }
 export type TCollectionModelIndexDirection = 1 | -1 | 'text';
 export interface ICollectionModelIndexOptions {
@@ -63,6 +71,13 @@ export interface ICollectionModelConfig<TModel extends object = any> {
      * ascending unique index in `indexes`.
      */
     identityFields?: ReadonlyArray<TStringFieldKey<TModel>>;
+    /**
+     * Stores one declared string identity as the document `_id`. The primary key
+     * becomes the uniqueness authority, so the field must not declare its own
+     * unique index. Irreversible for an existing collection: every stored
+     * document must already satisfy `_id === document[field]`.
+     */
+    identityAsDocumentId?: TStringFieldKey<TModel>;
     /**
      * Persisted fields used by SmartData's search helpers.
      */
@@ -78,6 +93,8 @@ export interface INormalizedCollectionModelSchema {
     readonly persistedFields: readonly string[];
     readonly numericFields: readonly string[];
     readonly identityFields: readonly string[];
+    /** Declared identity field stored as the document `_id`, if any. */
+    readonly identityAsDocumentId?: string;
     readonly identityValueTypes: Readonly<Record<string, TSmartdataIdentityValueType>>;
     readonly searchableFields: readonly string[];
     readonly indexes: ReadonlyArray<{
@@ -111,6 +128,11 @@ type TCollectionModelConstructor<TModel extends SmartDataDbDoc<any, any>> = {
     name: string;
     prototype: TModel;
 };
+/**
+ * Returns the declared identity field a model stores as its document `_id`.
+ * Reading the bound schema resolver never resolves a database.
+ */
+export declare const getIdentityDocumentIdField: (modelArg: any) => string | undefined;
 /**
  * Programmatically declares and binds an ordinary SmartData model.
  *
@@ -229,6 +251,15 @@ export declare class SmartdataCollection<T> {
      * create an object in the database
      */
     private prepareOrdinaryInsert;
+    /**
+     * Keys a stored document by its declared identity when the model opted into
+     * `identityAsDocumentId`. The identity keeps its own stored field, but reads
+     * address `_id`, so a document written before the option was declared is
+     * reachable only if its `_id` already equals that identity.
+     */
+    private applyIdentityDocumentId;
+    /** True when stored documents need SmartData-owned preparation before a write. */
+    private get preparesStoredDocuments();
     insert(dbDocArg: T & SmartDataDbDoc<T, unknown>, opts?: {
         session?: TSmartdataOrdinarySession;
     }): Promise<any>;