velocious 1.0.474 → 1.0.475

package/build/src/sync/local-mutation-log.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Local mutation log record query options.
+ * @typedef {object} LocalMutationLogRecordsOptions
+ * @property {LocalMutationStatus[]} [statuses] - Optional status filter.
+ */
+/**
+ * Local mutation log row-oriented storage adapter.
+ *
+ * Implementations should store each mutation log record as its own row/entry.
+ * Native apps should back this with SQLite and indexes on storage key, status,
+ * and sequence. Avoid storing the whole log as one JSON blob.
+ *
+ * @typedef {object} LocalMutationLogStorage
+ * @property {(storageKey: string, record: LocalMutationLogRecord) => Promise<void> | void} appendRecord - Appends one log record.
+ * @property {(storageKey: string, ids: string[]) => Promise<void> | void} deleteRecords - Deletes log records by id.
+ * @property {(storageKey: string) => Promise<number> | number} nextSequence - Returns the next local sequence number.
+ * @property {(storageKey: string, id: string) => Promise<LocalMutationLogRecord | null | undefined> | LocalMutationLogRecord | null | undefined} record - Reads one log record by id.
+ * @property {(storageKey: string, options?: LocalMutationLogRecordsOptions) => Promise<LocalMutationLogRecord[]> | LocalMutationLogRecord[]} records - Reads log records.
+ * @property {(storageKey: string, record: LocalMutationLogRecord) => Promise<void> | void} updateRecord - Replaces one log record.
+ */
+/**
+ * Local sync mutation dependency metadata.
+ * @typedef {object} LocalMutationDependency
+ * @property {string} clientMutationId - Client mutation id this mutation depends on.
+ * @property {string} model - Dependent model/resource name.
+ */
+/**
+ * Local mutation log status.
+ * @typedef {"pending" | "applied-locally" | "peer-applied" | "conflict" | "rejected" | "synced"} LocalMutationStatus
+ * */
+/**
+ * Local mutation log record.
+ * @typedef {object} LocalMutationLogRecord
+ * @property {string} createdAt - ISO timestamp when the record was created locally.
+ * @property {LocalMutationDependency[]} dependencies - Other local mutations that must replay first.
+ * @property {string} id - Local log record id.
+ * @property {import("./device-identity.js").SyncMutation} mutation - Device mutation payload.
+ * @property {number} sequence - Monotonic local sequence.
+ * @property {LocalMutationStatus} status - Local replay/apply status.
+ * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [syncResult] - Backend replay/result metadata.
+ * @property {string} updatedAt - ISO timestamp when the record was last changed.
+ */
+/** Client-side append-only sync mutation log with pluggable persistent storage. */
+export default class LocalMutationLog {
+    /**
+     * Creates a local mutation log.
+     * @param {object} args - Arguments.
+     * @param {() => string} [args.idGenerator] - Record id generator.
+     * @param {() => Date} [args.now] - Clock callback.
+     * @param {LocalMutationLogStorage} args.storage - Persistent storage adapter.
+     * @param {string} [args.storageKey] - Storage key.
+     */
+    constructor({ idGenerator, now, storage, storageKey }: {
+        idGenerator?: (() => string) | undefined;
+        now?: (() => Date) | undefined;
+        storage: LocalMutationLogStorage;
+        storageKey?: string | undefined;
+    });
+    idGenerator: () => string;
+    now: () => Date;
+    storage: LocalMutationLogStorage;
+    storageKey: string;
+    /**
+     * Appends a pending mutation record.
+     * @param {object} args - Arguments.
+     * @param {LocalMutationDependency[]} [args.dependencies] - Mutation dependencies.
+     * @param {import("./device-identity.js").SyncMutation} args.mutation - Mutation payload.
+     * @returns {Promise<LocalMutationLogRecord>} - Created log record.
+     */
+    append({ dependencies, mutation }: {
+        dependencies?: LocalMutationDependency[] | undefined;
+        mutation: import("./device-identity.js").SyncMutation;
+    }): Promise<LocalMutationLogRecord>;
+    /**
+     * Returns all records ordered by local sequence.
+     * @returns {Promise<LocalMutationLogRecord[]>} - Log records.
+     */
+    records(): Promise<LocalMutationLogRecord[]>;
+    /**
+     * Returns records that still need local/server reconciliation.
+     * @returns {Promise<LocalMutationLogRecord[]>} - Pending records.
+     */
+    pendingRecords(): Promise<LocalMutationLogRecord[]>;
+    /**
+     * Updates a record status.
+     * @param {object} args - Arguments.
+     * @param {string} args.id - Record id.
+     * @param {LocalMutationStatus} args.status - New status.
+     * @param {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [args.syncResult] - Result metadata.
+     * @returns {Promise<LocalMutationLogRecord>} - Updated record.
+     */
+    updateStatus({ id, status, syncResult }: {
+        id: string;
+        status: LocalMutationStatus;
+        syncResult?: Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue> | undefined;
+    }): Promise<LocalMutationLogRecord>;
+    /**
+     * Prunes terminal records that are no longer needed for replay dependencies.
+     * @param {object} [args] - Compaction options.
+     * @param {number} [args.maxTerminalRecords] - Maximum terminal records to retain.
+     * @param {number} [args.terminalRetentionMs] - Minimum age before pruning terminal records.
+     * @returns {Promise<{deletedRecordIds: string[]}>} - Compaction result.
+     */
+    compact({ maxTerminalRecords, terminalRetentionMs }?: {
+        maxTerminalRecords?: number | undefined;
+        terminalRetentionMs?: number | undefined;
+    }): Promise<{
+        deletedRecordIds: string[];
+    }>;
+    /**
+     * Returns the current log timestamp.
+     * @returns {string} - Current ISO timestamp.
+     */
+    currentTimestamp(): string;
+}
+/**
+ * Local mutation log record query options.
+ */
+export type LocalMutationLogRecordsOptions = {
+    /**
+     * - Optional status filter.
+     */
+    statuses?: LocalMutationStatus[] | undefined;
+};
+/**
+ * Local mutation log row-oriented storage adapter.
+ *
+ * Implementations should store each mutation log record as its own row/entry.
+ * Native apps should back this with SQLite and indexes on storage key, status,
+ * and sequence. Avoid storing the whole log as one JSON blob.
+ */
+export type LocalMutationLogStorage = {
+    /**
+     * - Appends one log record.
+     */
+    appendRecord: (storageKey: string, record: LocalMutationLogRecord) => Promise<void> | void;
+    /**
+     * - Deletes log records by id.
+     */
+    deleteRecords: (storageKey: string, ids: string[]) => Promise<void> | void;
+    /**
+     * - Returns the next local sequence number.
+     */
+    nextSequence: (storageKey: string) => Promise<number> | number;
+    /**
+     * - Reads one log record by id.
+     */
+    record: (storageKey: string, id: string) => Promise<LocalMutationLogRecord | null | undefined> | LocalMutationLogRecord | null | undefined;
+    /**
+     * - Reads log records.
+     */
+    records: (storageKey: string, options?: LocalMutationLogRecordsOptions) => Promise<LocalMutationLogRecord[]> | LocalMutationLogRecord[];
+    /**
+     * - Replaces one log record.
+     */
+    updateRecord: (storageKey: string, record: LocalMutationLogRecord) => Promise<void> | void;
+};
+/**
+ * Local sync mutation dependency metadata.
+ */
+export type LocalMutationDependency = {
+    /**
+     * - Client mutation id this mutation depends on.
+     */
+    clientMutationId: string;
+    /**
+     * - Dependent model/resource name.
+     */
+    model: string;
+};
+/**
+ * Local mutation log status.
+ */
+export type LocalMutationStatus = "pending" | "applied-locally" | "peer-applied" | "conflict" | "rejected" | "synced";
+/**
+ * Local mutation log record.
+ */
+export type LocalMutationLogRecord = {
+    /**
+     * - ISO timestamp when the record was created locally.
+     */
+    createdAt: string;
+    /**
+     * - Other local mutations that must replay first.
+     */
+    dependencies: LocalMutationDependency[];
+    /**
+     * - Local log record id.
+     */
+    id: string;
+    /**
+     * - Device mutation payload.
+     */
+    mutation: import("./device-identity.js").SyncMutation;
+    /**
+     * - Monotonic local sequence.
+     */
+    sequence: number;
+    /**
+     * - Local replay/apply status.
+     */
+    status: LocalMutationStatus;
+    /**
+     * - Backend replay/result metadata.
+     */
+    syncResult?: Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue> | undefined;
+    /**
+     * - ISO timestamp when the record was last changed.
+     */
+    updatedAt: string;
+};
+//# sourceMappingURL=local-mutation-log.d.ts.map

