@lossless.org/client 0.1.0

package/ts/nosqldb/classes.session.ts

@@ -0,0 +1,389 @@
+import * as plugins from './plugins.js';
+
+import type { SmartdataDb } from './classes.db.js';
+import {
+  SmartdataPersistenceError,
+  normalizeOrdinaryPersistenceError,
+} from './classes.persistence.js';
+
+interface ISmartdataSessionBinding {
+  session: SmartdataSession;
+  contextToken: symbol;
+  owner: SmartdataDb;
+  client: plugins.mongodb.MongoClient;
+  rawSession: plugins.mongodb.ClientSession;
+  operationActive: boolean;
+  transactionActive: boolean;
+  transactionCallbackOpen: boolean;
+  transactionUsesOrdinaryWrite: boolean;
+  transactionAttempt?: symbol;
+  transactionFailure?: { error: unknown };
+  operationSettled?: Promise<void>;
+  resolveOperationSettled?: () => void;
+  invalidated: boolean;
+  closing?: Promise<void>;
+}
+
+const bindings = new WeakMap<SmartdataSession, ISmartdataSessionBinding>();
+const bindingsByOwner = new WeakMap<SmartdataDb, Set<ISmartdataSessionBinding>>();
+const smartdataSessionInvalidationAggregateBrand = Symbol(
+  'smartdataSessionInvalidationAggregate',
+);
+
+class SmartdataSessionInvalidationAggregateError extends AggregateError {
+  public readonly [smartdataSessionInvalidationAggregateBrand] = true;
+}
+interface ITransactionContext {
+  contextToken: symbol;
+  attempt: symbol;
+}
+
+interface ISmartdataSessionAcquireOptions {
+  ordinaryWrite?: boolean;
+}
+
+interface IOrdinarySessionOperationOptions {
+  ordinaryWrite?: boolean;
+  prepared?: boolean;
+  preparationMessage?: string;
+}
+
+const transactionContext = new plugins.nodeAsyncHooks.AsyncLocalStorage<
+  ITransactionContext
+>();
+
+const resolveBinding = (
+  sessionArg: SmartdataSession,
+  ownerArg?: SmartdataDb,
+): ISmartdataSessionBinding => {
+  const binding = bindings.get(sessionArg);
+  if (!binding || binding.invalidated || binding.rawSession.hasEnded) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'The SmartData session has ended or is no longer valid.',
+    );
+  }
+  if (ownerArg && binding.owner !== ownerArg) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'The SmartData session belongs to another database.',
+    );
+  }
+  if (
+    binding.owner.status !== 'connected'
+    || binding.owner.mongoDbClient !== binding.client
+  ) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'The SmartData session belongs to a stale database lifecycle.',
+    );
+  }
+  return binding;
+};
+
+const assertTransactionSucceeded = (bindingArg: ISmartdataSessionBinding): void => {
+  if (bindingArg.transactionFailure) {
+    throw bindingArg.transactionFailure.error;
+  }
+};
+
+export class SmartdataSession {
+  public async withTransaction<TResult>(
+    callbackArg: (sessionArg: SmartdataSession) => Promise<TResult>,
+  ): Promise<TResult | undefined> {
+    if (typeof callbackArg !== 'function') {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'SmartData transaction callback must be a function.',
+      );
+    }
+    const binding = resolveBinding(this);
+    if (binding.operationActive || binding.transactionActive) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Parallel or nested SmartData session operations are not supported.',
+      );
+    }
+    binding.transactionActive = true;
+    let callbackError: unknown;
+    try {
+      return await binding.rawSession.withTransaction(async () => {
+        const attempt = Symbol('smartdataTransactionAttempt');
+        binding.transactionAttempt = attempt;
+        binding.transactionCallbackOpen = true;
+        binding.transactionUsesOrdinaryWrite = false;
+        binding.transactionFailure = undefined;
+        callbackError = undefined;
+        try {
+          let callbackReturned = false;
+          try {
+            const result = await transactionContext.run(
+              { contextToken: binding.contextToken, attempt },
+              async () => callbackArg(this),
+            );
+            callbackReturned = true;
+            return result;
+          } finally {
+            const activeOperation = binding.operationActive
+              ? binding.operationSettled
+              : undefined;
+            binding.transactionCallbackOpen = false;
+            if (binding.transactionAttempt === attempt) {
+              binding.transactionAttempt = undefined;
+            }
+            if (activeOperation) {
+              await activeOperation;
+            }
+            assertTransactionSucceeded(binding);
+            if (callbackReturned && activeOperation) {
+              throw new SmartdataPersistenceError(
+                'unsupported_operation',
+                'A SmartData transaction callback returned with an operation still active.',
+              );
+            }
+          }
+        } catch (errorArg) {
+          callbackError = errorArg;
+          throw errorArg;
+        }
+      });
+    } catch (errorArg) {
+      if (errorArg === callbackError) {
+        throw errorArg;
+      }
+      if (binding.transactionUsesOrdinaryWrite) {
+        return normalizeOrdinaryPersistenceError(
+          errorArg,
+          'SmartData transaction conflicts with a unique index.',
+        );
+      }
+      throw errorArg;
+    } finally {
+      binding.transactionActive = false;
+      binding.transactionUsesOrdinaryWrite = false;
+      binding.transactionFailure = undefined;
+    }
+  }
+
+  public async close(): Promise<void> {
+    const binding = bindings.get(this);
+    if (!binding) {
+      return;
+    }
+    if (binding.operationActive || binding.transactionActive) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Cannot close a SmartData session while an operation is active.',
+      );
+    }
+    await closeSessionBinding(binding);
+  }
+}
+
+export const createSmartdataSession = (ownerArg: SmartdataDb): SmartdataSession => {
+  if (ownerArg.status !== 'connected' || !ownerArg.mongoDbClient) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'Cannot create a SmartData session before the database is connected.',
+    );
+  }
+  const session = new SmartdataSession();
+  const binding: ISmartdataSessionBinding = {
+    session,
+    contextToken: Symbol('smartdataSessionContext'),
+    owner: ownerArg,
+    client: ownerArg.mongoDbClient,
+    rawSession: ownerArg.mongoDbClient.startSession(),
+    operationActive: false,
+    transactionActive: false,
+    transactionCallbackOpen: false,
+    transactionUsesOrdinaryWrite: false,
+    invalidated: false,
+  };
+  bindings.set(session, binding);
+  let ownerBindings = bindingsByOwner.get(ownerArg);
+  if (!ownerBindings) {
+    ownerBindings = new Set();
+    bindingsByOwner.set(ownerArg, ownerBindings);
+  }
+  ownerBindings.add(binding);
+  return session;
+};
+
+export const acquireSmartdataSession = (
+  sessionArg: SmartdataSession,
+  ownerArg: SmartdataDb,
+  optionsArg: ISmartdataSessionAcquireOptions = {},
+): {
+  rawSession: plugins.mongodb.ClientSession;
+  release: () => void;
+} => {
+  const binding = resolveBinding(sessionArg, ownerArg);
+  if (binding.transactionFailure) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'The SmartData transaction attempt has aborted and cannot accept further operations.',
+    );
+  }
+  const currentContext = transactionContext.getStore();
+  const isOwnedTransactionContext =
+    currentContext?.contextToken === binding.contextToken;
+  if (
+    binding.operationActive
+    || (
+      binding.transactionActive
+      && (
+        !binding.transactionCallbackOpen
+        || !isOwnedTransactionContext
+        || currentContext.attempt !== binding.transactionAttempt
+      )
+    )
+    || (!binding.transactionActive && isOwnedTransactionContext)
+  ) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'Parallel SmartData session operations are not supported.',
+    );
+  }
+  if (optionsArg.ordinaryWrite && binding.transactionActive) {
+    binding.transactionUsesOrdinaryWrite = true;
+  }
+  binding.operationActive = true;
+  binding.operationSettled = new Promise<void>((resolveArg) => {
+    binding.resolveOperationSettled = resolveArg;
+  });
+  let released = false;
+  return {
+    rawSession: binding.rawSession,
+    release: () => {
+      if (!released) {
+        released = true;
+        binding.operationActive = false;
+        binding.resolveOperationSettled?.();
+        binding.operationSettled = undefined;
+        binding.resolveOperationSettled = undefined;
+      }
+    },
+  };
+};
+
+/** Marks the current owned attempt for rollback by withTransaction. */
+export const failSmartdataTransaction = (
+  sessionArg: SmartdataSession,
+  ownerArg: SmartdataDb,
+  errorArg: unknown,
+): never => {
+  const binding = resolveBinding(sessionArg, ownerArg);
+  const context = transactionContext.getStore();
+  if (
+    !binding.operationActive
+    || !binding.transactionActive
+    || context?.contextToken !== binding.contextToken
+    || context.attempt !== binding.transactionAttempt
+  ) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'Only the active owned operation can abort a SmartData transaction attempt.',
+    );
+  }
+  binding.transactionFailure ??= { error: errorArg };
+  throw binding.transactionFailure.error;
+};
+
+export type TSmartdataOrdinarySession =
+  | plugins.mongodb.ClientSession
+  | SmartdataSession;
+
+export const isSmartdataSession = (
+  sessionArg: TSmartdataOrdinarySession | undefined,
+): sessionArg is SmartdataSession => sessionArg instanceof SmartdataSession;
+
+export const isOrdinarySessionInTransaction = (
+  sessionArg: TSmartdataOrdinarySession | undefined,
+): boolean => {
+  if (!sessionArg) {
+    return false;
+  }
+  if (isSmartdataSession(sessionArg)) {
+    return resolveBinding(sessionArg).transactionActive;
+  }
+  return sessionArg.inTransaction();
+};
+
+export const runWithOrdinarySmartdataSession = async <TResult>(
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  ownerArg: SmartdataDb,
+  optionsArg: IOrdinarySessionOperationOptions,
+  operationArg: (
+    rawSessionArg: plugins.mongodb.ClientSession | undefined,
+  ) => Promise<TResult>,
+): Promise<TResult> => {
+  if (!isSmartdataSession(sessionArg)) {
+    return operationArg(sessionArg);
+  }
+  if (!optionsArg.prepared) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      optionsArg.preparationMessage ||
+        'Initialize every participating SmartData model before using an owned session.',
+    );
+  }
+  const lease = acquireSmartdataSession(sessionArg, ownerArg, {
+    ordinaryWrite: optionsArg.ordinaryWrite,
+  });
+  try {
+    return await operationArg(lease.rawSession);
+  } finally {
+    lease.release();
+  }
+};
+
+export const invalidateSmartdataSessions = async (
+  ownerArg: SmartdataDb,
+): Promise<void> => {
+  const ownerBindings = bindingsByOwner.get(ownerArg);
+  if (!ownerBindings) {
+    return;
+  }
+  const sessions = [...ownerBindings];
+  for (const bindingArg of sessions) {
+    bindingArg.invalidated = true;
+  }
+  const results = await Promise.allSettled(
+    sessions.map((bindingArg) =>
+      closeSessionBinding(bindingArg),
+    ),
+  );
+  const errors = results.flatMap((resultArg) =>
+    resultArg.status === 'rejected' ? [resultArg.reason] : [],
+  );
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  if (errors.length > 1) {
+    throw new SmartdataSessionInvalidationAggregateError(
+      errors,
+      'Multiple SmartData sessions failed to close.',
+    );
+  }
+};
+
+/** Failed cleanup remains owned and invalidated until an explicit retry succeeds. */
+const closeSessionBinding = async (bindingArg: ISmartdataSessionBinding): Promise<void> => {
+  if (bindingArg.closing) return bindingArg.closing;
+  bindingArg.invalidated = true;
+  const closing = Promise.resolve().then(async () => {
+    await bindingArg.rawSession.endSession();
+    bindingsByOwner.get(bindingArg.owner)?.delete(bindingArg);
+    bindings.delete(bindingArg.session);
+  });
+  bindingArg.closing = closing;
+  try { await closing; } finally { bindingArg.closing = undefined; }
+};
+
+export const unwrapSmartdataSessionInvalidationErrors = (
+  errorArg: unknown,
+): readonly unknown[] | undefined =>
+  errorArg instanceof SmartdataSessionInvalidationAggregateError
+    ? errorArg.errors
+    : undefined;

