@lossless.org/client 0.1.0

package/ts/nosqldb/classes.collectionfactory.ts

@@ -0,0 +1,87 @@
+import * as plugins from './plugins.js';
+import {
+  SmartdataCollection,
+  type INormalizedCollectionModelSchema,
+} from './classes.collection.js';
+import { SmartdataDb } from './classes.db.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+
+/**
+ * Per-SmartdataDb collection cache.
+ *
+ * Historically this class keyed its cache by class name alone, which meant
+ * the first SmartdataDb to request a collection of a given class name
+ * "won" — every subsequent call from a different SmartdataDb instance
+ * received the cached collection bound to the first db. That silently
+ * broke multi-tenant SaaS apps (one db per tenant), tests instantiating
+ * multiple SmartdataDbs in sequence, and any in-process db cluster switch.
+ *
+ * The cache is now keyed by `(SmartdataDb instance, className)` using a
+ * WeakMap of db → Map<className, SmartdataCollection>. Entries are GC'd
+ * with their parent db automatically.
+ */
+export class CollectionFactory {
+  private perDbCollections: WeakMap<
+    SmartdataDb,
+    Map<
+      string,
+      {
+        collection: SmartdataCollection<any>;
+        schema?: INormalizedCollectionModelSchema;
+      }
+    >
+  > = new WeakMap();
+
+  public getCollection = (
+    nameArg: string,
+    dbArg: SmartdataDb,
+    schemaArg?: INormalizedCollectionModelSchema,
+  ): SmartdataCollection<any> => {
+    if (!(dbArg instanceof SmartdataDb)) {
+      // Preserve the historical behavior of returning undefined-ish for
+      // non-db args. All in-repo callers already guard on instanceof
+      // before using the result (see classes.collection.ts).
+      return undefined as unknown as SmartdataCollection<any>;
+    }
+    let dbMap = this.perDbCollections.get(dbArg);
+    if (!dbMap) {
+      dbMap = new Map();
+      this.perDbCollections.set(dbArg, dbMap);
+    }
+    let entry = dbMap.get(nameArg);
+    if (!entry) {
+      const collection = new SmartdataCollection(nameArg, dbArg);
+      entry = { collection, schema: schemaArg };
+      if (schemaArg) {
+        collection.bindModelSchema(schemaArg);
+      }
+      dbMap.set(nameArg, entry);
+    } else if (schemaArg) {
+      if (
+        entry.schema &&
+        entry.schema.fingerprint !== schemaArg.fingerprint
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_configuration',
+          `Collection "${nameArg}" already has a divergent model schema in this SmartdataDb.`,
+        );
+      }
+      if (!entry.schema) {
+        entry.schema = schemaArg;
+      }
+      entry.collection.bindModelSchema(schemaArg);
+    }
+    return entry.collection;
+  };
+
+  /**
+   * @deprecated Internal back-compat shim. The previous field was a public
+   * Record<className, SmartdataCollection> but was not part of the
+   * documented public API. WeakMap is not iterable, so this getter returns
+   * an empty object — anyone actually relying on the old shape would get
+   * clean nothing rather than wrong-db data. Will be removed in 8.0.
+   */
+  public get collections(): { [key: string]: SmartdataCollection<any> } {
+    return {};
+  }
+}

package/ts/nosqldb/classes.collectionlifecycle.ts

@@ -0,0 +1,24 @@
+type TCollectionReconnectHandler = () => void;
+
+const reconnectHandlersByCollection = new WeakMap<
+  object,
+  Set<TCollectionReconnectHandler>
+>();
+
+export const registerCollectionReconnectHandler = (
+  collectionArg: object,
+  handlerArg: TCollectionReconnectHandler,
+): void => {
+  let handlers = reconnectHandlersByCollection.get(collectionArg);
+  if (!handlers) {
+    handlers = new Set();
+    reconnectHandlersByCollection.set(collectionArg, handlers);
+  }
+  handlers.add(handlerArg);
+};
+
+export const notifyCollectionReconnect = (collectionArg: object): void => {
+  for (const handler of reconnectHandlersByCollection.get(collectionArg) || []) {
+    handler();
+  }
+};

