@lossless.org/client 1.2.0 → 1.3.0

package/ts/nosqldb/classes.collection.ts

@@ -15,6 +15,7 @@ import { SmartdataDbCursor } from './classes.cursor.js';
 import {
   SmartDataDbDoc,
   type IIndexOptions,
+  type SvDbOptions,
   type TSmartdataNumericDocumentPath,
   type TSmartdataIdentityValueType,
 } from './classes.doc.js';
@@ -28,6 +29,7 @@ import {
 } from './classes.persistence.js';
 import { notifyCollectionReconnect } from './classes.collectionlifecycle.js';
 import {
+  leaseOrdinarySmartdataSession,
   runWithOrdinarySmartdataSession,
   type TSmartdataOrdinarySession,
 } from './classes.session.js';
@@ -69,6 +71,14 @@ export interface ICollectionBindingOptions {
    * `_id === document[field]`.
    */
   identityAsDocumentId?: string;
+  /**
+   * Names of installed indexes this model accepts without declaring them —
+   * typically migration-owned indexes SmartData does not express, such as
+   * partial or filtered unique indexes. A tolerated index is never created,
+   * never dropped and never verified beyond its name, and it no longer makes
+   * the collection topology divergent.
+   */
+  toleratedIndexNames?: ReadonlyArray<string>;
 }
 
 export type TCollectionModelIndexDirection = 1 | -1 | 'text';
@@ -112,6 +122,16 @@ export interface ICollectionModelConfig<TModel extends object = any> {
    * numeric-field constraint.
    */
   numericFields?: ReadonlyArray<TSmartdataNumericDocumentPath<TModel>>;
+  /**
+   * Persisted top-level fields that only atomic operations may overwrite. Every
+   * write that creates a document stores them — `insert()`, `insertMany()`,
+   * `insertManyIfAbsent()` and the insert branch of `save()` — and they read
+   * like any other declared field, but a `save()` that matches a stored
+   * document leaves them untouched, so a stale instance cannot overwrite a
+   * value concurrent atomic writers own. An identity field cannot be
+   * atomic-only.
+   */
+  atomicOnlyFields?: ReadonlyArray<keyof TModel & string>;
   /**
    * Persisted string identity fields with @unI()-equivalent selector and
    * immutability semantics. Each field requires an explicit single-field,
@@ -133,6 +153,15 @@ export interface ICollectionModelConfig<TModel extends object = any> {
    * Stable named MongoDB indexes. Object property order defines key order.
    */
   indexes?: ReadonlyArray<ICollectionModelIndex>;
+  /**
+   * Names of installed indexes this model does not declare but accepts —
+   * typically indexes a migration owns, such as partial or filtered unique
+   * indexes SmartData does not express. A tolerated index is never created,
+   * never dropped and never verified beyond its name, and it no longer makes
+   * the collection topology divergent. Every undeclared index outside this
+   * list still does.
+   */
+  toleratedIndexNames?: ReadonlyArray<string>;
 }
 
 export interface INormalizedCollectionModelSchema {
@@ -140,6 +169,8 @@ export interface INormalizedCollectionModelSchema {
   readonly collectionName: string;
   readonly persistedFields: readonly string[];
   readonly numericFields: readonly string[];
+  /** Declared persisted fields a matching instance `save()` never overwrites. */
+  readonly atomicOnlyFields: readonly string[];
   readonly identityFields: readonly string[];
   /** Declared identity field stored as the document `_id`, if any. */
   readonly identityAsDocumentId?: string;
@@ -154,6 +185,8 @@ export interface INormalizedCollectionModelSchema {
     >;
     readonly options: Readonly<IIndexOptions>;
   }>;
+  /** Undeclared installed indexes this model accepts by name, never touches. */
+  readonly toleratedIndexNames: readonly string[];
   readonly fingerprint: string;
 }
 
@@ -344,10 +377,12 @@ const normalizeCollectionModelSchema = (
     'collectionName',
     'persistedFields',
     'numericFields',
+    'atomicOnlyFields',
     'identityFields',
     'identityAsDocumentId',
     'searchableFields',
     'indexes',
+    'toleratedIndexNames',
   ]);
   for (const key of Object.keys(configArg)) {
     if (!allowedConfigKeys.has(key)) {
@@ -436,6 +471,37 @@ const normalizeCollectionModelSchema = (
       );
     }
   }
