@lossless.org/nosqldb 10.11.0 → 11.0.0

package/ts/ts_local/classes.localnosqldb.ts

@@ -0,0 +1,631 @@
+import {
+  normalizeStoppedStorageRootAlignmentInput, normalizeStoppedStorageRootAlignmentResult,
+  normalizeStoppedStorageRootAlignmentAbortResult,
+  type ILocalNoSqlDbStoppedStorageRootAlignmentInput, type TLocalNoSqlDbStoppedStorageRootAlignmentResult,
+  type ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult,
+} from '../ts_nosqldb/storage-root-alignment.js';
+import {
+  NoSqlDbStoppedOperationError,
+  normalizeStoppedStorageRootInspectionInput,
+  validateNoSqlDbStoppedOperationOptions,
+  isStoppedOperationUnknownMethod,
+  type INoSqlDbStoppedOperationOptions,
+  type ILocalNoSqlDbStoppedStorageRootInspectionInput,
+  type TLocalNoSqlDbStoppedStorageRootInspection,
+} from '../ts_nosqldb/stopped-storage.js';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as net from 'node:net';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  NoSqlDbServer,
+  type NoSqlDbEngineExitError,
+  type INoSqlDbAuthOptions,
+  type ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+  type ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult,
+  type ILocalNoSqlDbStoppedStorageRootRelocationInput,
+  type ILocalNoSqlDbStoppedStorageRootRelocationReceipt,
+  type ILocalNoSqlDbOfflineStringValueInspection,
+  type INoSqlDbManagementOperationOptions,
+  type TLocalNoSqlDbOfflineStringValueInspectionResult,
+} from '../ts_nosqldb/index.js';
+import {
+  RustDbBridge,
+  attachNoSqlDbEngineStderrTail,
+  rustDbBridgeStorageRootRelocation,
+  rustDbBridgeStorageRootAlignment,
+  rustDbBridgeStorageRootAlignmentAbort,
+} from '../ts_nosqldb/rust-db-bridge.js';
+import { validateNoSqlDbStorageRehearsalStartup } from '../ts_nosqldb/storage-rehearsal.js';
+import { noStopRequestResult, type INoSqlDbServerStopResult } from '../ts_nosqldb/server/classes.nosqldbserver.js';
+import {
+  type TNoSqlDbFileStorageStartup,
+} from '../ts_nosqldb/file-storage-startup.js';
+import {
+  normalizeNoSqlDbFileStorageOptions,
+} from '../ts_nosqldb/file-storage-options.js';
+import {
+  normalizeLocalNoSqlDbOfflinePhysicalNamespaceInspectionInput,
+  normalizeLocalNoSqlDbOfflineInspectionInput,
+  validateNoSqlDbManagementOperationOptions,
+} from '../ts_nosqldb/offline-inspection.js';
+import {
+  assertNoLocalNoSqlDbStorageRootRelocationWorkspace,
+  isLocalNoSqlDbStorageRootRelocationErrorCode,
+  LocalNoSqlDbStorageRootRelocationError,
+  normalizeLocalNoSqlDbStoppedStorageRootRelocationInput,
+  normalizeLocalNoSqlDbStoppedStorageRootRelocationReceipt,
+} from '../ts_nosqldb/storage-root-relocation.js';
+
+/**
+ * Connection information returned by LocalNoSqlDb.start()
+ */
+export interface ILocalNoSqlDbConnectionInfo {
+  /** The Unix socket file path */
+  socketPath: string;
+  /** Connection URI (mongodb:// scheme) ready for MongoClient */
+  connectionUri: string;
+}
+
+export interface ILocalNoSqlDbOptions {
+  /** Persisted authentication, including the source-verbatim credentials of a rehearsal destination. */
+  auth?: INoSqlDbAuthOptions;
+  /** Exact rehearsal operation ID; requires current-format-only startup and an explicit private socket. */
+  storageRehearsalId?: string;
+  /** Exact engine executable. Invalid explicit paths reject without chmod or discovery fallback. Omit for normal discovery. */
+  binaryPath?: string;
+  /** Default: current-format-only. existing-only refuses missing, empty or uninitialized storage. */
+  fileStorageStartup?: TNoSqlDbFileStorageStartup;
+  /** Required: where to store data */
+  folderPath: string;
+  /** Optional: custom socket path (default: auto-generated in /tmp) */
+  socketPath?: string;
+  /** Receives every engine standard-error line; as `INoSqlDbServerOptions.engineLog`. */
+  engineLog?: (line: string) => void;
+  /** Called once for each unexpected engine exit; as `INoSqlDbServerOptions.onEngineExit`. */
+  onEngineExit?: (error: NoSqlDbEngineExitError) => void;
+}
+
+/**
+ * LocalNoSqlDb - Lightweight local MongoDB-compatible database using Unix sockets
+ *
+ * This class wraps NoSqlDbServer and provides a simple interface for
+ * starting a local file-based database server. Returns connection
+ * info that you can use with any compatible driver instance.
+ *
+ * @example
+ * ```typescript
+ * import { LocalNoSqlDb } from '@lossless.org/nosqldb';
+ * import { MongoClient } from 'mongodb';
+ *
+ * const db = new LocalNoSqlDb({ folderPath: './data' });
+ * const { connectionUri } = await db.start();
+ *
+ * // Connect with the driver
+ * const client = new MongoClient(connectionUri, { directConnection: true });
+ * await client.connect();
+ *
+ * // Use the client
+ * const collection = client.db('mydb').collection('users');
+ * await collection.insertOne({ name: 'Alice' });
+ *
+ * // When done
+ * await client.close();
+ * await db.stop();
+ * ```
+ */
+export class LocalNoSqlDb {
+  private static storageRootRelocationGate: Promise<void> = Promise.resolve();
+  private static storageRootRelocationBridge: RustDbBridge | undefined;
+  private options: ILocalNoSqlDbOptions;
+  private server: NoSqlDbServer | null = null;
+  private generatedSocketPath: string | null = null;
+
+  constructor(options: ILocalNoSqlDbOptions) {
+    validateNoSqlDbStorageRehearsalStartup({ ...options, storage: 'file', storagePath: options.folderPath });
+    this.options = {
+      ...options,
+      ...normalizeNoSqlDbFileStorageOptions({ ...options, storage: 'file' }),
+    };
+  }
+
+  private static createOfflineInspectionBridge(binaryPath?: string): RustDbBridge {
+    return new RustDbBridge({ binaryPath });
+  }
+
+  private static createStorageRootRelocationBridge(binaryPath?: string): RustDbBridge {
+    return new RustDbBridge({ binaryPath });
+  }
+
+  private static async withStorageRootRelocationGate<TResult>(
+    operationArg: () => Promise<TResult>,
+  ): Promise<TResult> {
+    const previous = LocalNoSqlDb.storageRootRelocationGate;
+    let release!: () => void;
+    LocalNoSqlDb.storageRootRelocationGate = new Promise<void>((resolveArg) => {
+      release = resolveArg;
+    });
+    await previous;
+    try {
+      return await operationArg();
+    } finally {
+      release();
+    }
+  }
+
+  private static remainingManagementTimeout(
+    deadlineArg: number | undefined,
+  ): number | undefined {
+    if (deadlineArg === undefined) return undefined;
+    const remaining = deadlineArg - Date.now();
+    if (remaining <= 0) {
+      throw new LocalNoSqlDbStorageRootRelocationError('IO');
+    }
+    return remaining;
+  }
+
+  /**
+   * Relocate one stopped current native file root, including authenticated
+   * roots, under continuous ownership. Preserve the returned source receipt;
+   * interrupted operations require the identical request to finish recovery.
+   */
+  public static async relocateStoppedStorageRoot(
+    inputArg: ILocalNoSqlDbStoppedStorageRootRelocationInput,
+    optionsArg?: INoSqlDbStoppedOperationOptions,
+  ): Promise<ILocalNoSqlDbStoppedStorageRootRelocationReceipt> {
+    let input: ILocalNoSqlDbStoppedStorageRootRelocationInput;
+    try {
+      input = normalizeLocalNoSqlDbStoppedStorageRootRelocationInput(inputArg);
+      validateNoSqlDbStoppedOperationOptions(optionsArg);
+    } catch (error) {
+      if (error instanceof LocalNoSqlDbStorageRootRelocationError) throw error;
+      throw new LocalNoSqlDbStorageRootRelocationError('INVALID_REQUEST');
+    }
+    if (optionsArg?.signal?.aborted) {
+      throw new LocalNoSqlDbStorageRootRelocationError('IO');
+    }
+    if (process.platform !== 'linux' && process.platform !== 'darwin') {
+      throw new LocalNoSqlDbStorageRootRelocationError('UNSUPPORTED');
+    }
+    const deadline = optionsArg?.timeoutMs === undefined
+      ? undefined
+      : Date.now() + optionsArg.timeoutMs;
+
+    return LocalNoSqlDb.withStorageRootRelocationGate(async () => {
+      const retainedBridge = LocalNoSqlDb.storageRootRelocationBridge;
+      if (retainedBridge) {
+        try {
+          await retainedBridge.terminate({ gracePeriodMs: 0 });
+        } catch {
+          throw new LocalNoSqlDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+        if (!retainedBridge.ownershipReleased) {
+          throw new LocalNoSqlDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+        if (LocalNoSqlDb.storageRootRelocationBridge === retainedBridge) {
+          LocalNoSqlDb.storageRootRelocationBridge = undefined;
+        }
+      }
+
+      let bridge: RustDbBridge | undefined;
+      let receipt: ILocalNoSqlDbStoppedStorageRootRelocationReceipt | undefined;
+      let operationError: LocalNoSqlDbStorageRootRelocationError | undefined;
+      try {
+        bridge = LocalNoSqlDb.createStorageRootRelocationBridge(optionsArg?.binaryPath);
+        LocalNoSqlDb.storageRootRelocationBridge = bridge;
+        const spawnTimeout = LocalNoSqlDb.remainingManagementTimeout(deadline);
+        const spawned = await bridge.spawn({
+          ...(optionsArg?.signal ? { signal: optionsArg.signal } : {}),
+          ...(spawnTimeout === undefined ? {} : { timeoutMs: spawnTimeout }),
+        });
+        if (!spawned) {
+          throw new LocalNoSqlDbStorageRootRelocationError('IO');
+        }
+        const commandTimeout = LocalNoSqlDb.remainingManagementTimeout(deadline);
+        const result = await bridge[rustDbBridgeStorageRootRelocation](input, {
+          ...(optionsArg?.signal ? { signal: optionsArg.signal } : {}),
+          ...(commandTimeout === undefined ? {} : { timeoutMs: commandTimeout }),
+        });
+        receipt = normalizeLocalNoSqlDbStoppedStorageRootRelocationReceipt(result, input);
+      } catch (error) {
+        if (error instanceof NoSqlDbStoppedOperationError || isStoppedOperationUnknownMethod(error, 'relocateStoppedStorageRoot')) {
+          operationError = new LocalNoSqlDbStorageRootRelocationError(error instanceof NoSqlDbStoppedOperationError ? error.code : 'UNSUPPORTED');
+        } else if (error instanceof LocalNoSqlDbStorageRootRelocationError) {
+          operationError = error;
+        } else {
+          const requestWasDispatched = error instanceof Error
+            && 'requestId' in error
+            && typeof error.requestId === 'string';
+          if (
+            requestWasDispatched
+            && error instanceof Error
+            && 'responseErrorCode' in error
+            && isLocalNoSqlDbStorageRootRelocationErrorCode(error.responseErrorCode)
+          ) {
+            operationError = new LocalNoSqlDbStorageRootRelocationError(error.responseErrorCode);
+          } else {
+            operationError = new LocalNoSqlDbStorageRootRelocationError(
+              requestWasDispatched ? 'RECOVERY_REQUIRED' : 'IO',
+            );
+          }
+        }
+      }
+
+      if (bridge) {
+        try {
+          await bridge.terminate({ gracePeriodMs: 0 });
+          if (!bridge.ownershipReleased) {
+            throw new Error('termination was not confirmed');
+          }
+          if (LocalNoSqlDb.storageRootRelocationBridge === bridge) {
+            LocalNoSqlDb.storageRootRelocationBridge = undefined;
+          }
+        } catch {
+          operationError = new LocalNoSqlDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+      }
+      if (operationError) throw operationError;
+      if (!receipt) {
+        throw new LocalNoSqlDbStorageRootRelocationError('RECOVERY_REQUIRED');
+      }
+      return receipt;
+    });
+  }
+
+  private static createStorageRootAlignmentBridge(binaryPath?: string): RustDbBridge {
+    return new RustDbBridge({ binaryPath });
+  }
+
+  /** Adopt an authority-free stopped copy as an independent provider. Retain its external receipt. */
+  public static alignStoppedStorageRoot(input: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
+    options?: INoSqlDbStoppedOperationOptions): Promise<TLocalNoSqlDbStoppedStorageRootAlignmentResult> {
+    return LocalNoSqlDb.runStorageRootAlignment(input, options, false, normalizeStoppedStorageRootAlignmentResult);
+  }
+  /** Abort only the exact incomplete profile append; a complete append must be finished. */
+  public static abortStoppedStorageRootAlignment(input: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
+    options?: INoSqlDbStoppedOperationOptions): Promise<ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult> {
+    return LocalNoSqlDb.runStorageRootAlignment(input, options, true, normalizeStoppedStorageRootAlignmentAbortResult);
+  }
+  private static async runStorageRootAlignment<TResult>(inputArg: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
+    options: INoSqlDbStoppedOperationOptions | undefined, abort: boolean,
+    normalize: (value: unknown, input: ILocalNoSqlDbStoppedStorageRootAlignmentInput) => TResult): Promise<TResult> {
+    let input: ILocalNoSqlDbStoppedStorageRootAlignmentInput;
+    try {
+      input = normalizeStoppedStorageRootAlignmentInput(inputArg);
+      validateNoSqlDbStoppedOperationOptions(options);
+      if (abort && input.dryRun) throw new Error('abort cannot be a dry run');
+    } catch { throw new NoSqlDbStoppedOperationError('INVALID_REQUEST'); }
+    if (options?.signal?.aborted) throw new NoSqlDbStoppedOperationError('CANCELLED');
+    if (!['linux', 'darwin'].includes(process.platform)) throw new NoSqlDbStoppedOperationError('UNSUPPORTED');
+    const deadline = Date.now() + (options?.timeoutMs ?? 3_600_000);
+    const remaining = () => {
+      if (options?.signal?.aborted) throw new NoSqlDbStoppedOperationError('CANCELLED');
+      const timeoutMs = deadline - Date.now();
+      if (timeoutMs <= 0) throw new NoSqlDbStoppedOperationError('CANCELLED');
+      return { signal: options?.signal, timeoutMs };
+    };
+    // Share the mutation gate and retained ownership with relocation, including
+    // retries after an earlier sidecar could not confirm termination.
+    return LocalNoSqlDb.withStorageRootRelocationGate(async () => {
+      const retained = LocalNoSqlDb.storageRootRelocationBridge;
+      if (retained) {
+        try { await retained.terminate({ gracePeriodMs: 0 }); }
+        catch { throw new NoSqlDbStoppedOperationError('RECOVERY_REQUIRED'); }
+        if (!retained.ownershipReleased) throw new NoSqlDbStoppedOperationError('RECOVERY_REQUIRED');
+        LocalNoSqlDb.storageRootRelocationBridge = undefined;
+      }
+      let bridge: RustDbBridge | undefined;
+      let result: TResult | undefined;
+      let failure: NoSqlDbStoppedOperationError | undefined;
+      let dispatched = false;
+      const method = abort ? 'abortStoppedStorageRootAlignment' : 'alignStoppedStorageRoot';
+      try {
+        remaining();
+        bridge = LocalNoSqlDb.createStorageRootAlignmentBridge(options?.binaryPath);
+        LocalNoSqlDb.storageRootRelocationBridge = bridge;
+        if (!await bridge.spawn(remaining())) throw new NoSqlDbStoppedOperationError('IO');
+        const commandOptions = remaining();
+        dispatched = true;
+        const value = abort ? await bridge[rustDbBridgeStorageRootAlignmentAbort](input, commandOptions)
+          : await bridge[rustDbBridgeStorageRootAlignment](input, commandOptions);
+        result = normalize(value, input);
+      } catch (error) {
+        if (error instanceof NoSqlDbStoppedOperationError) failure = error;
+        else if (isStoppedOperationUnknownMethod(error, method)) failure = new NoSqlDbStoppedOperationError('UNSUPPORTED');
+        else if (error instanceof Error && 'code' in error && error.code === 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE'
+          && 'method' in error && error.method === method && 'responseErrorCode' in error
+          && isLocalNoSqlDbStorageRootRelocationErrorCode(error.responseErrorCode)) {
+          failure = new NoSqlDbStoppedOperationError(error.responseErrorCode);
+        } else failure = new NoSqlDbStoppedOperationError(dispatched ? 'RECOVERY_REQUIRED' : 'IO');
+      }
+      if (bridge) {
+        try {
+          await bridge.terminate({ gracePeriodMs: 0 });
+          if (!bridge.ownershipReleased) throw new Error('termination unconfirmed');
+          if (LocalNoSqlDb.storageRootRelocationBridge === bridge) LocalNoSqlDb.storageRootRelocationBridge = undefined;
+        } catch { failure = new NoSqlDbStoppedOperationError('RECOVERY_REQUIRED'); }
+      }
+      if (failure) throw failure;
+      if (result === undefined) throw new NoSqlDbStoppedOperationError('RECOVERY_REQUIRED');
+      return result;
+    });
+  }
+
+  /** Read-only complete owner audit of a stopped source or physically admissible copy. */
+  public static async inspectStoppedStorageRoot(
+    inputArg: ILocalNoSqlDbStoppedStorageRootInspectionInput,
+    optionsArg?: INoSqlDbStoppedOperationOptions,
+  ): Promise<TLocalNoSqlDbStoppedStorageRootInspection> {
+    return LocalNoSqlDb.runOfflineInspection(inputArg, optionsArg,
+      normalizeStoppedStorageRootInspectionInput,
+      (bridge, input, options) => bridge.inspectStoppedStorageRoot(input, options));
+  }
+
+  private static async runOfflineInspection<
+    TInput extends { folderPath: string },
+    TResult,
+  >(
+    inputArg: TInput,
+    optionsArg: INoSqlDbStoppedOperationOptions | undefined,
+    normalizeInputArg: (inputArg: TInput) => TInput,
+    inspectArg: (
+      bridgeArg: RustDbBridge,
+      inputArg: TInput,
+      optionsArg?: INoSqlDbStoppedOperationOptions,
+    ) => Promise<TResult>,
+  ): Promise<TResult> {
+    const validatedInput = normalizeInputArg(inputArg);
+    validateNoSqlDbStoppedOperationOptions(optionsArg);
+    optionsArg?.signal?.throwIfAborted();
+
+    const input = normalizeInputArg({
+      ...validatedInput,
+      folderPath: path.resolve(validatedInput.folderPath),
+    });
+    const deadline = optionsArg?.timeoutMs === undefined
+      ? undefined
+      : Date.now() + optionsArg.timeoutMs;
+    const bridge = LocalNoSqlDb.createOfflineInspectionBridge(optionsArg?.binaryPath);
+    let operationFailed = false;
+    let operationError: unknown;
+    let result: TResult | undefined;
+    try {
+      let spawnOptions = optionsArg;
+      if (deadline !== undefined) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          throw new Error('NoSQLDB offline inspection timed out before sidecar spawn');
+        }
+        spawnOptions = {
+          signal: optionsArg?.signal,
+          timeoutMs: remainingMs,
+        };
+      }
+      if (!await bridge.spawn(spawnOptions)) {
+        // The bridge states what it knows: that the engine at its binaryPath did not report ready, or, without one, both meanings.
+        throw new Error(bridge.spawnFailureMessage ?? 'the nosqldb engine did not start: spawn() returned false');
+      }
+      let commandOptions = optionsArg;
+      if (deadline !== undefined) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          throw new Error('NoSQLDB offline inspection timed out while starting the sidecar');
+        }
+        commandOptions = {
+          signal: optionsArg?.signal,
+          timeoutMs: remainingMs,
+        };
+      }
+      result = await inspectArg(bridge, input, commandOptions);
+    } catch (error) {
+      operationFailed = true;
+      operationError = error;
+    }
+
+    try {
+      await bridge.terminate({ gracePeriodMs: 0 });
+    } catch (terminationError) {
+      if (operationFailed) {
+        throw new AggregateError(
+          [operationError, terminationError],
+          'NoSQLDB offline inspection failed and sidecar termination was incomplete',
+          { cause: operationError },
+        );
+      }
+      throw terminationError;
+    }
+    if (operationFailed) {
+      throw operationError;
+    }
+    return result as TResult;
+  }
+
+  /**
+   * Inspect physical database and collection names while the owning engine is stopped.
+   * This starts only the Rust management sidecar and never initializes storage.
+   */
+  public static async inspectOfflinePhysicalNamespaces(
+    inputArg: ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+    optionsArg?: INoSqlDbStoppedOperationOptions,
+  ): Promise<ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult> {
+    return LocalNoSqlDb.runOfflineInspection(
+      inputArg,
+      optionsArg,
+      normalizeLocalNoSqlDbOfflinePhysicalNamespaceInspectionInput,
+      (bridgeArg, input, commandOptions) =>
+        bridgeArg.inspectOfflinePhysicalNamespaces(input, commandOptions),
+    );
+  }
+
+  /**
+   * Inspect one exact string value while the owning LocalNoSqlDb engine is stopped.
+   * This starts only the Rust management sidecar and never initializes storage.
+   */
+  public static async inspectOfflineStringValue(
+    inputArg: ILocalNoSqlDbOfflineStringValueInspection,
+    optionsArg?: INoSqlDbStoppedOperationOptions,
+  ): Promise<TLocalNoSqlDbOfflineStringValueInspectionResult> {
+    return LocalNoSqlDb.runOfflineInspection(
+      inputArg,
+      optionsArg,
+      normalizeLocalNoSqlDbOfflineInspectionInput,
+      (bridgeArg, input, commandOptions) =>
+        bridgeArg.inspectOfflineStringValue(input, commandOptions),
+    );
+  }
+
+  /**
+   * Generate a unique socket path in /tmp
+   */
+  private generateSocketPath(): string {
+    const randomId = crypto.randomBytes(8).toString('hex');
+    return path.join(os.tmpdir(), `nosqldb-${randomId}.sock`);
+  }
+
+  /**
+   * Check if a Unix socket is alive by attempting to connect.
+   */
+  private static isSocketAlive(socketPath: string): Promise<boolean> {
+    return new Promise((resolve) => {
+      const client = net.createConnection({ path: socketPath }, () => {
+        client.destroy();
+        resolve(true);
+      });
+      client.on('error', () => {
+        resolve(false);
+      });
+      client.setTimeout(500, () => {
+        client.destroy();
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Remove stale nosqldb-*.sock files from /tmp.
+   * A socket is considered stale if connecting to it fails.
+   */
+  private static async cleanStaleSockets(): Promise<void> {
+    const tmpDir = os.tmpdir();
+    let entries: string[];
+    try {
+      entries = await fs.readdir(tmpDir);
+    } catch {
+      return;
+    }
+    const socketFiles = entries.filter(
+      (f) => f.startsWith('nosqldb-') && f.endsWith('.sock')
+    );
+    for (const name of socketFiles) {
+      const fullPath = path.join(tmpDir, name);
+      try {
+        const stat = await fs.stat(fullPath);
+        if (!stat.isSocket()) continue;
+        const alive = await LocalNoSqlDb.isSocketAlive(fullPath);
+        if (!alive) {
+          await fs.unlink(fullPath);
+        }
+      } catch {
+        // File may have been removed already; ignore
+      }
+    }
+  }
+
+  /**
+   * Start the local NoSQLDB server and return connection info. A rejection
+   * carries `engineStderrTail`: the server's start sets it, and a rejection
+   * from before the server's start, which spawned no engine, carries an empty
+   * array.
+   */
+  async start(): Promise<ILocalNoSqlDbConnectionInfo> {
+    try {
+      return await this.startServer();
+    } catch (error) {
+      if (!(error !== null && typeof error === 'object' && Object.prototype.hasOwnProperty.call(error, 'engineStderrTail'))) {
+        attachNoSqlDbEngineStderrTail(error, []);
+      }
+      throw error;
+    }
+  }
+
+  private async startServer(): Promise<ILocalNoSqlDbConnectionInfo> {
+    if (this.server) {
+      throw new Error('LocalNoSqlDb is already running');
+    }
+
+    // Use provided socket path or generate one
+    this.generatedSocketPath = this.options.socketPath ?? this.generateSocketPath();
+
+    this.server = new NoSqlDbServer({
+      binaryPath: this.options.binaryPath,
+      storageRehearsalId: this.options.storageRehearsalId,
+      auth: this.options.auth,
+      fileStorageStartup: this.options.fileStorageStartup,
+      socketPath: this.generatedSocketPath,
+      storage: 'file',
+      storagePath: this.options.folderPath,
+      engineLog: this.options.engineLog,
+      onEngineExit: this.options.onEngineExit,
+    });
+    await this.server.start();
+
+    return {
+      socketPath: this.generatedSocketPath,
+      connectionUri: this.server.getConnectionUri(),
+    };
+  }
+
+  /**
+   * Get connection info (throws if not started)
+   */
+  getConnectionInfo(): ILocalNoSqlDbConnectionInfo {
+    if (!this.server || !this.generatedSocketPath) {
+      throw new Error('LocalNoSqlDb is not running. Call start() first.');
+    }
+    return {
+      socketPath: this.generatedSocketPath,
+      connectionUri: this.server.getConnectionUri(),
+    };
+  }
+
+  /**
+   * Get the underlying NoSqlDbServer instance (throws if not started)
+   */
+  getServer(): NoSqlDbServer {
+    if (!this.server) {
+      throw new Error('LocalNoSqlDb is not running. Call start() first.');
+    }
+    return this.server;
+  }
+
+  /**
+   * Get the connection URI
+   */
+  getConnectionUri(): string {
+    if (!this.server) {
+      throw new Error('LocalNoSqlDb is not running. Call start() first.');
+    }
+    return this.server.getConnectionUri();
+  }
+
+  /**
+   * Check if the server is running
+   */
+  get running(): boolean {
+    return this.server !== null && this.server.running;
+  }
+
+  /**
+   * Stop the local NoSQLDB server. Resolves with the result of its
+   * `NoSqlDbServer.stop()`, which says how the engine ended; without a server,
+   * with a result saying that no stop request was sent.
+   */
+  async stop(): Promise<INoSqlDbServerStopResult> {
+    if (!this.server) return noStopRequestResult;
+    const result = await this.server.stop();
+    this.server = null;
+    this.generatedSocketPath = null;
+    return result;
+  }
+}

package/ts/ts_local/index.ts

@@ -0,0 +1,19 @@
+export { LocalNoSqlDb } from './classes.localnosqldb.js';
+export type { ILocalNoSqlDbOptions, ILocalNoSqlDbConnectionInfo } from './classes.localnosqldb.js';
+export type {
+  ILocalNoSqlDbOfflineInspectionLimits,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionLimits,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult,
+  ILocalNoSqlDbOfflineStringValueInspection,
+  TLocalNoSqlDbOfflineStringValueInspectionResult,
+} from '../ts_nosqldb/service-types.js';
+export type {
+  ILocalNoSqlDbStoppedStorageRootRelocationInput,
+  ILocalNoSqlDbStoppedStorageRootRelocationReceipt,
+  TLocalNoSqlDbStorageRootRelocationErrorCode,
+} from '../ts_nosqldb/storage-root-relocation.js';
+export {
+  LocalNoSqlDbStorageRootRelocationError,
+  localNoSqlDbStorageRootRelocationErrorCodes,
+} from '../ts_nosqldb/storage-root-relocation.js';

package/ts/ts_local/plugins.ts

@@ -0,0 +1 @@
+// Local module plugins - currently no external dependencies needed