@peers-app/peers-sdk 0.21.3 → 0.21.5

package/dist/data/index.d.ts

@@ -18,6 +18,7 @@ export * from "./packages";
 export * from "./packages.utils";
 export * from "./peer-types";
 export * from "./persistent-vars";
+export * from "./sync-recovery-queue";
 export * from "./table-definitions-table";
 export * from "./tool-tests";
 export * from "./tools";

package/dist/data/index.js

@@ -34,6 +34,7 @@ __exportStar(require("./packages"), exports);
 __exportStar(require("./packages.utils"), exports);
 __exportStar(require("./peer-types"), exports);
 __exportStar(require("./persistent-vars"), exports);
+__exportStar(require("./sync-recovery-queue"), exports);
 __exportStar(require("./table-definitions-table"), exports);
 __exportStar(require("./tool-tests"), exports);
 __exportStar(require("./tools"), exports);

package/dist/data/sync-recovery-queue.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Local-only queue of synchronized records that failed to materialize into their
+ * target table. One entry per (tableName, recordId); change history is retained
+ * separately in ChangeTrackingV2.
+ */
+import { z } from "zod";
+import { type ISqlDb, type ITableMetaData, SQLDataSource } from "./orm";
+/** One recorded materialization failure for a synchronized record. */
+export declare const syncRecoveryFailureSchema: z.ZodObject<{
+    error: z.ZodString;
+    erroredAt: z.ZodNumber;
+    sourceDeviceId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+    erroredAt: number;
+    sourceDeviceId?: string | undefined;
+}, {
+    error: string;
+    erroredAt: number;
+    sourceDeviceId?: string | undefined;
+}>;
+/** Durable local recovery state for one synchronized record. */
+export declare const syncRecoveryEntrySchema: z.ZodObject<{
+    syncRecoveryId: z.ZodEffects<z.ZodString, string, string>;
+    tableName: z.ZodString;
+    recordId: z.ZodString;
+    firstFailedAt: z.ZodNumber;
+    lastFailedAt: z.ZodNumber;
+    attemptCount: z.ZodNumber;
+    failures: z.ZodArray<z.ZodObject<{
+        error: z.ZodString;
+        erroredAt: z.ZodNumber;
+        sourceDeviceId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        error: string;
+        erroredAt: number;
+        sourceDeviceId?: string | undefined;
+    }, {
+        error: string;
+        erroredAt: number;
+        sourceDeviceId?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    tableName: string;
+    recordId: string;
+    syncRecoveryId: string;
+    firstFailedAt: number;
+    lastFailedAt: number;
+    attemptCount: number;
+    failures: {
+        error: string;
+        erroredAt: number;
+        sourceDeviceId?: string | undefined;
+    }[];
+}, {
+    tableName: string;
+    recordId: string;
+    syncRecoveryId: string;
+    firstFailedAt: number;
+    lastFailedAt: number;
+    attemptCount: number;
+    failures: {
+        error: string;
+        erroredAt: number;
+        sourceDeviceId?: string | undefined;
+    }[];
+}>;
+/** One recorded materialization failure for a synchronized record. */
+export type ISyncRecoveryFailure = z.infer<typeof syncRecoveryFailureSchema>;
+/** Durable local recovery state for one synchronized record. */
+export type ISyncRecoveryEntry = z.infer<typeof syncRecoveryEntrySchema>;
+/** Input used to append a materialization failure to the recovery queue. */
+export interface IRecordSyncFailure {
+    tableName: string;
+    recordId: string;
+    error: unknown;
+    sourceDeviceId?: string;
+}
+/** Metadata for the local-only SyncRecoveryQueue table. */
+export declare const syncRecoveryQueueMetaData: ITableMetaData;
+/**
+ * SQL-backed SyncRecoveryQueue table for a single database (personal or group).
+ *
+ * Constructed with a db handle like ChangeTrackingTable; not accessed via TableContainer.
+ * Prefer {@link syncRecoveryQueueTable} so callers share one instance per database.
+ */
+export declare class SyncRecoveryQueueTable extends SQLDataSource<ISyncRecoveryEntry> {
+    constructor({ db }: {
+        db: ISqlDb;
+    });
+    /**
+     * Append a failure for a table/record, creating or updating the durable queue entry.
+     */
+    recordFailure(input: IRecordSyncFailure): Promise<void>;
+    /**
+     * Append a failure inside the caller's active transaction.
+     *
+     * The queue table must be initialized before this method is called.
+     */
+    recordFailureSync(input: IRecordSyncFailure): void;
+    /** Remove a successfully recovered record from the queue. */
+    clearRecord(tableName: string, recordId: string): Promise<void>;
+    /**
+     * Remove a successfully recovered record inside the caller's active transaction.
+     *
+     * The queue table must be initialized before this method is called.
+     */
+    clearRecordSync(tableName: string, recordId: string): void;
+    private mergeFailure;
+}
+/** Return the single SyncRecoveryQueue table associated with a database instance. */
+export declare function syncRecoveryQueueTable(db: ISqlDb): SyncRecoveryQueueTable;

package/dist/data/sync-recovery-queue.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Local-only queue of synchronized records that failed to materialize into their
+ * target table. One entry per (tableName, recordId); change history is retained
+ * separately in ChangeTrackingV2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncRecoveryQueueTable = exports.syncRecoveryQueueMetaData = exports.syncRecoveryEntrySchema = exports.syncRecoveryFailureSchema = void 0;
+exports.syncRecoveryQueueTable = syncRecoveryQueueTable;
+const zod_1 = require("zod");
+const zod_types_1 = require("../types/zod-types");
+const utils_1 = require("../utils");
+const orm_1 = require("./orm");
+const MAX_FAILURE_HISTORY = 10;
+const MAX_ERROR_LENGTH = 1_000;
+/** One recorded materialization failure for a synchronized record. */
+exports.syncRecoveryFailureSchema = zod_1.z.object({
+    error: zod_1.z.string(),
+    erroredAt: zod_1.z.number(),
+    sourceDeviceId: zod_1.z.string().optional(),
+});
+/** Durable local recovery state for one synchronized record. */
+exports.syncRecoveryEntrySchema = zod_1.z.object({
+    syncRecoveryId: zod_types_1.zodPeerId,
+    tableName: zod_1.z.string(),
+    recordId: zod_1.z.string(),
+    firstFailedAt: zod_1.z.number(),
+    lastFailedAt: zod_1.z.number(),
+    attemptCount: zod_1.z.number(),
+    failures: zod_1.z.array(exports.syncRecoveryFailureSchema),
+});
+/** Metadata for the local-only SyncRecoveryQueue table. */
+exports.syncRecoveryQueueMetaData = {
+    name: "SyncRecoveryQueue",
+    description: "Local queue of synchronized records that failed to materialize",
+    primaryKeyName: "syncRecoveryId",
+    fields: (0, orm_1.schemaToFields)(exports.syncRecoveryEntrySchema),
+    indexes: [{ fields: ["tableName", "recordId"], unique: true }],
+    localOnly: true,
+};
+function normalizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.slice(0, MAX_ERROR_LENGTH);
+}
+/**
+ * SQL-backed SyncRecoveryQueue table for a single database (personal or group).
+ *
+ * Constructed with a db handle like ChangeTrackingTable; not accessed via TableContainer.
+ * Prefer {@link syncRecoveryQueueTable} so callers share one instance per database.
+ */
+class SyncRecoveryQueueTable extends orm_1.SQLDataSource {
+    constructor({ db }) {
+        super(db, exports.syncRecoveryQueueMetaData, exports.syncRecoveryEntrySchema);
+    }
+    /**
+     * Append a failure for a table/record, creating or updating the durable queue entry.
+     */
+    async recordFailure(input) {
+        await this.initTable();
+        if (this.db.runInTransaction && this.db.getSync && this.db.execSync) {
+            this.db.runInTransaction(() => this.recordFailureSync(input));
+            return;
+        }
+        const existing = await this.findOne({
+            tableName: input.tableName,
+            recordId: input.recordId,
+        });
+        const entry = this.mergeFailure(existing, input);
+        if (existing) {
+            await this.update(entry);
+        }
+        else {
+            await this.insert(entry);
+        }
+    }
+    /**
+     * Append a failure inside the caller's active transaction.
+     *
+     * The queue table must be initialized before this method is called.
+     */
+    recordFailureSync(input) {
+        if (!this.db.getSync || !this.db.execSync) {
+            throw new Error("Synchronous database operations are required for recovery queue updates");
+        }
+        const sqlRecord = this.db.getSync(`SELECT * FROM "${this.tableName}" WHERE tableName = ? AND recordId = ?`, [input.tableName, input.recordId]);
+        const existing = sqlRecord ? this.sqlRecordToJsRecord(sqlRecord) : undefined;
+        const entry = this.mergeFailure(existing, input);
+        if (existing) {
+            this.updateSync(entry);
+        }
+        else {
+            this.insertSync(entry);
+        }
+    }
+    /** Remove a successfully recovered record from the queue. */
+    async clearRecord(tableName, recordId) {
+        await this.initTable();
+        await this.db.exec(`DELETE FROM "${this.tableName}" WHERE tableName = ? AND recordId = ?`, [
+            tableName,
+            recordId,
+        ]);
+    }
+    /**
+     * Remove a successfully recovered record inside the caller's active transaction.
+     *
+     * The queue table must be initialized before this method is called.
+     */
+    clearRecordSync(tableName, recordId) {
+        if (!this.db.execSync) {
+            throw new Error("Synchronous database operations are required for recovery queue updates");
+        }
+        this.db.execSync(`DELETE FROM "${this.tableName}" WHERE tableName = ? AND recordId = ?`, [
+            tableName,
+            recordId,
+        ]);
+    }
+    mergeFailure(existing, input) {
+        const erroredAt = (0, utils_1.getTimestamp)();
+        const failure = {
+            error: normalizeError(input.error),
+            erroredAt,
+            sourceDeviceId: input.sourceDeviceId,
+        };
+        return {
+            syncRecoveryId: existing?.syncRecoveryId ?? (0, utils_1.newid)(),
+            tableName: input.tableName,
+            recordId: input.recordId,
+            firstFailedAt: existing?.firstFailedAt ?? erroredAt,
+            lastFailedAt: erroredAt,
+            attemptCount: (existing?.attemptCount ?? 0) + 1,
+            failures: [...(existing?.failures ?? []), failure].slice(-MAX_FAILURE_HISTORY),
+        };
+    }
+}
+exports.SyncRecoveryQueueTable = SyncRecoveryQueueTable;
+const recoveryQueuesByDb = new WeakMap();
+/** Return the single SyncRecoveryQueue table associated with a database instance. */
+function syncRecoveryQueueTable(db) {
+    let table = recoveryQueuesByDb.get(db);
+    if (!table) {
+        table = new SyncRecoveryQueueTable({ db });
+        recoveryQueuesByDb.set(db, table);
+    }
+    return table;
+}

