@lossless.org/client 0.1.0

package/ts/nosqldb/classes.atomicupdate.ts

@@ -0,0 +1,99 @@
+import * as plugins from './plugins.js';
+import type { SmartdataCollection } from './classes.collection.js';
+import { normalizeOrdinaryPersistenceError } from './classes.persistence.js';
+import {
+  runWithOrdinarySmartdataSession,
+  type TSmartdataOrdinarySession,
+} from './classes.session.js';
+
+/**
+ * Executes a model-validated atomic update against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicUpdate()` owns the
+ * public API and must validate and normalize every filter and update before
+ * calling this raw persistence boundary.
+ */
+export const executeAtomicUpdate = async <T>(
+  collectionArg: SmartdataCollection<T>,
+  filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>,
+  updateArg: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>,
+  optsArg?: {
+    upsert?: boolean;
+    session?: TSmartdataOrdinarySession;
+  },
+): Promise<plugins.mongodb.UpdateResult> => {
+  return runWithOrdinarySmartdataSession(
+    optsArg?.session,
+    collectionArg.smartdataDb,
+    {
+      ordinaryWrite: true,
+      prepared: collectionArg.isInitializedForCurrentDatabase(),
+      preparationMessage:
+        `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    },
+    async (rawSessionArg) => {
+      await collectionArg.init();
+      try {
+        return await collectionArg.mongoDbCollection.updateOne(
+          filterArg,
+          updateArg,
+          {
+            upsert: optsArg?.upsert === true,
+            session: rawSessionArg,
+          },
+        );
+      } catch (errorArg) {
+        return normalizeOrdinaryPersistenceError(
+          errorArg,
+          `Atomic update conflicts with a unique index in collection "${collectionArg.collectionName}".`,
+        );
+      }
+    },
+  );
+};
+
+/**
+ * Executes a model-validated atomic update-many against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicUpdateMany()` owns
+ * the public API and must validate and normalize every filter and update
+ * before calling this raw persistence boundary. Each matched document is
+ * updated atomically; the batch as a whole is not isolated and no upsert is
+ * possible.
+ */
+export const executeAtomicUpdateMany = async <T>(
+  collectionArg: SmartdataCollection<T>,
+  filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>,
+  updateArg: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>,
+  optsArg?: {
+    session?: TSmartdataOrdinarySession;
+  },
+): Promise<plugins.mongodb.UpdateResult> => {
+  return runWithOrdinarySmartdataSession(
+    optsArg?.session,
+    collectionArg.smartdataDb,
+    {
+      ordinaryWrite: true,
+      prepared: collectionArg.isInitializedForCurrentDatabase(),
+      preparationMessage:
+        `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    },
+    async (rawSessionArg) => {
+      await collectionArg.init();
+      try {
+        return await collectionArg.mongoDbCollection.updateMany(
+          filterArg,
+          updateArg,
+          {
+            session: rawSessionArg,
+          },
+        );
+      } catch (errorArg) {
+        return normalizeOrdinaryPersistenceError(
+          errorArg,
+          `Atomic update-many conflicts with a unique index in collection "${collectionArg.collectionName}".`,
+        );
+      }
+    },
+  );
+};

package/ts/nosqldb/classes.bootstraprecord.ts

@@ -0,0 +1,107 @@
+import * as plugins from './plugins.js';
+import type { SmartdataDb } from './classes.db.js';
+import type { INormalizedCollectionModelSchema } from './classes.collection.js';
+import { assertDataOptions, SmartdataOperationBudget } from './classes.operationbudget.js';
+import { snapshotBoundedBsonDocument } from './classes.bsonsnapshot.js';
+import { validateOrdinaryStoredDocument } from './classes.ordinarypersistence.js';
+import { SmartdataPersistenceError, isMongoDuplicateKeyError } from './classes.persistence.js';
+import { readBoundedInspectionCursor } from './classes.namespaceinspection.js';
+import {
+  collectionModelSchemaResolverSymbol, collectionTopologyDbInspectionSymbol,
+  getExpectedCollectionTopologyForSchema, inspectCollectionTopologySnapshot,
+} from './classes.collectiontopology.js';
+
+export interface ISmartdataBootstrapRecordOptions {
+  /** Default 5000; maximum 120000 ms, shared by inspection and insertion. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /** Default 64 KiB, maximum 1 MiB of bounded inert BSON. */
+  maxBytes?: number;
+}
+
+export interface ISmartdataBootstrapRecordResult {
+  readonly acknowledged: true;
+  readonly insertedId: string;
+}
+
+type TBootstrapOutcome = 'inserted' | 'unique_conflict' | 'invalid_configuration' | 'ambiguous_write';
+
+/** @internal One validated insert command; no collection/index DDL or readiness publication. */
+export const insertBootstrapRecord = async (
+  modelArg: unknown,
+  dbArg: SmartdataDb,
+  recordArg: unknown,
+  optionsArg: ISmartdataBootstrapRecordOptions = {},
+): Promise<ISmartdataBootstrapRecordResult> => {
+  const options = assertDataOptions(optionsArg, ['timeoutMs', 'signal', 'maxBytes']);
+  const maxBytes = options.maxBytes === undefined ? 64 * 1024 : options.maxBytes;
+  if (!Number.isSafeInteger(maxBytes) || (maxBytes as number) < 1 || (maxBytes as number) > 1024 * 1024) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Invalid bootstrap record size bound.');
+  }
+  const budget = new SmartdataOperationBudget(options.timeoutMs === undefined ? 5000 : options.timeoutMs, options.signal);
+  try {
+    budget.check();
+    const model = modelArg as { [collectionModelSchemaResolverSymbol]?: () => INormalizedCollectionModelSchema };
+    if (!model || !Object.hasOwn(model, collectionModelSchemaResolverSymbol) ||
+      typeof model[collectionModelSchemaResolverSymbol] !== 'function') {
+      throw new SmartdataPersistenceError('invalid_configuration', 'Bootstrap insertion requires a declared model.');
+    }
+    const schema = model[collectionModelSchemaResolverSymbol]!();
+    if (!schema.ordinaryPersistence || schema.ordinaryPersistence.idType !== 'string' ||
+      schema.ordinaryPersistence.timestamps !== 'none' || schema.indexes.length !== 0) {
+      throw new SmartdataPersistenceError('invalid_configuration',
+        'Bootstrap insertion requires strict ordinary string-ID persistence without timestamps or secondary indexes.');
+    }
+    const document = validateOrdinaryStoredDocument(
+      snapshotBoundedBsonDocument(recordArg, maxBytes as number, () => new SmartdataPersistenceError(
+        'invalid_document', 'Bootstrap record must be bounded, inert, canonical BSON with an explicit string ID.',
+      )), schema.ordinaryPersistence, schema.persistedFields,
+    );
+    const expected = getExpectedCollectionTopologyForSchema(schema);
+    let dispatched = false;
+    let outcome: TBootstrapOutcome;
+    try {
+      // Explicit preparation uses this same connection-generation guard.
+      outcome = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg, assertCurrentArg) => {
+        budget.check();
+        const namespaces = await readBoundedInspectionCursor(mongoDbArg.listCollections(
+          { name: schema.collectionName },
+          { nameOnly: false, batchSize: 1, ...budget.operationOptions() },
+        ), 1, budget.signal, () => budget.cleanupOptions());
+        budget.check();
+        assertCurrentArg();
+        const namespace = namespaces[0] as unknown as Record<string, unknown> | undefined;
+        const collection = mongoDbArg.collection(schema.collectionName);
+        const indexes = namespace?.type === 'collection'
+          ? await readBoundedInspectionCursor(collection.listIndexes({
+              batchSize: 1, ...budget.cleanupOptions(),
+            }), 64, budget.signal, () => budget.cleanupOptions())
+          : [];
+        budget.check();
+        assertCurrentArg();
+        const topology = inspectCollectionTopologySnapshot(expected, { namespace: namespace ?? null, indexes });
+        if (topology.status !== 'absent' && topology.status !== 'exact') return 'invalid_configuration';
+        const insertOptions = budget.operationOptions();
+        dispatched = true;
+        try {
+          const result = await collection.insertOne(document, insertOptions);
+          budget.check();
+          return result.acknowledged && result.insertedId === document._id ? 'inserted' : 'ambiguous_write';
+        } catch (errorArg) {
+          return isMongoDuplicateKeyError(errorArg) ? 'unique_conflict' : 'ambiguous_write';
+        }
+      });
+    } catch {
+      throw new SmartdataPersistenceError(dispatched ? 'ambiguous_write' : 'unsupported_operation',
+        dispatched ? 'Bootstrap insertion outcome is uncertain; inspect its explicit ID before proceeding.'
+          : 'Bootstrap insertion could not inspect the current database connection.');
+    }
+    if (outcome === 'inserted') return Object.freeze({ acknowledged: true, insertedId: document._id as string });
+    const messages = {
+      unique_conflict: 'Bootstrap record conflicts with a unique index.',
+      invalid_configuration: 'Bootstrap insertion requires absent or exact primary-only collection topology.',
+      ambiguous_write: 'Bootstrap insertion outcome is uncertain; inspect its explicit ID before proceeding.',
+    };
+    throw new SmartdataPersistenceError(outcome, messages[outcome]);
+  } finally { budget.close(); }
+};

package/ts/nosqldb/classes.bsonassertion.ts

@@ -0,0 +1,25 @@
+import * as plugins from './plugins.js';
+
+/** @internal Shared ordinary/exact assertion invariant. */
+export const assertBsonWithoutMutation = (
+  documentArg: object,
+  assertionArg: (valueArg: unknown) => void,
+  errorArg: (reasonArg: 'assertion' | 'bson' | 'mutation', causeArg?: unknown) => Error,
+): void => {
+  const before = plugins.mongodb.BSON.serialize(documentArg);
+  try {
+    const result = assertionArg(documentArg) as unknown;
+    if (result !== undefined) {
+      // Reject asynchronous assertions and consume a native rejection so it
+      // cannot escape later as an unhandled process error.
+      if (result instanceof Promise) void result.catch(() => undefined);
+      throw new Error('Document assertions must be synchronous and return undefined.');
+    }
+  } catch (causeArg) { throw errorArg('assertion', causeArg); }
+  let after: Uint8Array;
+  try { after = plugins.mongodb.BSON.serialize(documentArg); }
+  catch (causeArg) { throw errorArg('bson', causeArg); }
+  if (before.length !== after.length || before.some((valueArg, indexArg) => valueArg !== after[indexArg])) {
+    throw errorArg('mutation');
+  }
+};

package/ts/nosqldb/classes.bsonobjectid.ts

@@ -0,0 +1,45 @@
+import * as plugins from './plugins.js';
+
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const bufferGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, 'buffer')!.get!;
+const offsetGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, 'byteOffset')!.get!;
+const lengthGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, 'byteLength')!.get!;
+
+/** @internal Read the official ObjectId layouts without executing caller code. */
+export const getInertObjectIdBytes = (valueArg: object, errorArg: () => Error): Uint8Array => {
+  if (plugins.nodeUtil.types.isProxy(valueArg) ||
+    Object.getPrototypeOf(valueArg) !== plugins.mongodb.ObjectId.prototype) throw errorArg();
+  const toBson = Object.getOwnPropertyDescriptor(valueArg, 'toBSON');
+  if (toBson && (!('value' in toBson) || toBson.value !== undefined || toBson.enumerable)) throw errorArg();
+  const keys = Reflect.ownKeys(valueArg).filter((keyArg) => keyArg !== 'toBSON');
+  const getData = (keyArg: string): unknown => {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, keyArg);
+    if (!descriptor || !('value' in descriptor)) throw errorArg();
+    return descriptor.value;
+  };
+  if (keys.length === 1 && keys[0] === 'buffer') {
+    const buffer = getData('buffer');
+    if (typeof buffer !== 'object' || !buffer || plugins.nodeUtil.types.isProxy(buffer) ||
+      !ArrayBuffer.isView(buffer)) throw errorArg();
+    const prototype = Object.getPrototypeOf(buffer);
+    if (prototype !== Uint8Array.prototype && prototype !== Buffer.prototype) throw errorArg();
+    if (Reflect.apply(lengthGetter, buffer, []) !== 12 || Reflect.ownKeys(buffer).length !== 12) throw errorArg();
+    return new Uint8Array(Reflect.apply(bufferGetter, buffer, []),
+      Reflect.apply(offsetGetter, buffer, []), 12).slice();
+  }
+  // BSON 7.3.2 replaced the byte buffer with four unsigned 24-bit words.
+  const wordKeys = ['i0', 'i1', 'i2', 'i3'];
+  if (keys.length !== 4 || keys.some((keyArg) => typeof keyArg !== 'string' || !wordKeys.includes(keyArg))) {
+    throw errorArg();
+  }
+  const bytes = new Uint8Array(12);
+  for (let index = 0; index < wordKeys.length; index++) {
+    const word = getData(wordKeys[index]);
+    if (typeof word !== 'number' || !Number.isInteger(word) ||
+      word < 0 || word > 0xffffff || Object.is(word, -0)) throw errorArg();
+    bytes[index * 3] = (word >>> 16) & 0xff;
+    bytes[index * 3 + 1] = (word >>> 8) & 0xff;
+    bytes[index * 3 + 2] = word & 0xff;
+  }
+  return bytes;
+};

package/ts/nosqldb/classes.bsonsnapshot.ts

@@ -0,0 +1,105 @@
+import * as plugins from './plugins.js';
+import { getInertObjectIdBytes } from './classes.bsonobjectid.js';
+
+/** @internal Snapshot bounded inert BSON without invoking caller serialization. */
+export const snapshotBoundedBsonDocument = (
+  valueArg: unknown, maxBytesArg: number, errorArg: () => Error,
+): plugins.mongodb.Document => {
+  const faultError = errorArg;
+  /** A deliberately small BSON subset; descriptors are read without invoking user code. */
+  const snapshotBsonValue = (
+    valueArg: unknown,
+    budgetArg: { remaining: number; bytes: number },
+    seenArg = new WeakSet<object>(),
+    depthArg = 0,
+  ): unknown => {
+    if (--budgetArg.remaining < 0 || depthArg > 64) throw faultError();
+    if (typeof valueArg === 'string') {
+      if (valueArg.length > budgetArg.bytes) throw faultError();
+      budgetArg.bytes -= Buffer.byteLength(valueArg, 'utf8');
+      if (budgetArg.bytes < 0) throw faultError();
+      return valueArg;
+    }
+    if (valueArg === null || typeof valueArg === 'boolean') return valueArg;
+    if (typeof valueArg === 'number' && Number.isFinite(valueArg)) return valueArg;
+    if (typeof valueArg !== 'object' || !valueArg || plugins.nodeUtil.types.isProxy(valueArg) ||
+      seenArg.has(valueArg)) throw faultError();
+    seenArg.add(valueArg);
+    try {
+      const prototype = Object.getPrototypeOf(valueArg);
+      if (prototype === Date.prototype && Reflect.ownKeys(valueArg).length === 0) {
+        const time = Date.prototype.getTime.call(valueArg);
+        if (!Number.isFinite(time)) throw faultError();
+        return new Date(time);
+      }
+      if (prototype === plugins.mongodb.ObjectId.prototype) {
+        if (Object.hasOwn(valueArg, 'toBSON')) throw faultError();
+        const bytes = getInertObjectIdBytes(valueArg, faultError);
+        budgetArg.bytes -= bytes.length;
+        if (budgetArg.bytes < 0) throw faultError();
+        return new plugins.mongodb.ObjectId(bytes);
+      }
+      if (prototype === Uint8Array.prototype || prototype === Buffer.prototype) {
+        // TypedArray intrinsics avoid overridable length, iterator and buffer getters.
+        const typedPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+        const length = Reflect.apply(Object.getOwnPropertyDescriptor(typedPrototype, 'byteLength')!.get!, valueArg, []);
+        if (length > budgetArg.bytes || Reflect.ownKeys(valueArg).length !== length) throw faultError();
+        budgetArg.bytes -= length;
+        const buffer = Reflect.apply(Object.getOwnPropertyDescriptor(typedPrototype, 'buffer')!.get!, valueArg, []);
+        const offset = Reflect.apply(Object.getOwnPropertyDescriptor(typedPrototype, 'byteOffset')!.get!, valueArg, []);
+        return new plugins.mongodb.Binary(new Uint8Array(buffer, offset, length).slice());
+      }
+      if (prototype === plugins.mongodb.Binary.prototype) {
+        const buffer = Object.getOwnPropertyDescriptor(valueArg, 'buffer');
+        const position = Object.getOwnPropertyDescriptor(valueArg, 'position');
+        const subtype = Object.getOwnPropertyDescriptor(valueArg, 'sub_type');
+        if (Reflect.ownKeys(valueArg).length !== 3 || !buffer || !position || !subtype ||
+          !('value' in buffer) || !('value' in position) || !('value' in subtype) ||
+          !Number.isSafeInteger(position.value) || position.value < 0 ||
+          !Number.isSafeInteger(subtype.value) || subtype.value < 0 || subtype.value > 255) throw faultError();
+        const bytes = snapshotBsonValue(buffer.value, budgetArg, seenArg, depthArg + 1);
+        if (!(bytes instanceof plugins.mongodb.Binary) || position.value > bytes.buffer.length) throw faultError();
+        return new plugins.mongodb.Binary(bytes.buffer.slice(0, position.value), subtype.value);
+      }
+      const array = Array.isArray(valueArg);
+      if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) throw faultError();
+      const keys = Reflect.ownKeys(valueArg);
+      if (keys.length > budgetArg.remaining || (array && keys.length !== valueArg.length + 1)) throw faultError();
+      const result: Record<string, unknown> | unknown[] = array ? [] : Object.create(null);
+      if (keys.some((keyArg) => typeof keyArg !== 'string')) throw faultError();
+      for (const key of (keys as string[]).sort()) {
+        if (array && key === 'length') continue;
+        if (typeof key !== 'string' || key.includes('\0') || key === 'toBSON' || key === '_bsontype') throw faultError();
+        if (key.length > budgetArg.bytes) throw faultError();
+        budgetArg.bytes -= Buffer.byteLength(key, 'utf8');
+        if (budgetArg.bytes < 0) throw faultError();
+        const descriptor = Object.getOwnPropertyDescriptor(valueArg, key)!;
+        if (!('value' in descriptor) || !descriptor.enumerable ||
+          (array && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= valueArg.length))) throw faultError();
+        Object.defineProperty(result, key, { value: snapshotBsonValue(descriptor.value, budgetArg, seenArg, depthArg + 1),
+          enumerable: true, writable: true, configurable: true });
+      }
+      return result;
+    } finally { seenArg.delete(valueArg); }
+  };
+
+  const canonicalBsonDocument = (valueArg: unknown, maxBytesArg: number): plugins.mongodb.Document => {
+    try {
+      const snapshot = snapshotBsonValue(valueArg, { remaining: 100_000, bytes: maxBytesArg });
+      if (!snapshot || Array.isArray(snapshot) || Object.getPrototypeOf(snapshot) !== null ||
+        !Object.hasOwn(snapshot, '_id')) throw faultError();
+      const document = snapshot as plugins.mongodb.Document;
+      const id = document._id;
+      if (!(typeof id === 'string' && id.length > 0) &&
+        !(typeof id === 'number' && Number.isFinite(id)) &&
+        !(id instanceof plugins.mongodb.ObjectId)) throw faultError();
+      const bytes = plugins.mongodb.BSON.serialize(document);
+      if (bytes.byteLength > maxBytesArg) throw faultError();
+      const canonical = plugins.mongodb.BSON.deserialize(bytes);
+      if (!Buffer.from(bytes).equals(Buffer.from(plugins.mongodb.BSON.serialize(canonical)))) throw faultError();
+      return canonical;
+    } catch { throw faultError(); }
+  };
+
+  return canonicalBsonDocument(valueArg, maxBytesArg);
+};

package/ts/nosqldb/classes.cached-document.ts

@@ -0,0 +1,67 @@
+import { SmartDataDbDoc, index, svDb } from './classes.doc.js';
+
+/**
+ * Common TTL values in milliseconds for cache-like documents.
+ */
+export const smartdataTtlValues = {
+  HOURS_1: 1 * 60 * 60 * 1000,
+  HOURS_24: 24 * 60 * 60 * 1000,
+  DAYS_7: 7 * 24 * 60 * 60 * 1000,
+  DAYS_30: 30 * 24 * 60 * 60 * 1000,
+  DAYS_90: 90 * 24 * 60 * 60 * 1000,
+} as const;
+
+/**
+ * Base class for SmartData documents that should expire after an absolute date.
+ */
+export abstract class SmartdataCachedDocument<
+  T extends SmartdataCachedDocument<T>,
+> extends SmartDataDbDoc<T, T> {
+  @svDb()
+  public createdAt: Date = new Date();
+
+  @index({ expireAfterSeconds: 0 })
+  public expiresAt?: Date;
+
+  @svDb()
+  public lastAccessedAt: Date = new Date();
+
+  public setTTL(ttlMs: number): void {
+    this.expiresAt = new Date(Date.now() + ttlMs);
+  }
+
+  public setTTLDays(days: number): void {
+    this.setTTL(days * 24 * 60 * 60 * 1000);
+  }
+
+  public setTTLHours(hours: number): void {
+    this.setTTL(hours * 60 * 60 * 1000);
+  }
+
+  public isExpired(): boolean {
+    if (!this.expiresAt) {
+      return false;
+    }
+    return Date.now() > this.expiresAt.getTime();
+  }
+
+  public touch(): void {
+    this.lastAccessedAt = new Date();
+  }
+
+  public getRemainingTTL(): number {
+    if (!this.expiresAt) {
+      return -1;
+    }
+    const remaining = this.expiresAt.getTime() - Date.now();
+    return remaining > 0 ? remaining : 0;
+  }
+
+  public extendTTL(ttlMs: number): void {
+    this.expiresAt = new Date(Date.now() + ttlMs);
+  }
+
+  public setNeverExpires(): void {
+    this.expiresAt = new Date(Date.now() + 100 * 365 * 24 * 60 * 60 * 1000);
+  }
+}