@lossless.org/client 0.1.0

package/ts/nosqldb/classes.collectiontopology.ts

@@ -0,0 +1,645 @@
+import type * as plugins from './plugins.js';
+import type { INormalizedCollectionModelSchema } from './classes.collection.js';
+import type { SmartdataDb } from './classes.db.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+
+export type TSmartdataCollectionTopologyStatus =
+  | 'absent'
+  | 'compatible'
+  | 'exact'
+  | 'divergent';
+
+export type TSmartdataCollectionTopologyReasonCode =
+  | 'namespace_not_collection'
+  | 'collection_options_present'
+  | 'id_index_missing'
+  | 'id_index_changed'
+  | 'expected_index_missing'
+  | 'unexpected_index'
+  | 'index_changed'
+  | 'unsupported_actual_index';
+
+export type TSmartdataCollectionTopologyIndexDirection = 1 | -1 | 'text';
+
+export interface ISmartdataCollectionTopologyIndexKey {
+  readonly path: string;
+  readonly direction: TSmartdataCollectionTopologyIndexDirection;
+  readonly weight: number | null;
+}
+
+export interface ISmartdataCollectionTopologyIndex {
+  readonly name: string;
+  readonly keys: readonly ISmartdataCollectionTopologyIndexKey[];
+  readonly unique: boolean;
+  readonly sparse: boolean;
+  readonly expireAfterSeconds: number | null;
+}
+
+export interface ISmartdataExpectedCollectionTopology {
+  readonly collectionName: string;
+  readonly indexes: readonly ISmartdataCollectionTopologyIndex[];
+}
+
+export interface ISmartdataCollectionTopologyInspection {
+  readonly collectionName: string;
+  readonly status: TSmartdataCollectionTopologyStatus;
+  readonly reasonCodes: readonly TSmartdataCollectionTopologyReasonCode[];
+  readonly expectedIndexes: readonly ISmartdataCollectionTopologyIndex[];
+  readonly actualIndexes: readonly ISmartdataCollectionTopologyIndex[];
+}
+
+type TCollectionModelSchemaResolver = () => INormalizedCollectionModelSchema;
+
+export const collectionModelSchemaResolverSymbol = Symbol(
+  '@push.rocks/smartdata.collectionModelSchemaResolver',
+);
+
+export const collectionTopologyDbInspectionSymbol = Symbol(
+  '@push.rocks/smartdata.collectionTopologyDbInspection',
+);
+
+interface ICollectionTopologyModelConstructor {
+  readonly name: string;
+  readonly [collectionModelSchemaResolverSymbol]?: TCollectionModelSchemaResolver;
+}
+
+interface ICollectionTopologyRawSnapshot {
+  namespace: Record<string, unknown> | null;
+  indexes: unknown[];
+}
+
+interface IActualIndexNormalization {
+  index?: ISmartdataCollectionTopologyIndex;
+  name?: string;
+  supported: boolean;
+}
+
+const maximumCollectionIndexCount = 64;
+const maximumIndexKeyCount = 32;
+const fixedIdIndex = freezeIndex({
+  name: '_id_',
+  keys: [{ path: '_id', direction: 1, weight: null }],
+  unique: true,
+  sparse: false,
+  expireAfterSeconds: null,
+});
+const reasonCodeOrder: readonly TSmartdataCollectionTopologyReasonCode[] = [
+  'namespace_not_collection',
+  'collection_options_present',
+  'id_index_missing',
+  'id_index_changed',
+  'expected_index_missing',
+  'unexpected_index',
+  'index_changed',
+  'unsupported_actual_index',
+];
+const ordinaryActualIndexKeys = new Set([
+  'v',
+  'key',
+  'name',
+  'ns',
+  'background',
+  'unique',
+  'sparse',
+  'expireAfterSeconds',
+]);
+const textActualIndexKeys = new Set([
+  ...ordinaryActualIndexKeys,
+  'weights',
+  'default_language',
+  'language_override',
+  'textIndexVersion',
+]);
+
+export const compareSmartdataTopologyStrings = (
+  leftArg: string,
+  rightArg: string,
+): number => {
+  const leftCodePoints = Array.from(leftArg, (characterArg) =>
+    characterArg.codePointAt(0)!,
+  );
+  const rightCodePoints = Array.from(rightArg, (characterArg) =>
+    characterArg.codePointAt(0)!,
+  );
+  const sharedLength = Math.min(leftCodePoints.length, rightCodePoints.length);
+  for (let index = 0; index < sharedLength; index++) {
+    if (leftCodePoints[index] !== rightCodePoints[index]) {
+      return leftCodePoints[index] < rightCodePoints[index] ? -1 : 1;
+    }
+  }
+  if (leftCodePoints.length === rightCodePoints.length) {
+    return 0;
+  }
+  return leftCodePoints.length < rightCodePoints.length ? -1 : 1;
+};
+
+function freezeIndex(
+  indexArg: {
+    name: string;
+    keys: Array<{
+      path: string;
+      direction: TSmartdataCollectionTopologyIndexDirection;
+      weight: number | null;
+    }>;
+    unique: boolean;
+    sparse: boolean;
+    expireAfterSeconds: number | null;
+  },
+): ISmartdataCollectionTopologyIndex {
+  return Object.freeze({
+    name: indexArg.name,
+    keys: Object.freeze(
+      indexArg.keys.map((keyArg) => Object.freeze({ ...keyArg })),
+    ),
+    unique: indexArg.unique,
+    sparse: indexArg.sparse,
+    expireAfterSeconds: indexArg.expireAfterSeconds,
+  });
+}
+
+const sortIndexes = (
+  indexesArg: readonly ISmartdataCollectionTopologyIndex[],
+): readonly ISmartdataCollectionTopologyIndex[] =>
+  Object.freeze(
+    [...indexesArg].sort((leftArg, rightArg) =>
+      compareSmartdataTopologyStrings(leftArg.name, rightArg.name),
+    ),
+  );
+
+const indexValuesEqual = (
+  leftArg: ISmartdataCollectionTopologyIndex,
+  rightArg: ISmartdataCollectionTopologyIndex,
+): boolean => JSON.stringify(leftArg) === JSON.stringify(rightArg);
+
+const getSchemaResolver = (
+  constructorArg: ICollectionTopologyModelConstructor,
+): TCollectionModelSchemaResolver => {
+  const resolver = constructorArg?.[collectionModelSchemaResolverSymbol];
+  if (
+    typeof constructorArg !== 'function' ||
+    !Object.prototype.hasOwnProperty.call(
+      constructorArg,
+      collectionModelSchemaResolverSymbol,
+    ) ||
+    typeof resolver !== 'function'
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Model "${constructorArg?.name || 'unknown'}" has no collection schema binding.`,
+    );
+  }
+  return resolver;
+};
+
+const normalizeExpectedIndex = (
+  indexArg: INormalizedCollectionModelSchema['indexes'][number],
+): ISmartdataCollectionTopologyIndex => {
+  if (indexArg.name === '_id_') {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      'Model index name "_id_" is reserved for MongoDB.',
+    );
+  }
+  if (indexArg.key.length > maximumIndexKeyCount) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Index "${indexArg.name}" exceeds MongoDB's compound index field limit.`,
+    );
+  }
+  const expectedPhysicalKeyCount =
+    indexArg.key.filter(([, directionArg]) => directionArg !== 'text').length +
+    (indexArg.key.some(([, directionArg]) => directionArg === 'text') ? 2 : 0);
+  if (expectedPhysicalKeyCount > maximumIndexKeyCount) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Index "${indexArg.name}" exceeds MongoDB's physical compound index field limit.`,
+    );
+  }
+  const supportedOptions = new Set([
+    'background',
+    'unique',
+    'sparse',
+    'expireAfterSeconds',
+  ]);
+  for (const optionName of Object.keys(indexArg.options)) {
+    if (!supportedOptions.has(optionName)) {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index "${indexArg.name}" defines an unsupported topology option.`,
+      );
+    }
+  }
+
+  const textKeys = indexArg.key
+    .filter(([, directionArg]) => directionArg === 'text')
+    .map(([pathArg]) => pathArg)
+    .sort(compareSmartdataTopologyStrings);
+  const keys: Array<{
+    path: string;
+    direction: TSmartdataCollectionTopologyIndexDirection;
+    weight: number | null;
+  }> = [];
+  let emittedTextKeys = false;
+  for (const [path, direction] of indexArg.key) {
+    if (path === '_fts' || path === '_ftsx') {
+      throw new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Index "${indexArg.name}" uses a reserved MongoDB text-index field.`,
+      );
+    }
+    if (direction === 'text') {
+      if (!emittedTextKeys) {
+        keys.push(
+          ...textKeys.map((pathArg) => ({
+            path: pathArg,
+            direction: 'text' as const,
+            weight: 1,
+          })),
+        );
+        emittedTextKeys = true;
+      }
+      continue;
+    }
+    keys.push({ path, direction, weight: null });
+  }
+  return freezeIndex({
+    name: indexArg.name,
+    keys,
+    unique: indexArg.options.unique === true,
+    sparse: indexArg.options.sparse === true,
+    expireAfterSeconds: indexArg.options.expireAfterSeconds ?? null,
+  });
+};
+
+export const getExpectedCollectionTopologyForModel = (
+  constructorArg: ICollectionTopologyModelConstructor,
+): ISmartdataExpectedCollectionTopology => {
+  const schema = getSchemaResolver(constructorArg)();
+  return getExpectedCollectionTopologyForSchema(schema);
+};
+
+/** @internal Normalizes the same contract for a bound collection. */
+export const getExpectedCollectionTopologyForSchema = (
+  schema: INormalizedCollectionModelSchema,
+): ISmartdataExpectedCollectionTopology => {
+  if (schema.indexes.length + 1 > maximumCollectionIndexCount) {
+    throw new SmartdataPersistenceError(
+      'invalid_configuration',
+      `Collection "${schema.collectionName}" exceeds MongoDB's collection index limit.`,
+    );
+  }
+  const indexes = sortIndexes([
+    fixedIdIndex,
+    ...schema.indexes.map((indexArg) => normalizeExpectedIndex(indexArg)),
+  ]);
+  return Object.freeze({
+    collectionName: schema.collectionName,
+    indexes,
+  });
+};
+
+const normalizeActualIndex = (
+  rawIndexArg: unknown,
+): IActualIndexNormalization => {
+  if (
+    typeof rawIndexArg !== 'object' ||
+    rawIndexArg === null ||
+    Array.isArray(rawIndexArg)
+  ) {
+    return { supported: false };
+  }
+  const rawIndex = rawIndexArg as Record<string, unknown>;
+  const name = typeof rawIndex.name === 'string' ? rawIndex.name : undefined;
+  if (!name || typeof rawIndex.key !== 'object' || rawIndex.key === null) {
+    return { name, supported: false };
+  }
+  const allRawKeyEntries = Object.entries(
+    rawIndex.key as Record<string, unknown>,
+  );
+  const maximumPhysicalKeyCount = maximumIndexKeyCount;
+  const rawKeyEntries = allRawKeyEntries.slice(0, maximumPhysicalKeyCount);
+  if (rawKeyEntries.length === 0) {
+    return { name, supported: false };
+  }
+
+  const textMarkerIndex = rawKeyEntries.findIndex(
+    ([pathArg, directionArg]) =>
+      pathArg === '_fts' && directionArg === 'text',
+  );
+  const hasTextMarker = textMarkerIndex !== -1;
+  let supported = Reflect.ownKeys(rawIndex).every(
+    (keyArg) =>
+      typeof keyArg === 'string' &&
+      (hasTextMarker ? textActualIndexKeys : ordinaryActualIndexKeys).has(
+        keyArg,
+      ),
+  );
+  if (
+    allRawKeyEntries.length > maximumPhysicalKeyCount ||
+    rawKeyEntries.some(
+      ([pathArg]) => pathArg === '$**' || pathArg.endsWith('.$**'),
+    )
+  ) {
+    supported = false;
+  }
+  if (
+    rawIndex.background !== undefined &&
+    typeof rawIndex.background !== 'boolean'
+  ) {
+    supported = false;
+  }
+  if (rawIndex.unique !== undefined && typeof rawIndex.unique !== 'boolean') {
+    supported = false;
+  }
+  if (rawIndex.sparse !== undefined && typeof rawIndex.sparse !== 'boolean') {
+    supported = false;
+  }
+  const expireAfterSeconds = rawIndex.expireAfterSeconds;
+  if (
+    expireAfterSeconds !== undefined &&
+    (typeof expireAfterSeconds !== 'number' ||
+      !Number.isFinite(expireAfterSeconds) ||
+      expireAfterSeconds < 0)
+  ) {
+    supported = false;
+  }
+
+  let textWeights = new Map<string, number>();
+  if (hasTextMarker) {
+    if (
+      rawKeyEntries.filter(([pathArg]) => pathArg === '_fts').length !== 1 ||
+      rawKeyEntries[textMarkerIndex + 1]?.[0] !== '_ftsx' ||
+      rawKeyEntries[textMarkerIndex + 1]?.[1] !== 1 ||
+      typeof rawIndex.weights !== 'object' ||
+      rawIndex.weights === null ||
+      Array.isArray(rawIndex.weights)
+    ) {
+      supported = false;
+    } else {
+      const rawWeightEntries = Object.entries(
+        rawIndex.weights as Record<string, unknown>,
+      );
+      if (rawWeightEntries.length > maximumIndexKeyCount) {
+        supported = false;
+      }
+      textWeights = new Map(
+        rawWeightEntries
+          .sort(([leftArg], [rightArg]) =>
+            compareSmartdataTopologyStrings(leftArg, rightArg),
+          )
+          .slice(0, maximumIndexKeyCount)
+          .flatMap(([pathArg, weightArg]) => {
+            if (
+              typeof weightArg !== 'number' ||
+              !Number.isFinite(weightArg) ||
+              weightArg <= 0
+            ) {
+              supported = false;
+              return [];
+            }
+            return [[pathArg, weightArg] as const];
+          }),
+      );
+      if (textWeights.size === 0) {
+        supported = false;
+      }
+    }
+    if (
+      (rawIndex.default_language !== undefined &&
+        rawIndex.default_language !== 'english') ||
+      (rawIndex.language_override !== undefined &&
+        rawIndex.language_override !== 'language') ||
+      (rawIndex.textIndexVersion !== undefined &&
+        rawIndex.textIndexVersion !== 3)
+    ) {
+      supported = false;
+    }
+  }
+
+  const keys: Array<{
+    path: string;
+    direction: TSmartdataCollectionTopologyIndexDirection;
+    weight: number | null;
+  }> = [];
+  for (let index = 0; index < rawKeyEntries.length; index++) {
+    const [path, direction] = rawKeyEntries[index];
+    if (hasTextMarker && index === textMarkerIndex) {
+      keys.push(
+        ...[...textWeights].map(([pathArg, weightArg]) => ({
+          path: pathArg,
+          direction: 'text' as const,
+          weight: weightArg,
+        })),
+      );
+      index++;
+      continue;
+    }
+    if (direction !== 1 && direction !== -1) {
+      supported = false;
+      continue;
+    }
+    keys.push({ path, direction, weight: null });
+  }
+  if (keys.length > maximumIndexKeyCount) {
+    supported = false;
+    keys.length = maximumIndexKeyCount;
+  }
+  if (keys.length === 0) {
+    return { name, supported: false };
+  }
+
+  let normalized = freezeIndex({
+    name,
+    keys,
+    unique: rawIndex.unique === true,
+    sparse: rawIndex.sparse === true,
+    expireAfterSeconds:
+      typeof expireAfterSeconds === 'number' &&
+      Number.isFinite(expireAfterSeconds) &&
+      expireAfterSeconds >= 0
+        ? expireAfterSeconds
+        : null,
+  });
+  if (
+    name === '_id_' &&
+    normalized.keys.length === 1 &&
+    normalized.keys[0].path === '_id' &&
+    normalized.keys[0].direction === 1 &&
+    normalized.keys[0].weight === null &&
+    (rawIndex.unique === undefined || rawIndex.unique === true) &&
+    normalized.sparse === false &&
+    normalized.expireAfterSeconds === null
+  ) {
+    normalized = fixedIdIndex;
+  }
+  return { index: normalized, name, supported };
+};
+
+const buildReasonCodes = (
+  reasonsArg: ReadonlySet<TSmartdataCollectionTopologyReasonCode>,
+): readonly TSmartdataCollectionTopologyReasonCode[] =>
+  Object.freeze(
+    reasonCodeOrder.filter((reasonCodeArg) => reasonsArg.has(reasonCodeArg)),
+  );
+
+const createInspection = (
+  expectedArg: ISmartdataExpectedCollectionTopology,
+  statusArg: TSmartdataCollectionTopologyStatus,
+  reasonsArg: ReadonlySet<TSmartdataCollectionTopologyReasonCode>,
+  actualIndexesArg: readonly ISmartdataCollectionTopologyIndex[],
+): ISmartdataCollectionTopologyInspection =>
+  Object.freeze({
+    collectionName: expectedArg.collectionName,
+    status: statusArg,
+    reasonCodes: buildReasonCodes(reasonsArg),
+    expectedIndexes: expectedArg.indexes,
+    actualIndexes: sortIndexes(actualIndexesArg),
+  });
+
+export const inspectCollectionTopologyForModel = async (
+  constructorArg: ICollectionTopologyModelConstructor,
+  dbArg: SmartdataDb,
+): Promise<ISmartdataCollectionTopologyInspection> => {
+  const expected = getExpectedCollectionTopologyForModel(constructorArg);
+  const inspectionHost = dbArg as unknown as {
+    [collectionTopologyDbInspectionSymbol]?: <TResult>(
+      operationArg: (mongoDbArg: plugins.mongodb.Db) => Promise<TResult>,
+    ) => Promise<TResult>;
+  };
+  if (
+    typeof inspectionHost?.[collectionTopologyDbInspectionSymbol] !== 'function'
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'Collection topology inspection requires a SmartdataDb.',
+    );
+  }
+
+  const rawSnapshot = await inspectionHost[collectionTopologyDbInspectionSymbol](
+    async (mongoDbArg): Promise<ICollectionTopologyRawSnapshot> => {
+      const namespace = (await mongoDbArg
+        .listCollections(
+          { name: expected.collectionName },
+          { nameOnly: false },
+        )
+        .next()) as Record<string, unknown> | null;
+      if (!namespace || namespace.type !== 'collection') {
+        return { namespace, indexes: [] };
+      }
+      const indexes = await mongoDbArg
+        .collection(expected.collectionName)
+        .listIndexes()
+        .toArray();
+      return { namespace, indexes };
+    },
+  );
+
+  return inspectCollectionTopologySnapshot(expected, rawSnapshot);
+};
+
+/** @internal Pure normalization shared by model and namespace inspection. */
+export const inspectCollectionTopologySnapshot = (
+  expected: ISmartdataExpectedCollectionTopology,
+  rawSnapshot: ICollectionTopologyRawSnapshot,
+): ISmartdataCollectionTopologyInspection => {
+
+  if (!rawSnapshot.namespace) {
+    return createInspection(expected, 'absent', new Set(), []);
+  }
+
+  try {
+    const reasons = new Set<TSmartdataCollectionTopologyReasonCode>();
+    const namespace = rawSnapshot.namespace;
+    if (
+      namespace.name !== expected.collectionName ||
+      namespace.type !== 'collection'
+    ) {
+      reasons.add('namespace_not_collection');
+    }
+    if (
+      typeof namespace.options !== 'object' ||
+      namespace.options === null ||
+      Array.isArray(namespace.options) ||
+      Reflect.ownKeys(namespace.options).length !== 0
+    ) {
+      reasons.add('collection_options_present');
+    }
+
+    const rawIndexes = rawSnapshot.indexes.slice(
+      0,
+      maximumCollectionIndexCount,
+    );
+    if (rawSnapshot.indexes.length > maximumCollectionIndexCount) {
+      reasons.add('unsupported_actual_index');
+    }
+    const normalizedIndexes: ISmartdataCollectionTopologyIndex[] = [];
+    const unsupportedNames = new Set<string>();
+    for (const rawIndex of rawIndexes) {
+      const normalized = normalizeActualIndex(rawIndex);
+      if (!normalized.supported) {
+        reasons.add('unsupported_actual_index');
+        if (normalized.name) {
+          unsupportedNames.add(normalized.name);
+        }
+      }
+      if (normalized.index) {
+        normalizedIndexes.push(normalized.index);
+      }
+    }
+
+    const actualByName = new Map<string, ISmartdataCollectionTopologyIndex>();
+    for (const actualIndex of normalizedIndexes) {
+      if (actualByName.has(actualIndex.name)) {
+        reasons.add('unsupported_actual_index');
+        continue;
+      }
+      actualByName.set(actualIndex.name, actualIndex);
+    }
+    const expectedByName = new Map(
+      expected.indexes.map((indexArg) => [indexArg.name, indexArg]),
+    );
+    const actualIdIndex = actualByName.get('_id_');
+    if (!actualIdIndex && !unsupportedNames.has('_id_')) {
+      reasons.add('id_index_missing');
+    } else if (
+      actualIdIndex &&
+      !indexValuesEqual(actualIdIndex, fixedIdIndex)
+    ) {
+      reasons.add('id_index_changed');
+    }
+
+    for (const expectedIndex of expected.indexes) {
+      if (expectedIndex.name === '_id_') {
+        continue;
+      }
+      const actualIndex = actualByName.get(expectedIndex.name);
+      if (!actualIndex) {
+        if (!unsupportedNames.has(expectedIndex.name)) {
+          reasons.add('expected_index_missing');
+        }
+      } else if (!indexValuesEqual(expectedIndex, actualIndex)) {
+        reasons.add('index_changed');
+      }
+    }
+    for (const actualIndex of actualByName.values()) {
+      if (!expectedByName.has(actualIndex.name)) {
+        reasons.add('unexpected_index');
+      }
+    }
+
+    const status: TSmartdataCollectionTopologyStatus =
+      reasons.size === 0
+        ? 'exact'
+        : [...reasons].every(
+              (reasonArg) => reasonArg === 'expected_index_missing',
+            )
+          ? 'compatible'
+          : 'divergent';
+    return createInspection(expected, status, reasons, normalizedIndexes);
+  } catch {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'Collection topology inspection returned unreadable metadata.',
+    );
+  }
+};