package/dist/data/sync-recovery-queue.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/data/sync-recovery-queue.test.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const sync_recovery_queue_1 = require("./sync-recovery-queue");
+const SQLiteDB = require("better-sqlite3");
+class DBHarness {
+    sqlite = new SQLiteDB(":memory:");
+    async get(sql, params = []) {
+        return this.sqlite.prepare(sql).get(params);
+    }
+    async all(sql, params = []) {
+        return this.sqlite.prepare(sql).all(params);
+    }
+    async exec(sql, params = []) {
+        const result = this.sqlite.prepare(sql).run(params);
+        return { changes: result.changes };
+    }
+    getSync(sql, params = []) {
+        return this.sqlite.prepare(sql).get(params);
+    }
+    allSync(sql, params = []) {
+        return this.sqlite.prepare(sql).all(params);
+    }
+    execSync(sql, params = []) {
+        this.sqlite.prepare(sql).run(params);
+    }
+    runInTransaction(fn) {
+        return this.sqlite.transaction(fn)();
+    }
+    async close() {
+        this.sqlite.close();
+    }
+}
+describe("SyncRecoveryQueueTable", () => {
+    let db;
+    let queue;
+    beforeEach(() => {
+        db = new DBHarness();
+        queue = (0, sync_recovery_queue_1.syncRecoveryQueueTable)(db);
+    });
+    afterEach(async () => {
+        await db.close();
+    });
+    it("returns one queue instance per database", async () => {
+        const otherDb = new DBHarness();
+        try {
+            expect((0, sync_recovery_queue_1.syncRecoveryQueueTable)(db)).toBe(queue);
+            expect((0, sync_recovery_queue_1.syncRecoveryQueueTable)(otherDb)).toBe((0, sync_recovery_queue_1.syncRecoveryQueueTable)(otherDb));
+            expect((0, sync_recovery_queue_1.syncRecoveryQueueTable)(otherDb)).not.toBe(queue);
+        }
+        finally {
+            await otherDb.close();
+        }
+    });
+    it("upserts failures for a record while preserving its queue identity", async () => {
+        await queue.recordFailure({
+            tableName: "Notes",
+            recordId: "note-1",
+            error: new Error("first failure"),
+            sourceDeviceId: "device-1",
+        });
+        const first = await queue.findOne({ tableName: "Notes", recordId: "note-1" });
+        await queue.recordFailure({
+            tableName: "Notes",
+            recordId: "note-1",
+            error: "second failure",
+            sourceDeviceId: "device-2",
+        });
+        const updated = await queue.findOne({ tableName: "Notes", recordId: "note-1" });
+        expect(first).toBeDefined();
+        expect(updated).toMatchObject({
+            syncRecoveryId: first?.syncRecoveryId,
+            tableName: "Notes",
+            recordId: "note-1",
+            firstFailedAt: first?.firstFailedAt,
+            attemptCount: 2,
+            failures: [
+                expect.objectContaining({ error: "first failure", sourceDeviceId: "device-1" }),
+                expect.objectContaining({ error: "second failure", sourceDeviceId: "device-2" }),
+            ],
+        });
+        if (!updated)
+            throw new Error("Expected an updated recovery entry");
+        expect(updated.lastFailedAt).toBeGreaterThanOrEqual(updated.firstFailedAt);
+        await expect(queue.count()).resolves.toBe(1);
+    });
+    it("bounds failure history and stored error length", async () => {
+        for (let attempt = 1; attempt <= 12; attempt++) {
+            await queue.recordFailure({
+                tableName: "Notes",
+                recordId: "note-1",
+                error: attempt === 12 ? "x".repeat(2_000) : `failure-${attempt}`,
+            });
+        }
+        const entry = await queue.findOne({ tableName: "Notes", recordId: "note-1" });
+        expect(entry?.attemptCount).toBe(12);
+        expect(entry?.failures).toHaveLength(10);
+        expect(entry?.failures[0].error).toBe("failure-3");
+        expect(entry?.failures.at(-1)?.error).toHaveLength(1_000);
+    });
+    it("supports asynchronous databases without transaction methods", async () => {
+        const asyncOnlyDb = {
+            get: db.get.bind(db),
+            all: db.all.bind(db),
+            exec: db.exec.bind(db),
+            close: async () => { },
+        };
+        const asyncQueue = new sync_recovery_queue_1.SyncRecoveryQueueTable({ db: asyncOnlyDb });
+        await asyncQueue.recordFailure({
+            tableName: "Notes",
+            recordId: "note-1",
+            error: new Error("first"),
+        });
+        await asyncQueue.recordFailure({
+            tableName: "Notes",
+            recordId: "note-1",
+            error: new Error("second"),
+        });
+        expect(await asyncQueue.findOne({ tableName: "Notes", recordId: "note-1" })).toMatchObject({
+            attemptCount: 2,
+        });
+        await asyncQueue.clearRecord("Notes", "note-1");
+        await expect(asyncQueue.count()).resolves.toBe(0);
+    });
+    it("rolls back synchronous queue clearing with its surrounding transaction", async () => {
+        await queue.recordFailure({
+            tableName: "Notes",
+            recordId: "note-1",
+            error: new Error("materialization failed"),
+        });
+        expect(() => db.runInTransaction(() => {
+            queue.clearRecordSync("Notes", "note-1");
+            throw new Error("rollback");
+        })).toThrow("rollback");
+        await expect(queue.count()).resolves.toBe(1);
+        db.runInTransaction(() => queue.clearRecordSync("Notes", "note-1"));
+        await expect(queue.count()).resolves.toBe(0);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.21.3",
+  "version": "0.21.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"