@lossless.org/client 1.18.3 → 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)}`);
+      }
+    }
+  };
+};

package/ts/objectstorage/classes.bucket.ts

@@ -18,7 +18,12 @@ import {
   purgeExactPath as purgeExactPathOperation,
 } from './internal.exactpathpurge.operations.js';
 import { beginBasicBucketOperation } from './internal.exactupload.capability.js';
-import { getProviderStatus, headBucketExists, runAccountRequest } from './internal.bucketrequests.js';
+import {
+  getProviderStatus,
+  headBucketExists,
+  isMissingObjectError,
+  runAccountRequest,
+} from './internal.bucketrequests.js';
 import { ObjectRangeError } from './classes.objectrangeerror.js';
 
 export interface IListObjectKeysPageOptions {
@@ -288,6 +293,15 @@ const destroyReadableAndWaitForSettlement = async (
   }
 };
 
+/** Reads a downloaded object body to its end and destroys the stream. */
+const readObjectBody = async (sourceArg: plugins.stream.Readable): Promise<Buffer> => {
+  const chunks: Buffer[] = [];
+  try {
+    for await (const chunk of sourceArg) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks);
+  } finally { sourceArg.destroy(); }
+};
+
 /**
  * The bucket class exposes the basic functionality of a bucket.
  * The functions of the bucket alone are enough to
@@ -456,12 +470,30 @@ export class Bucket {
    * get file
    */
   public async fastGet(optionsArg: { path: string }): Promise<Buffer> {
-    const source = await this.fastGetStream(optionsArg);
-    const chunks: Buffer[] = [];
+    return await readObjectBody(await this.fastGetStream(optionsArg));
+  }
+
+  /**
+   * Reads an object that may be missing with one GetObject request: resolves
+   * its bytes, or `null` when the provider answers that the key does not
+   * exist (`NoSuchKey`, `NotFound` or HTTP 404). Every other failure rejects
+   * as `fastGet()` does: a missing bucket, a denied request, a failure while
+   * the body streams, and an abort through `signal` or `SmartBucket.close()`,
+   * which rejects with the abort reason.
+   */
+  public async fastGetIfPresent(
+    optionsArg: interfaces.IFastGetIfPresentOptions,
+  ): Promise<Buffer | null> {
+    let source: plugins.stream.Readable;
     try {
-      for await (const chunk of source) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-      return Buffer.concat(chunks);
-    } finally { source.destroy(); }
+      source = await this.fastGetStream(optionsArg);
+    } catch (error) {
+      if (isMissingObjectError(error)) {
+        return null;
+      }
+      throw error;
+    }
+    return await readObjectBody(source);
   }
 
   /**
@@ -822,13 +854,13 @@ export class Bucket {
             { abortSignal: operation.signal },
           ));
           exists = true;
-        } catch (error: any) {
+        } catch (error) {
           try {
             operation.assertCurrent();
           } catch (abortError) {
             throw abortError;
           }
-          if (error?.name === 'NotFound') {
+          if (isMissingObjectError(error)) {
             exists = false;
           } else {
             throw error;
@@ -989,13 +1021,13 @@ export class Bucket {
         () => operation.client.send(command, { abortSignal: operation.signal }),
       );
       return true;
-    } catch (error: any) {
+    } catch (error) {
       try {
         operation.assertCurrent();
       } catch (abortError) {
         throw abortError;
       }
-      if (error?.name === 'NotFound') {
+      if (isMissingObjectError(error)) {
         return false;
       } else {
         throw error; // Rethrow if it's not a NotFound error to handle unexpected issues

package/ts/objectstorage/classes.metadata.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 
 import { File } from './classes.file.js';
+import { isMissingObjectError } from './internal.bucketrequests.js';
 
 export class MetaData {
   public static async hasMetaData(optionsArg: { file: File }) {
@@ -10,12 +11,10 @@ export class MetaData {
         path: optionsArg.file.name + '.metadata',
       });
       return !!existingFile;
-    } catch (error: any) {
-      const message = error?.message || '';
+    } catch (error) {
       const isNotFound =
-        message.includes('File not found') ||
-        error?.name === 'NotFound' ||
-        error?.$metadata?.httpStatusCode === 404;
+        (error instanceof Error && error.message.includes('File not found')) ||
+        isMissingObjectError(error);
       if (isNotFound) {
         return false;
       }

package/ts/objectstorage/interfaces.ts

@@ -78,6 +78,11 @@ export interface IFastExistsOptions {
   signal?: AbortSignal;
 }
 
+export interface IFastGetIfPresentOptions {
+  path: string;
+  signal?: AbortSignal;
+}
+
 export interface IFastStatOptions extends IPathDecriptor {
   signal?: AbortSignal;
 }

package/ts/objectstorage/internal.bucketrequests.ts

@@ -35,6 +35,20 @@ export const getProviderStatus = (errorArg: unknown): { name?: string; httpStatu
   };
 };
 
+/**
+ * Answers whether a provider error says the addressed object does not exist:
+ * GetObject's `NoSuchKey`, HeadObject's body-less `NotFound`, or any other
+ * HTTP 404. A `NoSuchBucket` answer names a missing bucket, not a missing
+ * object, and is not one.
+ */
+export const isMissingObjectError = (errorArg: unknown): boolean => {
+  const { name, httpStatusCode } = getProviderStatus(errorArg);
+  if (name === 'NoSuchBucket') {
+    return false;
+  }
+  return name === 'NoSuchKey' || name === 'NotFound' || httpStatusCode === 404;
+};
+
 /**
  * Answers whether the bucket exists with one HeadBucket request, which a
  * bucket-scoped credential may send for its own bucket. A missing bucket