@lossless.org/client 0.1.0

package/ts/nosqldb/classes.db.ts

@@ -0,0 +1,637 @@
+import * as plugins from './plugins.js';
+
+import { SmartdataCollection } from './classes.collection.js';
+import { EasyStore } from './classes.easystore.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import { SmartdataMongoAdministration } from './classes.mongoadministration.js';
+import {
+  createSmartdataSession,
+  invalidateSmartdataSessions,
+  SmartdataSession,
+  unwrapSmartdataSessionInvalidationErrors,
+} from './classes.session.js';
+import { collectionTopologyDbInspectionSymbol } from './classes.collectiontopology.js';
+import {
+  inspectSmartdataNamespace,
+  type ISmartdataNamespaceInspectionOptions,
+  type ISmartdataNamespaceInspection,
+} from './classes.namespaceinspection.js';
+
+export { SmartdataSession } from './classes.session.js';
+export type { TSmartdataOrdinarySession } from './classes.session.js';
+
+import { logger } from './logging.js';
+import { assertDataOptions, SmartdataOperationBudget } from './classes.operationbudget.js';
+
+/**
+ * interface - indicates the connection status of the db
+ */
+export type TConnectionStatus = 'initial' | 'disconnected' | 'connected' | 'failed';
+
+export interface ISmartdataReadinessOptions {
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface ISmartdataInitOptions {
+  /** Bounds connection setup; cleanup is always joined before the call settles. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface ISmartdataCloseOptions {
+  /** Total deadline for removal, including preceding session cleanup (1..120000 ms). */
+  timeoutMs?: number;
+  dropDatabase?: {
+    expectedDatabaseName: string;
+  };
+}
+
+export type TSmartdataReadinessFailureReason =
+  | 'not_initialized'
+  | 'connecting'
+  | 'connection_failed'
+  | 'closing'
+  | 'closed'
+  | 'close_failed'
+  | 'aborted'
+  | 'timeout'
+  | 'unavailable';
+
+export type TSmartdataReadinessResult =
+  | {
+      ready: true;
+      status: 'ready';
+      durationMs: number;
+    }
+  | {
+      ready: false;
+      status: 'unavailable';
+      reason: TSmartdataReadinessFailureReason;
+      durationMs: number;
+    };
+
+type TSmartdataDbLifecycleState =
+  | 'initial'
+  | 'connecting'
+  | 'connected'
+  | 'connection_failed'
+  | 'closing'
+  | 'closed'
+  | 'close_failed';
+
+type TSmartdataDbLifecycleOperation = 'init' | 'close';
+
+const readinessDefaultTimeoutMs = 2_000;
+const readinessMaximumTimeoutMs = 30_000;
+
+const assertExactDataObject = (
+  valueArg: unknown,
+  expectedKeysArg: readonly string[],
+  descriptionArg: string,
+  allowEmptyArg = false,
+): Record<string, unknown> => {
+  if (
+    valueArg === null ||
+    typeof valueArg !== 'object' ||
+    Array.isArray(valueArg) ||
+    Object.getPrototypeOf(valueArg) !== Object.prototype
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${descriptionArg} must be a plain object.`,
+    );
+  }
+  const keys = Reflect.ownKeys(valueArg);
+  if (
+    (!allowEmptyArg && keys.length !== expectedKeysArg.length) ||
+    (allowEmptyArg && keys.length !== 0 && keys.length !== expectedKeysArg.length) ||
+    keys.some(
+      (keyArg) =>
+        typeof keyArg !== 'string' || !expectedKeysArg.includes(keyArg),
+    )
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${descriptionArg} has an invalid shape.`,
+    );
+  }
+  for (const key of keys as string[]) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (!descriptor || !('value' in descriptor)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${descriptionArg} must contain data properties only.`,
+      );
+    }
+  }
+  return valueArg as Record<string, unknown>;
+};
+
+export class SmartdataDb {
+  smartdataOptions: plugins.tsclass.database.IMongoDescriptor;
+  mongoDbClient!: plugins.mongodb.MongoClient;
+  mongoDb!: plugins.mongodb.Db;
+  status: TConnectionStatus;
+  statusConnectedDeferred = plugins.smartpromise.defer();
+  smartdataCollectionMap = new plugins.lik.ObjectMap<SmartdataCollection<any>>();
+  private lifecycleState: TSmartdataDbLifecycleState = 'initial';
+  private lifecycleEpoch = 0;
+  private activeLifecycleOperation: TSmartdataDbLifecycleOperation | null = null;
+  private pendingClient?: plugins.mongodb.MongoClient;
+
+  constructor(smartdataOptions: plugins.tsclass.database.IMongoDescriptor) {
+    this.smartdataOptions = smartdataOptions;
+    this.status = 'initial';
+    void this.statusConnectedDeferred.promise.catch(() => {});
+  }
+
+  // easystore
+  public async createEasyStore<T = unknown>(nameIdArg: string): Promise<EasyStore<T>> {
+    const easyStore = new EasyStore<T>(nameIdArg, this);
+    return easyStore;
+  }
+
+  // basic connection stuff ----------------------------------------------
+
+  /**
+   * connects to the database that was specified during instance creation
+   */
+  public async init(optionsArg: ISmartdataInitOptions = {}): Promise<void> {
+    this.assertLifecycleOperationCanBegin('init');
+    const options = assertDataOptions(optionsArg, ['timeoutMs', 'signal']);
+    const budget = Object.keys(options).length
+      ? new SmartdataOperationBudget(options.timeoutMs ?? 30_000, options.signal) : undefined;
+    try { budget?.check(); } catch (errorArg) { budget?.close(); throw errorArg; }
+    this.beginLifecycleOperation('init');
+    this.transitionLifecycle('connecting');
+    let candidateClient: plugins.mongodb.MongoClient | undefined;
+    try {
+      try {
+        // Safely encode credentials to handle special characters
+        const encodedUser = this.smartdataOptions.mongoDbUser
+          ? encodeURIComponent(this.smartdataOptions.mongoDbUser)
+          : '';
+        const encodedPass = this.smartdataOptions.mongoDbPass
+          ? encodeURIComponent(this.smartdataOptions.mongoDbPass)
+          : '';
+
+        const finalConnectionUrl = this.smartdataOptions.mongoDbUrl
+          .replace('<USERNAME>', encodedUser)
+          .replace('<username>', encodedUser)
+          .replace('<USER>', encodedUser)
+          .replace('<user>', encodedUser)
+          .replace('<PASSWORD>', encodedPass)
+          .replace('<password>', encodedPass)
+          .replace('<DBNAME>', this.smartdataOptions.mongoDbName || '')
+          .replace('<dbname>', this.smartdataOptions.mongoDbName || '');
+
+        const descriptor = this.smartdataOptions as plugins.tsclass.database.IMongoDescriptor &
+          Pick<plugins.mongodb.MongoClientOptions, 'maxPoolSize' | 'maxIdleTimeMS' |
+            'serverSelectionTimeoutMS' | 'socketTimeoutMS'>;
+        const clientOptions: plugins.mongodb.MongoClientOptions = {
+          maxPoolSize: descriptor.maxPoolSize ?? 100,
+          maxIdleTimeMS: descriptor.maxIdleTimeMS ?? 300000,
+          serverSelectionTimeoutMS:
+            budget?.remainingMs() ?? descriptor.serverSelectionTimeoutMS ?? 30000,
+          ...(budget ? { connectTimeoutMS: budget.remainingMs() } : {}),
+          socketTimeoutMS: descriptor.socketTimeoutMS ?? 30000,
+          retryWrites: true,
+        };
+
+        candidateClient = new plugins.mongodb.MongoClient(finalConnectionUrl, clientOptions);
+        this.pendingClient = candidateClient;
+        const connectingClient = candidateClient;
+        let cancellationCleanup: Promise<void> | undefined;
+        const onAbort = () => {
+          cancellationCleanup ??= connectingClient.close();
+          // The connection and this cleanup are both joined below.
+          void cancellationCleanup.catch(() => {});
+        };
+        budget?.signal.addEventListener('abort', onAbort, { once: true });
+        try {
+          budget?.check();
+          await connectingClient.connect();
+          budget?.check();
+        } finally {
+          budget?.signal.removeEventListener('abort', onAbort);
+          if (cancellationCleanup) await cancellationCleanup;
+        }
+        const candidateDb = candidateClient.db(
+          this.smartdataOptions.mongoDbName,
+        );
+        for (const collection of this.smartdataCollectionMap.getArray()) {
+          collection.resetForDatabaseReconnect();
+        }
+        budget?.check();
+        this.mongoDbClient = candidateClient;
+        this.mongoDb = candidateDb;
+        candidateClient = undefined;
+        this.pendingClient = undefined;
+        this.status = 'connected';
+        this.transitionLifecycle('connected');
+        this.statusConnectedDeferred.resolve();
+        logger.log('info', `Connected to database ${this.smartdataOptions.mongoDbName}`);
+      } catch (error) {
+        let cleanupError: unknown;
+        if (candidateClient) {
+          try {
+            // A cancelled connect may establish resources after its first close.
+            await candidateClient.close();
+            this.pendingClient = undefined;
+          } catch (errorArg) {
+            cleanupError = errorArg;
+          }
+        }
+        this.status = 'disconnected';
+        this.transitionLifecycle(this.pendingClient ? 'close_failed' : 'connection_failed');
+        logger.log('error', 'Failed to connect to the SmartData database.');
+        if (budget) {
+          throw new SmartdataPersistenceError('unsupported_operation', this.pendingClient
+            ? 'SmartData connection setup and cleanup failed; close must be retried.'
+            : 'SmartData connection setup failed or was cancelled.');
+        }
+        if (cleanupError) throw new AggregateError([error, cleanupError],
+          'SmartData connection setup and cleanup failed; close must be retried.');
+        throw error;
+      }
+    } finally {
+      this.endLifecycleOperation('init');
+      budget?.close();
+    }
+  }
+
+  /**
+   * closes the connection to the databse
+   */
+  public async close(optionsArg: ISmartdataCloseOptions = {}): Promise<void> {
+    this.assertLifecycleOperationCanBegin('close');
+    const databaseToDrop = this.resolveDatabaseToDrop(optionsArg);
+    const timeoutMs = Object.hasOwn(optionsArg, 'timeoutMs') ? optionsArg.timeoutMs : undefined;
+    const budget = timeoutMs === undefined ? undefined : new SmartdataOperationBudget(timeoutMs);
+    this.beginLifecycleOperation('close');
+    this.transitionLifecycle('closing');
+    this.status = 'disconnected';
+    const mongoDbClient = this.pendingClient ?? this.mongoDbClient;
+    try {
+      const closeErrors: unknown[] = [];
+      try {
+        await invalidateSmartdataSessions(this);
+      } catch (errorArg) {
+        closeErrors.push(
+          ...(unwrapSmartdataSessionInvalidationErrors(errorArg) ?? [errorArg]),
+        );
+      }
+      if (databaseToDrop) {
+        try {
+          const databaseDropped = await databaseToDrop.dropDatabase(budget?.operationOptions());
+          if (!databaseDropped) {
+            throw new SmartdataPersistenceError(
+              'unsupported_operation',
+              'MongoDB did not acknowledge the requested database removal.',
+            );
+          }
+        } catch (errorArg) {
+          closeErrors.push(errorArg);
+        }
+      }
+      try {
+        await mongoDbClient?.close();
+        this.pendingClient = undefined;
+      } catch (errorArg) {
+        closeErrors.push(errorArg);
+      }
+      if (closeErrors.length > 0) {
+        this.transitionLifecycle('close_failed');
+        if (budget) throw new SmartdataPersistenceError('unsupported_operation',
+          'SmartData database cleanup failed; close must be retried.');
+        if (closeErrors.length === 1) {
+          throw closeErrors[0];
+        }
+        throw new AggregateError(
+          closeErrors,
+          'Multiple SmartData database cleanup operations failed.',
+        );
+      }
+      this.transitionLifecycle('closed');
+      logger.log('info', `disconnected from database ${this.smartdataOptions.mongoDbName}`);
+    } finally {
+      this.endLifecycleOperation('close');
+      budget?.close();
+    }
+  }
+
+  /**
+   * Performs a bounded, read-only round trip to verify database readiness.
+   */
+  public async checkReadiness(
+    optionsArg: ISmartdataReadinessOptions = {},
+  ): Promise<TSmartdataReadinessResult> {
+    const startedAt = performance.now();
+    const timeoutMs = optionsArg.timeoutMs ?? readinessDefaultTimeoutMs;
+    if (
+      !Number.isSafeInteger(timeoutMs) ||
+      timeoutMs <= 0 ||
+      timeoutMs > readinessMaximumTimeoutMs
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `Readiness timeoutMs must be a positive safe integer no greater than ${readinessMaximumTimeoutMs}.`,
+      );
+    }
+
+    const lifecycleReason = this.getReadinessLifecycleReason();
+    if (lifecycleReason) {
+      return this.createReadinessFailure(lifecycleReason, startedAt);
+    }
+
+    const signal = optionsArg.signal;
+    if (signal?.aborted) {
+      return this.createReadinessFailure('aborted', startedAt);
+    }
+
+    const lifecycleEpoch = this.lifecycleEpoch;
+    const mongoDb = this.mongoDb;
+    const mongoDbClient = this.mongoDbClient;
+    let response: plugins.mongodb.BSON.Document;
+    try {
+      response = await mongoDb.command(
+        { ping: 1 },
+        {
+          timeoutMS: timeoutMs,
+          signal,
+        },
+      );
+    } catch (error) {
+      if (signal?.aborted) {
+        return this.createReadinessFailure('aborted', startedAt);
+      }
+      if (
+        this.lifecycleEpoch !== lifecycleEpoch ||
+        this.mongoDb !== mongoDb ||
+        this.mongoDbClient !== mongoDbClient
+      ) {
+        return this.createReadinessFailure(
+          this.getReadinessLifecycleReason() ?? 'unavailable',
+          startedAt,
+        );
+      }
+      if (error instanceof plugins.mongodb.MongoOperationTimeoutError) {
+        return this.createReadinessFailure('timeout', startedAt);
+      }
+      return this.createReadinessFailure('unavailable', startedAt);
+    }
+
+    if (
+      this.lifecycleEpoch !== lifecycleEpoch ||
+      this.mongoDb !== mongoDb ||
+      this.mongoDbClient !== mongoDbClient
+    ) {
+      return this.createReadinessFailure(
+        this.getReadinessLifecycleReason() ?? 'unavailable',
+        startedAt,
+      );
+    }
+
+    if (response.ok !== 1) {
+      return this.createReadinessFailure('unavailable', startedAt);
+    }
+
+    return {
+      ready: true,
+      status: 'ready',
+      durationMs: performance.now() - startedAt,
+    };
+  }
+
+  /**
+   * Starts a raw MongoDB session. Use createSession() when every transaction
+   * operation goes through SmartData and stable persistence errors are needed.
+   */
+  public startSession(): plugins.mongodb.ClientSession {
+    return this.mongoDbClient.startSession();
+  }
+
+  /**
+   * Creates a SmartData-owned session for model transactions.
+   */
+  public createSession(): SmartdataSession {
+    return createSmartdataSession(this);
+  }
+
+  /**
+   * Creates a narrowly scoped MongoDB administration facade bound to this
+   * SmartData lifecycle. Applications never need direct driver access.
+   */
+  public createMongoAdministration(): SmartdataMongoAdministration {
+    return new SmartdataMongoAdministration(this);
+  }
+
+  /** Observe all namespaces, indexes and bounded counts without initializing models. */
+  public async inspectNamespace(
+    optionsArg?: ISmartdataNamespaceInspectionOptions,
+  ): Promise<ISmartdataNamespaceInspection> {
+    return inspectSmartdataNamespace(this, optionsArg);
+  }
+
+  /** @internal Runs inspection or explicit model preparation against one connection generation. */
+  public async [collectionTopologyDbInspectionSymbol]<TResult>(
+    operationArg: (mongoDbArg: plugins.mongodb.Db, assertCurrentArg: () => void) => Promise<TResult>,
+  ): Promise<TResult> {
+    if (
+      this.lifecycleState !== 'connected' ||
+      this.status !== 'connected' ||
+      !this.mongoDb ||
+      !this.mongoDbClient ||
+      this.mongoDb.client !== this.mongoDbClient
+    ) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Collection topology inspection requires a connected SmartdataDb.',
+      );
+    }
+    const lifecycleEpoch = this.lifecycleEpoch;
+    const mongoDb = this.mongoDb;
+    const mongoDbClient = this.mongoDbClient;
+    const connectionIsCurrent = () =>
+      this.lifecycleState === 'connected' &&
+      this.status === 'connected' &&
+      this.lifecycleEpoch === lifecycleEpoch &&
+      this.mongoDb === mongoDb &&
+      this.mongoDbClient === mongoDbClient &&
+      mongoDb.client === mongoDbClient;
+    let result: TResult;
+    try {
+      result = await operationArg(mongoDb, () => {
+        if (!connectionIsCurrent()) {
+          throw new SmartdataPersistenceError('unsupported_operation', 'SmartData connection changed during operation.');
+        }
+      });
+    } catch {
+      if (!connectionIsCurrent()) {
+        throw new SmartdataPersistenceError(
+          'unsupported_operation',
+          'SmartData connection changed during collection topology inspection.',
+        );
+      }
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'Collection topology inspection failed.',
+      );
+    }
+    if (!connectionIsCurrent()) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'SmartData connection changed during collection topology inspection.',
+      );
+    }
+    return result;
+  }
+
+  // handle table to class distribution
+
+  public addCollection(SmartdataCollectionArg: SmartdataCollection<any>) {
+    this.smartdataCollectionMap.add(SmartdataCollectionArg);
+  }
+
+  /**
+   * Gets a collection's name and returns a SmartdataCollection instance
+   * @param nameArg
+   * @returns DbTable
+   */
+  public async getSmartdataCollectionByName<T>(nameArg: string): Promise<SmartdataCollection<T>> {
+    const resultCollection = await this.smartdataCollectionMap.find(async (dbTableArg) => {
+      return dbTableArg.collectionName === nameArg;
+    });
+    return resultCollection;
+  }
+
+  private beginLifecycleOperation(operationArg: TSmartdataDbLifecycleOperation): void {
+    this.assertLifecycleOperationCanBegin(operationArg);
+    this.activeLifecycleOperation = operationArg;
+  }
+
+  private assertLifecycleOperationCanBegin(
+    operationArg: TSmartdataDbLifecycleOperation,
+  ): void {
+    if (this.activeLifecycleOperation) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        `Cannot start SmartData database ${operationArg} while ${this.activeLifecycleOperation} is still running.`,
+      );
+    }
+    if (
+      operationArg === 'init' &&
+      (this.lifecycleState === 'connected' ||
+        this.lifecycleState === 'close_failed')
+    ) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        `Cannot start SmartData database init while the existing client is ${this.lifecycleState}.`,
+      );
+    }
+  }
+
+  private resolveDatabaseToDrop(
+    optionsArg: ISmartdataCloseOptions,
+  ): plugins.mongodb.Db | undefined {
+    const options = assertDataOptions(optionsArg, ['dropDatabase', 'timeoutMs']);
+    if (!Object.hasOwn(options, 'dropDatabase')) {
+      return undefined;
+    }
+    const dropDatabaseOptions = assertExactDataObject(
+      options.dropDatabase,
+      ['expectedDatabaseName'],
+      'SmartData dropDatabase options',
+    );
+    const expectedDatabaseName = dropDatabaseOptions.expectedDatabaseName;
+    if (
+      typeof expectedDatabaseName !== 'string' ||
+      expectedDatabaseName.length === 0 ||
+      expectedDatabaseName.trim() !== expectedDatabaseName
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'SmartData expectedDatabaseName must be a non-empty string without surrounding whitespace.',
+      );
+    }
+    if (
+      this.lifecycleState !== 'connected' ||
+      this.status !== 'connected' ||
+      !this.mongoDbClient ||
+      !this.mongoDb
+    ) {
+      throw new SmartdataPersistenceError(
+        'unsupported_operation',
+        'SmartData can remove a database only from a connected lifecycle.',
+      );
+    }
+    if (this.mongoDb.client !== this.mongoDbClient) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'SmartData database and client bindings are inconsistent.',
+      );
+    }
+    const boundDatabaseName = this.mongoDb.databaseName;
+    if (expectedDatabaseName !== boundDatabaseName) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'SmartData expectedDatabaseName does not match the connected database.',
+      );
+    }
+    if (this.smartdataOptions.mongoDbName !== boundDatabaseName) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        'SmartData database descriptor no longer matches the connected database.',
+      );
+    }
+    return this.mongoDb;
+  }
+
+  private endLifecycleOperation(operationArg: TSmartdataDbLifecycleOperation): void {
+    if (this.activeLifecycleOperation === operationArg) {
+      this.activeLifecycleOperation = null;
+    }
+  }
+
+  private transitionLifecycle(stateArg: TSmartdataDbLifecycleState): void {
+    this.lifecycleState = stateArg;
+    this.lifecycleEpoch++;
+  }
+
+  private getReadinessLifecycleReason():
+    | Exclude<
+        TSmartdataReadinessFailureReason,
+        'aborted' | 'timeout' | 'unavailable'
+      >
+    | undefined {
+    switch (this.lifecycleState) {
+      case 'initial':
+        return 'not_initialized';
+      case 'connecting':
+        return 'connecting';
+      case 'connection_failed':
+        return 'connection_failed';
+      case 'closing':
+        return 'closing';
+      case 'closed':
+        return 'closed';
+      case 'close_failed':
+        return 'close_failed';
+      case 'connected':
+        return undefined;
+    }
+  }
+
+  private createReadinessFailure(
+    reasonArg: TSmartdataReadinessFailureReason,
+    startedAtArg: number,
+  ): TSmartdataReadinessResult {
+    return {
+      ready: false,
+      status: 'unavailable',
+      reason: reasonArg,
+      durationMs: performance.now() - startedAtArg,
+    };
+  }
+}