@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

pnpm add @bayonai/offline

Read Cache

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

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:

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

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.