@mxpicture/gcp-functions-backend 2.1.34 → 2.1.35

package/dist/firebase/firebase.tasks.js

@@ -1,6 +1,25 @@
 import { computeScheduleTimeUtc } from "@mxpicture/gcp-functions-common/helper";
+/**
+ * Pattern matching a fully-qualified Cloud Tasks task resource path.
+ *
+ * @remarks
+ * Capture groups (in order): project ID, region, queue ID, task ID.
+ * Used by {@link fromTaskPath}.
+ */
 export const taskPathRegex = /^projects\/([a-zA-Z0-9-_]+)\/locations\/([a-zA-Z0-9-_]+)\/queues\/([a-zA-Z0-9-_]+)\/tasks\/([a-zA-Z0-9-_]+)$/;
+/**
+ * Pattern matching a fully-qualified Cloud Tasks queue resource path.
+ *
+ * @remarks
+ * Capture groups (in order): project ID, region, queue ID. Used by {@link fromQueuePath}.
+ */
 export const queuePathRegex = /^projects\/([a-zA-Z0-9-_]+)\/locations\/([a-zA-Z0-9-_]+)\/queues\/([a-zA-Z0-9-_]+)$/;
+/**
+ * Pattern matching the short `<queueId>-<taskId>` form used as a friendly task name.
+ *
+ * @remarks
+ * Used by {@link fromTaskName} and {@link toTaskName}.
+ */
 export const taskNameRegex = /^([a-zA-Z0-9_]+)-([a-zA-Z0-9_]+)$/;
 /**
  * Compute a Cloud Tasks schedule timestamp from a duration specification or an absolute `Date`.
@@ -66,6 +85,12 @@ export const fromQueuePath = (path) => {
         queueId: found[3],
     };
 };
+/**
+ * Parses a short `<queueId>-<taskId>` task name into its parts.
+ *
+ * @param name - The short task name to parse.
+ * @returns The parsed parts, or `null` if `name` does not match {@link taskNameRegex}.
+ */
 export const fromTaskName = (name) => {
     const found = name.match(taskNameRegex);
     if (!found)
@@ -75,5 +100,11 @@ export const fromTaskName = (name) => {
         taskId: found[2],
     };
 };
+/**
+ * Formats a {@link FirebaseTaskName} back into its short `<queueId>-<taskId>` string form.
+ *
+ * @param name - The task name parts.
+ * @returns The joined `<queueId>-<taskId>` string.
+ */
 export const toTaskName = (name) => `${name.queueId}-${name.taskId}`;
 //# sourceMappingURL=firebase.tasks.js.map

package/dist/firebase/firebase.tasks.js.map

