@lossless.org/client 1.19.0 → 1.20.0

package/ts/nosqldb/classes.writeobserver.ts

@@ -0,0 +1,224 @@
+import type { SmartdataDb } from './classes.db.js';
+import { assertDataOptions } from './classes.operationbudget.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import { logger } from './logging.js';
+
+/** What a write did to its documents. An upsert that inserted is an `insert`. */
+export type TSmartdataWriteKind = 'insert' | 'update' | 'replace' | 'delete';
+
+/** The values a report carries; any other stored value is left out. */
+export type TSmartdataObservedValue = string | number | boolean | null;
+
+/** The observed fields of one document or selector, by field name. */
+export type TSmartdataObservedFields = Readonly<Record<string, TSmartdataObservedValue>>;
+
+/** One acknowledged write, reported to every write observer of its database. */
+export interface ISmartdataWriteReport {
+  /** The collection the write went to. */
+  readonly collection: string;
+  readonly kind: TSmartdataWriteKind;
+  /**
+   * The observed fields of each document the write named or returned: the
+   * inserted documents, a model instance's save or delete, an exact write, the
+   * document a find-one-and-modify returned. `null` when the write addressed
+   * its documents by selector only; `anchors` then says what it pinned.
+   */
+  readonly documents: readonly TSmartdataObservedFields[] | null;
+  /**
+   * The observed fields the write's selector pinned by top-level equality
+   * (`{ field: value }`, `{ field: { $eq: value } }`, or inside `$and`).
+   * Empty for an insert, which has no selector.
+   */
+  readonly anchors: TSmartdataObservedFields;
+}
+
+export interface ISmartdataWriteObserverOptions {
+  /** Top-level field names the reports carry: 1 to 64 distinct names, no `.` and no leading `$`. */
+  fields: readonly string[];
+  /**
+   * Called synchronously once per write. A listener that throws is logged and
+   * never fails the write; one that needs to do async work schedules it.
+   */
+  listener: (reportArg: ISmartdataWriteReport) => void;
+}
+
+/** @internal What a write path states about one acknowledged write. */
+export interface ISmartdataWrite {
+  collection: string;
+  kind: TSmartdataWriteKind;
+  /** The documents as written or returned; `null` for a write by selector only. */
+  documents: readonly object[] | null;
+  selector?: unknown;
+  /** The model's `identityAsDocumentId` field, whose value a selector carries as `_id`. */
+  identityDocumentIdField?: string;
+}
+
+interface IWriteObserver {
+  fields: readonly string[];
+  listener: (reportArg: ISmartdataWriteReport) => void;
+}
+
+const maximumObservedFields = 64;
+const observersByDb = new WeakMap<SmartdataDb, Set<IWriteObserver>>();
+
+const normalizeObserverOptions = (optionsArg: unknown): IWriteObserver => {
+  const { fields, listener } = assertDataOptions(optionsArg, ['fields', 'listener']);
+  if (typeof listener !== 'function') {
+    throw new SmartdataPersistenceError('invalid_argument',
+      'A SmartData write observer requires a listener function.');
+  }
+  if (
+    !Array.isArray(fields)
+    || fields.length === 0
+    || fields.length > maximumObservedFields
+    || fields.some((fieldArg) =>
+      typeof fieldArg !== 'string'
+      || fieldArg.length === 0
+      || fieldArg.includes('.')
+      || fieldArg.startsWith('$'))
+    || new Set(fields).size !== fields.length
+  ) {
+    throw new SmartdataPersistenceError('invalid_argument',
+      `A SmartData write observer requires 1 to ${maximumObservedFields} distinct top-level field names.`);
+  }
+  return {
+    fields: Object.freeze([...fields] as string[]),
+    listener: listener as IWriteObserver['listener'],
+  };
+};
+
+/** @internal Registers a write observer; the returned function removes it. */
+export const addSmartdataWriteObserver = (
+  dbArg: SmartdataDb,
+  optionsArg: ISmartdataWriteObserverOptions,
+): (() => void) => {
+  const observer = normalizeObserverOptions(optionsArg);
+  let observers = observersByDb.get(dbArg);
+  if (!observers) {
+    observers = new Set();
+    observersByDb.set(dbArg, observers);
+  }
+  observers.add(observer);
+  return () => {
+    observersByDb.get(dbArg)?.delete(observer);
+  };
+};
+
+/** @internal */
+export const hasSmartdataWriteObservers = (dbArg: SmartdataDb): boolean =>
+  (observersByDb.get(dbArg)?.size ?? 0) > 0;
+
+const observedValueOf = (valueArg: unknown): TSmartdataObservedValue | undefined =>
+  valueArg === null
+    || typeof valueArg === 'string'
+    || typeof valueArg === 'boolean'
+    || (typeof valueArg === 'number' && Number.isFinite(valueArg))
+    ? valueArg as TSmartdataObservedValue
+    : undefined;
+
+const isPlainRecord = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  if (typeof valueArg !== 'object' || valueArg === null || Array.isArray(valueArg)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(valueArg);
+  return prototype === Object.prototype || prototype === null;
+};
+
+const pickDocumentFields = (
+  documentArg: object,
+  fieldsArg: readonly string[],
+): Record<string, TSmartdataObservedValue> => {
+  const picked: Record<string, TSmartdataObservedValue> = {};
+  for (const field of fieldsArg) {
+    if (!Object.hasOwn(documentArg, field)) continue;
+    const value = observedValueOf((documentArg as Record<string, unknown>)[field]);
+    if (value !== undefined) picked[field] = value;
+  }
+  return picked;
+};
+
+/**
+ * A `null` condition also matches a missing field, so only concrete values
+ * anchor a selector.
+ */
+const collectSelectorAnchors = (
+  selectorArg: unknown,
+  fieldsArg: ReadonlySet<string>,
+  identityDocumentIdFieldArg: string | undefined,
+  anchorsArg: Record<string, TSmartdataObservedValue>,
+): void => {
+  if (!isPlainRecord(selectorArg)) return;
+  for (const key of Object.keys(selectorArg)) {
+    const condition = selectorArg[key];
+    if (key === '$and') {
+      if (Array.isArray(condition)) {
+        for (const conjunct of condition) {
+          collectSelectorAnchors(conjunct, fieldsArg, identityDocumentIdFieldArg, anchorsArg);
+        }
+      }
+      continue;
+    }
+    let value = observedValueOf(condition);
+    if (
+      value === undefined
+      && isPlainRecord(condition)
+      && Object.keys(condition).length === 1
+      && Object.hasOwn(condition, '$eq')
+    ) {
+      value = observedValueOf(condition.$eq);
+    }
+    if (value === undefined || value === null) continue;
+    const fields = key === '_id' && identityDocumentIdFieldArg
+      ? [key, identityDocumentIdFieldArg]
+      : [key];
+    for (const field of fields) {
+      if (fieldsArg.has(field) && !Object.hasOwn(anchorsArg, field)) {
+        anchorsArg[field] = value;
+      }
+    }
+  }
+};
+
+const describeError = (errorArg: unknown): string =>
+  errorArg instanceof Error ? errorArg.message : String(errorArg);
+
+/**
+ * @internal Captures one acknowledged write for the observers registered now,
+ * and returns the delivery, or `undefined` when nobody observes the database.
+ * The observed values are copied at capture, so a delivery deferred to a
+ * transaction's commit reports the write as it was made. An observer removed
+ * before the delivery receives nothing.
+ */
+export const captureSmartdataWrite = (
+  dbArg: SmartdataDb,
+  writeArg: ISmartdataWrite,
+): (() => void) | undefined => {
+  const registered = observersByDb.get(dbArg);
+  if (!registered || registered.size === 0) return undefined;
+  const observers = [...registered];
+  const fields = [...new Set(observers.flatMap((observerArg) => observerArg.fields))];
+  const documents = writeArg.documents?.map((documentArg) =>
+    pickDocumentFields(documentArg, fields)) ?? null;
+  const anchors: Record<string, TSmartdataObservedValue> = {};
+  collectSelectorAnchors(writeArg.selector, new Set(fields), writeArg.identityDocumentIdField, anchors);
+  return () => {
+    for (const observer of observers) {
+      if (!observersByDb.get(dbArg)?.has(observer)) continue;
+      const report: ISmartdataWriteReport = Object.freeze({
+        collection: writeArg.collection,
+        kind: writeArg.kind,
+        documents: documents === null
+          ? null
+          : Object.freeze(documents.map((documentArg) =>
+            Object.freeze(pickDocumentFields(documentArg, observer.fields)))),
+        anchors: Object.freeze(pickDocumentFields(anchors, observer.fields)),
+      });
+      try {
+        observer.listener(report);
+      } catch (errorArg) {
+        logger.log('error',
+          `A SmartData write observer threw on a write to "${writeArg.collection}": ${describeError(errorArg)}`);
+      }
+    }
+  };
+};