@steve31415/baselib 2.0.0 → 2.2.0

package/dist/sync-browser/index.d.ts

@@ -0,0 +1,2 @@
+export * from './outbox.js';
+export * from './client.js';

package/dist/sync-browser/index.js

@@ -0,0 +1,2 @@
+export * from './outbox.js';
+export * from './client.js';

package/dist/sync-browser/outbox.d.ts

@@ -0,0 +1,47 @@
+interface OutboxRecord {
+    event: {
+        eventGuid: string;
+    };
+    summary: unknown;
+    createdAt: number;
+    ordinal?: number;
+}
+export interface IndexedDbOutboxOptions {
+    databaseName: string;
+    storeName: string;
+    version: number;
+    /** Defaults to the browser global; injectable for isolation and testing. */
+    indexedDB?: IDBFactory;
+    onDurabilityChange(durable: false, error: unknown): void;
+}
+/** A durable browser outbox with an explicit, observable memory fallback. */
+export declare class IndexedDbOutbox<T extends OutboxRecord> {
+    private readonly options;
+    private readonly memory;
+    private database;
+    private initialization;
+    private mutationTail;
+    private memoryOnly;
+    private nextMemoryOrdinal;
+    constructor(options: IndexedDbOutboxOptions);
+    init(): Promise<T[]>;
+    private initialize;
+    add(entry: T): Promise<void>;
+    private addInternal;
+    remove(eventGuid: string): Promise<void>;
+    private removeInternal;
+    get(eventGuid: string): Promise<T | undefined>;
+    all(): Promise<T[]>;
+    count(): Promise<number>;
+    private enqueueMutation;
+    private snapshot;
+    private loadAndBackfill;
+    private addWithOrdinal;
+    private nextOrdinal;
+    private highestOrdinal;
+    private withMemoryOrdinal;
+    private open;
+    private fallback;
+    private persisted;
+}
+export {};

package/dist/sync-browser/outbox.js