@@ -1 +1 @@
-{"version":3,"file":"firebase.tasks.js","sourceRoot":"","sources":["../../src/firebase/firebase.tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAShF,MAAM,CAAC,MAAM,aAAa,GACxB,8GAA8G,CAAC;AAEjH,MAAM,CAAC,MAAM,cAAc,GACzB,qFAAqF,CAAC;AAExF,MAAM,CAAC,MAAM,aAAa,GAAG,mCAAmC,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,aAAgD,EACzB,EAAE;IACzB,IAAI,QAAQ,GAAgB,IAAI,CAAC;IAEjC,IAAI,aAAa,YAAY,IAAI,EAAE,CAAC;QAClC,QAAQ,GAAG,aAAa,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,IAAI,EAAE,GAAG,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QACzD,EAAE,IAAI,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAClD,EAAE,IAAI,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QAC/C,EAAE,IAAI,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QAE1C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QACvC,QAAQ;YACN,CAAC,CAAC,aAAa,CAAC,eAAe,IAAI,CAAC,CAAC,aAAa,CAAC,aAAa;gBAC9D,CAAC,CAAC,sBAAsB,CACpB,IAAI,EACJ,aAAa,CAAC,eAAe,EAC7B,aAAa,CAAC,aAAa,CAC5B;gBACH,CAAC,CAAC,IAAI,CAAC;IACb,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;AAC5D,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAA6B,EAAE;IACtE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;QAChB,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QACjB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;KACjB,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAA8B,EAAE;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;QAChB,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;KAClB,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAA2B,EAAE;IACpE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QACjB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;KACjB,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAsB,EAAU,EAAE,CAC3D,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC"}
+{"version":3,"file":"firebase.tasks.js","sourceRoot":"","sources":["../../src/firebase/firebase.tasks.ts"],"names":[],"mappings":"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"}

package/dist/function/CompositeBackendFunction.d.ts

@@ -20,8 +20,17 @@ export declare class CompositeBackendFunction {
     readonly projectId: string;
     readonly region: string;
     readonly serviceAccount: string;
-    protected readonly funcs: Map<string, IBackendFunction<any, any, any, any>>;
+    protected readonly funcs: Map<string, IBackendFunction<any, any, any, any, any>>;
+    /**
+     * Creates a new composite function.
+     *
+     * @param name - Deployed Cloud Function name.
+     * @param projectId - GCP project ID.
+     * @param region - Cloud Functions deployment region.
+     * @param serviceAccount - Service account email used by the deployed function.
+     */
     constructor(name: string, projectId: string, region: string, serviceAccount: string);
+    /** Deployed HTTPS URL for this composite function. */
     get url(): string;
     /**
      * Register a per-topic function under the given topic key.
@@ -30,10 +39,32 @@ export declare class CompositeBackendFunction {
      * Sets the per-topic API's `functionUrl` to `${this.url}/${topic}` so per-topic code
      * (e.g., Cloud Tasks integration) can derive correct callback URLs.
      */
-    useTopic<STORE_DOC extends DocumentKeyAdmin, DTO extends STORE_DOC, SIDE_EFFECTS extends DocumentData, API extends BackendBaseApi<DTO, SIDE_EFFECTS>>(topic: string, func: IBackendFunction<STORE_DOC, DTO, SIDE_EFFECTS, API>): this;
+    useTopic<STORE_DOC extends DocumentKeyAdmin, DTO extends STORE_DOC, INPUT_DTO extends DocumentData, SIDE_EFFECTS extends DocumentData, API extends BackendBaseApi<DTO, INPUT_DTO, SIDE_EFFECTS>>(topic: string, func: IBackendFunction<STORE_DOC, DTO, INPUT_DTO, SIDE_EFFECTS, API>): this;
     /** Flattened `topic/route` strings used by `buildCheckServiceAuth` audience derivation. */
     get routes(): string[];
+    /**
+     * Builds a Firebase callable Cloud Function that dispatches by `{ topic, route, data }`.
+     *
+     * @remarks
+     * Wraps each registered per-topic {@link IBackendFunction} behind a single
+     * `onCall` handler. The composite verifies the topic exists and delegates
+     * to the per-topic function's `ingress`.
+     *
+     * @returns A Firebase callable function ready for deployment.
+     */
     buildCallableFunction(): ZCallableFunction<CompositeFunctionRequest<any>, Promise<FunctionResponse<any>>>;
+    /**
+     * Builds a Firebase HTTPS Cloud Function exposing each topic+route at `POST /<topic>/<route>`.
+     *
+     * @remarks
+     * Verifies the path has exactly two segments, looks up the topic, and
+     * delegates to the per-topic function's `ingress`. When `auth` is omitted, a
+     * default OIDC middleware (built via {@link buildCheckServiceAuth}) guards
+     * the function. Pass `null` explicitly to disable authentication.
+     *
+     * @param auth - Authentication middleware to install. Omit for the default OIDC check; pass `null` to disable.
+     * @returns A Firebase {@link HttpsFunction} ready for deployment.
+     */
     buildHttpsFunction(auth?: ExpressAuthHandler | null): HttpsFunction;
 }
 //# sourceMappingURL=CompositeBackendFunction.d.ts.map

package/dist/function/CompositeBackendFunction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeBackendFunction.d.ts","sourceRoot":"","sources":["../../src/function/CompositeBackendFunction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EACV,gBAAgB,IAAI,iBAAiB,EACrC,aAAa,EACd,MAAM,6BAA6B,CAAC;AAGrC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAwB;aAKjB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM;aACjB,MAAM,EAAE,MAAM;aACd,cAAc,EAAE,MAAM;IANxC,SAAS,CAAC,QAAQ,CAAC,KAAK,oDAA2D;gBAGjE,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM;IAGxC,IAAW,GAAG,IAAI,MAAM,CAEvB;IAED;;;;;;OAMG;IACI,QAAQ,CACb,SAAS,SAAS,gBAAgB,EAClC,GAAG,SAAS,SAAS,EACrB,YAAY,SAAS,YAAY,EACjC,GAAG,SAAS,cAAc,CAAC,GAAG,EAAE,YAAY,CAAC,EAC7C,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,GAAG,IAAI;IAMjF,2FAA2F;IAC3F,IAAW,MAAM,IAAI,MAAM,EAAE,CAK5B;IAEM,qBAAqB,IAAI,iBAAiB,CAE/C,wBAAwB,CAAC,GAAG,CAAC,EAE7B,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAC/B;IAaM,kBAAkB,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,aAAa;CAqD3E"}
+{"version":3,"file":"CompositeBackendFunction.d.ts","sourceRoot":"","sources":["../../src/function/CompositeBackendFunction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EACV,gBAAgB,IAAI,iBAAiB,EACrC,aAAa,EACd,MAAM,6BAA6B,CAAC;AAGrC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAwB;aAgBjB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM;aACjB,MAAM,EAAE,MAAM;aACd,cAAc,EAAE,MAAM;IAlBxC,SAAS,CAAC,QAAQ,CAAC,KAAK,yDAIpB;IAEJ;;;;;;;OAOG;gBAEe,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM;IAGxC,sDAAsD;IACtD,IAAW,GAAG,IAAI,MAAM,CAEvB;IAED;;;;;;OAMG;IACI,QAAQ,CACb,SAAS,SAAS,gBAAgB,EAClC,GAAG,SAAS,SAAS,EACrB,SAAS,SAAS,YAAY,EAC9B,YAAY,SAAS,YAAY,EACjC,GAAG,SAAS,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,CAAC,EAExD,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,CAAC,GACnE,IAAI;IAMP,2FAA2F;IAC3F,IAAW,MAAM,IAAI,MAAM,EAAE,CAK5B;IAED;;;;;;;;;OASG;IACI,qBAAqB,IAAI,iBAAiB,CAE/C,wBAAwB,CAAC,GAAG,CAAC,EAE7B,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAC/B;IAgBD;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,aAAa;CAwD3E"}

package/dist/function/CompositeBackendFunction.js

@@ -18,14 +18,22 @@ export class CompositeBackendFunction {
     projectId;
     region;
     serviceAccount;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     funcs = new Map();
+    /**
+     * Creates a new composite function.
+     *
+     * @param name - Deployed Cloud Function name.
+     * @param projectId - GCP project ID.
+     * @param region - Cloud Functions deployment region.
+     * @param serviceAccount - Service account email used by the deployed function.
+     */
     constructor(name, projectId, region, serviceAccount) {
         this.name = name;
         this.projectId = projectId;
         this.region = region;
         this.serviceAccount = serviceAccount;
     }
+    /** Deployed HTTPS URL for this composite function. */
     get url() {
         return `https://${this.region}-${this.projectId}.cloudfunctions.net/${this.name}`;
     }
@@ -49,6 +57,16 @@ export class CompositeBackendFunction {
                 out.push(`${topic}/${route}`);
         return out;
     }
+    /**
+     * Builds a Firebase callable Cloud Function that dispatches by `{ topic, route, data }`.
+     *
+     * @remarks
+     * Wraps each registered per-topic {@link IBackendFunction} behind a single
+     * `onCall` handler. The composite verifies the topic exists and delegates
+     * to the per-topic function's `ingress`.
+     *
+     * @returns A Firebase callable function ready for deployment.
+     */
     buildCallableFunction() {
         return onCall({ region: this.region, serviceAccount: this.serviceAccount }, async (req) => {
             const { topic, route, data } = req.data;
@@ -58,6 +76,18 @@ export class CompositeBackendFunction {
             return func.ingress({ route, data }, !!req.auth);
         });
     }
+    /**
+     * Builds a Firebase HTTPS Cloud Function exposing each topic+route at `POST /<topic>/<route>`.
+     *
+     * @remarks
+     * Verifies the path has exactly two segments, looks up the topic, and
+     * delegates to the per-topic function's `ingress`. When `auth` is omitted, a
+     * default OIDC middleware (built via {@link buildCheckServiceAuth}) guards
+     * the function. Pass `null` explicitly to disable authentication.
+     *
+     * @param auth - Authentication middleware to install. Omit for the default OIDC check; pass `null` to disable.
+     * @returns A Firebase {@link HttpsFunction} ready for deployment.
+     */
     buildHttpsFunction(auth) {
         const app = express();
         app.use(express.json());

package/dist/function/CompositeBackendFunction.js.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeBackendFunction.js","sourceRoot":"","sources":["../../src/function/CompositeBackendFunction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CompositeBackendFunction.js","sourceRoot":"","sources":["../../src/function/CompositeBackendFunction.ts"],"names":[],"mappings":"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"}

package/dist/function/IBackendFunction.d.ts

@@ -2,75 +2,97 @@ import type { DocumentData, DocumentKeyAdmin, FunctionRequest, FunctionResponse
 import type { CallableFunction, HttpsFunction } from "firebase-functions/v2/https";
 import type { ExpressAuthHandler } from "../types/types.express.js";
 import type { BackendBaseApi } from "../api/BackendBaseApi.js";
+/**
+ * Construction parameters for {@link IBackendFunction}.
+ */
 export interface BackendFunctionParams {
+    /** Deployed Cloud Function name. */
     name: string;
+    /** GCP project ID. */
     projectId: string;
+    /** Cloud Functions deployment region. */
     region: string;
+    /** Service account email used by the deployed function. */
     serviceAccount: string;
+    /** Paths within request/response payloads holding date values that need timestamp conversion. */
     datePaths: string[];
 }
 /**
- * Abstract base class for Firebase callable backend functions.
+ * Abstract base class for backend Cloud Functions.
  *
  * @remarks
- * Encapsulates the wiring between an incoming callable request and a {@link BackendDefaultApi}.
- * Subclasses configure the API, routes, region, and service account, then call
- * {@link IBackendFunction.buildFunction} to produce a deployable Cloud Function.
+ * Encapsulates the wiring between an incoming Firebase callable or HTTPS
+ * request and a {@link BackendBaseApi}. Subclasses inject the API via
+ * {@link useApi}; consumers call {@link buildCallableFunction} or
+ * {@link buildHttpsFunction} to produce a deployable Cloud Function.
  *
- * @typeParam DTO - The document data transfer object type.
+ * @typeParam STORE_DOC - The shape stored in the underlying {@link Store}.
+ * @typeParam DTO - The shape returned by the API (extends `STORE_DOC`).
+ * @typeParam INPUT_DTO - The shape accepted on write operations.
+ * @typeParam SIDE_EFFECTS - Type of side-effect payloads supported by the API.
  * @typeParam API - The backend API implementation that handles route logic.
  */
-export declare abstract class IBackendFunction<STORE_DOC extends DocumentKeyAdmin, DTO extends STORE_DOC, SIDE_EFFECTS extends DocumentData, API extends BackendBaseApi<DTO, SIDE_EFFECTS>> {
+export declare abstract class IBackendFunction<STORE_DOC extends DocumentKeyAdmin, DTO extends STORE_DOC, INPUT_DTO extends DocumentData, SIDE_EFFECTS extends DocumentData, API extends BackendBaseApi<DTO, INPUT_DTO, SIDE_EFFECTS>> {
     protected readonly params: BackendFunctionParams;
     protected _api?: API;
     /**
-     * Create a new backend function instance.
+     * Creates a new backend function instance.
      *
-     * @param name - A descriptive name for this function, used in error messages.
-     * @param region - The GCP region in which the function is deployed.
-     * @param serviceAccount - The service account email used to run the function.
-     * @param datePaths - JSON paths within the response payload that contain date values to convert to Firestore Timestamps.
+     * @param params - Deployment parameters; see {@link BackendFunctionParams}.
      */
     constructor(params: BackendFunctionParams);
+    /** Deployed HTTPS URL for this function. */
     get url(): string;
+    /** Deployed function name. */
     get name(): string;
+    /** GCP project ID. */
     get projectId(): string;
+    /** Cloud Functions deployment region. */
     get region(): string;
+    /** Service account email used by the deployed function. */
     get serviceAccount(): string;
+    /** Paths within payloads holding date values that need timestamp conversion. */
     protected get datePaths(): string[];
     /**
-     * Inject the backend API instance that handles route logic.
+     * Injects the backend API instance that handles route logic.
+     *
+     * @remarks
+     * Also pushes this function's deployed URL into the API via
+     * {@link BackendBaseApi.useFunctionUrl} so the API can derive callback URLs.
      *
      * @param api - The API instance to delegate requests to.
+     * @returns This instance for chaining.
      */
     useApi(api: API): this;
     /**
-     * Retrieve the injected API instance.
+     * Retrieves the injected API instance.
      *
      * @returns The API instance.
-     * @throws {@link Error} if no API has been provided via {@link useApi}.
+     * @throws Error when no API has been provided via {@link useApi}.
      */
     get api(): API;
     /**
-     * Retrieve the registered route names.
+     * Returns the route names registered on the underlying API.
      *
      * @returns The array of allowed route names.
-     * @throws {@link Error} if no routes have been provided via {@link useRoutes}.
+     * @throws Error when the API has not been injected, or when its routes have not been configured.
      */
     get routes(): string[];
     /**
-     * Route an incoming function request to the appropriate API method.
+     * Dispatches an incoming function request to the underlying API.
      *
      * @remarks
-     * Validates that the requested route is registered, delegates to the API, and
-     * converts date fields in the response payload to Firestore Timestamps.
+     * Rejects unauthenticated requests with `HttpsError("unauthenticated")` and
+     * wraps unexpected API errors in `HttpsError("internal")`. Existing
+     * {@link HttpsError} instances are re-thrown unchanged.
      *
      * @typeParam REQ - The request payload type.
      * @typeParam RES - The response document data type.
      * @param request - The incoming function request containing route and data.
+     * @param isAuthenticated - Whether the caller has been authenticated upstream.
      * @returns The function response wrapping the API result.
-     * @throws {@link HttpsError} with `invalid-argument` if the route is not registered.
-     * @throws {@link HttpsError} with `internal` if the API method throws an unexpected error.
+     * @throws {@link HttpsError} with `unauthenticated` when `isAuthenticated` is `false`.
+     * @throws {@link HttpsError} with `internal` when the API method throws an unexpected error.
      */
     ingress<REQ, RES extends DocumentData>(request: FunctionRequest<REQ>, isAuthenticated: boolean): Promise<FunctionResponse<RES>>;
     /**
@@ -84,12 +106,15 @@ export declare abstract class IBackendFunction<STORE_DOC extends DocumentKeyAdmi
      */
     buildCallableFunction(): CallableFunction<FunctionRequest<any>, Promise<FunctionResponse<any>>>;
     /**
-     * Build and return a Firebase Https Cloud Function.
+     * Builds a Firebase HTTPS Cloud Function exposing each route at `POST /<route>`.
      *
      * @remarks
      * Wraps {@link ingress} in a Firebase `onRequest` handler configured with the
-     * specified region and service account.
+     * function's region and service account. When `auth` is omitted, a default
+     * OIDC middleware built by {@link buildCheckServiceAuth} guards the function.
+     * Pass `null` explicitly to disable authentication.
      *
+     * @param auth - Authentication middleware to install. Omit for the default OIDC check; pass `null` to disable.
      * @returns A Firebase {@link HttpsFunction} ready for deployment.
      */
     buildHttpsFunction(auth?: ExpressAuthHandler | null): HttpsFunction;

package/dist/function/IBackendFunction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IBackendFunction.d.ts","sourceRoot":"","sources":["../../src/function/IBackendFunction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACd,MAAM,6BAA6B,CAAC;AAGrC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,8BAAsB,gBAAgB,CACpC,SAAS,SAAS,gBAAgB,EAClC,GAAG,SAAS,SAAS,EACrB,YAAY,SAAS,YAAY,EACjC,GAAG,SAAS,cAAc,CAAC,GAAG,EAAE,YAAY,CAAC;IAY1B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAVnE,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC;IAErB;;;;;;;OAOG;gBACmC,MAAM,EAAE,qBAAqB;IAEnE,IAAW,GAAG,IAAI,MAAM,CAEvB;IAED,IAAW,IAAI,IAAI,MAAM,CAExB;IACD,IAAW,SAAS,IAAI,MAAM,CAE7B;IACD,IAAW,MAAM,IAAI,MAAM,CAE1B;IACD,IAAW,cAAc,IAAI,MAAM,CAElC;IACD,SAAS,KAAK,SAAS,IAAI,MAAM,EAAE,CAElC;IAED;;;;OAIG;IACI,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI;IAK7B;;;;;OAKG;IACH,IAAW,GAAG,IAAI,GAAG,CAIpB;IAED;;;;;OAKG;IACH,IAAW,MAAM,IAAI,MAAM,EAAE,CAE5B;IAED;;;;;;;;;;;;;OAaG;IACU,OAAO,CAAC,GAAG,EAAE,GAAG,SAAS,YAAY,EAChD,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAC7B,eAAe,EAAE,OAAO,GACvB,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAejC;;;;;;;;OAQG;IACI,qBAAqB,IAAI,gBAAgB,CAE9C,eAAe,CAAC,GAAG,CAAC,EAEpB,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAC/B;IAOD;;;;;;;;OAQG;IACI,kBAAkB,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,aAAa;CAmD3E"}
+{"version":3,"file":"IBackendFunction.d.ts","sourceRoot":"","sources":["../../src/function/IBackendFunction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACd,MAAM,6BAA6B,CAAC;AAGrC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,iGAAiG;IACjG,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,gBAAgB,CACpC,SAAS,SAAS,gBAAgB,EAClC,GAAG,SAAS,SAAS,EACrB,SAAS,SAAS,YAAY,EAC9B,YAAY,SAAS,YAAY,EACjC,GAAG,SAAS,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,CAAC;IASrC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAPnE,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC;IAErB;;;;OAIG;gBACmC,MAAM,EAAE,qBAAqB;IAEnE,4CAA4C;IAC5C,IAAW,GAAG,IAAI,MAAM,CAEvB;IAED,8BAA8B;IAC9B,IAAW,IAAI,IAAI,MAAM,CAExB;IACD,sBAAsB;IACtB,IAAW,SAAS,IAAI,MAAM,CAE7B;IACD,yCAAyC;IACzC,IAAW,MAAM,IAAI,MAAM,CAE1B;IACD,2DAA2D;IAC3D,IAAW,cAAc,IAAI,MAAM,CAElC;IACD,gFAAgF;IAChF,SAAS,KAAK,SAAS,IAAI,MAAM,EAAE,CAElC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI;IAK7B;;;;;OAKG;IACH,IAAW,GAAG,IAAI,GAAG,CAIpB;IAED;;;;;OAKG;IACH,IAAW,MAAM,IAAI,MAAM,EAAE,CAE5B;IAED;;;;;;;;;;;;;;;OAeG;IACU,OAAO,CAAC,GAAG,EAAE,GAAG,SAAS,YAAY,EAChD,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAC7B,eAAe,EAAE,OAAO,GACvB,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAejC;;;;;;;;OAQG;IACI,qBAAqB,IAAI,gBAAgB,CAE9C,eAAe,CAAC,GAAG,CAAC,EAEpB,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAC/B;IAOD;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,aAAa;CAmD3E"}

package/dist/function/IBackendFunction.js

@@ -2,62 +2,74 @@ import { onCall, HttpsError, onRequest } from "firebase-functions/v2/https";
 import express from "express";
 import { buildCheckServiceAuth } from "../firebase/firebase.express.js";
 /**
- * Abstract base class for Firebase callable backend functions.
+ * Abstract base class for backend Cloud Functions.
  *
  * @remarks
- * Encapsulates the wiring between an incoming callable request and a {@link BackendDefaultApi}.
- * Subclasses configure the API, routes, region, and service account, then call
- * {@link IBackendFunction.buildFunction} to produce a deployable Cloud Function.
+ * Encapsulates the wiring between an incoming Firebase callable or HTTPS
+ * request and a {@link BackendBaseApi}. Subclasses inject the API via
+ * {@link useApi}; consumers call {@link buildCallableFunction} or
+ * {@link buildHttpsFunction} to produce a deployable Cloud Function.
  *
- * @typeParam DTO - The document data transfer object type.
+ * @typeParam STORE_DOC - The shape stored in the underlying {@link Store}.
+ * @typeParam DTO - The shape returned by the API (extends `STORE_DOC`).
+ * @typeParam INPUT_DTO - The shape accepted on write operations.
+ * @typeParam SIDE_EFFECTS - Type of side-effect payloads supported by the API.
  * @typeParam API - The backend API implementation that handles route logic.
  */
 export class IBackendFunction {
     params;
     _api;
     /**
-     * Create a new backend function instance.
+     * Creates a new backend function instance.
      *
-     * @param name - A descriptive name for this function, used in error messages.
-     * @param region - The GCP region in which the function is deployed.
-     * @param serviceAccount - The service account email used to run the function.
-     * @param datePaths - JSON paths within the response payload that contain date values to convert to Firestore Timestamps.
+     * @param params - Deployment parameters; see {@link BackendFunctionParams}.
      */
     constructor(params) {
         this.params = params;
     }
+    /** Deployed HTTPS URL for this function. */
     get url() {
         return `https://${this.region}-${this.projectId}.cloudfunctions.net/${this.name}`;
     }
+    /** Deployed function name. */
     get name() {
         return this.params.name;
     }
+    /** GCP project ID. */
     get projectId() {
         return this.params.projectId;
     }
+    /** Cloud Functions deployment region. */
     get region() {
         return this.params.region;
     }
+    /** Service account email used by the deployed function. */
     get serviceAccount() {
         return this.params.serviceAccount;
     }
+    /** Paths within payloads holding date values that need timestamp conversion. */
     get datePaths() {
         return this.params.datePaths;
     }
     /**
-     * Inject the backend API instance that handles route logic.
+     * Injects the backend API instance that handles route logic.
+     *
+     * @remarks
+     * Also pushes this function's deployed URL into the API via
+     * {@link BackendBaseApi.useFunctionUrl} so the API can derive callback URLs.
      *
      * @param api - The API instance to delegate requests to.
+     * @returns This instance for chaining.
      */
     useApi(api) {
         this._api = api.useFunctionUrl(this.url);
         return this;
     }
     /**
-     * Retrieve the injected API instance.
+     * Retrieves the injected API instance.
      *
      * @returns The API instance.
-     * @throws {@link Error} if no API has been provided via {@link useApi}.
+     * @throws Error when no API has been provided via {@link useApi}.
      */
     get api() {
         if (!this._api)
@@ -65,27 +77,29 @@ export class IBackendFunction {
         return this._api;
     }
     /**
-     * Retrieve the registered route names.
+     * Returns the route names registered on the underlying API.
      *
      * @returns The array of allowed route names.
-     * @throws {@link Error} if no routes have been provided via {@link useRoutes}.
+     * @throws Error when the API has not been injected, or when its routes have not been configured.
      */
     get routes() {
         return this.api.routes;
     }
     /**
-     * Route an incoming function request to the appropriate API method.
+     * Dispatches an incoming function request to the underlying API.
      *
      * @remarks
-     * Validates that the requested route is registered, delegates to the API, and
-     * converts date fields in the response payload to Firestore Timestamps.
+     * Rejects unauthenticated requests with `HttpsError("unauthenticated")` and
+     * wraps unexpected API errors in `HttpsError("internal")`. Existing
+     * {@link HttpsError} instances are re-thrown unchanged.
      *
      * @typeParam REQ - The request payload type.
      * @typeParam RES - The response document data type.
      * @param request - The incoming function request containing route and data.
+     * @param isAuthenticated - Whether the caller has been authenticated upstream.
      * @returns The function response wrapping the API result.
-     * @throws {@link HttpsError} with `invalid-argument` if the route is not registered.
-     * @throws {@link HttpsError} with `internal` if the API method throws an unexpected error.
+     * @throws {@link HttpsError} with `unauthenticated` when `isAuthenticated` is `false`.
+     * @throws {@link HttpsError} with `internal` when the API method throws an unexpected error.
      */
     async ingress(request, isAuthenticated) {
         if (!isAuthenticated)
@@ -115,12 +129,15 @@ export class IBackendFunction {
         return onCall({ region: this.region, serviceAccount: this.serviceAccount }, async (req) => this.ingress(req.data, !!req.auth));
     }
     /**
-     * Build and return a Firebase Https Cloud Function.
+     * Builds a Firebase HTTPS Cloud Function exposing each route at `POST /<route>`.
      *
      * @remarks
      * Wraps {@link ingress} in a Firebase `onRequest` handler configured with the
-     * specified region and service account.
+     * function's region and service account. When `auth` is omitted, a default
+     * OIDC middleware built by {@link buildCheckServiceAuth} guards the function.
+     * Pass `null` explicitly to disable authentication.
      *
+     * @param auth - Authentication middleware to install. Omit for the default OIDC check; pass `null` to disable.
      * @returns A Firebase {@link HttpsFunction} ready for deployment.
      */
     buildHttpsFunction(auth) {

package/dist/function/IBackendFunction.js.map

@@ -1 +1 @@
-{"version":3,"file":"IBackendFunction.js","sourceRoot":"","sources":["../../src/function/IBackendFunction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"IBackendFunction.js","sourceRoot":"","sources":["../../src/function/IBackendFunction.ts"],"names":[],"mappings":"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"}

package/dist/store/Store.d.ts

@@ -83,18 +83,37 @@ export declare class Store<DTO extends DocumentKeyAdmin> {
      * @returns The persisted document including its generated key metadata.
      */
     create(doc: CreateInput<DTO>): Promise<DTO>;
+    /**
+     * Returns a document ID, generating a short UUID when none is supplied.
+     *
+     * @param id - Optional ID to use unchanged.
+     * @returns The provided `id`, or a freshly generated short UUID.
+     */
     createId(id?: string): string;
     /**
-     * Update an existing document by merging partial data.
+     * Updates an existing document by merging partial data.
      *
      * @param id - The document ID to update.
      * @param doc - The partial document data to merge.
-     * @returns The updated document including its key metadata.
+     * @param requestChanges - When `true`, the result includes the list of dot-delimited paths that changed.
+     * @returns The updated document plus the optionally-populated list of changed paths.
      */
     update(id: string, doc: Partial<DTO>, requestChanges?: boolean): Promise<{
         updated: DTO;
         changedPaths: string[];
     }>;
+    /**
+     * Compares a partial document against the persisted version and returns changed paths.
+     *
+     * @remarks
+     * Only the keys present on `doc` are considered; the persisted document is
+     * narrowed to the same key set before comparison so unmentioned fields don't
+     * appear as changes.
+     *
+     * @param id - The document ID.
+     * @param doc - Partial document data to diff against the persisted version.
+     * @returns Dot-delimited paths whose values differ between persisted and provided data.
+     */
     compare(id: string, doc: Partial<DTO>): Promise<string[]>;
     /**
      * Delete one or more documents by their IDs.

package/dist/store/Store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Store.d.ts","sourceRoot":"","sources":["../../src/store/Store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,EACL,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAO/C;;;;;;;;GAQG;AACH,qBAAa,KAAK,CAAC,GAAG,SAAS,gBAAgB;aAW3B,cAAc,EAAE,MAAM;aACtB,SAAS,EAAE,MAAM;IACjC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,GAAG,CAAC;IAZ5D,SAAS,CAAC,GAAG,CAAC,EAAE,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAEzC;;;;;;OAMG;gBAEe,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,sBAAsB,CAAC,GAAG,CAAC,YAAA;IAG5D;;;;OAIG;IACI,EAAE,IAAI,mBAAmB,CAAC,GAAG,CAAC;IAarC;;;;;OAKG;IACU,KAAK,CAAC,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IActD;;;;;;;;OAQG;cACa,aAAa,CAC3B,CAAC,CAAC,EAAE,cAAc,GACjB,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAc9B;;;;;OAKG;IACU,KAAK,CAAC,CAAC,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAS9D;;;;;OAKG;IACI,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC;IAI9C;;;;;;OAMG;IACU,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAW1C;;;;;OAKG;IACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjD;;;;;OAKG;IACU,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAOjD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAIpC;;;;;;OAMG;IACU,MAAM,CACjB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EACjB,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAmBvC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAWtE;;;;OAIG;IACU,MAAM,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD;;;;OAIG;IACU,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;;;;OAKG;IACI,WAAW,CAAC,QAAQ,EAAE,MAAM;CAGpC"}
+{"version":3,"file":"Store.d.ts","sourceRoot":"","sources":["../../src/store/Store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,EACL,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAO/C;;;;;;;;GAQG;AACH,qBAAa,KAAK,CAAC,GAAG,SAAS,gBAAgB;aAW3B,cAAc,EAAE,MAAM;aACtB,SAAS,EAAE,MAAM;IACjC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,GAAG,CAAC;IAZ5D,SAAS,CAAC,GAAG,CAAC,EAAE,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAEzC;;;;;;OAMG;gBAEe,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,sBAAsB,CAAC,GAAG,CAAC,YAAA;IAG5D;;;;OAIG;IACI,EAAE,IAAI,mBAAmB,CAAC,GAAG,CAAC;IAarC;;;;;OAKG;IACU,KAAK,CAAC,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IActD;;;;;;;;OAQG;cACa,aAAa,CAC3B,CAAC,CAAC,EAAE,cAAc,GACjB,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAc9B;;;;;OAKG;IACU,KAAK,CAAC,CAAC,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAS9D;;;;;OAKG;IACI,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC;IAI9C;;;;;;OAMG;IACU,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAW1C;;;;;OAKG;IACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjD;;;;;OAKG;IACU,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAOxD;;;;;OAKG;IACI,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAIpC;;;;;;;OAOG;IACU,MAAM,CACjB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EACjB,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAmBpD;;;;;;;;;;;OAWG;IACU,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAWtE;;;;OAIG;IACU,MAAM,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD;;;;OAIG;IACU,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;;;;OAKG;IACI,WAAW,CAAC,QAAQ,EAAE,MAAM;CAGpC"}

package/dist/store/Store.js

@@ -145,15 +145,22 @@ export class Store {
         await ref.set({ ...doc, id });
         return this.get(id);
     }
+    /**
+     * Returns a document ID, generating a short UUID when none is supplied.
+     *
+     * @param id - Optional ID to use unchanged.
+     * @returns The provided `id`, or a freshly generated short UUID.
+     */
     createId(id) {
         return id ?? uuid.generate();
     }
     /**
-     * Update an existing document by merging partial data.
+     * Updates an existing document by merging partial data.
      *
      * @param id - The document ID to update.
      * @param doc - The partial document data to merge.
-     * @returns The updated document including its key metadata.
+     * @param requestChanges - When `true`, the result includes the list of dot-delimited paths that changed.
+     * @returns The updated document plus the optionally-populated list of changed paths.
      */
     async update(id, doc, requestChanges) {
         const entry = this.ref(id);
@@ -168,9 +175,21 @@ export class Store {
                 : [],
         };
     }
+    /**
+     * Compares a partial document against the persisted version and returns changed paths.
+     *
+     * @remarks
+     * Only the keys present on `doc` are considered; the persisted document is
+     * narrowed to the same key set before comparison so unmentioned fields don't
+     * appear as changes.
+     *
+     * @param id - The document ID.
+     * @param doc - Partial document data to diff against the persisted version.
+     * @returns Dot-delimited paths whose values differ between persisted and provided data.
+     */
     async compare(id, doc) {
         const _current = await this.get(id);
-        // onl compare provided props (doc)
+        // only compare provided props (doc)
         const current = stripObject(_current, Object.keys(doc));
         return compare(current, doc).filter((change) => change.split(".")[0]);
     }