package/ts/nosqldb/classes.collectionpreparation.ts

@@ -0,0 +1,164 @@
+import type * as plugins from './plugins.js';
+import type { INormalizedCollectionModelSchema } from './classes.collection.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import { readBoundedInspectionCursor } from './classes.namespaceinspection.js';
+import {
+  getExpectedCollectionTopologyForSchema,
+  inspectCollectionTopologySnapshot,
+} from './classes.collectiontopology.js';
+
+export interface ISmartdataCollectionPreparationOptions {
+  /** Observe an exact topology, or install only missing declarations. */
+  mode: 'requireExact' | 'ensureCompatible';
+  /** Total budget including queueing and cursor cleanup: 1 through 120000 ms. */
+  timeoutMs: number;
+  signal?: AbortSignal;
+}
+
+/** @internal Validate before resolving a model manager or starting a deadline. */
+export const validateCollectionPreparationOptions = (opts: ISmartdataCollectionPreparationOptions): void => {
+  if (!opts || Object.getPrototypeOf(opts) !== Object.prototype ||
+    Reflect.ownKeys(opts).some((keyArg) => typeof keyArg !== 'string' ||
+      !['mode', 'timeoutMs', 'signal'].includes(keyArg) ||
+      !('value' in Object.getOwnPropertyDescriptor(opts, keyArg)!)) ||
+    !['requireExact', 'ensureCompatible'].includes(opts.mode) ||
+    !Number.isSafeInteger(opts.timeoutMs) || opts.timeoutMs < 1 || opts.timeoutMs > 120_000 ||
+    (opts.signal !== undefined && !(opts.signal instanceof AbortSignal))) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Invalid collection preparation options.');
+  }
+  opts.signal?.throwIfAborted();
+};
+
+/** @internal Owns the explicit preparation caller's deadline and queue wait. */
+export class CollectionPreparationBudget {
+  public readonly signal: AbortSignal;
+  public readonly mode: ISmartdataCollectionPreparationOptions['mode'];
+  private readonly deadline = new AbortController();
+  private readonly expiresAt: number;
+  private readonly timer: ReturnType<typeof setTimeout>;
+
+  constructor(opts: ISmartdataCollectionPreparationOptions) {
+    validateCollectionPreparationOptions(opts);
+    this.mode = opts.mode;
+    this.expiresAt = performance.now() + opts.timeoutMs;
+    this.timer = setTimeout(() => this.expire(), opts.timeoutMs);
+    this.signal = opts.signal ? AbortSignal.any([opts.signal, this.deadline.signal]) : this.deadline.signal;
+  }
+
+  private expire(): void {
+    this.deadline.abort(new SmartdataPersistenceError(
+      'unsupported_operation', 'Collection preparation deadline exceeded.',
+    ));
+  }
+
+  public check(): void {
+    if (performance.now() >= this.expiresAt) this.expire();
+    this.signal.throwIfAborted();
+  }
+
+  public operationOptions(): { timeoutMS: number } {
+    this.check();
+    return this.cleanupOptions();
+  }
+
+  /** Cleanup still runs after expiration; zero would disable the driver's timeout. */
+  public cleanupOptions(): { timeoutMS: number } {
+    return { timeoutMS: Math.max(1, Math.ceil(this.expiresAt - performance.now())) };
+  }
+
+  /** Cancellation detaches only this waiter, never the operation it is waiting for. */
+  public async waitFor(operationArg: Promise<void>): Promise<void> {
+    this.check();
+    await new Promise<void>((resolveArg, rejectArg) => {
+      const onAbort = () => { cleanup(); rejectArg(this.signal.reason); };
+      const cleanup = () => this.signal.removeEventListener('abort', onAbort);
+      this.signal.addEventListener('abort', onAbort, { once: true });
+      operationArg.then(
+        () => { cleanup(); resolveArg(); },
+        () => { cleanup(); resolveArg(); },
+      );
+      if (this.signal.aborted) onAbort();
+    });
+    this.check();
+  }
+
+  public close(): void { clearTimeout(this.timer); }
+}
+
+/** @internal No state is published until all commands and cleanup have settled. */
+export const prepareBoundCollection = async (
+  dbArg: plugins.mongodb.Db,
+  schemaArg: INormalizedCollectionModelSchema,
+  budgetArg: CollectionPreparationBudget,
+  assertCurrentArg: () => void,
+): Promise<plugins.mongodb.Collection> => {
+  const expected = getExpectedCollectionTopologyForSchema(schemaArg);
+  const collection = dbArg.collection(schemaArg.collectionName);
+  const check = () => { budgetArg.check(); assertCurrentArg(); };
+  const inspect = async () => {
+    check();
+    const namespaces = await readBoundedInspectionCursor(dbArg.listCollections(
+      { name: schemaArg.collectionName },
+      { nameOnly: false, batchSize: 1, ...budgetArg.operationOptions(), signal: budgetArg.signal },
+    ), 1, budgetArg.signal, () => budgetArg.cleanupOptions());
+    check();
+    const namespace = namespaces[0] as unknown as Record<string, unknown> | undefined;
+    const indexes = namespace?.type === 'collection'
+      ? await readBoundedInspectionCursor(collection.listIndexes({
+          batchSize: 1, ...budgetArg.operationOptions(),
+        }), 64, budgetArg.signal, () => budgetArg.cleanupOptions())
+      : [];
+    check();
+    return inspectCollectionTopologySnapshot(expected, { namespace: namespace ?? null, indexes });
+  };
+  const requireAcceptable = (inspectionArg: Awaited<ReturnType<typeof inspect>>, exactArg: boolean) => {
+    if (inspectionArg.status === 'divergent' || (exactArg && inspectionArg.status !== 'exact')) {
+      throw new SmartdataPersistenceError('invalid_configuration',
+        `Collection "${schemaArg.collectionName}" requires ${exactArg ? 'exact' : 'compatible'} topology: ` +
+        `${inspectionArg.status}${inspectionArg.reasonCodes.length ? ` (${inspectionArg.reasonCodes.join(', ')})` : ''}.`);
+    }
+  };
+
+  let inspection = await inspect();
+  requireAcceptable(inspection, budgetArg.mode === 'requireExact');
+  if (budgetArg.mode === 'ensureCompatible' && inspection.status !== 'exact') {
+    if (inspection.status === 'absent') {
+      check();
+      try {
+        await dbArg.createCollection(schemaArg.collectionName, budgetArg.operationOptions());
+      } catch (errorArg) {
+        if ((errorArg as { code?: unknown })?.code !== 48) throw errorArg;
+      }
+      // A competing creator may have installed divergent options or indexes.
+      inspection = await inspect();
+      requireAcceptable(inspection, false);
+      if (inspection.status === 'absent') {
+        throw new SmartdataPersistenceError('unsupported_operation', 'Created collection is not observable.');
+      }
+    }
+    const existing = new Set(inspection.actualIndexes.map((indexArg) => indexArg.name));
+    for (const index of schemaArg.indexes) {
+      if (existing.has(index.name)) continue;
+      check();
+      try {
+        await collection.createIndex(Object.fromEntries(index.key), {
+          ...index.options, name: index.name, ...budgetArg.operationOptions(),
+        });
+      } catch (errorArg) {
+        // A rejected acknowledgement does not prove the index build failed.
+        // Continue only from compatible observed topology containing this exact
+        // declaration, within the same deadline and connection generation.
+        inspection = await inspect();
+        requireAcceptable(inspection, false);
+        if (!inspection.actualIndexes.some((actualArg) => actualArg.name === index.name)) {
+          throw errorArg;
+        }
+        for (const actual of inspection.actualIndexes) existing.add(actual.name);
+      }
+    }
+    inspection = await inspect();
+    requireAcceptable(inspection, true);
+  }
+  check();
+  return collection;
+};