package/build/src/sync/local-mutation-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-mutation-log.d.ts","sourceRoot":"","sources":["../../../src/sync/local-mutation-log.js"],"names":[],"mappings":"AAUA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AAEH;;;KAGK;AAEL;;;;;;;;;;;GAWG;AAEH,mFAAmF;AACnF;IACE;;;;;;;OAOG;IACH,uDALG;QAA4B,WAAW,UAAzB,MAAM;QACM,GAAG,UAAf,IAAI;QACoB,OAAO,EAArC,uBAAuB;QACT,UAAU;KAClC,EAUA;IAJC,mBAVe,MAAM,CAUS;IAC9B,WAVe,IAAI,CAUL;IACd,iCAAsB;IACtB,mBAA4B;IAG9B;;;;;;OAMG;IACH,mCAJG;QAAyC,YAAY;QACK,QAAQ,EAA1D,OAAO,sBAAsB,EAAE,YAAY;KACnD,GAAU,OAAO,CAAC,sBAAsB,CAAC,CAmB3C;IAED;;;OAGG;IACH,WAFa,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAI7C;IAED;;;OAGG;IACH,kBAFa,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAI7C;IAED;;;;;;;OAOG;IACH,yCALG;QAAqB,EAAE,EAAf,MAAM;QACoB,MAAM,EAAhC,mBAAmB;QACmE,UAAU;KACxG,GAAU,OAAO,CAAC,sBAAsB,CAAC,CAmB3C;IAED;;;;;;OAMG;IACH,sDAJG;QAAsB,kBAAkB;QAClB,mBAAmB;KACzC,GAAU,OAAO,CAAC;QAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;KAAC,CAAC,CAkCjD;IAED;;;OAGG;IACH,oBAFa,MAAM,CAQlB;CACF;;;;;;;;;;;;;;;;;;;;;kBA/Ka,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;;;;mBAC5E,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;;;;kBAC3D,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM;;;;YAChD,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,sBAAsB,GAAG,IAAI,GAAG,SAAS;;;;aAClI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,8BAA8B,KAAK,OAAO,CAAC,sBAAsB,EAAE,CAAC,GAAG,sBAAsB,EAAE;;;;kBAC9H,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;;;;;;;;;sBAM5E,MAAM;;;;WACN,MAAM;;;;;kCAKP,SAAS,GAAG,iBAAiB,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ;;;;;;;;eAMlF,MAAM;;;;kBACN,uBAAuB,EAAE;;;;QACzB,MAAM;;;;cACN,OAAO,sBAAsB,EAAE,YAAY;;;;cAC3C,MAAM;;;;YACN,mBAAmB;;;;;;;;eAEnB,MAAM"}