@push.rocks/smartdb 5.0.1 → 5.0.2

package/ts/ts_local/classes.localsmartdb.ts

@@ -6,12 +6,15 @@ import * as os from 'os';
 import {
   RustDbBridge,
   SmartdbServer,
+  type ILocalSmartDbOfflinePhysicalNamespaceInspection,
+  type ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
   type ILocalSmartDbOfflineStringValueInspection,
   type ISmartDbManagementOperationOptions,
   type TLocalSmartDbOfflineStringValueInspectionResult,
 } from '../ts_smartdb/index.js';
 import { StorageMigrator } from '../ts_migration/index.js';
 import {
+  normalizeLocalSmartDbOfflinePhysicalNamespaceInspectionInput,
   normalizeLocalSmartDbOfflineInspectionInput,
   validateSmartDbManagementOperationOptions,
 } from '../ts_smartdb/offline-inspection.js';
@@ -74,19 +77,24 @@ export class LocalSmartDb {
     return new RustDbBridge();
   }
 
-  /**
-   * Inspect one exact string value while the owning LocalSmartDb engine is stopped.
-   * This starts only the Rust management sidecar and never initializes storage.
-   */
-  public static async inspectOfflineStringValue(
-    inputArg: ILocalSmartDbOfflineStringValueInspection,
-    optionsArg?: ISmartDbManagementOperationOptions,
-  ): Promise<TLocalSmartDbOfflineStringValueInspectionResult> {
-    const validatedInput = normalizeLocalSmartDbOfflineInspectionInput(inputArg);
+  private static async runOfflineInspection<
+    TInput extends { folderPath: string },
+    TResult,
+  >(
+    inputArg: TInput,
+    optionsArg: ISmartDbManagementOperationOptions | undefined,
+    normalizeInputArg: (inputArg: TInput) => TInput,
+    inspectArg: (
+      bridgeArg: RustDbBridge,
+      inputArg: TInput,
+      optionsArg?: ISmartDbManagementOperationOptions,
+    ) => Promise<TResult>,
+  ): Promise<TResult> {
+    const validatedInput = normalizeInputArg(inputArg);
     validateSmartDbManagementOperationOptions(optionsArg);
     optionsArg?.signal?.throwIfAborted();
 
-    const input = normalizeLocalSmartDbOfflineInspectionInput({
+    const input = normalizeInputArg({
       ...validatedInput,
       folderPath: path.resolve(validatedInput.folderPath),
     });
@@ -96,7 +104,7 @@ export class LocalSmartDb {
     const bridge = LocalSmartDb.createOfflineInspectionBridge();
     let operationFailed = false;
     let operationError: unknown;
-    let result: TLocalSmartDbOfflineStringValueInspectionResult | undefined;
+    let result: TResult | undefined;
     try {
       let spawnOptions = optionsArg;
       if (deadline !== undefined) {
@@ -126,7 +134,7 @@ export class LocalSmartDb {
           timeoutMs: remainingMs,
         };
       }
-      result = await bridge.inspectOfflineStringValue(input, commandOptions);
+      result = await inspectArg(bridge, input, commandOptions);
     } catch (error) {
       operationFailed = true;
       operationError = error;
@@ -147,7 +155,41 @@ export class LocalSmartDb {
     if (operationFailed) {
       throw operationError;
     }
-    return result as TLocalSmartDbOfflineStringValueInspectionResult;
+    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: ILocalSmartDbOfflinePhysicalNamespaceInspection,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<ILocalSmartDbOfflinePhysicalNamespaceInspectionResult> {
+    return LocalSmartDb.runOfflineInspection(
+      inputArg,
+      optionsArg,
+      normalizeLocalSmartDbOfflinePhysicalNamespaceInspectionInput,
+      (bridgeArg, input, commandOptions) =>
+        bridgeArg.inspectOfflinePhysicalNamespaces(input, commandOptions),
+    );
+  }
+
+  /**
+   * Inspect one exact string value while the owning LocalSmartDb engine is stopped.
+   * This starts only the Rust management sidecar and never initializes storage.
+   */
+  public static async inspectOfflineStringValue(
+    inputArg: ILocalSmartDbOfflineStringValueInspection,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<TLocalSmartDbOfflineStringValueInspectionResult> {
+    return LocalSmartDb.runOfflineInspection(
+      inputArg,
+      optionsArg,
+      normalizeLocalSmartDbOfflineInspectionInput,
+      (bridgeArg, input, commandOptions) =>
+        bridgeArg.inspectOfflineStringValue(input, commandOptions),
+    );
   }
 
   /**

package/ts/ts_local/index.ts

@@ -2,6 +2,9 @@ export { LocalSmartDb } from './classes.localsmartdb.js';
 export type { ILocalSmartDbOptions, ILocalSmartDbConnectionInfo } from './classes.localsmartdb.js';
 export type {
   ILocalSmartDbOfflineInspectionLimits,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionLimits,
+  ILocalSmartDbOfflinePhysicalNamespaceInspection,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
   ILocalSmartDbOfflineStringValueInspection,
   TLocalSmartDbOfflineStringValueInspectionResult,
 } from '../ts_smartdb/service-types.js';

package/ts/ts_smartdb/index.ts

@@ -44,6 +44,9 @@ export type {
   ISmartDbRevokeDatabaseAllocationReadAccessGrantInput,
   ISmartDbRevokeDatabaseAllocationReadAccessGrantResult,
   ILocalSmartDbOfflineInspectionLimits,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionLimits,
+  ILocalSmartDbOfflinePhysicalNamespaceInspection,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
   ILocalSmartDbOfflineStringValueInspection,
   TLocalSmartDbOfflineStringValueInspectionResult,
   TSmartDbCommitDatabasePublicationResult,

package/ts/ts_smartdb/offline-inspection.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 import type {
+  ILocalSmartDbOfflinePhysicalNamespaceInspection,
   ILocalSmartDbOfflineStringValueInspection,
   ISmartDbManagementOperationOptions,
 } from './service-types.js';
@@ -20,6 +21,24 @@ export const localSmartDbOfflineInspectionBounds = {
   },
 } as const;
 
+export const localSmartDbOfflinePhysicalNamespaceInspectionBounds = {
+  maximumFolderPathBytes: 4096,
+  maximumRequestBytes: 2 * 1024 * 1024,
+  limits: {
+    maximumEntries: { minimum: 1, maximum: 100_000 },
+    maximumDatabases: { minimum: 1, maximum: 4096 },
+    maximumCollections: { minimum: 1, maximum: 10_000 },
+    maximumIndexes: { minimum: 1, maximum: 100_000 },
+    maximumDataFileBytes: { minimum: 64, maximum: 256 * 1024 * 1024 },
+    maximumWalFileBytes: { minimum: 64, maximum: 64 * 1024 * 1024 },
+    maximumIndexFileBytes: { minimum: 2, maximum: 16 * 1024 * 1024 },
+    maximumTotalFileBytes: { minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 },
+    maximumRecordsPerCollection: { minimum: 1, maximum: 1_000_000 },
+    maximumRecordBytes: { minimum: 22, maximum: 17 * 1024 * 1024 },
+    maximumResultBytes: { minimum: 32, maximum: 16 * 1024 * 1024 },
+  },
+} as const;
+
 const inputKeys = new Set([
   'folderPath',
   'databaseName',
@@ -46,9 +65,57 @@ const requestEnvelopeBytes = plugins.buffer.Buffer.byteLength(
   'utf8',
 );
 
+const physicalNamespaceInputKeys = new Set(['folderPath', 'limits']);
+const physicalNamespaceLimitKeys = [
+  'maximumEntries',
+  'maximumDatabases',
+  'maximumCollections',
+  'maximumIndexes',
+  'maximumDataFileBytes',
+  'maximumWalFileBytes',
+  'maximumIndexFileBytes',
+  'maximumTotalFileBytes',
+  'maximumRecordsPerCollection',
+  'maximumRecordBytes',
+  'maximumResultBytes',
+] as const;
+const physicalNamespaceLimitKeySet = new Set<string>(physicalNamespaceLimitKeys);
+
 const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
   typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
 
+const requirePhysicalNamespacePlainObject = (
+  valueArg: unknown,
+  allowedKeysArg: Set<string>,
+  labelArg: string,
+): Record<string, unknown> => {
+  if (!isRecord(valueArg)) {
+    throw new TypeError(
+      `LocalSmartDb offline physical namespace inspection ${labelArg} must be a plain object`,
+    );
+  }
+  for (const key in valueArg) {
+    if (!allowedKeysArg.has(key)) {
+      throw new TypeError(
+        `LocalSmartDb offline physical namespace inspection ${labelArg} contains unknown key '${key}'`,
+      );
+    }
+  }
+  if (Object.getPrototypeOf(valueArg) !== Object.prototype) {
+    throw new TypeError(
+      `LocalSmartDb offline physical namespace inspection ${labelArg} must be a plain object`,
+    );
+  }
+  for (const key of allowedKeysArg) {
+    if (!Object.prototype.propertyIsEnumerable.call(valueArg, key)) {
+      throw new TypeError(
+        `LocalSmartDb offline physical namespace inspection ${labelArg} must contain own enumerable key '${key}'`,
+      );
+    }
+  }
+  return valueArg;
+};
+
 const rejectUnknownEnumerableKeys = (
   valueArg: object,
   allowedKeysArg: Set<string>,
@@ -219,6 +286,81 @@ export const normalizeLocalSmartDbOfflineInspectionInput = (
   return normalized;
 };
 
+export const normalizeLocalSmartDbOfflinePhysicalNamespaceInspectionInput = (
+  inputArg: ILocalSmartDbOfflinePhysicalNamespaceInspection,
+): ILocalSmartDbOfflinePhysicalNamespaceInspection => {
+  const inputRecord = requirePhysicalNamespacePlainObject(
+    inputArg,
+    physicalNamespaceInputKeys,
+    'input',
+  );
+  const limits = requirePhysicalNamespacePlainObject(
+    inputRecord.limits,
+    physicalNamespaceLimitKeySet,
+    'limits',
+  );
+  const normalized: ILocalSmartDbOfflinePhysicalNamespaceInspection = {
+    folderPath: inputRecord.folderPath as string,
+    limits: {
+      maximumEntries: limits.maximumEntries as number,
+      maximumDatabases: limits.maximumDatabases as number,
+      maximumCollections: limits.maximumCollections as number,
+      maximumIndexes: limits.maximumIndexes as number,
+      maximumDataFileBytes: limits.maximumDataFileBytes as number,
+      maximumWalFileBytes: limits.maximumWalFileBytes as number,
+      maximumIndexFileBytes: limits.maximumIndexFileBytes as number,
+      maximumTotalFileBytes: limits.maximumTotalFileBytes as number,
+      maximumRecordsPerCollection: limits.maximumRecordsPerCollection as number,
+      maximumRecordBytes: limits.maximumRecordBytes as number,
+      maximumResultBytes: limits.maximumResultBytes as number,
+    },
+  };
+  const bounds = localSmartDbOfflinePhysicalNamespaceInspectionBounds;
+  if (typeof normalized.folderPath !== 'string') {
+    throw new TypeError(
+      'LocalSmartDb offline physical namespace inspection folderPath must be a string',
+    );
+  }
+  const folderPathBytes = plugins.buffer.Buffer.byteLength(normalized.folderPath, 'utf8');
+  if (folderPathBytes < 1 || folderPathBytes > bounds.maximumFolderPathBytes) {
+    throw new RangeError(
+      `LocalSmartDb offline physical namespace inspection folderPath must be between 1 and ${bounds.maximumFolderPathBytes} UTF-8 bytes`,
+    );
+  }
+  for (const character of normalized.folderPath) {
+    if (/\p{Cc}/u.test(character)) {
+      throw new TypeError(
+        'LocalSmartDb offline physical namespace inspection folderPath must not contain control characters',
+      );
+    }
+  }
+
+  for (const key of physicalNamespaceLimitKeys) {
+    const value = normalized.limits[key];
+    const range = bounds.limits[key];
+    if (!Number.isSafeInteger(value) || value < range.minimum || value > range.maximum) {
+      throw new RangeError(
+        `LocalSmartDb offline physical namespace inspection limits.${key} must be a safe integer between ${range.minimum} and ${range.maximum}`,
+      );
+    }
+  }
+
+  const requestBytes = plugins.buffer.Buffer.byteLength(JSON.stringify({
+    id: 'req_9007199254740991',
+    method: 'inspectOfflinePhysicalNamespaces',
+    params: {
+      folderPath: normalized.folderPath,
+      ...normalized.limits,
+    },
+  }), 'utf8');
+  if (requestBytes > bounds.maximumRequestBytes) {
+    throw new RangeError(
+      `LocalSmartDb offline physical namespace inspection request exceeds the ${bounds.maximumRequestBytes}-byte serialized limit`,
+    );
+  }
+  return normalized;
+};
+
 export const validateSmartDbManagementOperationOptions = (
   optionsArg?: ISmartDbManagementOperationOptions,
 ): void => {

package/ts/ts_smartdb/rust-db-bridge.ts

@@ -7,6 +7,7 @@ import {
   normalizeSmartDbResourceFenceError,
 } from './service-types.js';
 import {
+  normalizeLocalSmartDbOfflinePhysicalNamespaceInspectionInput,
   normalizeLocalSmartDbOfflineInspectionInput,
   validateSmartDbManagementOperationOptions,
 } from './offline-inspection.js';
@@ -36,6 +37,8 @@ import type {
   ISmartDbCommitDatabasePublicationInput,
   ISmartDbManagementOperationOptions,
   ISmartDbDatabaseResourceFenceState,
+  ILocalSmartDbOfflinePhysicalNamespaceInspection,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
   ILocalSmartDbOfflineStringValueInspection,
   TLocalSmartDbOfflineStringValueInspectionResult,
   TSmartDbCommitDatabasePublicationResult,
@@ -68,6 +71,9 @@ export type {
   ISmartDbManagementOperationOptions,
   ISmartDbDatabaseResourceFenceState,
   ILocalSmartDbOfflineInspectionLimits,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionLimits,
+  ILocalSmartDbOfflinePhysicalNamespaceInspection,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
   ILocalSmartDbOfflineStringValueInspection,
   TLocalSmartDbOfflineStringValueInspectionResult,
   TSmartDbCommitDatabasePublicationResult,
@@ -169,7 +175,15 @@ export interface ISmartDbMetrics {
 /**
  * Type-safe command definitions for the RustDb IPC protocol.
  */
+type TOfflinePhysicalNamespaceInspectionCommandParams = {
+  folderPath: string;
+} & ILocalSmartDbOfflinePhysicalNamespaceInspection['limits'];
+
 type TSmartDbCommands = {
+  inspectOfflinePhysicalNamespaces: {
+    params: TOfflinePhysicalNamespaceInspectionCommandParams;
+    result: ILocalSmartDbOfflinePhysicalNamespaceInspectionResult;
+  };
   inspectOfflineStringValue: {
     params: ILocalSmartDbOfflineStringValueInspection;
     result: TLocalSmartDbOfflineStringValueInspectionResult;
@@ -543,6 +557,28 @@ export class RustDbBridge extends EventEmitter {
 
   // --- Convenience methods for each management command ---
 
+  public async inspectOfflinePhysicalNamespaces(
+    inputArg: ILocalSmartDbOfflinePhysicalNamespaceInspection,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<ILocalSmartDbOfflinePhysicalNamespaceInspectionResult> {
+    const input = normalizeLocalSmartDbOfflinePhysicalNamespaceInspectionInput(inputArg);
+    validateSmartDbManagementOperationOptions(optionsArg);
+    const params: TOfflinePhysicalNamespaceInspectionCommandParams = {
+      folderPath: input.folderPath,
+      ...input.limits,
+    };
+    try {
+      return await this.bridge.sendCommand(
+        'inspectOfflinePhysicalNamespaces',
+        params,
+        optionsArg,
+      ) as ILocalSmartDbOfflinePhysicalNamespaceInspectionResult;
+    } catch (error) {
+      await this.awaitManagementOperationTermination(error);
+      throw error;
+    }
+  }
+
   public async inspectOfflineStringValue(
     inputArg: ILocalSmartDbOfflineStringValueInspection,
     optionsArg?: ISmartDbManagementOperationOptions,

package/ts/ts_smartdb/service-types.ts

@@ -45,6 +45,33 @@ export type TLocalSmartDbOfflineStringValueInspectionResult =
   | { status: 'not-found' }
   | { status: 'found'; value: string };
 
+export interface ILocalSmartDbOfflinePhysicalNamespaceInspectionLimits {
+  maximumEntries: number;
+  maximumDatabases: number;
+  maximumCollections: number;
+  maximumIndexes: number;
+  maximumDataFileBytes: number;
+  maximumWalFileBytes: number;
+  maximumIndexFileBytes: number;
+  maximumTotalFileBytes: number;
+  maximumRecordsPerCollection: number;
+  maximumRecordBytes: number;
+  maximumResultBytes: number;
+}
+
+export interface ILocalSmartDbOfflinePhysicalNamespaceInspection {
+  folderPath: string;
+  limits: ILocalSmartDbOfflinePhysicalNamespaceInspectionLimits;
+}
+
+export interface ILocalSmartDbOfflinePhysicalNamespaceInspectionResult {
+  schemaVersion: 1;
+  databases: Array<{
+    name: string;
+    collections: string[];
+  }>;
+}
+
 export const smartDbResourceFenceErrorCodes = [
   'EFENCE_REQUIRED',
   'EFENCE_STALE',