@lossless.org/client 1.1.0 → 1.3.0

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,9 +303,37 @@ export const getExpectedCollectionTopologyForSchema = (
   return Object.freeze({
     collectionName: schema.collectionName,
     indexes,
+    toleratedIndexNames: Object.freeze(
+      [...schema.toleratedIndexNames].sort(compareSmartdataTopologyStrings),
+    ),
   });
 };
 
+/**
+ * @internal A single-field ascending unique index is what makes a declared
+ * identity globally constraining, whatever the index is called.
+ */
+export const isIdentityIndexFor = (
+  indexArg: INormalizedCollectionModelSchema['indexes'][number],
+  fieldArg: string,
+): boolean =>
+  indexArg.options.unique === true &&
+  indexArg.key.length === 1 &&
+  indexArg.key[0][0] === fieldArg &&
+  indexArg.key[0][1] === 1;
+
+/**
+ * @internal Name of the unique index that backs an identity field in a bound
+ * schema. Index-creation fallbacks resolve it here so that a model naming its
+ * own backing index never gets a second unique index over the same key.
+ */
+export const getIdentityIndexName = (
+  schemaArg: INormalizedCollectionModelSchema | undefined,
+  fieldArg: string,
+): string | undefined =>
+  schemaArg?.indexes.find((indexArg) => isIdentityIndexFor(indexArg, fieldArg))
+    ?.name;
+
 const normalizeActualIndex = (
   rawIndexArg: unknown,
 ): IActualIndexNormalization => {
@@ -487,6 +523,7 @@ const createInspection = (
   statusArg: TSmartdataCollectionTopologyStatus,
   reasonsArg: ReadonlySet<TSmartdataCollectionTopologyReasonCode>,
   actualIndexesArg: readonly ISmartdataCollectionTopologyIndex[],
+  toleratedIndexesArg: readonly string[] = [],
 ): ISmartdataCollectionTopologyInspection =>
   Object.freeze({
     collectionName: expectedArg.collectionName,
@@ -494,6 +531,9 @@ const createInspection = (
     reasonCodes: buildReasonCodes(reasonsArg),
     expectedIndexes: expectedArg.indexes,
     actualIndexes: sortIndexes(actualIndexesArg),
+    toleratedIndexes: Object.freeze(
+      [...toleratedIndexesArg].sort(compareSmartdataTopologyStrings),
+    ),
   });
 
 export const inspectCollectionTopologyForModel = async (
@@ -574,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) {
@@ -635,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> {