package/ts/nosqldb/classes.storedinspection.ts

@@ -0,0 +1,151 @@
+import * as plugins from './plugins.js';
+import type { SmartdataDb } from './classes.db.js';
+import { convertFilterForMongoDb } from './classes.doc.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import { runCursorOperation } from './classes.cursoroperation.js';
+import { acquireSmartdataSession, isSmartdataSession, type SmartdataSession } from './classes.session.js';
+import {
+  collectionTopologyDbInspectionSymbol, collectionModelSchemaResolverSymbol,
+} from './classes.collectiontopology.js';
+import type { INormalizedCollectionModelSchema } from './classes.collection.js';
+import { validateOrdinaryStoredDocument } from './classes.ordinarypersistence.js';
+
+export interface ISmartdataStoredInspectionOptions {
+  filter?: Record<string, unknown>;
+  /** Default 100, maximum 10000. Results are ordered by immutable _id. */
+  limit?: number;
+  skip?: number;
+  /** Default 4 MiB, maximum 64 MiB; overflow rejects the entire page. */
+  maxBytes?: number;
+  /** Default 5000ms, maximum 120000ms. */
+  timeoutMS?: number;
+  signal?: AbortSignal;
+  session?: SmartdataSession;
+}
+
+export interface ISmartdataStoredInspection {
+  readonly documents: readonly Readonly<Record<string, unknown>>[];
+  readonly hasMore: boolean;
+}
+
+export type TSmartdataOrdinaryDocumentEvidence =
+  | { readonly status: 'valid' }
+  | { readonly status: 'invalid'; readonly code: 'invalid_document' }
+  | { readonly status: 'not_configured' };
+
+export interface ISmartdataStoredDocumentEvidence {
+  /** Untouched stored BSON for diagnosis, never an authorized application record. */
+  readonly document: Readonly<Record<string, unknown>>;
+  /** Reports only the model's ordinary persistence assertion, not exact/domain assertions. */
+  readonly ordinaryValidation: TSmartdataOrdinaryDocumentEvidence;
+}
+
+export interface ISmartdataStoredEvidenceInspection {
+  readonly evidence: readonly ISmartdataStoredDocumentEvidence[];
+  readonly hasMore: boolean;
+}
+
+/** No model binding, index initialization, hydration, or raw handle escapes. */
+const readStoredDocuments = async (
+  modelArg: any,
+  dbArg: SmartdataDb,
+  opts: ISmartdataStoredInspectionOptions = {},
+): Promise<{
+  schema: INormalizedCollectionModelSchema;
+  page: { documents: plugins.mongodb.Document[]; hasMore: boolean };
+}> => {
+  if (!opts || Object.getPrototypeOf(opts) !== Object.prototype ||
+    Reflect.ownKeys(opts).some((keyArg) => typeof keyArg !== 'string' ||
+      !['filter', 'limit', 'skip', 'maxBytes', 'timeoutMS', 'signal', 'session'].includes(keyArg) ||
+      !('value' in Object.getOwnPropertyDescriptor(opts, keyArg)!))) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Invalid stored inspection options.');
+  }
+  const limit = opts.limit === undefined ? 100 : opts.limit;
+  const skip = opts.skip === undefined ? 0 : opts.skip;
+  const maxBytes = opts.maxBytes === undefined ? 4 * 1024 * 1024 : opts.maxBytes;
+  const timeoutMS = opts.timeoutMS === undefined ? 5_000 : opts.timeoutMS;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 10_000 ||
+    !Number.isSafeInteger(skip) || skip < 0 || skip > 2_147_483_647 ||
+    !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 64 * 1024 * 1024 ||
+    !Number.isSafeInteger(timeoutMS) || timeoutMS < 1 || timeoutMS > 120_000 ||
+    (opts.signal !== undefined && !(opts.signal instanceof AbortSignal)) ||
+    (opts.session !== undefined && !isSmartdataSession(opts.session))) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Invalid stored inspection bounds or context.');
+  }
+  opts.signal?.throwIfAborted();
+  const schema: INormalizedCollectionModelSchema = modelArg[collectionModelSchemaResolverSymbol]();
+  const filter = convertFilterForMongoDb(opts.filter || {});
+  const lease = opts.session ? acquireSmartdataSession(opts.session, dbArg) : undefined;
+  let page: { documents: plugins.mongodb.Document[]; hasMore: boolean };
+  try {
+    page = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg) => {
+      const cursor = mongoDbArg.collection(schema.collectionName).find(filter, {
+        sort: { _id: 1 }, skip, limit: limit + 1, batchSize: 1,
+        timeoutMS, timeoutMode: 'cursorLifetime', signal: opts.signal, session: lease?.rawSession,
+      });
+      return runCursorOperation(cursor, async (cursorArg) => {
+        const documents: plugins.mongodb.Document[] = [];
+        let bytes = 0;
+        while (true) {
+          const next = await cursorArg.next();
+          if (next === null) return { documents, hasMore: false };
+          if (documents.length === limit) return { documents, hasMore: true };
+          bytes += plugins.mongodb.BSON.calculateObjectSize(next);
+          if (bytes > maxBytes) throw new SmartdataPersistenceError('unsupported_operation',
+            'Stored inspection exceeds its byte budget.');
+          documents.push(next);
+        }
+      }, opts.signal);
+    });
+  } catch (errorArg) {
+    opts.signal?.throwIfAborted();
+    throw errorArg;
+  } finally { lease?.release(); }
+  return { schema, page };
+};
+
+/** @internal Strict inspection used by Model.inspectStoredDocuments. */
+export const inspectStoredDocuments = async (
+  modelArg: any,
+  dbArg: SmartdataDb,
+  opts: ISmartdataStoredInspectionOptions = {},
+): Promise<ISmartdataStoredInspection> => {
+  const { schema, page } = await readStoredDocuments(modelArg, dbArg, opts);
+  // Full validation occurs on the untouched stored envelope, before any
+  // constructor/default/serializer can hide field-presence evidence.
+  const documents = schema.ordinaryPersistence
+    ? page.documents.map((documentArg) => validateOrdinaryStoredDocument(
+      documentArg, schema.ordinaryPersistence!, schema.persistedFields,
+    ))
+    : page.documents;
+  return Object.freeze({ documents: Object.freeze(documents), hasMore: page.hasMore });
+};
+
+/**
+ * @internal Diagnostic inspection preserves malformed evidence from the same
+ * model and bounds as strict inspection. Invalid records must never enter
+ * normal application flows. Exact and domain assertions remain caller-owned.
+ */
+export const inspectStoredDocumentEvidence = async (
+  modelArg: any,
+  dbArg: SmartdataDb,
+  opts: ISmartdataStoredInspectionOptions = {},
+): Promise<ISmartdataStoredEvidenceInspection> => {
+  const { schema, page } = await readStoredDocuments(modelArg, dbArg, opts);
+  const evidence = page.documents.map((documentArg): ISmartdataStoredDocumentEvidence => {
+    let ordinaryValidation: TSmartdataOrdinaryDocumentEvidence = { status: 'not_configured' };
+    if (schema.ordinaryPersistence) {
+      try {
+        validateOrdinaryStoredDocument(documentArg, schema.ordinaryPersistence, schema.persistedFields);
+        ordinaryValidation = { status: 'valid' };
+      } catch (errorArg) {
+        if (!(errorArg instanceof SmartdataPersistenceError) || errorArg.code !== 'invalid_document') {
+          throw errorArg;
+        }
+        ordinaryValidation = { status: 'invalid', code: 'invalid_document' };
+      }
+    }
+    return Object.freeze({ document: documentArg, ordinaryValidation: Object.freeze(ordinaryValidation) });
+  });
+  return Object.freeze({ evidence: Object.freeze(evidence), hasMore: page.hasMore });
+};