@lossless.org/client 0.1.0

package/ts/nosqldb/classes.testdatabase.ts

@@ -0,0 +1,272 @@
+import * as plugins from './plugins.js';
+import { snapshotBoundedBsonDocument } from './classes.bsonsnapshot.js';
+import { SmartdataDb } from './classes.db.js';
+import { SmartDataDbDoc } from './classes.doc.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import { assertDataOptions, SmartdataOperationBudget } from './classes.operationbudget.js';
+
+export interface ISmartdataTestConnection {
+  /** Literal loopback IPv4, ::1, or localhost (normalized to 127.0.0.1). */
+  host: string;
+  port: number;
+  /** Supply both credentials or neither. Authentication uses admin. */
+  username?: string;
+  password?: string;
+}
+
+export interface ISmartdataTestDatabaseOptions {
+  connection: ISmartdataTestConnection;
+  /** Default 5000; maximum 120000 ms, shared by connection and ownership checks. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface ISmartdataStoredDocumentFaultOptions {
+  /** Default 64 KiB, maximum 1 MiB. */
+  maxBytes?: number;
+  /** Default 5000; maximum 120000 ms, including collection preparation. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface ISmartdataIndexFaultOptions {
+  /** Default 5000; maximum 120000 ms, shared by topology verification and removal. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export type TSmartdataTestModel = Pick<typeof SmartDataDbDoc,
+  'prototype' | 'collection' | 'getExpectedCollectionTopology' | 'prepareCollection'> &
+  (abstract new (...args: never[]) => object);
+
+/** Construction failed and cleanup also failed. Explicit close retries the retained owner. */
+export class SmartdataTestDatabaseCreationError extends SmartdataPersistenceError {
+  readonly #cleanup: () => Promise<void>;
+  constructor(cleanupArg: () => Promise<void>) {
+    super('unsupported_operation', 'Disposable database setup failed and cleanup must be retried with close().');
+    this.name = 'SmartdataTestDatabaseCreationError';
+    this.#cleanup = cleanupArg;
+  }
+  public close(): Promise<void> { return this.#cleanup(); }
+}
+
+const faultError = (): SmartdataPersistenceError => new SmartdataPersistenceError(
+  'invalid_argument', 'Fault data must be bounded, inert, canonical BSON with an explicit scalar _id.',
+);
+
+const canonicalFaultDocument = (valueArg: unknown, maxBytesArg: number): plugins.mongodb.Document =>
+  snapshotBoundedBsonDocument(valueArg, maxBytesArg, faultError);
+
+/** Disposable fault injection is available only through the testsupport package subpath. */
+export class SmartdataTestDatabase {
+  public readonly db: SmartdataDb;
+  readonly #name = `smartdata_test_${plugins.nodeCrypto.randomBytes(24).toString('hex')}`;
+  readonly #descriptor: SmartdataDb['smartdataOptions'];
+  #owned = false;
+  #closed = false;
+  #stopping = false;
+  #reconnectForRemoval = false;
+  #active?: Promise<void>;
+  #closing?: Promise<void>;
+
+  private constructor(connectionArg: ISmartdataTestConnection) {
+    const host = connectionArg.host === 'localhost' ? '127.0.0.1' : connectionArg.host;
+    const authority = host === '::1' ? '[::1]' : host;
+    const credentials = connectionArg.username === undefined ? ''
+      : `${encodeURIComponent(connectionArg.username)}:${encodeURIComponent(connectionArg.password!)}@`;
+    this.#descriptor = Object.freeze({
+      mongoDbName: this.#name,
+      mongoDbUrl: `mongodb://${credentials}${authority}:${connectionArg.port}/?directConnection=true&authSource=admin`,
+    });
+    this.db = new SmartdataDb(this.#descriptor);
+  }
+
+  public static async create(optionsArg: ISmartdataTestDatabaseOptions): Promise<SmartdataTestDatabase> {
+    const options = assertDataOptions(optionsArg, ['connection', 'timeoutMs', 'signal']);
+    const connection = assertDataOptions(options.connection, ['host', 'port', 'username', 'password']);
+    if (typeof connection.host !== 'string' ||
+      !(connection.host === 'localhost' || connection.host === '::1' ||
+        (plugins.nodeNet.isIP(connection.host) === 4 && connection.host.startsWith('127.'))) ||
+      !Number.isSafeInteger(connection.port) || (connection.port as number) < 1 || (connection.port as number) > 65535 ||
+      ((connection.username === undefined) !== (connection.password === undefined)) ||
+      [connection.username, connection.password].some((valueArg) => valueArg !== undefined &&
+        (typeof valueArg !== 'string' || valueArg.length < 1 || valueArg.length > 1024))) {
+      throw new SmartdataPersistenceError('invalid_argument', 'An explicit loopback host, port and optional credential pair are required.');
+    }
+    const budget = new SmartdataOperationBudget(options.timeoutMs ?? 5000, options.signal);
+    let fixture: SmartdataTestDatabase | undefined;
+    try {
+      budget.check();
+      fixture = new SmartdataTestDatabase(connection as unknown as ISmartdataTestConnection);
+      await fixture.db.init({ timeoutMs: budget.remainingMs(), signal: budget.signal });
+      const databases = await fixture.db.mongoDb.admin().listDatabases({
+        filter: { name: fixture.#name }, nameOnly: true, authorizedDatabases: false,
+        ...budget.operationOptions(),
+      });
+      if (databases.ok !== 1 || !Array.isArray(databases.databases) || databases.databases.length !== 0) {
+        throw new SmartdataPersistenceError('invalid_configuration', 'The disposable namespace already exists or cannot be verified.');
+      }
+      const namespace = await fixture.db.inspectNamespace({ maxCollections: 1,
+        timeoutMs: budget.remainingMs(), signal: budget.signal });
+      if (namespace.collections.length) throw new SmartdataPersistenceError('invalid_configuration',
+        'The disposable namespace is not blank.');
+      budget.check();
+      fixture.#owned = true;
+      return fixture;
+    } catch (errorArg) {
+      if (fixture) {
+        try { await fixture.close(); } catch {
+          const retained = fixture;
+          throw new SmartdataTestDatabaseCreationError(() => retained.close());
+        }
+      }
+      throw new SmartdataPersistenceError(errorArg instanceof SmartdataPersistenceError ? errorArg.code : 'unsupported_operation',
+        'Disposable database setup failed or was cancelled.');
+    } finally { budget.close(); }
+  }
+
+  public insertStoredDocumentFault(modelArg: TSmartdataTestModel, documentArg: unknown,
+    optionsArg: ISmartdataStoredDocumentFaultOptions = {}): Promise<void> {
+    return this.inject(modelArg, documentArg, undefined, optionsArg);
+  }
+
+  public replaceStoredDocumentFault(modelArg: TSmartdataTestModel, expectedIdArg: unknown,
+    documentArg: unknown, optionsArg: ISmartdataStoredDocumentFaultOptions = {}): Promise<void> {
+    return this.inject(modelArg, documentArg, { expectedId: expectedIdArg }, optionsArg);
+  }
+
+  /** Remove one declared secondary index from an exact, owned test collection. */
+  public async dropDeclaredIndexFault(modelArg: TSmartdataTestModel, indexNameArg: string,
+    optionsArg: ISmartdataIndexFaultOptions = {}): Promise<void> {
+    const options = assertDataOptions(optionsArg, ['timeoutMs', 'signal']);
+    const budget = new SmartdataOperationBudget(options.timeoutMs ?? 5000, options.signal);
+    try {
+      budget.check();
+      this.assertFaultAvailable();
+      const expected = this.getFaultModelTopology(modelArg);
+      if (typeof indexNameArg !== 'string' || indexNameArg === '_id_' || indexNameArg === '*' ||
+        !expected.indexes.some((indexArg) => indexArg.name === indexNameArg)) {
+        throw new SmartdataPersistenceError('invalid_argument',
+          'Index fault injection requires one declared secondary index name.');
+      }
+      const operation = (async () => {
+        this.assertOwnedBinding();
+        const targetDb = this.db.mongoDb;
+        await modelArg.prepareCollection({ mode: 'requireExact', timeoutMs: budget.remainingMs(), signal: budget.signal });
+        this.assertOwnedBinding();
+        if (this.db.mongoDb !== targetDb) throw new SmartdataPersistenceError(
+          'unsupported_operation', 'The disposable database connection changed.');
+        await targetDb.collection(expected.collectionName).dropIndex(indexNameArg, budget.operationOptions());
+        budget.check();
+        this.assertOwnedBinding();
+        if (this.db.mongoDb !== targetDb) throw new SmartdataPersistenceError(
+          'unsupported_operation', 'The disposable database connection changed.');
+      })();
+      this.#active = operation;
+      try { await operation; } finally { this.#active = undefined; }
+    } catch (errorArg) {
+      throw new SmartdataPersistenceError(errorArg instanceof SmartdataPersistenceError ? errorArg.code : 'unsupported_operation',
+        'Declared-index fault injection failed or was cancelled.');
+    } finally { budget.close(); }
+  }
+
+  private assertFaultAvailable(): void {
+    if (this.#stopping || this.#closed || !this.#owned || this.#active) throw new SmartdataPersistenceError(
+      'unsupported_operation', 'The disposable database is closed, closing, or already injecting a fault.');
+  }
+
+  private getFaultModelTopology(modelArg: TSmartdataTestModel) {
+    if (typeof modelArg !== 'function' || plugins.nodeUtil.types.isProxy(modelArg) ||
+      !(modelArg.prototype instanceof SmartDataDbDoc)) throw new SmartdataPersistenceError(
+        'invalid_argument', 'Fault injection requires the declared SmartData model constructor.');
+    const collection = modelArg.collection;
+    const expected = modelArg.getExpectedCollectionTopology();
+    if (collection.smartdataDb !== this.db || collection.collectionName !== expected.collectionName) {
+      throw new SmartdataPersistenceError('invalid_configuration', 'The fault model must belong to this disposable database.');
+    }
+    return expected;
+  }
+
+  private assertOwnedBinding(): void {
+    if (this.db.smartdataOptions !== this.#descriptor || this.db.mongoDb.databaseName !== this.#name ||
+      this.db.mongoDb.client !== this.db.mongoDbClient || this.db.status !== 'connected') {
+      throw new SmartdataPersistenceError('invalid_configuration', 'The disposable database binding has changed.');
+    }
+  }
+
+  private async inject(modelArg: TSmartdataTestModel, documentArg: unknown,
+    replacementArg: { expectedId: unknown } | undefined, optionsArg: ISmartdataStoredDocumentFaultOptions): Promise<void> {
+    const options = assertDataOptions(optionsArg, ['maxBytes', 'timeoutMs', 'signal']);
+    const maxBytes = options.maxBytes ?? 65536;
+    if (!Number.isSafeInteger(maxBytes) || (maxBytes as number) < 1 || (maxBytes as number) > 1024 * 1024) throw faultError();
+    const budget = new SmartdataOperationBudget(options.timeoutMs ?? 5000, options.signal);
+    try {
+      budget.check();
+      this.assertFaultAvailable();
+      const document = canonicalFaultDocument(documentArg, maxBytes as number);
+      if (replacementArg) {
+        const expected = canonicalFaultDocument({ _id: replacementArg.expectedId }, maxBytes as number);
+        if (!Buffer.from(plugins.mongodb.BSON.serialize(expected)).equals(
+          Buffer.from(plugins.mongodb.BSON.serialize({ _id: document._id })))) throw faultError();
+      }
+      const expected = this.getFaultModelTopology(modelArg);
+      const operation = (async () => {
+        this.assertOwnedBinding();
+        await modelArg.prepareCollection({ mode: 'ensureCompatible', timeoutMs: budget.remainingMs(), signal: budget.signal });
+        this.assertOwnedBinding();
+        const raw = this.db.mongoDb.collection(expected.collectionName);
+        if (replacementArg) {
+          const result = await raw.replaceOne({ _id: document._id }, document,
+            { upsert: false, ...budget.operationOptions() });
+          if (!result.acknowledged || result.matchedCount !== 1) throw new SmartdataPersistenceError(
+            'unsupported_operation', 'Exact fault replacement requires one existing document.');
+        } else {
+          const result = await raw.insertOne(document, budget.operationOptions());
+          if (!result.acknowledged) throw new SmartdataPersistenceError('unsupported_operation', 'Fault insertion was not acknowledged.');
+        }
+        budget.check();
+      })();
+      this.#active = operation;
+      try { await operation; } finally { this.#active = undefined; }
+    } catch (errorArg) {
+      throw new SmartdataPersistenceError(errorArg instanceof SmartdataPersistenceError ? errorArg.code : 'unsupported_operation',
+        'Stored-document fault injection failed or was cancelled.');
+    } finally { budget.close(); }
+  }
+
+  /** Idempotent after success. A failed close retains ownership for an explicit retry. */
+  public async close(optionsArg: { timeoutMs?: number } = {}): Promise<void> {
+    const options = assertDataOptions(optionsArg, ['timeoutMs']);
+    const budget = new SmartdataOperationBudget(options.timeoutMs ?? 5000);
+    try {
+      if (this.#closed) return;
+      this.#stopping = true;
+      if (this.#closing) {
+        const closing = this.#closing;
+        await budget.waitFor(closing);
+        await closing;
+        return;
+      }
+      const closing = this.dispose(budget);
+      this.#closing = closing;
+      try { await closing; } finally { this.#closing = undefined; }
+    } catch {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'Disposable database cleanup failed; close must be retried.');
+    } finally { budget.close(); }
+  }
+
+  private async dispose(budgetArg: SmartdataOperationBudget): Promise<void> {
+    if (this.#active) await budgetArg.waitFor(this.#active);
+    if (this.#owned && this.#reconnectForRemoval) {
+      await this.db.close({ timeoutMs: budgetArg.remainingMs() });
+      this.db.smartdataOptions = this.#descriptor;
+      await this.db.init({ timeoutMs: budgetArg.remainingMs(), signal: budgetArg.signal });
+    }
+    this.#reconnectForRemoval = this.#owned;
+    await this.db.close({ timeoutMs: budgetArg.remainingMs(),
+      ...(this.#owned ? { dropDatabase: { expectedDatabaseName: this.#name } } : {}) });
+    this.#closed = true;
+    this.#owned = false;
+  }
+}

package/ts/nosqldb/classes.watcher.ts

@@ -0,0 +1,96 @@
+import { SmartDataDbDoc } from './classes.doc.js';
+import * as plugins from './plugins.js';
+import { EventEmitter } from 'node:events';
+
+/**
+ * a wrapper for the native mongodb cursor. Exposes better
+ */
+/**
+ * Wraps a MongoDB ChangeStream with RxJS and EventEmitter support.
+ */
+export class SmartdataDbWatcher<T = any> extends EventEmitter {
+  // STATIC
+  public readyDeferred = plugins.smartpromise.defer();
+
+  // INSTANCE
+  private changeStream: plugins.mongodb.ChangeStream<any>;
+  private rawSubject: plugins.smartrx.rxjs.Subject<T>;
+  private closePromise?: Promise<void>;
+  private onChange: (itemArg: any) => void;
+  private onStreamError: (errorArg: unknown) => void;
+  /** Terminal read/hydration failure, also delivered to subscribed error handlers. */
+  public failure?: unknown;
+  /** Emits change documents (or arrays of documents if buffered) */
+  public changeSubject: any;
+  /**
+   * @param changeStreamArg native MongoDB ChangeStream
+   * @param smartdataDbDocArg document class for instance creation
+   * @param opts.bufferTimeMs optional milliseconds to buffer events via RxJS
+   */
+  constructor(
+    changeStreamArg: plugins.mongodb.ChangeStream<any>,
+    smartdataDbDocArg: typeof SmartDataDbDoc,
+    opts?: { bufferTimeMs?: number },
+  ) {
+    super();
+    this.rawSubject = new plugins.smartrx.rxjs.Subject<T>();
+    // Apply buffering if requested
+    if (opts && opts.bufferTimeMs) {
+      this.changeSubject = this.rawSubject.pipe(plugins.smartrx.rxjs.ops.bufferTime(opts.bufferTimeMs));
+    } else {
+      this.changeSubject = this.rawSubject;
+    }
+    this.changeStream = changeStreamArg;
+    this.onStreamError = (errorArg) => {
+      if (this.closePromise) return;
+      this.failure = errorArg;
+      void this.close().catch((closeErrorArg) => {
+        this.failure = new AggregateError([errorArg, closeErrorArg], 'Watcher failed and cleanup failed.');
+      });
+      this.rawSubject.error(errorArg);
+      if (this.listenerCount('error') > 0) this.emit('error', errorArg);
+    };
+    this.onChange = (item: any) => {
+      if (this.closePromise) return;
+      let docInstance: T | null = null;
+      try {
+        if (item.fullDocument) {
+          docInstance = smartdataDbDocArg.createInstanceFromMongoDbNativeDoc(
+            item.fullDocument
+          ) as any as T;
+        }
+      } catch (errorArg) { this.onStreamError(errorArg); return; }
+      // Notify subscribers
+      this.rawSubject.next(docInstance as T);
+      this.emit('change', docInstance);
+    };
+    this.changeStream.on('change', this.onChange);
+    this.changeStream.on('error', this.onStreamError);
+    // Signal readiness after one tick
+    plugins.smartdelay.delayFor(0).then(() => {
+      this.readyDeferred.resolve();
+    });
+  }
+
+  /**
+   * Close the change stream, complete the RxJS subject, and remove listeners.
+   */
+  public async close(): Promise<void> {
+    this.closePromise ??= (async () => {
+      try { await this.changeStream.close(); }
+      finally {
+        this.changeStream.off('change', this.onChange);
+        this.changeStream.off('error', this.onStreamError);
+        this.rawSubject.complete();
+        this.removeAllListeners();
+      }
+    })();
+    return this.closePromise;
+  }
+  /**
+   * Alias for close(), matching README usage
+   */
+  public async stop(): Promise<void> {
+    return this.close();
+  }
+}

package/ts/nosqldb/index.ts

@@ -0,0 +1,51 @@
+// Polyfill must be imported first - ES modules hoist exports before code runs
+import './shim.js';
+
+export { NoSqlConnection } from './classes.connection.js';
+export type { INoSqlConnectionOptions } from './classes.connection.js';
+
+export * from './classes.db.js';
+export * from './classes.mongoadministration.js';
+export type {
+  ISmartdataNamespaceInspectionOptions,
+  ISmartdataNamespaceInspection,
+  ISmartdataObservedCollection,
+  TSmartdataObservedDocumentCount,
+} from './classes.namespaceinspection.js';
+export * from './classes.collection.js';
+export type { ISmartdataCollectionPreparationOptions } from './classes.collectionpreparation.js';
+export type { ISmartdataBootstrapRecordOptions, ISmartdataBootstrapRecordResult } from './classes.bootstraprecord.js';
+export type {
+  ISmartdataCollectionTopologyIndex,
+  ISmartdataCollectionTopologyIndexKey,
+  ISmartdataCollectionTopologyInspection,
+  ISmartdataExpectedCollectionTopology,
+  TSmartdataCollectionTopologyIndexDirection,
+  TSmartdataCollectionTopologyReasonCode,
+  TSmartdataCollectionTopologyStatus,
+} from './classes.collectiontopology.js';
+export * from './classes.doc.js';
+export { ordinaryPersistence } from './classes.ordinarypersistence.js';
+export type { IOrdinaryPersistenceOptions } from './classes.ordinarypersistence.js';
+export type {
+  ISmartdataStoredInspectionOptions, ISmartdataStoredInspection,
+  ISmartdataStoredDocumentEvidence, ISmartdataStoredEvidenceInspection,
+  TSmartdataOrdinaryDocumentEvidence,
+} from './classes.storedinspection.js';
+export { SmartdataPersistenceError } from './classes.persistence.js';
+export type { TSmartdataPersistenceErrorCode } from './classes.persistence.js';
+export * from './classes.exactpersistence.js';
+export * from './classes.easystore.js';
+export * from './classes.cursor.js';
+export * from './classes.watcher.js';
+export * from './classes.distributedcoordinator.js';
+export * from './classes.cached-document.js';
+
+import * as convenience from './classes.convenience.js';
+
+export { convenience };
+
+// to be removed with the next breaking update
+import type * as plugins from './plugins.js';
+type IMongoDescriptor = plugins.tsclass.database.IMongoDescriptor;
+export type { IMongoDescriptor };

package/ts/nosqldb/logging.ts

@@ -0,0 +1,3 @@
+import * as plugins from './plugins.js';
+
+export const logger = new plugins.smartlog.ConsoleLog();

package/ts/nosqldb/plugins.ts

@@ -0,0 +1,37 @@
+// tsclass scope
+import * as tsclass from '@tsclass/tsclass';
+
+export { tsclass };
+
+// @pushrocks scope
+import * as lik from '@push.rocks/lik';
+import * as smartdelay from '@push.rocks/smartdelay';
+import * as smartlog from '@push.rocks/smartlog';
+import * as smartpromise from '@push.rocks/smartpromise';
+import * as smartrx from '@push.rocks/smartrx';
+import * as smartstring from '@push.rocks/smartstring';
+import * as smarttime from '@push.rocks/smarttime';
+import * as smartunique from '@push.rocks/smartunique';
+import * as taskbuffer from '@push.rocks/taskbuffer';
+import * as mongodb from 'mongodb';
+import * as nodeUtil from 'node:util';
+import * as nodeAsyncHooks from 'node:async_hooks';
+import * as nodeCrypto from 'node:crypto';
+import * as nodeNet from 'node:net';
+
+export {
+  lik,
+  smartdelay,
+  smartpromise,
+  smartlog,
+  smartrx,
+  mongodb,
+  nodeUtil,
+  nodeAsyncHooks,
+  nodeCrypto,
+  nodeNet,
+  smartstring,
+  smarttime,
+  smartunique,
+  taskbuffer,
+};

package/ts/nosqldb/shim.ts

@@ -0,0 +1,6 @@
+/**
+ * Polyfill for Symbol.metadata required by TC39 Stage 3 decorators.
+ * Must be imported before any decorator code loads.
+ * @see https://github.com/tc39/proposal-decorator-metadata
+ */
+(Symbol as any).metadata ??= Symbol.for('Symbol.metadata');

package/ts/nosqldb/testsupport.ts

@@ -0,0 +1,13 @@
+import './shim.js';
+
+export {
+  SmartdataTestDatabase,
+  SmartdataTestDatabaseCreationError,
+} from './classes.testdatabase.js';
+export type {
+  ISmartdataTestConnection,
+  ISmartdataTestDatabaseOptions,
+  ISmartdataStoredDocumentFaultOptions,
+  ISmartdataIndexFaultOptions,
+  TSmartdataTestModel,
+} from './classes.testdatabase.js';