@@ -0,0 +1,317 @@
+function transaction(database, storeName, mode, operation) {
+    return new Promise((resolve, reject) => {
+        let request;
+        let result;
+        try {
+            const tx = database.transaction(storeName, mode);
+            request = operation(tx.objectStore(storeName));
+            request.onsuccess = () => {
+                result = request.result;
+            };
+            request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed'));
+            tx.oncomplete = () => resolve(result);
+            tx.onerror = () => reject(tx.error ?? request.error ?? new Error('IndexedDB transaction failed'));
+            tx.onabort = () => reject(tx.error ?? request.error ?? new Error('IndexedDB transaction aborted'));
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+function hasOrdinal(record) {
+    const ordinal = record.ordinal;
+    return typeof ordinal === 'number' && Number.isSafeInteger(ordinal) && ordinal > 0;
+}
+function compareGuids(left, right) {
+    if (left.event.eventGuid < right.event.eventGuid)
+        return -1;
+    if (left.event.eventGuid > right.event.eventGuid)
+        return 1;
+    return 0;
+}
+function compareLegacy(left, right) {
+    const leftCreatedAt = Number.isFinite(left.createdAt) ? left.createdAt : 0;
+    const rightCreatedAt = Number.isFinite(right.createdAt) ? right.createdAt : 0;
+    return leftCreatedAt - rightCreatedAt || compareGuids(left, right);
+}
+function compareOrdered(left, right) {
+    if (hasOrdinal(left) && hasOrdinal(right))
+        return left.ordinal - right.ordinal || compareGuids(left, right);
+    if (hasOrdinal(left))
+        return -1;
+    if (hasOrdinal(right))
+        return 1;
+    return compareLegacy(left, right);
+}
+class OutboxOrdinalCapacityError extends Error {
+    name = 'OutboxOrdinalCapacityError';
+    constructor() {
+        super('Outbox ordinal space exhausted');
+    }
+}
+/** A durable browser outbox with an explicit, observable memory fallback. */
+export class IndexedDbOutbox {
+    options;
+    memory = new Map();
+    database = null;
+    initialization = null;
+    mutationTail = Promise.resolve();
+    memoryOnly = false;
+    nextMemoryOrdinal = 1;
+    constructor(options) {
+        this.options = options;
+    }
+    init() {
+        this.initialization ??= this.initialize();
+        return this.initialization;
+    }
+    async initialize() {
+        let entries = [];
+        try {
+            this.database = await this.open();
+            entries = await this.loadAndBackfill(this.database, (recovered) => {
+                entries = recovered;
+            });
+        }
+        catch (error) {
+            this.fallback(error);
+        }
+        this.memory.clear();
+        for (const entry of entries)
+            this.memory.set(entry.event.eventGuid, entry);
+        const highest = this.highestOrdinal(entries);
+        this.nextMemoryOrdinal = highest >= Number.MAX_SAFE_INTEGER ? null : highest + 1;
+        return this.snapshot();
+    }
+    add(entry) {
+        return this.enqueueMutation(() => this.addInternal(entry));
+    }
+    async addInternal(entry) {
+        await this.init();
+        let persisted;
+        if (this.database && !this.memoryOnly) {
+            try {
+                const durable = await this.addWithOrdinal(this.database, entry);
+                persisted = durable;
+                if (durable.ordinal >= Number.MAX_SAFE_INTEGER) {
+                    this.nextMemoryOrdinal = null;
+                }
+                else if (this.nextMemoryOrdinal !== null) {
+                    this.nextMemoryOrdinal = Math.max(this.nextMemoryOrdinal, durable.ordinal + 1);
+                }
+            }
+            catch (error) {
+                if (error instanceof OutboxOrdinalCapacityError)
+                    throw error;
+                this.fallback(error);
+                persisted = this.withMemoryOrdinal(entry);
+            }
+        }
+        else {
+            persisted = this.withMemoryOrdinal(entry);
+        }
+        this.memory.set(persisted.event.eventGuid, persisted);
+    }
+    remove(eventGuid) {
+        return this.enqueueMutation(() => this.removeInternal(eventGuid));
+    }
+    async removeInternal(eventGuid) {
+        await this.init();
+        if (this.database && !this.memoryOnly) {
+            try {
+                await transaction(this.database, this.options.storeName, 'readwrite', (store) => store.delete(eventGuid));
+            }
+            catch (error) {
+                this.fallback(error);
+            }
+        }
+        this.memory.delete(eventGuid);
+    }
+    async get(eventGuid) {
+        await this.init();
+        await this.mutationTail;
+        return this.memory.get(eventGuid);
+    }
+    async all() {
+        await this.init();
+        await this.mutationTail;
+        return this.snapshot();
+    }
+    async count() {
+        await this.init();
+        await this.mutationTail;
+        return this.memory.size;
+    }
+    enqueueMutation(operation) {
+        const result = this.mutationTail.then(operation);
+        this.mutationTail = result.catch(() => undefined);
+        return result;
+    }
+    snapshot() {
+        return [...this.memory.values()].sort(compareOrdered);
+    }
+    loadAndBackfill(database, onRead) {
+        // Record-only migration: the existing keyPath store provides the readwrite lock, so no DB version bump is needed.
+        return new Promise((resolve, reject) => {
+            let entries = [];
+            let request;
+            try {
+                const tx = database.transaction(this.options.storeName, 'readwrite');
+                const store = tx.objectStore(this.options.storeName);
+                request = store.getAll();
+                request.onsuccess = () => {
+                    const records = request.result.map((entry) => this.persisted(entry));
+                    const legacy = records.filter((entry) => !hasOrdinal(entry)).sort(compareLegacy);
+                    try {
+                        if (legacy.length > 0) {
+                            const existingOrdinals = records.flatMap((entry) => (hasOrdinal(entry) ? [entry.ordinal] : []));
+                            const firstOrdinal = existingOrdinals.length > 0 ? this.nextOrdinal(records, legacy.length) : 1;
+                            legacy.forEach((entry, index) => {
+                                entry.ordinal = firstOrdinal + index;
+                                store.put(entry);
+                            });
+                        }
+                        entries = records.sort(compareOrdered);
+                        onRead(entries);
+                    }
+                    catch (error) {
+                        entries = records.sort(compareOrdered);
+                        onRead(entries);
+                        reject(error);
+                        try {
+                            tx.abort();
+                        }
+                        catch {
+                            // Preserve the allocation error if IndexedDB has already ended the transaction.
+                        }
+                    }
+                };
+                request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed'));
+                tx.oncomplete = () => resolve(entries);
+                tx.onerror = () => reject(tx.error ?? request.error ?? new Error('IndexedDB transaction failed'));
+                tx.onabort = () => reject(tx.error ?? request.error ?? new Error('IndexedDB transaction aborted'));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    addWithOrdinal(database, entry) {
+        return new Promise((resolve, reject) => {
+            let recordsRequest;
+            let putRequest;
+            let persisted;
+            try {
+                const tx = database.transaction(this.options.storeName, 'readwrite');
+                const store = tx.objectStore(this.options.storeName);
+                recordsRequest = store.getAll();
+                recordsRequest.onsuccess = () => {
+                    try {
+                        const records = recordsRequest.result.map((record) => this.persisted(record));
+                        const legacy = records.filter((record) => !hasOrdinal(record)).sort(compareLegacy);
+                        const existing = records.find((record) => record.event.eventGuid === entry.event.eventGuid);
+                        const requiredOrdinals = legacy.length + (existing === undefined ? 1 : 0);
+                        const firstOrdinal = requiredOrdinals > 0 ? this.nextOrdinal(records, requiredOrdinals) : null;
+                        const migratedOrdinals = new Map();
+                        legacy.forEach((record, index) => {
+                            if (firstOrdinal === null)
+                                throw new Error('Outbox ordinal allocation invariant failed');
+                            const ordinal = firstOrdinal + index;
+                            migratedOrdinals.set(record.event.eventGuid, ordinal);
+                            store.put(this.persisted(record, ordinal));
+                        });
+                        const migratedOrdinal = migratedOrdinals.get(entry.event.eventGuid);
+                        let ordinal;
+                        if (existing && hasOrdinal(existing)) {
+                            ordinal = existing.ordinal;
+                        }
+                        else if (migratedOrdinal !== undefined) {
+                            ordinal = migratedOrdinal;
+                        }
+                        else if (firstOrdinal !== null) {
+                            ordinal = firstOrdinal + legacy.length;
+                        }
+                        else {
+                            throw new Error('Outbox ordinal allocation invariant failed');
+                        }
+                        persisted = this.persisted(entry, ordinal);
+                        putRequest = store.put(persisted);
+                        putRequest.onerror = () => reject(putRequest.error ?? new Error('IndexedDB request failed'));
+                    }
+                    catch (error) {
+                        reject(error);
+                        try {
+                            tx.abort();
+                        }
+                        catch {
+                            // Preserve the allocation error if IndexedDB has already ended the transaction.
+                        }
+                    }
+                };
+                recordsRequest.onerror = () => reject(recordsRequest.error ?? new Error('IndexedDB request failed'));
+                tx.oncomplete = () => resolve(persisted);
+                tx.onerror = () => reject(tx.error ?? putRequest?.error ?? recordsRequest.error ?? new Error('IndexedDB transaction failed'));
+                tx.onabort = () => reject(tx.error ?? putRequest?.error ?? recordsRequest.error ?? new Error('IndexedDB transaction aborted'));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    nextOrdinal(entries, count = 1) {
+        const highest = this.highestOrdinal(entries);
+        if (count > Number.MAX_SAFE_INTEGER - highest)
+            throw new OutboxOrdinalCapacityError();
+        return highest + 1;
+    }
+    highestOrdinal(entries) {
+        return entries.reduce((maximum, entry) => (hasOrdinal(entry) ? Math.max(maximum, entry.ordinal) : maximum), 0);
+    }
+    withMemoryOrdinal(entry) {
+        const existing = this.memory.get(entry.event.eventGuid);
+        if (existing && hasOrdinal(existing))
+            return this.persisted(entry, existing.ordinal);
+        if (this.nextMemoryOrdinal === null)
+            throw new OutboxOrdinalCapacityError();
+        const ordinal = this.nextMemoryOrdinal;
+        this.nextMemoryOrdinal = ordinal >= Number.MAX_SAFE_INTEGER ? null : ordinal + 1;
+        return this.persisted(entry, ordinal);
+    }
+    open() {
+        return new Promise((resolve, reject) => {
+            try {
+                const factory = this.options.indexedDB ?? globalThis.indexedDB;
+                if (!factory)
+                    throw new Error('IndexedDB is unavailable');
+                const request = factory.open(this.options.databaseName, this.options.version);
+                request.onupgradeneeded = () => {
+                    if (!request.result.objectStoreNames.contains(this.options.storeName)) {
+                        request.result.createObjectStore(this.options.storeName, { keyPath: 'event.eventGuid' });
+                    }
+                };
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error ?? new Error('IndexedDB open failed'));
+                request.onblocked = () => reject(new Error('IndexedDB open blocked'));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    fallback(error) {
+        if (this.memoryOnly)
+            return;
+        this.memoryOnly = true;
+        this.database?.close();
+        this.database = null;
+        this.options.onDurabilityChange(false, error);
+    }
+    persisted(entry, ordinal = hasOrdinal(entry) ? entry.ordinal : undefined) {
+        return {
+            event: entry.event,
+            summary: entry.summary,
+            createdAt: entry.createdAt,
+            ...(ordinal === undefined ? {} : { ordinal }),
+        };
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@steve31415/baselib",
-  "version": "2.0.0",
-  "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, http",
+  "version": "2.2.0",
+  "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
   "repository": "github:plasticine-apps/baselib",
@@ -44,6 +44,22 @@
     "./rum": {
       "types": "./dist/rum.d.ts",
       "default": "./dist/rum.js"
+    },
+    "./sync": {
+      "types": "./dist/sync/index.d.ts",
+      "default": "./dist/sync/index.js"
+    },
+    "./sync-browser": {
+      "types": "./dist/sync-browser/index.d.ts",
+      "default": "./dist/sync-browser/index.js"
+    },
+    "./app-update": {
+      "types": "./dist/app-update/index.d.ts",
+      "default": "./dist/app-update/index.js"
+    },
+    "./app-update-browser": {
+      "types": "./dist/app-update-browser/index.d.ts",
+      "default": "./dist/app-update-browser/index.js"
     }
   },
   "bin": {
@@ -71,7 +87,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/pg": "^8.11.0",
-    "happy-dom": "^18.0.0",
+    "fake-indexeddb": "^6.2.5",
+    "happy-dom": "^20.11.2",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"