lowdata 0.1.0 → 0.2.0

package/README.md

@@ -6,7 +6,9 @@ Automatic retries with backoff, an offline request queue that survives page relo
 forms, and bandwidth-aware image compression — for web apps that have to keep working on 2G, on a
 flaky café Wi-Fi, or mid-load-shedding. Framework-agnostic, near-zero dependencies, fully typed.
 
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![CI](https://github.com/bassmoses/lowdata/actions/workflows/ci.yml/badge.svg)](https://github.com/bassmoses/lowdata/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/lowdata.svg)](https://www.npmjs.com/package/lowdata)
+[![license](https://img.shields.io/npm/l/lowdata.svg)](./LICENSE)
 [![bundle size](https://img.shields.io/badge/core%20%2B%20network%20%2B%20forms-~9%20KB%20gzip-brightgreen.svg)](#bundle-size)
 
 ```ts
@@ -138,6 +140,20 @@ client.onSync((event) => {
 });
 ```
 
+Background sync failures are deliberately never thrown (a queued item retrying in the background
+shouldn't crash your app) — but they're not silent either. Pass `onError` to see them (a
+`console.warn` is the default if you don't):
+
+```ts
+createLowdataClient({
+  onError: (error, { scope }) => reportToMonitoring(error, { scope }),
+  // scope: 'db-open' (IndexedDB unavailable, fell back to memory for the session)
+  //      | 'db-operation' (one IndexedDB call failed — e.g. a transient quota error — persistence
+  //        is still available, just that one call fell back)
+  //      | 'sync' (the background sync loop hit an unexpected error)
+});
+```
+
 ### Retry & backoff
 
 ```ts
@@ -228,8 +244,24 @@ cross-tab-raced request is still possible in rare edge cases.
   for that session.
 - **SSR-safe to import**: `createLowdataClient()` and friends never assume `window`/`navigator`
   exist; on the server, connection quality reports `'online'` and nothing touches the DOM.
-- Sync only runs while a tab is open (no Service Worker in v1) — closing the tab while offline
-  defers sync to the next time the app is opened, not true background sync.
+
+## Known limitations & roadmap
+
+- **Sync only runs while a tab is open.** There's no Service Worker in v1 (by design — see
+  "vs. alternatives" below) — closing the tab while offline defers sync to the next time the app
+  is opened, not true background sync.
+- **No live cross-tab queue state.** The cross-tab _lock_ (preventing double-sends) is real and
+  tested against real multiple tabs (see `e2e/`) — but `queue.list()` in tab B doesn't reactively
+  update when tab A's queue changes; you'd need to poll or re-call it.
+- **Storage quota** is enforced via `maxQueueItemSizeBytes` (rejects oversized items explicitly,
+  default 5 MB) rather than proactively checked against `navigator.storage.estimate()` — a
+  same-origin quota that's already nearly full can still surface as an `onError` `'db-operation'`
+  event rather than being caught in advance.
+- **No per-endpoint circuit breaker.** Many queued items to the same persistently-down host each
+  retry independently (with jitter) rather than coordinating — fine at normal scale, untested at
+  very large queue sizes against one failing endpoint.
+
+See [`ROADMAP.md`](./ROADMAP.md) for what's deliberately deferred and why.
 
 ## Bundle size
 
@@ -260,7 +292,8 @@ quality search) is never pulled in by the root import; you opt in explicitly via
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
+See [CONTRIBUTING.md](./CONTRIBUTING.md), [VERSIONING.md](./VERSIONING.md) for the (fully
+automated) release process, and [SECURITY.md](./SECURITY.md) to report a vulnerability.
 
 ## License
 

package/dist/{client-CqO3Y1J5.d.cts → client-BmsR0Pf6.d.cts}

@@ -1,4 +1,4 @@
-import { C as ConnectionInfo, a as ConnectionListener, U as Unsubscribe, R as RequestPriority, c as RetryBackoffConfig } from './types--FRrBa-i.cjs';
+import { C as ConnectionInfo, a as ConnectionListener, U as Unsubscribe, R as RequestPriority, d as RetryBackoffConfig, L as LowdataErrorHandler } from './types-D6fjl8Wy.cjs';
 
 interface ConnectionMonitorOptions {
     /**
@@ -115,6 +115,12 @@ interface LowdataClientConfig {
         url: string;
         method: HttpMethod;
     }) => boolean;
+    /**
+     * Observe otherwise-silent internal failures (a background sync error, a fallback to an
+     * in-memory queue/draft store) instead of them only producing a single `console.warn`. Useful
+     * for piping into your own logging/monitoring in production.
+     */
+    onError?: LowdataErrorHandler;
 }
 
 interface QueueListFilter {
@@ -128,7 +134,7 @@ interface QueueListFilter {
 declare class RequestQueue {
     private memory;
     private accessor;
-    constructor(getDb: () => Promise<IDBDatabase>);
+    constructor(getDb: () => Promise<IDBDatabase>, onError?: LowdataErrorHandler);
     isPersistent(): boolean;
     add(item: QueueItem): Promise<QueueItem>;
     update(item: QueueItem): Promise<void>;

package/dist/{client-BvdWSYIM.d.ts → client-DSKoYUj9.d.ts}

@@ -1,4 +1,4 @@
-import { C as ConnectionInfo, a as ConnectionListener, U as Unsubscribe, R as RequestPriority, c as RetryBackoffConfig } from './types--FRrBa-i.js';
+import { C as ConnectionInfo, a as ConnectionListener, U as Unsubscribe, R as RequestPriority, d as RetryBackoffConfig, L as LowdataErrorHandler } from './types-D6fjl8Wy.js';
 
 interface ConnectionMonitorOptions {
     /**
@@ -115,6 +115,12 @@ interface LowdataClientConfig {
         url: string;
         method: HttpMethod;
     }) => boolean;
+    /**
+     * Observe otherwise-silent internal failures (a background sync error, a fallback to an
+     * in-memory queue/draft store) instead of them only producing a single `console.warn`. Useful
+     * for piping into your own logging/monitoring in production.
+     */
+    onError?: LowdataErrorHandler;
 }
 
 interface QueueListFilter {
@@ -128,7 +134,7 @@ interface QueueListFilter {
 declare class RequestQueue {
     private memory;
     private accessor;
-    constructor(getDb: () => Promise<IDBDatabase>);
+    constructor(getDb: () => Promise<IDBDatabase>, onError?: LowdataErrorHandler);
     isPersistent(): boolean;
     add(item: QueueItem): Promise<QueueItem>;
     update(item: QueueItem): Promise<void>;

package/dist/forms.cjs

@@ -256,16 +256,23 @@ function getSharedDb() {
   }
   return sharedDbPromise;
 }
-function createDbFallbackAccessor(getDb) {
+function createDbFallbackAccessor(getDb, onError) {
   let dbAvailable = true;
   return {
     async run(fn, fallback) {
       if (!dbAvailable) return fallback();
+      let db;
       try {
-        const db = await getDb();
-        return await fn(db);
-      } catch {
+        db = await getDb();
+      } catch (error) {
         dbAvailable = false;
+        onError == null ? void 0 : onError(error, { scope: "db-open" });
+        return fallback();
+      }
+      try {
+        return await fn(db);
+      } catch (error) {
+        onError == null ? void 0 : onError(error, { scope: "db-operation" });
         return fallback();
       }
     },
@@ -291,9 +298,9 @@ var LowdataRequestError = class extends Error {
 var STORE = "queue";
 var PRIORITY_ORDER = { high: 0, normal: 1, low: 2 };
 var RequestQueue = class {
-  constructor(getDb) {
+  constructor(getDb, onError) {
     this.memory = /* @__PURE__ */ new Map();
-    this.accessor = createDbFallbackAccessor(getDb);
+    this.accessor = createDbFallbackAccessor(getDb, onError);
   }
   isPersistent() {
     return this.accessor.isPersistent();
@@ -608,12 +615,16 @@ var SyncManager = class {
    * or safety poll simply tries again.
    */
   async drain() {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f;
     if (this.draining || this.disposed) return;
     if (this.opts.connection.getStatus().quality === "offline") return;
     this.draining = true;
     try {
-      const db = await this.opts.getDb().catch(() => void 0);
+      const db = await this.opts.getDb().catch((error) => {
+        var _a2, _b2;
+        (_b2 = (_a2 = this.opts).onError) == null ? void 0 : _b2.call(_a2, error, { scope: "db-open" });
+        return void 0;
+      });
       const lock = await acquireSyncLock(db, SYNC_LOCK_NAME, this.ownerId);
       if (!lock) return;
       let succeeded = 0;
@@ -636,7 +647,8 @@ var SyncManager = class {
         await lock.release().catch(() => {
         });
       }
-    } catch {
+    } catch (error) {
+      (_f = (_e = this.opts).onError) == null ? void 0 : _f.call(_e, error, { scope: "sync" });
     } finally {
       this.draining = false;
     }
@@ -722,6 +734,9 @@ var MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"
 function defaultShouldQueueOffline({ method }) {
   return MUTATING_METHODS.has(method);
 }
+var defaultOnError = (error, { scope }) => {
+  console.warn(`lowdata: internal error (${scope})`, error);
+};
 function normalizeHeaders(headers) {
   if (!headers) return void 0;
   if (headers instanceof Headers) {
@@ -750,15 +765,18 @@ var LowdataClient = class {
     this.config = config;
     this.syncEmitter = new Emitter();
     this.destroyed = false;
+    var _a;
+    const onError = (_a = config.onError) != null ? _a : defaultOnError;
     this.monitor = new ConnectionMonitor(config.connection);
-    this.requestQueue = new RequestQueue(() => getSharedDb());
+    this.requestQueue = new RequestQueue(() => getSharedDb(), onError);
     this.syncManager = new SyncManager({
       queue: this.requestQueue,
       connection: this.monitor,
       getDb: () => getSharedDb(),
       retryConfig: config.retry,
       syncConcurrency: config.syncConcurrency,
-      onEvent: (event) => this.syncEmitter.emit(event)
+      onEvent: (event) => this.syncEmitter.emit(event),
+      onError
     });
     this.connection = {
       getStatus: () => this.monitor.getStatus(),