@lossless.org/client 0.1.0

package/ts/nosqldb/classes.namespaceinspection.ts

@@ -0,0 +1,199 @@
+import * as plugins from './plugins.js';
+import type { SmartdataDb } from './classes.db.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import { SmartdataSession, acquireSmartdataSession, isSmartdataSession } from './classes.session.js';
+import { runCursorOperation } from './classes.cursoroperation.js';
+import {
+  collectionTopologyDbInspectionSymbol,
+  compareSmartdataTopologyStrings,
+  inspectCollectionTopologySnapshot,
+  type ISmartdataCollectionTopologyIndex,
+  type TSmartdataCollectionTopologyReasonCode,
+} from './classes.collectiontopology.js';
+
+export interface ISmartdataNamespaceInspectionOptions {
+  /** Default 256, maximum 1024. Overflow fails the entire observation. */
+  maxCollections?: number;
+  /** Default bounded. Exact counts scan the collection within the shared deadline. */
+  documentCountMode?: 'bounded' | 'exact';
+  /** Default 1, maximum 10000. Read one additional document to detect overflow. */
+  documentCountUpTo?: number;
+  /** Cumulative deadline. Default 5000ms, maximum 120000ms. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /** Owned session for sequential observation; active transactions are unsupported. */
+  session?: SmartdataSession;
+}
+
+export type TSmartdataObservedDocumentCount =
+  | { readonly kind: 'exact'; readonly value: number }
+  | { readonly kind: 'at_least'; readonly value: number };
+
+export interface ISmartdataObservedCollection {
+  readonly collectionName: string;
+  readonly namespaceType: 'collection' | 'view' | 'other';
+  readonly reasonCodes: readonly TSmartdataCollectionTopologyReasonCode[];
+  readonly actualIndexes: readonly ISmartdataCollectionTopologyIndex[];
+  readonly documentCount: TSmartdataObservedDocumentCount | null;
+}
+
+export interface ISmartdataNamespaceInspection {
+  /** Explicitly observational: catalog and data reads are not an atomic snapshot. */
+  readonly consistency: 'observational';
+  readonly collections: readonly ISmartdataObservedCollection[];
+}
+
+const requireBound = (
+  valueArg: number | undefined,
+  defaultArg: number,
+  minimumArg: number,
+  maximumArg: number,
+  labelArg: string,
+): number => {
+  const value = valueArg === undefined ? defaultArg : valueArg;
+  if (!Number.isSafeInteger(value) || value < minimumArg || value > maximumArg) {
+    throw new SmartdataPersistenceError('invalid_argument',
+      `${labelArg} must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return value;
+};
+
+/** @internal Bounded catalog reading shared with collection preparation. */
+export const readBoundedInspectionCursor = async <T>(
+  cursorArg: plugins.mongodb.AbstractCursor<T>,
+  maximumArg: number,
+  signalArg: AbortSignal,
+  closeOptionsArg?: () => { timeoutMS: number },
+): Promise<T[]> => runCursorOperation(cursorArg, async (cursor) => {
+  const result: T[] = [];
+  while (true) {
+    signalArg.throwIfAborted();
+    const next = await cursor.next();
+    if (next === null) return result;
+    if (result.length === maximumArg) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Namespace inspection exceeded its metadata bound.');
+    }
+    if (plugins.mongodb.BSON.calculateObjectSize(next as plugins.mongodb.Document) > 65_536) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Namespace inspection metadata exceeds 64 KiB per document.');
+    }
+    result.push(next);
+  }
+}, signalArg, closeOptionsArg ? () => [closeOptionsArg()] as [{ timeoutMS: number }] : undefined);
+
+/** @internal Entry point exposed through SmartdataDb.inspectNamespace(). */
+export const inspectSmartdataNamespace = async (
+  dbArg: SmartdataDb,
+  opts: ISmartdataNamespaceInspectionOptions = {},
+): Promise<ISmartdataNamespaceInspection> => {
+  if (!opts || Object.getPrototypeOf(opts) !== Object.prototype ||
+    Reflect.ownKeys(opts).some((keyArg) => typeof keyArg !== 'string' ||
+      !['maxCollections', 'documentCountMode', 'documentCountUpTo', 'timeoutMs', 'signal', 'session'].includes(keyArg) ||
+      !('value' in Object.getOwnPropertyDescriptor(opts, keyArg)!))) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Invalid namespace inspection options.');
+  }
+  const maxCollections = requireBound(opts.maxCollections, 256, 1, 1024, 'maxCollections');
+  const documentCountMode = opts.documentCountMode === undefined ? 'bounded' : opts.documentCountMode;
+  if (!['bounded', 'exact'].includes(documentCountMode) ||
+    (documentCountMode === 'exact' && opts.documentCountUpTo !== undefined)) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Invalid namespace document count mode.');
+  }
+  const documentCountUpTo = requireBound(opts.documentCountUpTo, 1, 0, 10_000, 'documentCountUpTo');
+  const timeoutMs = requireBound(opts.timeoutMs, 5_000, 1, 120_000, 'timeoutMs');
+  if (opts.signal !== undefined && !(opts.signal instanceof AbortSignal)) {
+    throw new SmartdataPersistenceError('invalid_argument', 'signal must be an AbortSignal.');
+  }
+  opts.signal?.throwIfAborted();
+  if (opts.session !== undefined && !isSmartdataSession(opts.session)) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Namespace inspection requires an owned session.');
+  }
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(new SmartdataPersistenceError(
+    'unsupported_operation', 'Namespace inspection deadline exceeded.',
+  )), timeoutMs);
+  const signal = opts.signal ? AbortSignal.any([opts.signal, deadline.signal]) : deadline.signal;
+  const expiresAt = performance.now() + timeoutMs;
+  const cleanupOptions = () => ({ timeoutMS: Math.max(1, Math.ceil(expiresAt - performance.now())) });
+  const operationOptions = () => {
+    signal.throwIfAborted();
+    return cleanupOptions();
+  };
+  let lease: ReturnType<typeof acquireSmartdataSession> | undefined;
+  try {
+    if (opts.session) {
+      lease = acquireSmartdataSession(opts.session, dbArg);
+      if (lease.rawSession.inTransaction()) {
+        throw new SmartdataPersistenceError('unsupported_operation',
+          'Namespace inspection cannot run in a transaction.');
+      }
+    }
+    const result = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg) => {
+      const session = lease?.rawSession;
+      const namespaces = await readBoundedInspectionCursor(mongoDbArg.listCollections({}, {
+        nameOnly: false, batchSize: 1,
+        ...operationOptions(), signal, session,
+      }), maxCollections, signal, cleanupOptions);
+      const collections: ISmartdataObservedCollection[] = [];
+      const names = new Set<string>();
+      for (const namespace of namespaces) {
+        if (typeof namespace.name !== 'string' || namespace.name.length === 0 ||
+          namespace.name.length > 255 || names.has(namespace.name)) {
+          throw new SmartdataPersistenceError('unsupported_operation', 'Unreadable namespace metadata.');
+        }
+        names.add(namespace.name);
+        const namespaceType = namespace.type === 'collection' || namespace.type === 'view'
+          ? namespace.type : 'other';
+        let indexes: unknown[] = [];
+        let documentCount: TSmartdataObservedDocumentCount | null = null;
+        if (namespaceType === 'collection') {
+          const collection = mongoDbArg.collection(namespace.name);
+          indexes = await readBoundedInspectionCursor(collection.listIndexes({
+            batchSize: 1, ...operationOptions(), session,
+          }), 64, signal, cleanupOptions);
+          // Both modes reduce on the server; no document bodies enter the
+          // observation. Exact mode retains the cumulative operation deadline.
+          const pipeline = documentCountMode === 'exact'
+            ? [{ $count: 'count' }]
+            : [{ $limit: documentCountUpTo + 1 }, { $count: 'count' }];
+          const countCursor = collection.aggregate<{ count: number }>(pipeline, {
+            ...operationOptions(), session, signal,
+          });
+          const count = await runCursorOperation(countCursor, async (cursorArg) => {
+            const reduction = await cursorArg.next();
+            return reduction === null ? 0 : reduction.count;
+          }, signal, (): [{ timeoutMS: number }] => [cleanupOptions()]);
+          if (!Number.isSafeInteger(count) || count < 0 ||
+            (documentCountMode === 'bounded' && count > documentCountUpTo + 1)) {
+            throw new SmartdataPersistenceError('unsupported_operation', 'Unreadable namespace count.');
+          }
+          documentCount = Object.freeze({
+            kind: documentCountMode === 'bounded' && count > documentCountUpTo ? 'at_least' : 'exact',
+            value: count,
+          });
+        }
+        const topology = inspectCollectionTopologySnapshot({
+          collectionName: namespace.name, indexes: [],
+        }, { namespace: namespace as unknown as Record<string, unknown>, indexes });
+        collections.push(Object.freeze({
+          collectionName: namespace.name, namespaceType, documentCount,
+          actualIndexes: topology.actualIndexes,
+          reasonCodes: Object.freeze(topology.reasonCodes.filter(
+            (reasonArg) => reasonArg !== 'unexpected_index',
+          )),
+        }));
+      }
+      signal.throwIfAborted();
+      collections.sort((leftArg, rightArg) =>
+        compareSmartdataTopologyStrings(leftArg.collectionName, rightArg.collectionName));
+      return Object.freeze({ consistency: 'observational' as const, collections: Object.freeze(collections) });
+    });
+    return result;
+  } catch (errorArg) {
+    signal.throwIfAborted();
+    throw errorArg;
+  } finally {
+    lease?.release();
+    clearTimeout(timer);
+  }
+};

package/ts/nosqldb/classes.operationbudget.ts

@@ -0,0 +1,75 @@
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import * as plugins from './plugins.js';
+
+/** @internal Options must not execute accessors or accept inherited configuration. */
+export const assertDataOptions = (
+  valueArg: unknown,
+  keysArg: readonly string[],
+): Record<string, unknown> => {
+  if (!valueArg || plugins.nodeUtil.types.isProxy(valueArg) || Object.getPrototypeOf(valueArg) !== Object.prototype ||
+    Reflect.ownKeys(valueArg).some((keyArg) => typeof keyArg !== 'string' ||
+      !keysArg.includes(keyArg) ||
+      !('value' in Object.getOwnPropertyDescriptor(valueArg, keyArg)!))) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Invalid SmartData operation options.');
+  }
+  const snapshot = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(valueArg) as string[]) {
+    snapshot[key] = Object.getOwnPropertyDescriptor(valueArg, key)!.value;
+  }
+  return snapshot;
+};
+
+/** @internal One deadline for an operation and all of its phases. Never exposes abort reasons. */
+export class SmartdataOperationBudget {
+  public readonly signal: AbortSignal;
+  private readonly controller = new AbortController();
+  private readonly expiresAt: number;
+  private readonly timer: ReturnType<typeof setTimeout>;
+
+  constructor(timeoutMsArg: unknown, signalArg?: unknown) {
+    if (!Number.isSafeInteger(timeoutMsArg) || (timeoutMsArg as number) < 1 ||
+      (timeoutMsArg as number) > 120_000 ||
+      (signalArg !== undefined && (plugins.nodeUtil.types.isProxy(signalArg) || !(signalArg instanceof AbortSignal)))) {
+      throw new SmartdataPersistenceError('invalid_argument', 'Invalid SmartData timeout or cancellation signal.');
+    }
+    this.expiresAt = performance.now() + (timeoutMsArg as number);
+    this.signal = signalArg instanceof AbortSignal
+      ? AbortSignal.any([signalArg, this.controller.signal]) : this.controller.signal;
+    this.timer = setTimeout(() => this.controller.abort(), timeoutMsArg as number);
+  }
+
+  public check(): void {
+    if (performance.now() >= this.expiresAt) this.controller.abort();
+    if (this.signal.aborted) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'SmartData operation was cancelled or exceeded its deadline.');
+    }
+  }
+
+  public remainingMs(): number {
+    this.check();
+    return this.cleanupOptions().timeoutMS;
+  }
+
+  public operationOptions(): { timeoutMS: number; signal: AbortSignal } {
+    return { timeoutMS: this.remainingMs(), signal: this.signal };
+  }
+
+  public cleanupOptions(): { timeoutMS: number } {
+    return { timeoutMS: Math.max(1, Math.ceil(this.expiresAt - performance.now())) };
+  }
+
+  /** Waiting does not cancel or abandon the owner of the pending operation. */
+  public async waitFor(operationArg: Promise<unknown>): Promise<void> {
+    this.check();
+    await new Promise<void>((resolveArg) => {
+      const finish = () => { this.signal.removeEventListener('abort', finish); resolveArg(); };
+      this.signal.addEventListener('abort', finish, { once: true });
+      operationArg.then(finish, finish);
+      if (this.signal.aborted) finish();
+    });
+    this.check();
+  }
+
+  public close(): void { clearTimeout(this.timer); }
+}

package/ts/nosqldb/classes.ordinarypersistence.ts

@@ -0,0 +1,84 @@
+import * as plugins from './plugins.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import { assertBsonWithoutMutation } from './classes.bsonassertion.js';
+
+export interface IOrdinaryPersistenceOptions {
+  /** Defaults to ObjectId. String IDs are caller-owned and immutable. */
+  idType?: 'objectId' | 'string';
+  /** Defaults to managed. `none` forbids SmartData timestamp fields in storage. */
+  timestamps?: 'managed' | 'none';
+  /** Validates the complete BSON envelope before model hydration. */
+  assertStoredDocument: (valueArg: unknown) => void;
+}
+
+export interface IOrdinaryPersistencePolicy {
+  readonly idType: 'objectId' | 'string';
+  readonly timestamps: 'managed' | 'none';
+  readonly assertStoredDocument: (valueArg: unknown) => void;
+}
+
+const policySymbol = Symbol.for('@push.rocks/smartdata.ordinaryPersistencePolicy');
+const exactSymbol = Symbol.for('@push.rocks/smartdata.exactPersistencePolicy');
+
+export const getOrdinaryPersistencePolicy = (modelArg: any): IOrdinaryPersistencePolicy | undefined => {
+  const policy = modelArg?.[policySymbol] as IOrdinaryPersistencePolicy | undefined;
+  if (policy && modelArg[exactSymbol]) {
+    throw new SmartdataPersistenceError('invalid_configuration',
+      'Ordinary and exact persistence policies cannot be combined.');
+  }
+  return policy;
+};
+
+/** Opt into immutable whole-stored-document validation for an ordinary model. */
+export const ordinaryPersistence = (opts: IOrdinaryPersistenceOptions) => {
+  if (!opts || Object.getPrototypeOf(opts) !== Object.prototype ||
+    Reflect.ownKeys(opts).some((keyArg) => typeof keyArg !== 'string' ||
+      !['idType', 'timestamps', 'assertStoredDocument'].includes(keyArg) ||
+      !('value' in Object.getOwnPropertyDescriptor(opts, keyArg)!)) ||
+    typeof opts.assertStoredDocument !== 'function' ||
+    (opts.idType !== undefined && !['objectId', 'string'].includes(opts.idType)) ||
+    (opts.timestamps !== undefined && !['managed', 'none'].includes(opts.timestamps))) {
+    throw new SmartdataPersistenceError('invalid_configuration', 'Invalid ordinary persistence policy.');
+  }
+  const policy: IOrdinaryPersistencePolicy = Object.freeze({
+    idType: opts.idType ?? 'objectId', timestamps: opts.timestamps ?? 'managed',
+    assertStoredDocument: opts.assertStoredDocument,
+  });
+  return <T extends new (...args: any[]) => any>(modelArg: T, _contextArg?: ClassDecoratorContext<T>): T => {
+    if (modelArg[policySymbol] || modelArg[exactSymbol]) {
+      throw new SmartdataPersistenceError('invalid_configuration', 'A persistence policy cannot be overridden.');
+    }
+    Object.defineProperty(modelArg, policySymbol, { value: policy });
+    return modelArg;
+  };
+};
+
+/** @internal Returns an isolated validated BSON document, never a hydrated model. */
+export const validateOrdinaryStoredDocument = (
+  documentArg: unknown,
+  policyArg: IOrdinaryPersistencePolicy,
+  persistedFieldsArg: readonly string[],
+): Record<string, any> => {
+  const invalid = () => new SmartdataPersistenceError('invalid_document',
+    'Stored document does not satisfy its ordinary persistence policy.');
+  if (!documentArg || typeof documentArg !== 'object' ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(documentArg))) throw invalid();
+  const allowed = new Set([...persistedFieldsArg, '_id']);
+  if (policyArg.timestamps === 'managed') { allowed.add('_createdAt'); allowed.add('_updatedAt'); }
+  for (const key of Reflect.ownKeys(documentArg)) {
+    if (typeof key !== 'string' || !allowed.has(key) ||
+      (policyArg.timestamps === 'none' && ['_createdAt', '_updatedAt'].includes(key)) ||
+      key === '_smartdataRevision' || !('value' in Object.getOwnPropertyDescriptor(documentArg, key)!)) throw invalid();
+  }
+  let clone: Record<string, any>;
+  try { clone = plugins.mongodb.BSON.deserialize(plugins.mongodb.BSON.serialize(documentArg)); }
+  catch { throw invalid(); }
+  if (policyArg.idType === 'string'
+    ? typeof clone._id !== 'string' || clone._id.trim().length === 0
+    : !(clone._id instanceof plugins.mongodb.ObjectId)) throw invalid();
+  if (policyArg.timestamps === 'managed' &&
+    (typeof clone._createdAt !== 'string' || typeof clone._updatedAt !== 'string')) throw invalid();
+  assertBsonWithoutMutation(clone, policyArg.assertStoredDocument, invalid);
+  // The assertion must not retain authority to mutate the returned document.
+  return plugins.mongodb.BSON.deserialize(plugins.mongodb.BSON.serialize(clone));
+};

package/ts/nosqldb/classes.persistence.ts

@@ -0,0 +1,62 @@
+import * as plugins from './plugins.js';
+
+export type TSmartdataPersistenceErrorCode =
+  | 'invalid_argument'
+  | 'invalid_configuration'
+  | 'invalid_document'
+  | 'unique_conflict'
+  | 'ambiguous_write'
+  | 'unsupported_operation';
+
+/**
+ * Stable errors for ordinary SmartData model configuration and persistence.
+ *
+ * Exact-persistence models keep using SmartdataExactPersistenceError.
+ */
+export class SmartdataPersistenceError extends Error {
+  public readonly code: TSmartdataPersistenceErrorCode;
+
+  constructor(
+    codeArg: TSmartdataPersistenceErrorCode,
+    messageArg: string,
+    optionsArg?: ErrorOptions,
+  ) {
+    super(messageArg, optionsArg);
+    this.name = 'SmartdataPersistenceError';
+    this.code = codeArg;
+  }
+}
+
+export const isMongoTransactionRetryError = (errorArg: unknown): boolean =>
+  errorArg instanceof plugins.mongodb.MongoServerError &&
+  (
+    errorArg.hasErrorLabel('TransientTransactionError') ||
+    errorArg.hasErrorLabel('UnknownTransactionCommitResult')
+  );
+
+export const isMongoDuplicateKeyError = (
+  errorArg: unknown,
+): errorArg is plugins.mongodb.MongoServerError => {
+  return (
+    errorArg instanceof plugins.mongodb.MongoServerError &&
+    (errorArg.code === 11000 || errorArg.codeName === 'DuplicateKey')
+  );
+};
+
+export const normalizeOrdinaryPersistenceError = (
+  errorArg: unknown,
+  messageArg: string,
+): never => {
+  if (
+    errorArg instanceof SmartdataPersistenceError ||
+    isMongoTransactionRetryError(errorArg)
+  ) {
+    throw errorArg;
+  }
+  if (isMongoDuplicateKeyError(errorArg)) {
+    throw new SmartdataPersistenceError('unique_conflict', messageArg, {
+      cause: errorArg,
+    });
+  }
+  throw errorArg;
+};