@lossless.org/nosqldb 10.11.0 → 11.0.0

package/ts/ts_nosqldb/offline-inspection.ts

@@ -0,0 +1,375 @@
+import * as plugins from './plugins.js';
+import type {
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+  ILocalNoSqlDbOfflineStringValueInspection,
+  INoSqlDbManagementOperationOptions,
+} from './service-types.js';
+
+export const localNoSqlDbOfflineInspectionBounds = {
+  maximumFolderPathBytes: 4095,
+  maximumNamespaceComponentBytes: 255,
+  maximumFieldNameBytes: 255,
+  maximumMatchValueBytes: 1024 * 1024,
+  maximumRequestBytes: 2 * 1024 * 1024,
+  maximumTimeoutMs: 2_147_483_647,
+  limits: {
+    maximumEntries: { minimum: 1, maximum: 100_000 },
+    maximumTotalFileBytes: { minimum: 1, maximum: 1024 ** 4 },
+    maximumRecords: { minimum: 1, maximum: 1_000_000_000 },
+    maximumRecordBytes: { minimum: 5, maximum: 16 * 1024 * 1024 },
+    maximumResultBytes: { minimum: 1, maximum: 16 * 1024 * 1024 },
+  },
+} as const;
+
+export const localNoSqlDbOfflinePhysicalNamespaceInspectionBounds = {
+  maximumFolderPathBytes: 4095,
+  maximumRequestBytes: 2 * 1024 * 1024,
+  limits: {
+    maximumDatabases: { minimum: 1, maximum: 1_000_000 },
+    maximumCollections: { minimum: 1, maximum: 1_000_000 },
+    maximumIndexes: { minimum: 1, maximum: 1_000_000 },
+    maximumEntries: { minimum: 1, maximum: 100_000 },
+    maximumTotalFileBytes: { minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 },
+    maximumRecordsPerCollection: { minimum: 1, maximum: 1_000_000_000 },
+    maximumRecordBytes: { minimum: 5, maximum: 16 * 1024 * 1024 },
+    maximumResultBytes: { minimum: 32, maximum: 16 * 1024 * 1024 },
+  },
+} as const;
+
+const inputKeys = new Set([
+  'folderPath',
+  'databaseName',
+  'collectionName',
+  'match',
+  'valueField',
+  'limits',
+]);
+const matchKeys = new Set(['field', 'value']);
+const limitKeys = [
+  'maximumEntries',
+  'maximumTotalFileBytes',
+  'maximumRecords',
+  'maximumRecordBytes',
+  'maximumResultBytes',
+] as const;
+const limitKeySet = new Set<string>(limitKeys);
+const requestStructuralBytes = plugins.buffer.Buffer.byteLength(
+  '{"folderPath":,"databaseName":,"collectionName":,"match":{"field":,"value":},"valueField":,"limits":{"maximumEntries":,"maximumTotalFileBytes":,"maximumRecords":,"maximumRecordBytes":,"maximumResultBytes":}}',
+  'utf8',
+);
+const requestEnvelopeBytes = plugins.buffer.Buffer.byteLength(
+  '{"id":"req_9007199254740991","method":"inspectOfflineStringValue","params":}',
+  'utf8',
+);
+
+const physicalNamespaceInputKeys = new Set(['folderPath', 'limits']);
+const physicalNamespaceLimitKeys = [
+  'maximumDatabases',
+  'maximumCollections',
+  'maximumIndexes',
+  'maximumEntries',
+  '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(
+      `LocalNoSqlDb offline physical namespace inspection ${labelArg} must be a plain object`,
+    );
+  }
+  for (const key in valueArg) {
+    if (!allowedKeysArg.has(key)) {
+      throw new TypeError(
+        `LocalNoSqlDb offline physical namespace inspection ${labelArg} contains unknown key '${key}'`,
+      );
+    }
+  }
+  if (Object.getPrototypeOf(valueArg) !== Object.prototype) {
+    throw new TypeError(
+      `LocalNoSqlDb 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(
+        `LocalNoSqlDb offline physical namespace inspection ${labelArg} must contain own enumerable key '${key}'`,
+      );
+    }
+  }
+  return valueArg;
+};
+
+const rejectUnknownEnumerableKeys = (
+  valueArg: object,
+  allowedKeysArg: Set<string>,
+  labelArg: string,
+): void => {
+  for (const key in valueArg) {
+    if (!allowedKeysArg.has(key)) {
+      throw new TypeError(`LocalNoSqlDb offline inspection ${labelArg} contains unknown key '${key}'`);
+    }
+  }
+};
+
+const encodedJsonStringBytes = (valueArg: string): number => {
+  let bytes = 2;
+  for (let index = 0; index < valueArg.length; index++) {
+    const code = valueArg.charCodeAt(index);
+    if (
+      code === 0x22
+      || code === 0x5c
+      || code === 0x08
+      || code === 0x09
+      || code === 0x0a
+      || code === 0x0c
+      || code === 0x0d
+    ) {
+      bytes += 2;
+    } else if (code <= 0x1f) {
+      bytes += 6;
+    } else if (code <= 0x7f) {
+      bytes += 1;
+    } else if (code <= 0x7ff) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = valueArg.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index++;
+      } else {
+        bytes += 6;
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      bytes += 6;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+
+const validateString = (
+  valueArg: unknown,
+  labelArg: string,
+  minimumBytesArg: number,
+  maximumBytesArg: number,
+  rejectControlsArg: boolean,
+): void => {
+  if (typeof valueArg !== 'string') {
+    throw new TypeError(`LocalNoSqlDb offline inspection ${labelArg} must be a string`);
+  }
+  const bytes = plugins.buffer.Buffer.byteLength(valueArg, 'utf8');
+  if (bytes < minimumBytesArg || bytes > maximumBytesArg) {
+    throw new RangeError(
+      `LocalNoSqlDb offline inspection ${labelArg} must be between ${minimumBytesArg} and ${maximumBytesArg} UTF-8 bytes`,
+    );
+  }
+  if (rejectControlsArg) {
+    for (const character of valueArg) {
+      if (/\p{Cc}/u.test(character)) {
+        throw new TypeError(
+          `LocalNoSqlDb offline inspection ${labelArg} must not contain control characters`,
+        );
+      }
+    }
+  }
+};
+
+export const normalizeLocalNoSqlDbOfflineInspectionInput = (
+  inputArg: ILocalNoSqlDbOfflineStringValueInspection,
+): ILocalNoSqlDbOfflineStringValueInspection => {
+  if (!isRecord(inputArg as unknown)) {
+    throw new TypeError('LocalNoSqlDb offline inspection input must be an object');
+  }
+  rejectUnknownEnumerableKeys(inputArg, inputKeys, 'input');
+  const inputRecord = inputArg as unknown as Record<string, unknown>;
+  const match = inputRecord.match;
+  if (!isRecord(match)) {
+    throw new TypeError('LocalNoSqlDb offline inspection match must be an object');
+  }
+  rejectUnknownEnumerableKeys(match, matchKeys, 'match');
+  const limits = inputRecord.limits;
+  if (!isRecord(limits)) {
+    throw new TypeError('LocalNoSqlDb offline inspection limits must be an object');
+  }
+  rejectUnknownEnumerableKeys(limits, limitKeySet, 'limits');
+
+  const normalized = {
+    folderPath: inputRecord.folderPath,
+    databaseName: inputRecord.databaseName,
+    collectionName: inputRecord.collectionName,
+    match: {
+      field: match.field,
+      value: match.value,
+    },
+    valueField: inputRecord.valueField,
+    limits: {
+      maximumEntries: limits.maximumEntries,
+      maximumTotalFileBytes: limits.maximumTotalFileBytes,
+      maximumRecords: limits.maximumRecords,
+      maximumRecordBytes: limits.maximumRecordBytes,
+      maximumResultBytes: limits.maximumResultBytes,
+    },
+  } as unknown as ILocalNoSqlDbOfflineStringValueInspection;
+
+  const bounds = localNoSqlDbOfflineInspectionBounds;
+  validateString(normalized.folderPath, 'folderPath', 1, bounds.maximumFolderPathBytes, true);
+  for (const [label, value] of [
+    ['databaseName', normalized.databaseName],
+    ['collectionName', normalized.collectionName],
+  ] as const) {
+    validateString(value, label, 1, bounds.maximumNamespaceComponentBytes, true);
+    if (value === '.' || value === '..' || value.includes('/') || value.includes('\\')) {
+      throw new TypeError(
+        `LocalNoSqlDb offline inspection ${label} must be one canonical path component`,
+      );
+    }
+  }
+  validateString(normalized.match.field, 'match.field', 1, bounds.maximumFieldNameBytes, true);
+  validateString(normalized.valueField, 'valueField', 1, bounds.maximumFieldNameBytes, true);
+  validateString(
+    normalized.match.value,
+    'match.value',
+    0,
+    bounds.maximumMatchValueBytes,
+    false,
+  );
+
+  for (const key of limitKeys) {
+    const value = normalized.limits[key];
+    const range = bounds.limits[key as keyof typeof bounds.limits];
+    if (!Number.isSafeInteger(value) || value < range.minimum || value > range.maximum) {
+      throw new RangeError(
+        `LocalNoSqlDb offline inspection limits.${key} must be a safe integer between ${range.minimum} and ${range.maximum}`,
+      );
+    }
+  }
+  if (plugins.buffer.Buffer.byteLength(normalized.match.value, 'utf8') > normalized.limits.maximumRecordBytes) {
+    throw new RangeError(
+      'LocalNoSqlDb offline inspection match.value must not exceed limits.maximumRecordBytes',
+    );
+  }
+
+  let requestBytes = 32 // Reserve the optional native deadline field.
+    + requestEnvelopeBytes
+    + requestStructuralBytes
+    + encodedJsonStringBytes(normalized.folderPath)
+    + encodedJsonStringBytes(normalized.databaseName)
+    + encodedJsonStringBytes(normalized.collectionName)
+    + encodedJsonStringBytes(normalized.match.field)
+    + encodedJsonStringBytes(normalized.match.value)
+    + encodedJsonStringBytes(normalized.valueField);
+  for (const key of limitKeys) {
+    requestBytes += String(normalized.limits[key]).length;
+  }
+  if (requestBytes > bounds.maximumRequestBytes) {
+    throw new RangeError(
+      `LocalNoSqlDb offline inspection request exceeds the ${bounds.maximumRequestBytes}-byte serialized limit`,
+    );
+  }
+  return normalized;
+};
+
+export const normalizeLocalNoSqlDbOfflinePhysicalNamespaceInspectionInput = (
+  inputArg: ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+): ILocalNoSqlDbOfflinePhysicalNamespaceInspection => {
+  const inputRecord = requirePhysicalNamespacePlainObject(
+    inputArg,
+    physicalNamespaceInputKeys,
+    'input',
+  );
+  const limits = requirePhysicalNamespacePlainObject(
+    inputRecord.limits,
+    physicalNamespaceLimitKeySet,
+    'limits',
+  );
+  const normalized: ILocalNoSqlDbOfflinePhysicalNamespaceInspection = {
+    folderPath: inputRecord.folderPath as string,
+    limits: {
+      maximumDatabases: limits.maximumDatabases as number,
+      maximumCollections: limits.maximumCollections as number,
+      maximumIndexes: limits.maximumIndexes as number,
+      maximumEntries: limits.maximumEntries as number,
+      maximumTotalFileBytes: limits.maximumTotalFileBytes as number,
+      maximumRecordsPerCollection: limits.maximumRecordsPerCollection as number,
+      maximumRecordBytes: limits.maximumRecordBytes as number,
+      maximumResultBytes: limits.maximumResultBytes as number,
+    },
+  };
+  const bounds = localNoSqlDbOfflinePhysicalNamespaceInspectionBounds;
+  if (typeof normalized.folderPath !== 'string') {
+    throw new TypeError(
+      'LocalNoSqlDb 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(
+      `LocalNoSqlDb 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(
+        'LocalNoSqlDb 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(
+        `LocalNoSqlDb 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(
+      `LocalNoSqlDb offline physical namespace inspection request exceeds the ${bounds.maximumRequestBytes}-byte serialized limit`,
+    );
+  }
+  return normalized;
+};
+
+export const validateNoSqlDbManagementOperationOptions = (
+  optionsArg?: INoSqlDbManagementOperationOptions,
+): void => {
+  if (optionsArg === undefined) return;
+  if (!isRecord(optionsArg as unknown)) {
+    throw new TypeError('NoSQLDB management operation options must be an object');
+  }
+  if (
+    optionsArg.timeoutMs !== undefined
+    && (
+      !Number.isSafeInteger(optionsArg.timeoutMs)
+      || optionsArg.timeoutMs <= 0
+      || optionsArg.timeoutMs > localNoSqlDbOfflineInspectionBounds.maximumTimeoutMs
+    )
+  ) {
+    throw new RangeError(
+      `NoSQLDB management operation timeoutMs must be an integer between 1 and ${localNoSqlDbOfflineInspectionBounds.maximumTimeoutMs}`,
+    );
+  }
+};

package/ts/ts_nosqldb/plugins.ts

@@ -0,0 +1,12 @@
+// node native scope
+import * as buffer from 'node:buffer';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+export { buffer, crypto, fs, path };
+
+// @push.rocks scope
+import * as smartrust from '@push.rocks/smartrust';
+
+export { smartrust };