@bayonai/offline 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+- Added the initial workspace package with generic read-cache and pending-write
+  primitives backed by `idb`.
+- Replaced app-specific test fixtures with neutral package examples.
+- Added package-local license, metadata, publish configuration, and deployment
+  documentation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bayon AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @bayonai/offline
+
+Reusable offline read-cache and pending-write primitives.
+
+This package owns generic browser and memory storage behavior. Host apps own
+their domain records, remote APIs, cache prefixes, database names, and sync
+functions.
+
+The package uses `idb` internally for IndexedDB access, but consumers should use
+the exported cache and pending-write APIs rather than depending on the storage
+implementation.
+
+## Install
+
+```bash
+pnpm add @bayonai/offline
+```
+
+## Read Cache
+
+```ts
+import {
+  createBrowserReadCache,
+  createReadCacheKey,
+  loadReadCacheResource,
+} from "@bayonai/offline";
+
+const cache = createBrowserReadCache({
+  databaseName: "my-app:v1",
+  storeName: "read-cache",
+});
+
+const key = createReadCacheKey({
+  namespace: "projects",
+  params: { limit: 20 },
+  prefix: "my-app:v1",
+  scope: "user-1",
+});
+
+const projects = await loadReadCacheResource({
+  cache,
+  key,
+  loadFresh: () => fetchProjects(),
+  maxAgeMs: 30_000,
+  onUpdate: ({ data, fromCache }) => {
+    renderProjects(data, { fromCache });
+  },
+});
+```
+
+## Pending Writes
+
+```ts
+import {
+  createBrowserPendingWriteStore,
+  syncPendingWrite,
+} from "@bayonai/offline";
+
+type Draft = {
+  body: string;
+  title: string;
+};
+
+const store = createBrowserPendingWriteStore<Draft>({
+  databaseName: "my-app:pending-writes:v1",
+  keyPrefix: "my-app:v1:pending-draft",
+  storeName: "pending-writes",
+});
+
+await store.set({
+  id: "draft-1",
+  payload: { body: "Local text", title: "Local draft" },
+  savedAt: new Date().toISOString(),
+  syncStatus: "pending",
+});
+
+await syncPendingWrite({
+  id: "draft-1",
+  store,
+  sync: (draft) => saveDraftRemotely(draft),
+});
+```
+
+Host apps that change their pending-write payload shape can normalize current
+records while keeping domain logic outside the package:
+
+```ts
+const store = createBrowserPendingWriteStore<Draft>({
+  databaseName: "my-app:pending-writes:v1",
+  keyPrefix: "my-app:v1:pending-draft",
+  storeName: "pending-writes",
+  normalizePayload(value) {
+    return isDraft(value) ? normalizeDraft(value) : null;
+  },
+});
+```
+
+## Boundary
+
+`@bayonai/offline` has no Firebase, Firestore, Next.js, React, or application
+domain dependencies. Host apps provide remote loaders and sync functions.
+
+Host apps are also responsible for:
+
+- Choosing database names, store names, and key prefixes.
+- Scoping storage by user, tenant, workspace, or other app identity.
+- Validating and migrating app-specific payloads.
+- Deciding when to clear browser storage, such as on sign-out.
+- Providing remote read and write functions.
+
+## Package Scripts
+
+```bash
+pnpm --filter @bayonai/offline test
+pnpm --filter @bayonai/offline run build
+pnpm --filter @bayonai/offline pack --dry-run
+```
+
+## Publish Checklist
+
+1. Run the package tests and build.
+2. Run `pnpm --filter @bayonai/offline pack --dry-run` and confirm the tarball
+   includes only `package.json`, `dist`, `dist-cjs`, `README.md`,
+   `CHANGELOG.md`, and `LICENSE`.
+3. Confirm `package.json` metadata, version, repository, license, and
+   `publishConfig.access` are correct.
+4. Publish from the package directory or with the package filter after the
+   workspace lockfile is current.

package/dist/idbDriver.d.ts

@@ -0,0 +1,16 @@
+export type BrowserKeyValueDriver = {
+    clear: () => Promise<void>;
+    close: () => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    get: (key: string) => Promise<unknown | null>;
+    list: () => Promise<unknown[]>;
+    set: (key: string, value: unknown) => Promise<void>;
+};
+export type BrowserKeyValueDriverOptions = {
+    databaseName: string;
+    databaseVersion?: number;
+    indexedDB?: IDBFactory;
+    operationTimeoutMs: number;
+    storeName: string;
+};
+export declare function createIdbKeyValueDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserKeyValueDriverOptions): BrowserKeyValueDriver | null;