+  if (
+    configArg.atomicOnlyFields !== undefined &&
+    !Array.isArray(configArg.atomicOnlyFields)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model atomicOnlyFields must be an array.',
+    );
+  }
+  const atomicOnlyFields: string[] = [];
+  for (const field of configArg.atomicOnlyFields || []) {
+    requireSafeFieldName(field, 'An atomic-only field');
+    if (!persistedFields.includes(field)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Atomic-only field "${field}" is not a declared persisted field.`,
+      );
+    }
+    if (identityFields.includes(field)) {
+      // An identity is immutable and addresses the document, so it is written
+      // by the insert that creates it and by nothing else afterwards. Making
+      // it atomic-only would promise an atomic write that is always refused.
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Identity field "${field}" cannot be atomic-only.`,
+      );
+    }
+    if (!atomicOnlyFields.includes(field)) {
+      atomicOnlyFields.push(field);
+    }
+  }
   const identityValueTypes: Record<string, TSmartdataIdentityValueType> = {};
   for (const field of Object.keys(identityValueTypesArg || {})) {
     if (!identityFields.includes(field)) {
@@ -627,16 +693,55 @@ const normalizeCollectionModelSchema = (
       );
     }
   }
+  if (
+    configArg.toleratedIndexNames !== undefined &&
+    !Array.isArray(configArg.toleratedIndexNames)
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Collection model toleratedIndexNames must be an array.',
+    );
+  }
+  const toleratedIndexNames: string[] = [];
+  for (const name of configArg.toleratedIndexNames || []) {
+    if (typeof name !== 'string' || name.trim().length === 0 || name.includes('\0')) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Every tolerated index name must be a non-empty safe name.',
+      );
+    }
+    if (name === '_id_') {
+      // The primary-key index is verified for every collection; tolerating it
+      // would accept a changed _id index in silence.
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'Index name "_id_" cannot be tolerated; SmartData always verifies the primary-key index.',
+      );
+    }
+    if (indexesByName.has(name)) {
+      // A declared index is created and verified. Tolerating the same name
+      // would state both contracts for one index.
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index "${name}" cannot be tolerated and declared at the same time.`,
+      );
+    }
+    if (!toleratedIndexNames.includes(name)) {
+      toleratedIndexNames.push(name);
+    }
+  }
   const normalizedCore = {
     ordinaryPersistence: ordinaryPolicyArg,
     collectionName,
     persistedFields: Object.freeze([...persistedFields]),
     numericFields: Object.freeze([...numericFields]),
+    atomicOnlyFields: Object.freeze([...atomicOnlyFields]),
     identityFields: Object.freeze([...identityFields]),
     ...(identityAsDocumentId !== undefined ? { identityAsDocumentId } : {}),
     identityValueTypes: Object.freeze({ ...identityValueTypes }),
     searchableFields: Object.freeze([...searchableFields]),
     indexes: Object.freeze([...indexesByName.values()]),
+    toleratedIndexNames: Object.freeze([...toleratedIndexNames]),
   };
   return Object.freeze({
     ...normalizedCore,
@@ -647,6 +752,7 @@ const normalizeCollectionModelSchema = (
       collectionName,
       persistedFields: [...persistedFields].sort(compareSmartdataTopologyStrings),
       numericFields: [...numericFields].sort(compareSmartdataTopologyStrings),
+      atomicOnlyFields: [...atomicOnlyFields].sort(compareSmartdataTopologyStrings),
       identityFields: [...identityFields].sort(compareSmartdataTopologyStrings),
       ...(identityAsDocumentId !== undefined ? { identityAsDocumentId } : {}),
       identityValueTypes,
@@ -656,6 +762,9 @@ const normalizeCollectionModelSchema = (
       indexes: [...indexesByName.values()].sort((leftArg, rightArg) =>
         compareSmartdataTopologyStrings(leftArg.name, rightArg.name),
       ),
+      toleratedIndexNames: [...toleratedIndexNames].sort(
+        compareSmartdataTopologyStrings,
+      ),
     }),
   });
 };
@@ -840,7 +949,22 @@ const mergeDecoratorMetadata = (
   for (const metadataArg of metadataArgs) {
     const options = getOwnMetadataValue<Record<string, any>>(metadataArg, '_svDbOptions');
     if (options) {
-      Object.assign(svDbOptions, options);
+      for (const [field, fieldOptions] of Object.entries(options)) {
+        const inherited = svDbOptions[field];
+        // A later declaration replaces the inherited options wholesale, which
+        // would silently drop an inherited atomic-only contract and let a
+        // subclass's save() overwrite an atomically owned value.
+        if (
+          inherited
+          && Boolean(inherited.atomicOnly) !== Boolean(fieldOptions?.atomicOnly)
+        ) {
+          throw new SmartdataPersistenceError(
+            'invalid_configuration',
+            `Persisted field "${field}" has divergent inherited atomicOnly declarations.`,
+          );
+        }
+        svDbOptions[field] = fieldOptions;
+      }
     }
   }
   if (Object.keys(svDbOptions).length > 0) {
@@ -923,10 +1047,44 @@ const definedModelSchemaSymbol = Symbol.for(
   '@push.rocks/smartdata.definedCollectionModelSchema',
 );
 
+/**
+ * Reads a model's merged `@svDb()` field options from decorator metadata.
+ * Unlike the constructor's `_svDbOptions`, this is available before the first
+ * instance exists, so a programmatic declaration can be checked against the
+ * decorators on the same class.
+ */
+const readDeclaredSvDbOptions = (
+  constructorArg: TCollectionModelConstructor<any>,
+): Record<string, SvDbOptions> => {
+  const ownMetadata = Object.prototype.hasOwnProperty.call(
+    constructorArg,
+    (Symbol as any).metadata,
+  )
+    ? ((constructorArg as any)[(Symbol as any).metadata] as
+        | ISmartdataDecoratorMetadata
+        | undefined)
+    : undefined;
+  return (
+    mergeDecoratorMetadata(
+      collectInheritedDecoratorMetadata(constructorArg),
+      ownMetadata,
+    )._svDbOptions as Record<string, SvDbOptions> | undefined
+  ) || {};
+};
+
+/** Declared persisted fields a model marks `@svDb({ atomicOnly: true })`. */
+const readDecoratedAtomicOnlyFields = (
+  svDbOptionsArg: Record<string, SvDbOptions>,
+): string[] =>
+  Object.entries(svDbOptionsArg)
+    .filter(([, optionsArg]) => optionsArg?.atomicOnly === true)
+    .map(([fieldArg]) => fieldArg);
+
 const schemaFromDecoratorMetadata = (
   constructorArg: TCollectionModelConstructor<any>,
   collectionNameArg: string,
   identityAsDocumentIdArg?: string,
+  toleratedIndexNamesArg?: ReadonlyArray<string>,
 ): INormalizedCollectionModelSchema => {
   const ownMetadata = Object.prototype.hasOwnProperty.call(
     constructorArg,
@@ -956,6 +1114,9 @@ const schemaFromDecoratorMetadata = (
   const numericFields = Object.entries(metadata._svDbOptions || {})
     .filter(([, optionsArg]) => optionsArg?.numeric === true)
     .map(([fieldArg]) => fieldArg);
+  const atomicOnlyFields = readDecoratedAtomicOnlyFields(
+    (metadata._svDbOptions as Record<string, SvDbOptions> | undefined) || {},
+  );
   const indexes: ICollectionModelIndex[] = [];
   for (const uniqueField of metadata.uniqueIndexes || []) {
     const declaredIndexName = metadata.identityIndexNames?.[uniqueField];
@@ -1008,12 +1169,16 @@ const schemaFromDecoratorMetadata = (
       collectionName: collectionNameArg,
       persistedFields,
       numericFields,
+      atomicOnlyFields,
       identityFields: metadata.uniqueIndexes || [],
       ...(identityAsDocumentIdArg !== undefined
         ? { identityAsDocumentId: identityAsDocumentIdArg }
         : {}),
       searchableFields: metadata.searchableFields || [],
       indexes,
+      ...(toleratedIndexNamesArg !== undefined
+        ? { toleratedIndexNames: toleratedIndexNamesArg }
+        : {}),
     },
     true,
     metadata.identityValueTypes,
@@ -1138,6 +1303,30 @@ export function defineCollectionModel<
   if (identityAsDocumentId !== undefined) {
     assertIdentityDocumentIdIsOrdinary(modelArg, identityAsDocumentId);
   }
+  // Where a field states `atomicOnly` explicitly through @svDb(), the
+  // programmatic declaration must say the same, so neither reader of the model
+  // can be misled about which fields instance save() writes. A plain @svDb()
+  // states nothing about it and leaves the decision to this configuration.
+  const declaredSvDbOptions = readDeclaredSvDbOptions(modelArg);
+  const configuredAtomicOnly = new Set<string>([
+    ...(inheritedSchema?.atomicOnlyFields || []),
+    ...(configArg.atomicOnlyFields || []),
+  ]);
+  for (const [field, fieldOptions] of Object.entries(declaredSvDbOptions)) {
+    if (
+      !fieldOptions
+      || !Object.prototype.hasOwnProperty.call(fieldOptions, 'atomicOnly')
+      || fieldOptions.atomicOnly === configuredAtomicOnly.has(field)
+    ) {
+      continue;
+    }
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      fieldOptions.atomicOnly
+        ? `Persisted field "${field}" is declared atomicOnly by @svDb() but missing from atomicOnlyFields.`
+        : `Atomic-only field "${field}" is declared by @svDb({ atomicOnly: false }).`,
+    );
+  }
   const normalizedSchema = normalizeCollectionModelSchema({
     ...configArg,
     persistedFields: [
@@ -1148,6 +1337,14 @@ export function defineCollectionModel<
       ...(inheritedSchema?.numericFields || []),
       ...(configArg.numericFields || []),
     ] as Array<TSmartdataNumericDocumentPath<TModel>>,
+    atomicOnlyFields: [
+      ...(inheritedSchema?.atomicOnlyFields || []),
+      ...(configArg.atomicOnlyFields || []),
+    ] as Array<keyof TModel & string>,
+    toleratedIndexNames: [
+      ...(inheritedSchema?.toleratedIndexNames || []),
+      ...(configArg.toleratedIndexNames || []),
+    ],
     identityFields: [
       ...(inheritedSchema?.identityFields || []),
       ...(configArg.identityFields || []),
@@ -1403,6 +1600,7 @@ export function Collection(
           constructor as TCollectionModelConstructor<any>,
           collectionName,
           identityAsDocumentId,
+          optionsArg?.toleratedIndexNames,
         );
       },
     ) as any;
@@ -1476,6 +1674,8 @@ export function managed<TManager extends IManager>(
         return schemaFromDecoratorMetadata(
           constructor as TCollectionModelConstructor<any>,
           collectionName,
+          undefined,
+          bindingOptions?.toleratedIndexNames,
         );
       },
     );
@@ -1611,8 +1811,7 @@ export class SmartdataCollection<T> {
       {
         ordinaryWrite: ordinaryWriteArg,
         prepared: this.isInitializedForCurrentDatabase(),
-        preparationMessage:
-          `Initialize collection "${this.collectionName}" before using an owned SmartData session.`,
+        collectionName: this.collectionName,
       },
       operationArg,
     );
@@ -2075,14 +2274,30 @@ export class SmartdataCollection<T> {
     );
   }
 
+  /**
+   * An owned session stays leased until the returned cursor is closed, because
+   * the cursor outlives this call and the driver forbids a parallel operation
+   * on the same session.
+   */
   public async getCursor(
     filterObjectArg: any,
     dbDocArg: typeof SmartDataDbDoc,
-    opts?: { session?: plugins.mongodb.ClientSession }
+    opts?: { session?: TSmartdataOrdinarySession }
   ): Promise<SmartdataDbCursor<any>> {
-    await this.init();
-    const cursor = this.mongoDbCollection.find(filterObjectArg, { session: opts?.session });
-    return new SmartdataDbCursor(cursor, dbDocArg);
+    const lease = leaseOrdinarySmartdataSession(opts?.session, this.smartdataDb, {
+      prepared: this.isInitializedForCurrentDatabase(),
+      collectionName: this.collectionName,
+    });
+    try {
+      await this.init();
+      const cursor = this.mongoDbCollection.find(filterObjectArg, {
+        session: lease.rawSession,
+      });
+      return new SmartdataDbCursor(cursor, dbDocArg, lease.release);
+    } catch (cursorCreationError) {
+      lease.release();
+      throw cursorCreationError;
+    }
   }
 
   /**
@@ -2438,17 +2653,34 @@ export class SmartdataCollection<T> {
         const identifiableObject = await dbDocArg.createIdentifiableObject();
         this.assertConstrainingIdentifiableObject(identifiableObject, 'update');
         const saveableObject = await dbDocArg.createSavableObject() as any;
+        // Atomic-only fields belong to concurrent atomic writers, so this
+        // instance's value never overwrites a stored one. It still seeds them
+        // when this upsert inserts: a document created here must be as
+        // complete as one created by insert(), or a later guard on a field
+        // that was never stored would fail closed forever. $set and
+        // $setOnInsert stay disjoint by construction, so MongoDB accepts both.
+        const atomicOnlyFields = new Set(this.modelSchema?.atomicOnlyFields || []);
         const updateableObject: any = {};
+        const insertOnlyObject: any = {};
         for (const key of Object.keys(saveableObject)) {
           if (identifiableObject[key]) {
             continue;
           }
+          if (atomicOnlyFields.has(key)) {
+            insertOnlyObject[key] = saveableObject[key];
+            continue;
+          }
           updateableObject[key] = saveableObject[key];
         }
         try {
           return await this.mongoDbCollection.updateOne(
             identifiableObject,
-            { $set: updateableObject },
+            {
+              $set: updateableObject,
+              ...(Object.keys(insertOnlyObject).length > 0
+                ? { $setOnInsert: insertOnlyObject }
+                : {}),
+            },
             { upsert: true, session: rawSessionArg },
           );
         } catch (errorArg) {

package/ts/nosqldb/classes.collectiontopology.ts

@@ -38,6 +38,8 @@ export interface ISmartdataCollectionTopologyIndex {
 export interface ISmartdataExpectedCollectionTopology {
   readonly collectionName: string;
   readonly indexes: readonly ISmartdataCollectionTopologyIndex[];
+  /** Undeclared installed indexes the model accepts by name, never verifies. */
+  readonly toleratedIndexNames: readonly string[];
 }
 
 export interface ISmartdataCollectionTopologyInspection {
@@ -45,7 +47,13 @@ export interface ISmartdataCollectionTopologyInspection {
   readonly status: TSmartdataCollectionTopologyStatus;
   readonly reasonCodes: readonly TSmartdataCollectionTopologyReasonCode[];
   readonly expectedIndexes: readonly ISmartdataCollectionTopologyIndex[];
+  /** Installed indexes SmartData declares and verifies. */
   readonly actualIndexes: readonly ISmartdataCollectionTopologyIndex[];
+  /**
+   * Installed indexes the model tolerates by name. They are observed, never
+   * verified, created or dropped, and they never make the topology divergent.
+   */
+  readonly toleratedIndexes: readonly string[];
 }
 
 type TCollectionModelSchemaResolver = () => INormalizedCollectionModelSchema;
@@ -295,6 +303,9 @@ export const getExpectedCollectionTopologyForSchema = (
   return Object.freeze({
     collectionName: schema.collectionName,
     indexes,
+    toleratedIndexNames: Object.freeze(
+      [...schema.toleratedIndexNames].sort(compareSmartdataTopologyStrings),
+    ),
   });
 };
 
@@ -512,6 +523,7 @@ const createInspection = (
   statusArg: TSmartdataCollectionTopologyStatus,
   reasonsArg: ReadonlySet<TSmartdataCollectionTopologyReasonCode>,
   actualIndexesArg: readonly ISmartdataCollectionTopologyIndex[],
+  toleratedIndexesArg: readonly string[] = [],
 ): ISmartdataCollectionTopologyInspection =>
   Object.freeze({
     collectionName: expectedArg.collectionName,
@@ -519,6 +531,9 @@ const createInspection = (
     reasonCodes: buildReasonCodes(reasonsArg),
     expectedIndexes: expectedArg.indexes,
     actualIndexes: sortIndexes(actualIndexesArg),
+    toleratedIndexes: Object.freeze(
+      [...toleratedIndexesArg].sort(compareSmartdataTopologyStrings),
+    ),
   });
 
 export const inspectCollectionTopologyForModel = async (
@@ -599,8 +614,17 @@ export const inspectCollectionTopologySnapshot = (
     }
     const normalizedIndexes: ISmartdataCollectionTopologyIndex[] = [];
     const unsupportedNames = new Set<string>();
+    const toleratedNames = new Set(expected.toleratedIndexNames);
+    const toleratedIndexes: string[] = [];
     for (const rawIndex of rawIndexes) {
       const normalized = normalizeActualIndex(rawIndex);
+      if (normalized.name && toleratedNames.has(normalized.name)) {
+        // A tolerated index belongs to whoever created it — a migration, an
+        // operator — so it is observed by name and nothing about its keys or
+        // options is asserted. SmartData neither creates nor drops it.
+        toleratedIndexes.push(normalized.name);
+        continue;
+      }
       if (!normalized.supported) {
         reasons.add('unsupported_actual_index');
         if (normalized.name) {
@@ -660,7 +684,13 @@ export const inspectCollectionTopologySnapshot = (
             )
           ? 'compatible'
           : 'divergent';
-    return createInspection(expected, status, reasons, normalizedIndexes);
+    return createInspection(
+      expected,
+      status,
+      reasons,
+      normalizedIndexes,
+      toleratedIndexes,
+    );
   } catch {
     throw new SmartdataPersistenceError(
       'unsupported_operation',

package/ts/nosqldb/classes.cursor.ts

@@ -10,9 +10,20 @@ export class SmartdataDbCursor<T = any> {
   // INSTANCE
   public mongodbCursor: plugins.mongodb.FindCursor<T>;
   private smartdataDbDoc: typeof SmartDataDbDoc;
-  constructor(cursorArg: plugins.mongodb.FindCursor<T>, dbDocArg: typeof SmartDataDbDoc) {
+  /**
+   * Releases an owned SmartData session lease the cursor holds for its whole
+   * lifetime. Supplied by the operation that created the cursor; inert for a
+   * raw driver session or no session at all.
+   */
+  private releaseSession: () => void;
+  constructor(
+    cursorArg: plugins.mongodb.FindCursor<T>,
+    dbDocArg: typeof SmartDataDbDoc,
+    releaseSessionArg: () => void = () => {},
+  ) {
     this.mongodbCursor = cursorArg;
     this.smartdataDbDoc = dbDocArg;
+    this.releaseSession = releaseSessionArg;
   }
 
   public async next(closeAtEnd = true): Promise<T | null> {
@@ -73,8 +84,17 @@ export class SmartdataDbCursor<T = any> {
     return convertedResult;
   }
 
+  /**
+   * Closes the driver cursor and releases an owned session lease even when the
+   * driver's own cleanup rejects, so a failed close can never strand the
+   * session and block every later operation on it.
+   */
   public async close() {
-    await this.mongodbCursor.close();
+    try {
+      await this.mongodbCursor.close();
+    } finally {
+      this.releaseSession();
+    }
   }
 
   private async closeAfterError(errorArg: unknown): Promise<never> {