package/ts/nosqldb/classes.connection.ts

@@ -0,0 +1,31 @@
+import { SmartdataDb } from './classes.db.js';
+import type { ICapabilities, IOperationOptions, IReadiness } from '../core/interfaces.js';
+
+export interface INoSqlConnectionOptions {
+  backend: 'nosqldb' | 'mongodb';
+  url: string;
+  database: string;
+  username?: string;
+  password?: string;
+  connectionLimit?: number;
+}
+
+export class NoSqlConnection extends SmartdataDb {
+  public readonly backend: 'nosqldb' | 'mongodb';
+  public readonly capabilities: ICapabilities;
+  constructor(public readonly options: INoSqlConnectionOptions) {
+    super({ mongoDbUrl: options.url, mongoDbName: options.database,
+      mongoDbUser: options.username, mongoDbPass: options.password,
+      ...(options.connectionLimit === undefined ? {} : { maxPoolSize: options.connectionLimit }) });
+    this.backend = options.backend;
+    this.capabilities = Object.freeze({ backend: options.backend,
+      transactions: options.backend === 'nosqldb' ? 'available' : 'unknown',
+      changeStreams: options.backend === 'nosqldb' ? 'unsupported' : 'unknown',
+      objectMetrics: 'unsupported', diskResidentScans: 'available' });
+  }
+  public async connect(options: IOperationOptions = {}): Promise<void> { await this.init(options); }
+  public async ready(options: IOperationOptions = {}): Promise<IReadiness> {
+    const result = await this.checkReadiness(options);
+    return result.ready ? { ready: true } : { ready: false, reason: result.reason };
+  }
+}

package/ts/nosqldb/classes.convenience.ts

@@ -0,0 +1,5 @@
+import * as plugins from './plugins.js';
+
+export const getNewUniqueId = async (prefixArg?: string) => {
+  return plugins.smartunique.uni(prefixArg);
+};