package/dist/idbDriver.js

@@ -0,0 +1,107 @@
+import { wrap } from "idb";
+export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
+    if (!indexedDB) {
+        return null;
+    }
+    const databasePromise = openKeyValueDatabase({
+        databaseName,
+        databaseVersion,
+        indexedDB,
+        storeName,
+    });
+    return {
+        async clear() {
+            await runBrowserStorageOperation({
+                fallback: undefined,
+                operation: async () => {
+                    const database = await databasePromise;
+                    await database.clear(storeName);
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async close() {
+            await runBrowserStorageOperation({
+                fallback: undefined,
+                operation: async () => {
+                    const database = await databasePromise;
+                    database.close();
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async delete(key) {
+            await runBrowserStorageOperation({
+                fallback: undefined,
+                operation: async () => {
+                    const database = await databasePromise;
+                    await database.delete(storeName, key);
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async get(key) {
+            return runBrowserStorageOperation({
+                fallback: null,
+                operation: async () => {
+                    const database = await databasePromise;
+                    return (await database.get(storeName, key)) ?? null;
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async list() {
+            return runBrowserStorageOperation({
+                fallback: [],
+                operation: async () => {
+                    const database = await databasePromise;
+                    return database.getAll(storeName);
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async set(key, value) {
+            await runBrowserStorageOperation({
+                fallback: undefined,
+                operation: async () => {
+                    const database = await databasePromise;
+                    await database.put(storeName, value, key);
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+    };
+}
+async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB, storeName, }) {
+    const request = indexedDB.open(databaseName, databaseVersion);
+    request.onupgradeneeded = () => {
+        const database = request.result;
+        if (!database.objectStoreNames.contains(storeName)) {
+            database.createObjectStore(storeName);
+        }
+    };
+    const database = await wrap(request);
+    if (!database) {
+        throw new Error(`Could not open IndexedDB database ${databaseName}.`);
+    }
+    return database;
+}
+async function runBrowserStorageOperation({ fallback, operation, timeoutMs, }) {
+    let timeoutId = null;
+    try {
+        return await Promise.race([
+            operation(),
+            new Promise((resolve) => {
+                timeoutId = setTimeout(() => resolve(fallback), timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        return fallback;
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./readCache";
+export * from "./pendingWrites";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./readCache.js";
+export * from "./pendingWrites.js";

package/dist/pendingWrites.d.ts

@@ -0,0 +1,63 @@
+import { type BrowserKeyValueDriverOptions } from "./idbDriver";
+export declare const pendingWriteSchemaVersion = 1;
+export declare const pendingWriteOperationTimeoutMs = 2000;
+export type PendingWriteStatus = "pending" | "syncing" | "failed";
+export type PendingWriteRecord<Payload = unknown> = {
+    error?: string;
+    id: string;
+    payload: Payload;
+    savedAt: string;
+    syncStatus: PendingWriteStatus;
+};
+export type PendingWritePayloadNormalizer<Payload = unknown> = (payload: unknown) => Payload | null;
+export type PendingWriteDriver = {
+    clear: (key: string) => Promise<void>;
+    clearAll: () => Promise<void>;
+    close?: () => Promise<void>;
+    get: (key: string) => Promise<unknown | null>;
+    list: () => Promise<unknown[]>;
+    set: (key: string, value: unknown) => Promise<void>;
+};
+export type PendingWriteStore<Payload = unknown> = {
+    clear: (id: string) => Promise<void>;
+    clearAll: () => Promise<void>;
+    clearIfSavedAt: (id: string, savedAt: string) => Promise<boolean>;
+    close: () => Promise<void>;
+    get: (id: string) => Promise<PendingWriteRecord<Payload> | null>;
+    list: () => Promise<Array<PendingWriteRecord<Payload>>>;
+    set: (record: PendingWriteRecord<Payload>) => Promise<void>;
+};
+export type PendingWriteStoreOptions<Payload = unknown> = {
+    keyPrefix: string;
+    normalizePayload?: PendingWritePayloadNormalizer<Payload>;
+    schemaVersion?: number;
+};
+export type BrowserPendingWriteStoreOptions<Payload = unknown> = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & PendingWriteStoreOptions<Payload> & {
+    databaseName: string;
+    operationTimeoutMs?: number;
+    storeName: string;
+};
+export type PendingWriteKeyOptions = {
+    id: string;
+    prefix: string;
+};
+export type SyncPendingWriteResult = {
+    status: "idle";
+} | {
+    status: "synced";
+} | {
+    status: "superseded";
+} | {
+    error: string;
+    status: "failed";
+};
+export declare function createPendingWriteStore<Payload = unknown>(driver: PendingWriteDriver, { keyPrefix, normalizePayload, schemaVersion, }: PendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+export declare function createMemoryPendingWriteDriver(): PendingWriteDriver;
+export declare function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: Omit<BrowserPendingWriteStoreOptions, "keyPrefix" | "normalizePayload" | "schemaVersion">): PendingWriteDriver | null;
+export declare function createBrowserPendingWriteStore<Payload = unknown>({ databaseName, databaseVersion, indexedDB, keyPrefix, normalizePayload, operationTimeoutMs, schemaVersion, storeName, }: BrowserPendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+export declare function createPendingWriteKey({ id, prefix }: PendingWriteKeyOptions): string;
+export declare function syncPendingWrite<Payload>({ id, store, sync, }: {
+    id: string;
+    store: PendingWriteStore<Payload>;
+    sync: (payload: Payload) => Promise<unknown>;
+}): Promise<SyncPendingWriteResult>;

package/dist/pendingWrites.js

@@ -0,0 +1,186 @@
+import { createIdbKeyValueDriver, } from "./idbDriver.js";
+export const pendingWriteSchemaVersion = 1;
+export const pendingWriteOperationTimeoutMs = 2_000;
+export function createPendingWriteStore(driver, { keyPrefix, normalizePayload, schemaVersion = pendingWriteSchemaVersion, }) {
+    return {
+        async clear(id) {
+            await driver.clear(createPendingWriteKey({ id, prefix: keyPrefix }));
+        },
+        async clearAll() {
+            await driver.clearAll();
+        },
+        async clearIfSavedAt(id, savedAt) {
+            const current = await this.get(id);
+            if (!current || current.savedAt !== savedAt) {
+                return false;
+            }
+            await this.clear(id);
+            return true;
+        },
+        async close() {
+            await driver.close?.();
+        },
+        async get(id) {
+            return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizePayload })?.record ?? null);
+        },
+        async list() {
+            return (await driver.list())
+                .map((value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizePayload,
+            })?.record)
+                .filter((record) => Boolean(record))
+                .sort((left, right) => left.savedAt.localeCompare(right.savedAt));
+        },
+        async set(record) {
+            await driver.set(createPendingWriteKey({ id: record.id, prefix: keyPrefix }), {
+                record,
+                schemaVersion,
+            });
+        },
+    };
+}
+export function createMemoryPendingWriteDriver() {
+    const records = new Map();
+    return {
+        async clear(key) {
+            records.delete(key);
+        },
+        async clearAll() {
+            records.clear();
+        },
+        async close() { },
+        async get(key) {
+            return records.get(key) ?? null;
+        },
+        async list() {
+            return [...records.values()];
+        },
+        async set(key, value) {
+            records.set(key, value);
+        },
+    };
+}
+export function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = pendingWriteOperationTimeoutMs, storeName, }) {
+    const driver = createIdbKeyValueDriver({
+        databaseName,
+        databaseVersion,
+        indexedDB,
+        operationTimeoutMs,
+        storeName,
+    });
+    return driver ? toPendingWriteDriver(driver) : null;
+}
+export function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, keyPrefix, normalizePayload, operationTimeoutMs = pendingWriteOperationTimeoutMs, schemaVersion = pendingWriteSchemaVersion, storeName, }) {
+    const driver = createBrowserPendingWriteDriver({
+        databaseName,
+        databaseVersion,
+        indexedDB,
+        operationTimeoutMs,
+        storeName,
+    });
+    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizePayload, schemaVersion });
+}
+export function createPendingWriteKey({ id, prefix }) {
+    return `${prefix}:${encodeURIComponent(id)}`;
+}
+export async function syncPendingWrite({ id, store, sync, }) {
+    const pending = await store.get(id);
+    if (!pending) {
+        return { status: "idle" };
+    }
+    await markPendingSnapshot({
+        id,
+        nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
+        savedAt: pending.savedAt,
+        store,
+    });
+    try {
+        await sync(pending.payload);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unable to sync pending write.";
+        await markPendingSnapshot({
+            id,
+            nextRecord: { ...pending, error: message, syncStatus: "failed" },
+            savedAt: pending.savedAt,
+            store,
+        });
+        return { error: message, status: "failed" };
+    }
+    return (await store.clearIfSavedAt(id, pending.savedAt))
+        ? { status: "synced" }
+        : { status: "superseded" };
+}
+function createNoopPendingWriteDriver() {
+    return {
+        async clear() { },
+        async clearAll() { },
+        async close() { },
+        async get() {
+            return null;
+        },
+        async list() {
+            return [];
+        },
+        async set() { },
+    };
+}
+function toPendingWriteDriver(driver) {
+    return {
+        clear: driver.delete,
+        clearAll: driver.clear,
+        close: driver.close,
+        get: driver.get,
+        list: driver.list,
+        set: driver.set,
+    };
+}
+async function markPendingSnapshot({ id, nextRecord, savedAt, store, }) {
+    const current = await store.get(id);
+    if (current?.savedAt !== savedAt) {
+        return false;
+    }
+    await store.set(nextRecord);
+    return true;
+}
+function toPendingWriteEnvelope(value, schemaVersion, { normalizePayload }) {
+    if (!value ||
+        typeof value !== "object" ||
+        !("schemaVersion" in value) ||
+        value.schemaVersion !== schemaVersion ||
+        !("record" in value) ||
+        !isPendingWriteRecord(value.record)) {
+        return null;
+    }
+    const record = normalizePendingWriteRecord(value.record, normalizePayload);
+    return record ? { record, schemaVersion } : null;
+}
+function normalizePendingWriteRecord(record, normalizePayload) {
+    if (!normalizePayload) {
+        return record;
+    }
+    const payload = normalizePayload(record.payload);
+    if (payload === null) {
+        return null;
+    }
+    return {
+        ...(typeof record.error === "string" ? { error: record.error } : {}),
+        id: record.id,
+        payload,
+        savedAt: record.savedAt,
+        syncStatus: record.syncStatus,
+    };
+}
+function isPendingWriteRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        "id" in value &&
+        typeof value.id === "string" &&
+        "savedAt" in value &&
+        typeof value.savedAt === "string" &&
+        "syncStatus" in value &&
+        (value.syncStatus === "pending" ||
+            value.syncStatus === "syncing" ||
+            value.syncStatus === "failed") &&
+        "payload" in value);
+}

package/dist/readCache.d.ts

@@ -0,0 +1,59 @@
+import { type BrowserKeyValueDriverOptions } from "./idbDriver";
+export declare const readCacheSchemaVersion = 1;
+export declare const readCacheFreshnessMaxAgeMs = 30000;
+export declare const browserReadCacheOperationTimeoutMs = 2000;
+export type ReadCacheHit<T> = {
+    fromCache: true;
+    savedAt: string;
+    value: T;
+};
+export type ReadCacheDriver = {
+    clear: () => Promise<void>;
+    close?: () => Promise<void>;
+    get: (key: string) => Promise<unknown | null>;
+    set: (key: string, value: unknown) => Promise<void>;
+};
+export type ReadCache = {
+    clear: () => Promise<void>;
+    close: () => Promise<void>;
+    get: <T>(key: string) => Promise<ReadCacheHit<T> | null>;
+    set: <T>(key: string, value: T) => Promise<void>;
+};
+export type ReadThroughCacheResult<T> = {
+    data: T;
+    error: Error | null;
+    fromCache: boolean;
+    stale: boolean;
+};
+export type ReadCacheResourceUpdate<T> = {
+    data: T;
+    error?: Error;
+    fromCache: boolean;
+};
+export type BrowserReadCacheOptions = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & {
+    databaseName: string;
+    operationTimeoutMs?: number;
+    storeName: string;
+};
+export type ReadCacheKeyOptions = {
+    namespace: string;
+    params?: Record<string, string | number | boolean | null | undefined>;
+    prefix: string;
+    scope: string;
+};
+export declare function createReadCache(driver: ReadCacheDriver): ReadCache;
+export declare function createMemoryReadCacheDriver(): ReadCacheDriver;
+export declare function createBrowserReadCache({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserReadCacheOptions): ReadCache;
+export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
+export declare function readThroughCache<T>({ cache, key, loadFresh, }: {
+    cache: ReadCache;
+    key: string;
+    loadFresh: () => Promise<T>;
+}): Promise<ReadThroughCacheResult<T>>;
+export declare function loadReadCacheResource<T>({ cache, key, loadFresh, maxAgeMs, onUpdate, }: {
+    cache: ReadCache;
+    key: string;
+    loadFresh: () => Promise<T>;
+    maxAgeMs?: number;
+    onUpdate: (update: ReadCacheResourceUpdate<T>) => void;
+}): Promise<T>;

package/dist/readCache.js

@@ -0,0 +1,171 @@
+import { createIdbKeyValueDriver, } from "./idbDriver.js";
+export const readCacheSchemaVersion = 1;
+export const readCacheFreshnessMaxAgeMs = 30_000;
+export const browserReadCacheOperationTimeoutMs = 2_000;
+const pendingFreshLoads = new Map();
+export function createReadCache(driver) {
+    return {
+        async clear() {
+            pendingFreshLoads.clear();
+            await driver.clear();
+        },
+        async close() {
+            await driver.close?.();
+        },
+        async get(key) {
+            const envelope = toReadCacheEnvelope(await driver.get(key));
+            return envelope
+                ? {
+                    fromCache: true,
+                    savedAt: envelope.savedAt,
+                    value: envelope.value,
+                }
+                : null;
+        },
+        async set(key, value) {
+            await driver.set(key, {
+                savedAt: new Date().toISOString(),
+                schemaVersion: readCacheSchemaVersion,
+                value,
+            });
+        },
+    };
+}
+export function createMemoryReadCacheDriver() {
+    const records = new Map();
+    return {
+        async clear() {
+            records.clear();
+        },
+        async close() { },
+        async get(key) {
+            return records.get(key) ?? null;
+        },
+        async set(key, value) {
+            records.set(key, value);
+        },
+    };
+}
+export function createBrowserReadCache({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = browserReadCacheOperationTimeoutMs, storeName, }) {
+    const driver = createIdbKeyValueDriver({
+        databaseName,
+        databaseVersion,
+        indexedDB,
+        operationTimeoutMs,
+        storeName,
+    });
+    return createReadCache(driver ?? createNoopReadCacheDriver());
+}
+export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
+    const serializedParams = Object.entries(params)
+        .filter(([, value]) => value !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join("&");
+    return [
+        prefix,
+        encodeURIComponent(namespace),
+        encodeURIComponent(scope),
+        serializedParams,
+    ]
+        .filter(Boolean)
+        .join(":");
+}
+export async function readThroughCache({ cache, key, loadFresh, }) {
+    const cached = await cache.get(key);
+    try {
+        const fresh = await loadFresh();
+        await cache.set(key, fresh);
+        return {
+            data: fresh,
+            error: null,
+            fromCache: false,
+            stale: false,
+        };
+    }
+    catch (error) {
+        if (cached) {
+            return {
+                data: cached.value,
+                error: normalizeError(error),
+                fromCache: true,
+                stale: true,
+            };
+        }
+        throw error;
+    }
+}
+export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onUpdate, }) {
+    const cached = await cache.get(key);
+    if (cached) {
+        onUpdate({ data: cached.value, fromCache: true });
+        if (isCacheFresh(cached.savedAt, maxAgeMs)) {
+            return cached.value;
+        }
+    }
+    try {
+        const fresh = await loadSharedFreshResource(key, loadFresh);
+        onUpdate({ data: fresh, fromCache: false });
+        void cache.set(key, fresh).catch(() => undefined);
+        return fresh;
+    }
+    catch (error) {
+        if (!cached) {
+            throw error;
+        }
+        onUpdate({
+            data: cached.value,
+            error: normalizeError(error),
+            fromCache: true,
+        });
+        return cached.value;
+    }
+}
+function createNoopReadCacheDriver() {
+    return {
+        async clear() { },
+        async close() { },
+        async get() {
+            return null;
+        },
+        async set() { },
+    };
+}
+function isCacheFresh(savedAt, maxAgeMs) {
+    if (!maxAgeMs || maxAgeMs <= 0) {
+        return false;
+    }
+    const savedTime = Date.parse(savedAt);
+    return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
+}
+async function loadSharedFreshResource(key, loadFresh) {
+    const pendingLoad = pendingFreshLoads.get(key);
+    if (pendingLoad) {
+        return (await pendingLoad);
+    }
+    const nextLoad = loadFresh();
+    pendingFreshLoads.set(key, nextLoad);
+    try {
+        return await nextLoad;
+    }
+    finally {
+        if (pendingFreshLoads.get(key) === nextLoad) {
+            pendingFreshLoads.delete(key);
+        }
+    }
+}
+function toReadCacheEnvelope(value) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const envelope = value;
+    if (envelope.schemaVersion !== readCacheSchemaVersion ||
+        typeof envelope.savedAt !== "string" ||
+        !("value" in envelope)) {
+        return null;
+    }
+    return envelope;
+}
+function normalizeError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist-cjs/idbDriver.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIdbKeyValueDriver = createIdbKeyValueDriver;
+const idb_1 = require("idb");
+function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
+    if (!indexedDB) {
+        return null;
+    }
+    const databasePromise = openKeyValueDatabase({
+        databaseName,
+        databaseVersion,
+        indexedDB,
+        storeName,
+    });
+    return {
+        async clear() {
+            await runBrowserStorageOperation({
+                fallback: undefined,
+                operation: async () => {
+                    const database = await databasePromise;
+                    await database.clear(storeName);
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async close() {
+            await runBrowserStorageOperation({
+                fallback: undefined,
+                operation: async () => {
+                    const database = await databasePromise;
+                    database.close();
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async delete(key) {
+            await runBrowserStorageOperation({
+                fallback: undefined,
+                operation: async () => {
+                    const database = await databasePromise;
+                    await database.delete(storeName, key);
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async get(key) {
+            return runBrowserStorageOperation({
+                fallback: null,
+                operation: async () => {
+                    const database = await databasePromise;
+                    return (await database.get(storeName, key)) ?? null;
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async list() {
+            return runBrowserStorageOperation({
+                fallback: [],
+                operation: async () => {
+                    const database = await databasePromise;
+                    return database.getAll(storeName);
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+        async set(key, value) {
+            await runBrowserStorageOperation({
+                fallback: undefined,
+                operation: async () => {
+                    const database = await databasePromise;
+                    await database.put(storeName, value, key);
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
+    };
+}
+async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB, storeName, }) {
+    const request = indexedDB.open(databaseName, databaseVersion);
+    request.onupgradeneeded = () => {
+        const database = request.result;
+        if (!database.objectStoreNames.contains(storeName)) {
+            database.createObjectStore(storeName);
+        }
+    };
+    const database = await (0, idb_1.wrap)(request);
+    if (!database) {
+        throw new Error(`Could not open IndexedDB database ${databaseName}.`);
+    }
+    return database;
+}
+async function runBrowserStorageOperation({ fallback, operation, timeoutMs, }) {
+    let timeoutId = null;
+    try {
+        return await Promise.race([
+            operation(),
+            new Promise((resolve) => {
+                timeoutId = setTimeout(() => resolve(fallback), timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        return fallback;
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}

package/dist-cjs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./readCache"), exports);
+__exportStar(require("./pendingWrites"), exports);

package/dist-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist-cjs/pendingWrites.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pendingWriteOperationTimeoutMs = exports.pendingWriteSchemaVersion = void 0;
+exports.createPendingWriteStore = createPendingWriteStore;
+exports.createMemoryPendingWriteDriver = createMemoryPendingWriteDriver;
+exports.createBrowserPendingWriteDriver = createBrowserPendingWriteDriver;
+exports.createBrowserPendingWriteStore = createBrowserPendingWriteStore;
+exports.createPendingWriteKey = createPendingWriteKey;
+exports.syncPendingWrite = syncPendingWrite;
+const idbDriver_1 = require("./idbDriver");
+exports.pendingWriteSchemaVersion = 1;
+exports.pendingWriteOperationTimeoutMs = 2_000;
+function createPendingWriteStore(driver, { keyPrefix, normalizePayload, schemaVersion = exports.pendingWriteSchemaVersion, }) {
+    return {
+        async clear(id) {
+            await driver.clear(createPendingWriteKey({ id, prefix: keyPrefix }));
+        },
+        async clearAll() {
+            await driver.clearAll();
+        },
+        async clearIfSavedAt(id, savedAt) {
+            const current = await this.get(id);
+            if (!current || current.savedAt !== savedAt) {
+                return false;
+            }
+            await this.clear(id);
+            return true;
+        },
+        async close() {
+            await driver.close?.();
+        },
+        async get(id) {
+            return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizePayload })?.record ?? null);
+        },
+        async list() {
+            return (await driver.list())
+                .map((value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizePayload,
+            })?.record)
+                .filter((record) => Boolean(record))
+                .sort((left, right) => left.savedAt.localeCompare(right.savedAt));
+        },
+        async set(record) {
+            await driver.set(createPendingWriteKey({ id: record.id, prefix: keyPrefix }), {
+                record,
+                schemaVersion,
+            });
+        },
+    };
+}
+function createMemoryPendingWriteDriver() {
+    const records = new Map();
+    return {
+        async clear(key) {
+            records.delete(key);
+        },
+        async clearAll() {
+            records.clear();
+        },
+        async close() { },
+        async get(key) {
+            return records.get(key) ?? null;
+        },
+        async list() {
+            return [...records.values()];
+        },
+        async set(key, value) {
+            records.set(key, value);
+        },
+    };
+}
+function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = exports.pendingWriteOperationTimeoutMs, storeName, }) {
+    const driver = (0, idbDriver_1.createIdbKeyValueDriver)({
+        databaseName,
+        databaseVersion,
+        indexedDB,
+        operationTimeoutMs,
+        storeName,
+    });
+    return driver ? toPendingWriteDriver(driver) : null;
+}
+function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, keyPrefix, normalizePayload, operationTimeoutMs = exports.pendingWriteOperationTimeoutMs, schemaVersion = exports.pendingWriteSchemaVersion, storeName, }) {
+    const driver = createBrowserPendingWriteDriver({
+        databaseName,
+        databaseVersion,
+        indexedDB,
+        operationTimeoutMs,
+        storeName,
+    });
+    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizePayload, schemaVersion });
+}
+function createPendingWriteKey({ id, prefix }) {
+    return `${prefix}:${encodeURIComponent(id)}`;
+}
+async function syncPendingWrite({ id, store, sync, }) {
+    const pending = await store.get(id);
+    if (!pending) {
+        return { status: "idle" };
+    }
+    await markPendingSnapshot({
+        id,
+        nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
+        savedAt: pending.savedAt,
+        store,
+    });
+    try {
+        await sync(pending.payload);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unable to sync pending write.";
+        await markPendingSnapshot({
+            id,
+            nextRecord: { ...pending, error: message, syncStatus: "failed" },
+            savedAt: pending.savedAt,
+            store,
+        });
+        return { error: message, status: "failed" };
+    }
+    return (await store.clearIfSavedAt(id, pending.savedAt))
+        ? { status: "synced" }
+        : { status: "superseded" };
+}
+function createNoopPendingWriteDriver() {
+    return {
+        async clear() { },
+        async clearAll() { },
+        async close() { },
+        async get() {
+            return null;
+        },
+        async list() {
+            return [];
+        },
+        async set() { },
+    };
+}
+function toPendingWriteDriver(driver) {
+    return {
+        clear: driver.delete,
+        clearAll: driver.clear,
+        close: driver.close,
+        get: driver.get,
+        list: driver.list,
+        set: driver.set,
+    };
+}
+async function markPendingSnapshot({ id, nextRecord, savedAt, store, }) {
+    const current = await store.get(id);
+    if (current?.savedAt !== savedAt) {
+        return false;
+    }
+    await store.set(nextRecord);
+    return true;
+}
+function toPendingWriteEnvelope(value, schemaVersion, { normalizePayload }) {
+    if (!value ||
+        typeof value !== "object" ||
+        !("schemaVersion" in value) ||
+        value.schemaVersion !== schemaVersion ||
+        !("record" in value) ||
+        !isPendingWriteRecord(value.record)) {
+        return null;
+    }
+    const record = normalizePendingWriteRecord(value.record, normalizePayload);
+    return record ? { record, schemaVersion } : null;
+}
+function normalizePendingWriteRecord(record, normalizePayload) {
+    if (!normalizePayload) {
+        return record;
+    }
+    const payload = normalizePayload(record.payload);
+    if (payload === null) {
+        return null;
+    }
+    return {
+        ...(typeof record.error === "string" ? { error: record.error } : {}),
+        id: record.id,
+        payload,
+        savedAt: record.savedAt,
+        syncStatus: record.syncStatus,
+    };
+}
+function isPendingWriteRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        "id" in value &&
+        typeof value.id === "string" &&
+        "savedAt" in value &&
+        typeof value.savedAt === "string" &&
+        "syncStatus" in value &&
+        (value.syncStatus === "pending" ||
+            value.syncStatus === "syncing" ||
+            value.syncStatus === "failed") &&
+        "payload" in value);
+}

package/dist-cjs/readCache.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserReadCacheOperationTimeoutMs = exports.readCacheFreshnessMaxAgeMs = exports.readCacheSchemaVersion = void 0;
+exports.createReadCache = createReadCache;
+exports.createMemoryReadCacheDriver = createMemoryReadCacheDriver;
+exports.createBrowserReadCache = createBrowserReadCache;
+exports.createReadCacheKey = createReadCacheKey;
+exports.readThroughCache = readThroughCache;
+exports.loadReadCacheResource = loadReadCacheResource;
+const idbDriver_1 = require("./idbDriver");
+exports.readCacheSchemaVersion = 1;
+exports.readCacheFreshnessMaxAgeMs = 30_000;
+exports.browserReadCacheOperationTimeoutMs = 2_000;
+const pendingFreshLoads = new Map();
+function createReadCache(driver) {
+    return {
+        async clear() {
+            pendingFreshLoads.clear();
+            await driver.clear();
+        },
+        async close() {
+            await driver.close?.();
+        },
+        async get(key) {
+            const envelope = toReadCacheEnvelope(await driver.get(key));
+            return envelope
+                ? {
+                    fromCache: true,
+                    savedAt: envelope.savedAt,
+                    value: envelope.value,
+                }
+                : null;
+        },
+        async set(key, value) {
+            await driver.set(key, {
+                savedAt: new Date().toISOString(),
+                schemaVersion: exports.readCacheSchemaVersion,
+                value,
+            });
+        },
+    };
+}
+function createMemoryReadCacheDriver() {
+    const records = new Map();
+    return {
+        async clear() {
+            records.clear();
+        },
+        async close() { },
+        async get(key) {
+            return records.get(key) ?? null;
+        },
+        async set(key, value) {
+            records.set(key, value);
+        },
+    };
+}
+function createBrowserReadCache({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = exports.browserReadCacheOperationTimeoutMs, storeName, }) {
+    const driver = (0, idbDriver_1.createIdbKeyValueDriver)({
+        databaseName,
+        databaseVersion,
+        indexedDB,
+        operationTimeoutMs,
+        storeName,
+    });
+    return createReadCache(driver ?? createNoopReadCacheDriver());
+}
+function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
+    const serializedParams = Object.entries(params)
+        .filter(([, value]) => value !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join("&");
+    return [
+        prefix,
+        encodeURIComponent(namespace),
+        encodeURIComponent(scope),
+        serializedParams,
+    ]
+        .filter(Boolean)
+        .join(":");
+}
+async function readThroughCache({ cache, key, loadFresh, }) {
+    const cached = await cache.get(key);
+    try {
+        const fresh = await loadFresh();
+        await cache.set(key, fresh);
+        return {
+            data: fresh,
+            error: null,
+            fromCache: false,
+            stale: false,
+        };
+    }
+    catch (error) {
+        if (cached) {
+            return {
+                data: cached.value,
+                error: normalizeError(error),
+                fromCache: true,
+                stale: true,
+            };
+        }
+        throw error;
+    }
+}
+async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onUpdate, }) {
+    const cached = await cache.get(key);
+    if (cached) {
+        onUpdate({ data: cached.value, fromCache: true });
+        if (isCacheFresh(cached.savedAt, maxAgeMs)) {
+            return cached.value;
+        }
+    }
+    try {
+        const fresh = await loadSharedFreshResource(key, loadFresh);
+        onUpdate({ data: fresh, fromCache: false });
+        void cache.set(key, fresh).catch(() => undefined);
+        return fresh;
+    }
+    catch (error) {
+        if (!cached) {
+            throw error;
+        }
+        onUpdate({
+            data: cached.value,
+            error: normalizeError(error),
+            fromCache: true,
+        });
+        return cached.value;
+    }
+}
+function createNoopReadCacheDriver() {
+    return {
+        async clear() { },
+        async close() { },
+        async get() {
+            return null;
+        },
+        async set() { },
+    };
+}
+function isCacheFresh(savedAt, maxAgeMs) {
+    if (!maxAgeMs || maxAgeMs <= 0) {
+        return false;
+    }
+    const savedTime = Date.parse(savedAt);
+    return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
+}
+async function loadSharedFreshResource(key, loadFresh) {
+    const pendingLoad = pendingFreshLoads.get(key);
+    if (pendingLoad) {
+        return (await pendingLoad);
+    }
+    const nextLoad = loadFresh();
+    pendingFreshLoads.set(key, nextLoad);
+    try {
+        return await nextLoad;
+    }
+    finally {
+        if (pendingFreshLoads.get(key) === nextLoad) {
+            pendingFreshLoads.delete(key);
+        }
+    }
+}
+function toReadCacheEnvelope(value) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const envelope = value;
+    if (envelope.schemaVersion !== exports.readCacheSchemaVersion ||
+        typeof envelope.savedAt !== "string" ||
+        !("value" in envelope)) {
+        return null;
+    }
+    return envelope;
+}
+function normalizeError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@bayonai/offline",
+  "version": "0.1.0",
+  "description": "Reusable offline read-cache and pending-write primitives.",
+  "license": "MIT",
+  "author": "Bayon AI",
+  "homepage": "https://github.com/toledoroy/bounded/tree/main/packages/offline#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toledoroy/bounded.git",
+    "directory": "packages/offline"
+  },
+  "bugs": {
+    "url": "https://github.com/toledoroy/bounded/issues"
+  },
+  "keywords": [
+    "offline",
+    "indexeddb",
+    "cache",
+    "pending-writes",
+    "idb",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist-cjs/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist-cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "dist-cjs",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/write-esm-extensions.mjs && tsc -p tsconfig.cjs.json && node scripts/write-cjs.mjs",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "prepack": "pnpm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "idb": "^8.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vitest": "^4.1.6"
+  }
+}