@tanstack/offline-transactions 0.0.0 → 0.1.0

package/dist/esm/storage/LocalStorageAdapter.d.ts

@@ -2,6 +2,14 @@ import { BaseStorageAdapter } from './StorageAdapter.js';
 export declare class LocalStorageAdapter extends BaseStorageAdapter {
     private prefix;
     constructor(prefix?: string);
+    /**
+     * Probe localStorage availability by attempting a test write.
+     * This catches private mode and other restrictions that block localStorage.
+     */
+    static probe(): {
+        available: boolean;
+        error?: Error;
+    };
     private getKey;
     get(key: string): Promise<string | null>;
     set(key: string, value: string): Promise<void>;

package/dist/esm/storage/LocalStorageAdapter.js

@@ -4,6 +4,37 @@ class LocalStorageAdapter extends BaseStorageAdapter {
     super();
     this.prefix = prefix;
   }
+  /**
+   * Probe localStorage availability by attempting a test write.
+   * This catches private mode and other restrictions that block localStorage.
+   */
+  static probe() {
+    if (typeof localStorage === `undefined`) {
+      return {
+        available: false,
+        error: new Error(`localStorage is not available in this environment`)
+      };
+    }
+    try {
+      const testKey = `__offline-tx-probe__`;
+      const testValue = `test`;
+      localStorage.setItem(testKey, testValue);
+      const retrieved = localStorage.getItem(testKey);
+      localStorage.removeItem(testKey);
+      if (retrieved !== testValue) {
+        return {
+          available: false,
+          error: new Error(`localStorage read/write verification failed`)
+        };
+      }
+      return { available: true };
+    } catch (error) {
+      return {
+        available: false,
+        error: error instanceof Error ? error : new Error(String(error))
+      };
+    }
+  }
   getKey(key) {
     return `${this.prefix}${key}`;
   }

package/dist/esm/storage/LocalStorageAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"LocalStorageAdapter.js","sources":["../../../src/storage/LocalStorageAdapter.ts"],"sourcesContent":["import { BaseStorageAdapter } from \"./StorageAdapter\"\n\nexport class LocalStorageAdapter extends BaseStorageAdapter {\n  private prefix: string\n\n  constructor(prefix = `offline-tx:`) {\n    super()\n    this.prefix = prefix\n  }\n\n  private getKey(key: string): string {\n    return `${this.prefix}${key}`\n  }\n\n  get(key: string): Promise<string | null> {\n    try {\n      return Promise.resolve(localStorage.getItem(this.getKey(key)))\n    } catch (error) {\n      console.warn(`localStorage get failed:`, error)\n      return Promise.resolve(null)\n    }\n  }\n\n  set(key: string, value: string): Promise<void> {\n    try {\n      localStorage.setItem(this.getKey(key), value)\n      return Promise.resolve()\n    } catch (error) {\n      if (\n        error instanceof DOMException &&\n        error.name === `QuotaExceededError`\n      ) {\n        return Promise.reject(\n          new Error(\n            `Storage quota exceeded. Consider clearing old transactions.`\n          )\n        )\n      }\n      return Promise.reject(error)\n    }\n  }\n\n  delete(key: string): Promise<void> {\n    try {\n      localStorage.removeItem(this.getKey(key))\n      return Promise.resolve()\n    } catch (error) {\n      console.warn(`localStorage delete failed:`, error)\n      return Promise.resolve()\n    }\n  }\n\n  keys(): Promise<Array<string>> {\n    try {\n      const keys: Array<string> = []\n      for (let i = 0; i < localStorage.length; i++) {\n        const key = localStorage.key(i)\n        if (key && key.startsWith(this.prefix)) {\n          keys.push(key.slice(this.prefix.length))\n        }\n      }\n      return Promise.resolve(keys)\n    } catch (error) {\n      console.warn(`localStorage keys failed:`, error)\n      return Promise.resolve([])\n    }\n  }\n\n  async clear(): Promise<void> {\n    try {\n      const keys = await this.keys()\n      for (const key of keys) {\n        localStorage.removeItem(this.getKey(key))\n      }\n    } catch (error) {\n      console.warn(`localStorage clear failed:`, error)\n    }\n  }\n}\n"],"names":[],"mappings":";AAEO,MAAM,4BAA4B,mBAAmB;AAAA,EAG1D,YAAY,SAAS,eAAe;AAClC,UAAA;AACA,SAAK,SAAS;AAAA,EAChB;AAAA,EAEQ,OAAO,KAAqB;AAClC,WAAO,GAAG,KAAK,MAAM,GAAG,GAAG;AAAA,EAC7B;AAAA,EAEA,IAAI,KAAqC;AACvC,QAAI;AACF,aAAO,QAAQ,QAAQ,aAAa,QAAQ,KAAK,OAAO,GAAG,CAAC,CAAC;AAAA,IAC/D,SAAS,OAAO;AACd,cAAQ,KAAK,4BAA4B,KAAK;AAC9C,aAAO,QAAQ,QAAQ,IAAI;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,IAAI,KAAa,OAA8B;AAC7C,QAAI;AACF,mBAAa,QAAQ,KAAK,OAAO,GAAG,GAAG,KAAK;AAC5C,aAAO,QAAQ,QAAA;AAAA,IACjB,SAAS,OAAO;AACd,UACE,iBAAiB,gBACjB,MAAM,SAAS,sBACf;AACA,eAAO,QAAQ;AAAA,UACb,IAAI;AAAA,YACF;AAAA,UAAA;AAAA,QACF;AAAA,MAEJ;AACA,aAAO,QAAQ,OAAO,KAAK;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,OAAO,KAA4B;AACjC,QAAI;AACF,mBAAa,WAAW,KAAK,OAAO,GAAG,CAAC;AACxC,aAAO,QAAQ,QAAA;AAAA,IACjB,SAAS,OAAO;AACd,cAAQ,KAAK,+BAA+B,KAAK;AACjD,aAAO,QAAQ,QAAA;AAAA,IACjB;AAAA,EACF;AAAA,EAEA,OAA+B;AAC7B,QAAI;AACF,YAAM,OAAsB,CAAA;AAC5B,eAAS,IAAI,GAAG,IAAI,aAAa,QAAQ,KAAK;AAC5C,cAAM,MAAM,aAAa,IAAI,CAAC;AAC9B,YAAI,OAAO,IAAI,WAAW,KAAK,MAAM,GAAG;AACtC,eAAK,KAAK,IAAI,MAAM,KAAK,OAAO,MAAM,CAAC;AAAA,QACzC;AAAA,MACF;AACA,aAAO,QAAQ,QAAQ,IAAI;AAAA,IAC7B,SAAS,OAAO;AACd,cAAQ,KAAK,6BAA6B,KAAK;AAC/C,aAAO,QAAQ,QAAQ,EAAE;AAAA,IAC3B;AAAA,EACF;AAAA,EAEA,MAAM,QAAuB;AAC3B,QAAI;AACF,YAAM,OAAO,MAAM,KAAK,KAAA;AACxB,iBAAW,OAAO,MAAM;AACtB,qBAAa,WAAW,KAAK,OAAO,GAAG,CAAC;AAAA,MAC1C;AAAA,IACF,SAAS,OAAO;AACd,cAAQ,KAAK,8BAA8B,KAAK;AAAA,IAClD;AAAA,EACF;AACF;"}
+{"version":3,"file":"LocalStorageAdapter.js","sources":["../../../src/storage/LocalStorageAdapter.ts"],"sourcesContent":["import { BaseStorageAdapter } from \"./StorageAdapter\"\n\nexport class LocalStorageAdapter extends BaseStorageAdapter {\n  private prefix: string\n\n  constructor(prefix = `offline-tx:`) {\n    super()\n    this.prefix = prefix\n  }\n\n  /**\n   * Probe localStorage availability by attempting a test write.\n   * This catches private mode and other restrictions that block localStorage.\n   */\n  static probe(): { available: boolean; error?: Error } {\n    // Check if localStorage exists\n    if (typeof localStorage === `undefined`) {\n      return {\n        available: false,\n        error: new Error(`localStorage is not available in this environment`),\n      }\n    }\n\n    // Try to actually write/read/delete to verify it works\n    try {\n      const testKey = `__offline-tx-probe__`\n      const testValue = `test`\n\n      localStorage.setItem(testKey, testValue)\n      const retrieved = localStorage.getItem(testKey)\n      localStorage.removeItem(testKey)\n\n      if (retrieved !== testValue) {\n        return {\n          available: false,\n          error: new Error(`localStorage read/write verification failed`),\n        }\n      }\n\n      return { available: true }\n    } catch (error) {\n      return {\n        available: false,\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n    }\n  }\n\n  private getKey(key: string): string {\n    return `${this.prefix}${key}`\n  }\n\n  get(key: string): Promise<string | null> {\n    try {\n      return Promise.resolve(localStorage.getItem(this.getKey(key)))\n    } catch (error) {\n      console.warn(`localStorage get failed:`, error)\n      return Promise.resolve(null)\n    }\n  }\n\n  set(key: string, value: string): Promise<void> {\n    try {\n      localStorage.setItem(this.getKey(key), value)\n      return Promise.resolve()\n    } catch (error) {\n      if (\n        error instanceof DOMException &&\n        error.name === `QuotaExceededError`\n      ) {\n        return Promise.reject(\n          new Error(\n            `Storage quota exceeded. Consider clearing old transactions.`\n          )\n        )\n      }\n      return Promise.reject(error)\n    }\n  }\n\n  delete(key: string): Promise<void> {\n    try {\n      localStorage.removeItem(this.getKey(key))\n      return Promise.resolve()\n    } catch (error) {\n      console.warn(`localStorage delete failed:`, error)\n      return Promise.resolve()\n    }\n  }\n\n  keys(): Promise<Array<string>> {\n    try {\n      const keys: Array<string> = []\n      for (let i = 0; i < localStorage.length; i++) {\n        const key = localStorage.key(i)\n        if (key && key.startsWith(this.prefix)) {\n          keys.push(key.slice(this.prefix.length))\n        }\n      }\n      return Promise.resolve(keys)\n    } catch (error) {\n      console.warn(`localStorage keys failed:`, error)\n      return Promise.resolve([])\n    }\n  }\n\n  async clear(): Promise<void> {\n    try {\n      const keys = await this.keys()\n      for (const key of keys) {\n        localStorage.removeItem(this.getKey(key))\n      }\n    } catch (error) {\n      console.warn(`localStorage clear failed:`, error)\n    }\n  }\n}\n"],"names":[],"mappings":";AAEO,MAAM,4BAA4B,mBAAmB;AAAA,EAG1D,YAAY,SAAS,eAAe;AAClC,UAAA;AACA,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,QAA+C;AAEpD,QAAI,OAAO,iBAAiB,aAAa;AACvC,aAAO;AAAA,QACL,WAAW;AAAA,QACX,OAAO,IAAI,MAAM,mDAAmD;AAAA,MAAA;AAAA,IAExE;AAGA,QAAI;AACF,YAAM,UAAU;AAChB,YAAM,YAAY;AAElB,mBAAa,QAAQ,SAAS,SAAS;AACvC,YAAM,YAAY,aAAa,QAAQ,OAAO;AAC9C,mBAAa,WAAW,OAAO;AAE/B,UAAI,cAAc,WAAW;AAC3B,eAAO;AAAA,UACL,WAAW;AAAA,UACX,OAAO,IAAI,MAAM,6CAA6C;AAAA,QAAA;AAAA,MAElE;AAEA,aAAO,EAAE,WAAW,KAAA;AAAA,IACtB,SAAS,OAAO;AACd,aAAO;AAAA,QACL,WAAW;AAAA,QACX,OAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAAA,MAAA;AAAA,IAEnE;AAAA,EACF;AAAA,EAEQ,OAAO,KAAqB;AAClC,WAAO,GAAG,KAAK,MAAM,GAAG,GAAG;AAAA,EAC7B;AAAA,EAEA,IAAI,KAAqC;AACvC,QAAI;AACF,aAAO,QAAQ,QAAQ,aAAa,QAAQ,KAAK,OAAO,GAAG,CAAC,CAAC;AAAA,IAC/D,SAAS,OAAO;AACd,cAAQ,KAAK,4BAA4B,KAAK;AAC9C,aAAO,QAAQ,QAAQ,IAAI;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,IAAI,KAAa,OAA8B;AAC7C,QAAI;AACF,mBAAa,QAAQ,KAAK,OAAO,GAAG,GAAG,KAAK;AAC5C,aAAO,QAAQ,QAAA;AAAA,IACjB,SAAS,OAAO;AACd,UACE,iBAAiB,gBACjB,MAAM,SAAS,sBACf;AACA,eAAO,QAAQ;AAAA,UACb,IAAI;AAAA,YACF;AAAA,UAAA;AAAA,QACF;AAAA,MAEJ;AACA,aAAO,QAAQ,OAAO,KAAK;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,OAAO,KAA4B;AACjC,QAAI;AACF,mBAAa,WAAW,KAAK,OAAO,GAAG,CAAC;AACxC,aAAO,QAAQ,QAAA;AAAA,IACjB,SAAS,OAAO;AACd,cAAQ,KAAK,+BAA+B,KAAK;AACjD,aAAO,QAAQ,QAAA;AAAA,IACjB;AAAA,EACF;AAAA,EAEA,OAA+B;AAC7B,QAAI;AACF,YAAM,OAAsB,CAAA;AAC5B,eAAS,IAAI,GAAG,IAAI,aAAa,QAAQ,KAAK;AAC5C,cAAM,MAAM,aAAa,IAAI,CAAC;AAC9B,YAAI,OAAO,IAAI,WAAW,KAAK,MAAM,GAAG;AACtC,eAAK,KAAK,IAAI,MAAM,KAAK,OAAO,MAAM,CAAC;AAAA,QACzC;AAAA,MACF;AACA,aAAO,QAAQ,QAAQ,IAAI;AAAA,IAC7B,SAAS,OAAO;AACd,cAAQ,KAAK,6BAA6B,KAAK;AAC/C,aAAO,QAAQ,QAAQ,EAAE;AAAA,IAC3B;AAAA,EACF;AAAA,EAEA,MAAM,QAAuB;AAC3B,QAAI;AACF,YAAM,OAAO,MAAM,KAAK,KAAA;AACxB,iBAAW,OAAO,MAAM;AACtB,qBAAa,WAAW,KAAK,OAAO,GAAG,CAAC;AAAA,MAC1C;AAAA,IACF,SAAS,OAAO;AACd,cAAQ,KAAK,8BAA8B,KAAK;AAAA,IAClD;AAAA,EACF;AACF;"}

package/dist/esm/telemetry/tracer.js

@@ -1,5 +1,5 @@
 import { trace, SpanStatusCode, context } from "@opentelemetry/api";
-const TRACER = trace.getTracer("@tanstack/offline-transactions", "0.0.1");
+const TRACER = trace.getTracer(`@tanstack/offline-transactions`, `0.0.1`);
 function getParentContext(options) {
   if (options?.parentContext) {
     const parentSpan = trace.wrapSpanContext(options.parentContext);

package/dist/esm/telemetry/tracer.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.js","sources":["../../../src/telemetry/tracer.ts"],"sourcesContent":["import {\n  trace,\n  type Span,\n  SpanStatusCode,\n  context,\n  type SpanContext,\n} from \"@opentelemetry/api\"\n\nconst TRACER = trace.getTracer(\"@tanstack/offline-transactions\", \"0.0.1\")\n\nexport interface SpanAttrs {\n  [key: string]: string | number | boolean | undefined\n}\n\ninterface WithSpanOptions {\n  parentContext?: SpanContext\n}\n\nfunction getParentContext(options?: WithSpanOptions) {\n  if (options?.parentContext) {\n    const parentSpan = trace.wrapSpanContext(options.parentContext)\n    return trace.setSpan(context.active(), parentSpan)\n  }\n\n  return context.active()\n}\n\n/**\n * Lightweight span wrapper with error handling.\n * Uses OpenTelemetry API which is no-op when tracing is disabled.\n *\n * By default, creates spans at the current context level (siblings).\n * Use withNestedSpan if you want parent-child relationships.\n */\nexport async function withSpan<T>(\n  name: string,\n  attrs: SpanAttrs,\n  fn: (span: Span) => Promise<T>,\n  options?: WithSpanOptions\n): Promise<T> {\n  const parentCtx = getParentContext(options)\n  const span = TRACER.startSpan(name, undefined, parentCtx)\n\n  // Filter out undefined attributes\n  const filteredAttrs: Record<string, string | number | boolean> = {}\n  for (const [key, value] of Object.entries(attrs)) {\n    if (value !== undefined) {\n      filteredAttrs[key] = value\n    }\n  }\n\n  span.setAttributes(filteredAttrs)\n\n  try {\n    const result = await fn(span)\n    span.setStatus({ code: SpanStatusCode.OK })\n    return result\n  } catch (error) {\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: error instanceof Error ? error.message : String(error),\n    })\n    span.recordException(error as Error)\n    throw error\n  } finally {\n    span.end()\n  }\n}\n\n/**\n * Like withSpan but propagates context so child spans nest properly.\n * Use this when you want operations inside fn to be child spans.\n */\nexport async function withNestedSpan<T>(\n  name: string,\n  attrs: SpanAttrs,\n  fn: (span: Span) => Promise<T>,\n  options?: WithSpanOptions\n): Promise<T> {\n  const parentCtx = getParentContext(options)\n  const span = TRACER.startSpan(name, undefined, parentCtx)\n\n  // Filter out undefined attributes\n  const filteredAttrs: Record<string, string | number | boolean> = {}\n  for (const [key, value] of Object.entries(attrs)) {\n    if (value !== undefined) {\n      filteredAttrs[key] = value\n    }\n  }\n\n  span.setAttributes(filteredAttrs)\n\n  // Set the span as active context so child spans nest properly\n  const ctx = trace.setSpan(parentCtx, span)\n\n  try {\n    // Execute the function within the span's context\n    const result = await context.with(ctx, () => fn(span))\n    span.setStatus({ code: SpanStatusCode.OK })\n    return result\n  } catch (error) {\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: error instanceof Error ? error.message : String(error),\n    })\n    span.recordException(error as Error)\n    throw error\n  } finally {\n    span.end()\n  }\n}\n\n/**\n * Creates a synchronous span for non-async operations\n */\nexport function withSyncSpan<T>(\n  name: string,\n  attrs: SpanAttrs,\n  fn: (span: Span) => T,\n  options?: WithSpanOptions\n): T {\n  const parentCtx = getParentContext(options)\n  const span = TRACER.startSpan(name, undefined, parentCtx)\n\n  // Filter out undefined attributes\n  const filteredAttrs: Record<string, string | number | boolean> = {}\n  for (const [key, value] of Object.entries(attrs)) {\n    if (value !== undefined) {\n      filteredAttrs[key] = value\n    }\n  }\n\n  span.setAttributes(filteredAttrs)\n\n  try {\n    const result = fn(span)\n    span.setStatus({ code: SpanStatusCode.OK })\n    return result\n  } catch (error) {\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: error instanceof Error ? error.message : String(error),\n    })\n    span.recordException(error as Error)\n    throw error\n  } finally {\n    span.end()\n  }\n}\n\n/**\n * Get the current tracer instance\n */\nexport function getTracer() {\n  return TRACER\n}\n"],"names":[],"mappings":";AAQA,MAAM,SAAS,MAAM,UAAU,kCAAkC,OAAO;AAUxE,SAAS,iBAAiB,SAA2B;AACnD,MAAI,SAAS,eAAe;AAC1B,UAAM,aAAa,MAAM,gBAAgB,QAAQ,aAAa;AAC9D,WAAO,MAAM,QAAQ,QAAQ,OAAA,GAAU,UAAU;AAAA,EACnD;AAEA,SAAO,QAAQ,OAAA;AACjB;AASA,eAAsB,SACpB,MACA,OACA,IACA,SACY;AACZ,QAAM,YAAY,iBAAiB,OAAO;AAC1C,QAAM,OAAO,OAAO,UAAU,MAAM,QAAW,SAAS;AAGxD,QAAM,gBAA2D,CAAA;AACjE,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,UAAU,QAAW;AACvB,oBAAc,GAAG,IAAI;AAAA,IACvB;AAAA,EACF;AAEA,OAAK,cAAc,aAAa;AAEhC,MAAI;AACF,UAAM,SAAS,MAAM,GAAG,IAAI;AAC5B,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI;AAC1C,WAAO;AAAA,EACT,SAAS,OAAO;AACd,SAAK,UAAU;AAAA,MACb,MAAM,eAAe;AAAA,MACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,IAAA,CAC/D;AACD,SAAK,gBAAgB,KAAc;AACnC,UAAM;AAAA,EACR,UAAA;AACE,SAAK,IAAA;AAAA,EACP;AACF;AAMA,eAAsB,eACpB,MACA,OACA,IACA,SACY;AACZ,QAAM,YAAY,iBAAiB,OAAO;AAC1C,QAAM,OAAO,OAAO,UAAU,MAAM,QAAW,SAAS;AAGxD,QAAM,gBAA2D,CAAA;AACjE,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,UAAU,QAAW;AACvB,oBAAc,GAAG,IAAI;AAAA,IACvB;AAAA,EACF;AAEA,OAAK,cAAc,aAAa;AAGhC,QAAM,MAAM,MAAM,QAAQ,WAAW,IAAI;AAEzC,MAAI;AAEF,UAAM,SAAS,MAAM,QAAQ,KAAK,KAAK,MAAM,GAAG,IAAI,CAAC;AACrD,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI;AAC1C,WAAO;AAAA,EACT,SAAS,OAAO;AACd,SAAK,UAAU;AAAA,MACb,MAAM,eAAe;AAAA,MACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,IAAA,CAC/D;AACD,SAAK,gBAAgB,KAAc;AACnC,UAAM;AAAA,EACR,UAAA;AACE,SAAK,IAAA;AAAA,EACP;AACF;AAKO,SAAS,aACd,MACA,OACA,IACA,SACG;AACH,QAAM,YAAY,iBAAiB,OAAO;AAC1C,QAAM,OAAO,OAAO,UAAU,MAAM,QAAW,SAAS;AAGxD,QAAM,gBAA2D,CAAA;AACjE,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,UAAU,QAAW;AACvB,oBAAc,GAAG,IAAI;AAAA,IACvB;AAAA,EACF;AAEA,OAAK,cAAc,aAAa;AAEhC,MAAI;AACF,UAAM,SAAS,GAAG,IAAI;AACtB,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI;AAC1C,WAAO;AAAA,EACT,SAAS,OAAO;AACd,SAAK,UAAU;AAAA,MACb,MAAM,eAAe;AAAA,MACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,IAAA,CAC/D;AACD,SAAK,gBAAgB,KAAc;AACnC,UAAM;AAAA,EACR,UAAA;AACE,SAAK,IAAA;AAAA,EACP;AACF;"}
+{"version":3,"file":"tracer.js","sources":["../../../src/telemetry/tracer.ts"],"sourcesContent":["import { SpanStatusCode, context, trace } from \"@opentelemetry/api\"\nimport type { Span, SpanContext } from \"@opentelemetry/api\"\n\nconst TRACER = trace.getTracer(`@tanstack/offline-transactions`, `0.0.1`)\n\nexport interface SpanAttrs {\n  [key: string]: string | number | boolean | undefined\n}\n\ninterface WithSpanOptions {\n  parentContext?: SpanContext\n}\n\nfunction getParentContext(options?: WithSpanOptions) {\n  if (options?.parentContext) {\n    const parentSpan = trace.wrapSpanContext(options.parentContext)\n    return trace.setSpan(context.active(), parentSpan)\n  }\n\n  return context.active()\n}\n\n/**\n * Lightweight span wrapper with error handling.\n * Uses OpenTelemetry API which is no-op when tracing is disabled.\n *\n * By default, creates spans at the current context level (siblings).\n * Use withNestedSpan if you want parent-child relationships.\n */\nexport async function withSpan<T>(\n  name: string,\n  attrs: SpanAttrs,\n  fn: (span: Span) => Promise<T>,\n  options?: WithSpanOptions\n): Promise<T> {\n  const parentCtx = getParentContext(options)\n  const span = TRACER.startSpan(name, undefined, parentCtx)\n\n  // Filter out undefined attributes\n  const filteredAttrs: Record<string, string | number | boolean> = {}\n  for (const [key, value] of Object.entries(attrs)) {\n    if (value !== undefined) {\n      filteredAttrs[key] = value\n    }\n  }\n\n  span.setAttributes(filteredAttrs)\n\n  try {\n    const result = await fn(span)\n    span.setStatus({ code: SpanStatusCode.OK })\n    return result\n  } catch (error) {\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: error instanceof Error ? error.message : String(error),\n    })\n    span.recordException(error as Error)\n    throw error\n  } finally {\n    span.end()\n  }\n}\n\n/**\n * Like withSpan but propagates context so child spans nest properly.\n * Use this when you want operations inside fn to be child spans.\n */\nexport async function withNestedSpan<T>(\n  name: string,\n  attrs: SpanAttrs,\n  fn: (span: Span) => Promise<T>,\n  options?: WithSpanOptions\n): Promise<T> {\n  const parentCtx = getParentContext(options)\n  const span = TRACER.startSpan(name, undefined, parentCtx)\n\n  // Filter out undefined attributes\n  const filteredAttrs: Record<string, string | number | boolean> = {}\n  for (const [key, value] of Object.entries(attrs)) {\n    if (value !== undefined) {\n      filteredAttrs[key] = value\n    }\n  }\n\n  span.setAttributes(filteredAttrs)\n\n  // Set the span as active context so child spans nest properly\n  const ctx = trace.setSpan(parentCtx, span)\n\n  try {\n    // Execute the function within the span's context\n    const result = await context.with(ctx, () => fn(span))\n    span.setStatus({ code: SpanStatusCode.OK })\n    return result\n  } catch (error) {\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: error instanceof Error ? error.message : String(error),\n    })\n    span.recordException(error as Error)\n    throw error\n  } finally {\n    span.end()\n  }\n}\n\n/**\n * Creates a synchronous span for non-async operations\n */\nexport function withSyncSpan<T>(\n  name: string,\n  attrs: SpanAttrs,\n  fn: (span: Span) => T,\n  options?: WithSpanOptions\n): T {\n  const parentCtx = getParentContext(options)\n  const span = TRACER.startSpan(name, undefined, parentCtx)\n\n  // Filter out undefined attributes\n  const filteredAttrs: Record<string, string | number | boolean> = {}\n  for (const [key, value] of Object.entries(attrs)) {\n    if (value !== undefined) {\n      filteredAttrs[key] = value\n    }\n  }\n\n  span.setAttributes(filteredAttrs)\n\n  try {\n    const result = fn(span)\n    span.setStatus({ code: SpanStatusCode.OK })\n    return result\n  } catch (error) {\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: error instanceof Error ? error.message : String(error),\n    })\n    span.recordException(error as Error)\n    throw error\n  } finally {\n    span.end()\n  }\n}\n\n/**\n * Get the current tracer instance\n */\nexport function getTracer() {\n  return TRACER\n}\n"],"names":[],"mappings":";AAGA,MAAM,SAAS,MAAM,UAAU,kCAAkC,OAAO;AAUxE,SAAS,iBAAiB,SAA2B;AACnD,MAAI,SAAS,eAAe;AAC1B,UAAM,aAAa,MAAM,gBAAgB,QAAQ,aAAa;AAC9D,WAAO,MAAM,QAAQ,QAAQ,OAAA,GAAU,UAAU;AAAA,EACnD;AAEA,SAAO,QAAQ,OAAA;AACjB;AASA,eAAsB,SACpB,MACA,OACA,IACA,SACY;AACZ,QAAM,YAAY,iBAAiB,OAAO;AAC1C,QAAM,OAAO,OAAO,UAAU,MAAM,QAAW,SAAS;AAGxD,QAAM,gBAA2D,CAAA;AACjE,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,UAAU,QAAW;AACvB,oBAAc,GAAG,IAAI;AAAA,IACvB;AAAA,EACF;AAEA,OAAK,cAAc,aAAa;AAEhC,MAAI;AACF,UAAM,SAAS,MAAM,GAAG,IAAI;AAC5B,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI;AAC1C,WAAO;AAAA,EACT,SAAS,OAAO;AACd,SAAK,UAAU;AAAA,MACb,MAAM,eAAe;AAAA,MACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,IAAA,CAC/D;AACD,SAAK,gBAAgB,KAAc;AACnC,UAAM;AAAA,EACR,UAAA;AACE,SAAK,IAAA;AAAA,EACP;AACF;AAMA,eAAsB,eACpB,MACA,OACA,IACA,SACY;AACZ,QAAM,YAAY,iBAAiB,OAAO;AAC1C,QAAM,OAAO,OAAO,UAAU,MAAM,QAAW,SAAS;AAGxD,QAAM,gBAA2D,CAAA;AACjE,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,UAAU,QAAW;AACvB,oBAAc,GAAG,IAAI;AAAA,IACvB;AAAA,EACF;AAEA,OAAK,cAAc,aAAa;AAGhC,QAAM,MAAM,MAAM,QAAQ,WAAW,IAAI;AAEzC,MAAI;AAEF,UAAM,SAAS,MAAM,QAAQ,KAAK,KAAK,MAAM,GAAG,IAAI,CAAC;AACrD,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI;AAC1C,WAAO;AAAA,EACT,SAAS,OAAO;AACd,SAAK,UAAU;AAAA,MACb,MAAM,eAAe;AAAA,MACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,IAAA,CAC/D;AACD,SAAK,gBAAgB,KAAc;AACnC,UAAM;AAAA,EACR,UAAA;AACE,SAAK,IAAA;AAAA,EACP;AACF;AAKO,SAAS,aACd,MACA,OACA,IACA,SACG;AACH,QAAM,YAAY,iBAAiB,OAAO;AAC1C,QAAM,OAAO,OAAO,UAAU,MAAM,QAAW,SAAS;AAGxD,QAAM,gBAA2D,CAAA;AACjE,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,UAAU,QAAW;AACvB,oBAAc,GAAG,IAAI;AAAA,IACvB;AAAA,EACF;AAEA,OAAK,cAAc,aAAa;AAEhC,MAAI;AACF,UAAM,SAAS,GAAG,IAAI;AACtB,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI;AAC1C,WAAO;AAAA,EACT,SAAS,OAAO;AACd,SAAK,UAAU;AAAA,MACb,MAAM,eAAe;AAAA,MACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,IAAA,CAC/D;AACD,SAAK,gBAAgB,KAAc;AACnC,UAAM;AAAA,EACR,UAAA;AACE,SAAK,IAAA;AAAA,EACP;AACF;"}

package/dist/esm/types.d.ts

@@ -49,6 +49,14 @@ export interface SerializedOfflineTransaction {
     spanContext?: SerializedSpanContext;
     version: 1;
 }
+export type OfflineMode = `offline` | `online-only`;
+export type StorageDiagnosticCode = `STORAGE_AVAILABLE` | `INDEXEDDB_UNAVAILABLE` | `LOCALSTORAGE_UNAVAILABLE` | `STORAGE_BLOCKED` | `QUOTA_EXCEEDED` | `UNKNOWN_ERROR`;
+export interface StorageDiagnostic {
+    code: StorageDiagnosticCode;
+    mode: OfflineMode;
+    message: string;
+    error?: Error;
+}
 export interface OfflineConfig {
     collections: Record<string, Collection>;
     mutationFns: Record<string, OfflineMutationFn>;
@@ -58,11 +66,8 @@ export interface OfflineConfig {
     beforeRetry?: (transactions: Array<OfflineTransaction>) => Array<OfflineTransaction>;
     onUnknownMutationFn?: (name: string, tx: OfflineTransaction) => void;
     onLeadershipChange?: (isLeader: boolean) => void;
+    onStorageFailure?: (diagnostic: StorageDiagnostic) => void;
     leaderElection?: LeaderElection;
-    otel?: {
-        endpoint: string;
-        headers?: Record<string, string>;
-    };
 }
 export interface StorageAdapter {
     get: (key: string) => Promise<string | null>;

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  Collection,\n  MutationFnParams,\n  PendingMutation,\n} from \"@tanstack/db\"\n\n// Extended mutation function that includes idempotency key\nexport type OfflineMutationFnParams<\n  T extends object = Record<string, unknown>,\n> = MutationFnParams<T> & {\n  idempotencyKey: string\n}\n\nexport type OfflineMutationFn<T extends object = Record<string, unknown>> = (\n  params: OfflineMutationFnParams<T>\n) => Promise<any>\n\n// Simplified mutation structure for serialization\nexport interface SerializedMutation {\n  globalKey: string\n  type: string\n  modified: any\n  original: any\n  collectionId: string\n}\n\nexport interface SerializedError {\n  name: string\n  message: string\n  stack?: string\n}\n\nexport interface SerializedSpanContext {\n  traceId: string\n  spanId: string\n  traceFlags: number\n  traceState?: string\n}\n\n// In-memory representation with full PendingMutation objects\nexport interface OfflineTransaction {\n  id: string\n  mutationFnName: string\n  mutations: Array<PendingMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: Date\n  retryCount: number\n  nextAttemptAt: number\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Serialized representation for storage\nexport interface SerializedOfflineTransaction {\n  id: string\n  mutationFnName: string\n  mutations: Array<SerializedMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: Date\n  retryCount: number\n  nextAttemptAt: number\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\nexport interface OfflineConfig {\n  collections: Record<string, Collection>\n  mutationFns: Record<string, OfflineMutationFn>\n  storage?: StorageAdapter\n  maxConcurrency?: number\n  jitter?: boolean\n  beforeRetry?: (\n    transactions: Array<OfflineTransaction>\n  ) => Array<OfflineTransaction>\n  onUnknownMutationFn?: (name: string, tx: OfflineTransaction) => void\n  onLeadershipChange?: (isLeader: boolean) => void\n  leaderElection?: LeaderElection\n  otel?: {\n    endpoint: string\n    headers?: Record<string, string>\n  }\n}\n\nexport interface StorageAdapter {\n  get: (key: string) => Promise<string | null>\n  set: (key: string, value: string) => Promise<void>\n  delete: (key: string) => Promise<void>\n  keys: () => Promise<Array<string>>\n  clear: () => Promise<void>\n}\n\nexport interface RetryPolicy {\n  calculateDelay: (retryCount: number) => number\n  shouldRetry: (error: Error, retryCount: number) => boolean\n}\n\nexport interface LeaderElection {\n  requestLeadership: () => Promise<boolean>\n  releaseLeadership: () => void\n  isLeader: () => boolean\n  onLeadershipChange: (callback: (isLeader: boolean) => void) => () => void\n}\n\nexport interface OnlineDetector {\n  subscribe: (callback: () => void) => () => void\n  notifyOnline: () => void\n}\n\nexport interface CreateOfflineTransactionOptions {\n  id?: string\n  mutationFnName: string\n  autoCommit?: boolean\n  idempotencyKey?: string\n  metadata?: Record<string, any>\n}\n\nexport interface CreateOfflineActionOptions<T> {\n  mutationFnName: string\n  onMutate: (variables: T) => void\n}\n\nexport class NonRetriableError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n"],"names":[],"mappings":"AA+HO,MAAM,0BAA0B,MAAM;AAAA,EAC3C,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;"}
+{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  Collection,\n  MutationFnParams,\n  PendingMutation,\n} from \"@tanstack/db\"\n\n// Extended mutation function that includes idempotency key\nexport type OfflineMutationFnParams<\n  T extends object = Record<string, unknown>,\n> = MutationFnParams<T> & {\n  idempotencyKey: string\n}\n\nexport type OfflineMutationFn<T extends object = Record<string, unknown>> = (\n  params: OfflineMutationFnParams<T>\n) => Promise<any>\n\n// Simplified mutation structure for serialization\nexport interface SerializedMutation {\n  globalKey: string\n  type: string\n  modified: any\n  original: any\n  collectionId: string\n}\n\nexport interface SerializedError {\n  name: string\n  message: string\n  stack?: string\n}\n\nexport interface SerializedSpanContext {\n  traceId: string\n  spanId: string\n  traceFlags: number\n  traceState?: string\n}\n\n// In-memory representation with full PendingMutation objects\nexport interface OfflineTransaction {\n  id: string\n  mutationFnName: string\n  mutations: Array<PendingMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: Date\n  retryCount: number\n  nextAttemptAt: number\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Serialized representation for storage\nexport interface SerializedOfflineTransaction {\n  id: string\n  mutationFnName: string\n  mutations: Array<SerializedMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: Date\n  retryCount: number\n  nextAttemptAt: number\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Storage diagnostics and mode\nexport type OfflineMode = `offline` | `online-only`\n\nexport type StorageDiagnosticCode =\n  | `STORAGE_AVAILABLE`\n  | `INDEXEDDB_UNAVAILABLE`\n  | `LOCALSTORAGE_UNAVAILABLE`\n  | `STORAGE_BLOCKED`\n  | `QUOTA_EXCEEDED`\n  | `UNKNOWN_ERROR`\n\nexport interface StorageDiagnostic {\n  code: StorageDiagnosticCode\n  mode: OfflineMode\n  message: string\n  error?: Error\n}\n\nexport interface OfflineConfig {\n  collections: Record<string, Collection>\n  mutationFns: Record<string, OfflineMutationFn>\n  storage?: StorageAdapter\n  maxConcurrency?: number\n  jitter?: boolean\n  beforeRetry?: (\n    transactions: Array<OfflineTransaction>\n  ) => Array<OfflineTransaction>\n  onUnknownMutationFn?: (name: string, tx: OfflineTransaction) => void\n  onLeadershipChange?: (isLeader: boolean) => void\n  onStorageFailure?: (diagnostic: StorageDiagnostic) => void\n  leaderElection?: LeaderElection\n}\n\nexport interface StorageAdapter {\n  get: (key: string) => Promise<string | null>\n  set: (key: string, value: string) => Promise<void>\n  delete: (key: string) => Promise<void>\n  keys: () => Promise<Array<string>>\n  clear: () => Promise<void>\n}\n\nexport interface RetryPolicy {\n  calculateDelay: (retryCount: number) => number\n  shouldRetry: (error: Error, retryCount: number) => boolean\n}\n\nexport interface LeaderElection {\n  requestLeadership: () => Promise<boolean>\n  releaseLeadership: () => void\n  isLeader: () => boolean\n  onLeadershipChange: (callback: (isLeader: boolean) => void) => () => void\n}\n\nexport interface OnlineDetector {\n  subscribe: (callback: () => void) => () => void\n  notifyOnline: () => void\n}\n\nexport interface CreateOfflineTransactionOptions {\n  id?: string\n  mutationFnName: string\n  autoCommit?: boolean\n  idempotencyKey?: string\n  metadata?: Record<string, any>\n}\n\nexport interface CreateOfflineActionOptions<T> {\n  mutationFnName: string\n  onMutate: (variables: T) => void\n}\n\nexport class NonRetriableError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n"],"names":[],"mappings":"AA8IO,MAAM,0BAA0B,MAAM;AAAA,EAC3C,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/offline-transactions",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Offline-first transaction capabilities for TanStack DB",
   "author": "TanStack",
   "license": "MIT",
@@ -42,17 +42,9 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "build": "vite build",
-    "dev": "vite build --watch",
-    "test": "vitest",
-    "test:watch": "vitest --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@tanstack/db": "workspace:*"
+    "@tanstack/db": "0.4.17"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -61,6 +53,14 @@
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "@tanstack/db": "workspace:*"
+    "@tanstack/db": "*"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
   }
-}
+}

package/src/OfflineExecutor.ts

@@ -28,23 +28,36 @@ import type {
   CreateOfflineTransactionOptions,
   LeaderElection,
   OfflineConfig,
+  OfflineMode,
   OfflineTransaction,
   StorageAdapter,
+  StorageDiagnostic,
 } from "./types"
 import type { Transaction } from "@tanstack/db"
 
 export class OfflineExecutor {
   private config: OfflineConfig
-  private storage: StorageAdapter
-  private outbox: OutboxManager
+
+  // @ts-expect-error - Set during async initialization in initialize()
+  private storage: StorageAdapter | null
+  private outbox: OutboxManager | null
   private scheduler: KeyScheduler
-  private executor: TransactionExecutor
-  private leaderElection: LeaderElection
+  private executor: TransactionExecutor | null
+  private leaderElection: LeaderElection | null
   private onlineDetector: DefaultOnlineDetector
   private isLeaderState = false
   private unsubscribeOnline: (() => void) | null = null
   private unsubscribeLeadership: (() => void) | null = null
 
+  // Public diagnostic properties
+  public readonly mode: OfflineMode
+  public readonly storageDiagnostic: StorageDiagnostic
+
+  // Track initialization completion
+  private initPromise: Promise<void>
+  private initResolve!: () => void
+  private initReject!: (error: Error) => void
+
   // Coordination mechanism for blocking transactions
   private pendingTransactionPromises: Map<
     string,
@@ -57,35 +70,109 @@ export class OfflineExecutor {
 
   constructor(config: OfflineConfig) {
     this.config = config
-    this.storage = this.createStorage()
-    this.outbox = new OutboxManager(this.storage, this.config.collections)
     this.scheduler = new KeyScheduler()
-    this.executor = new TransactionExecutor(
-      this.scheduler,
-      this.outbox,
-      this.config,
-      this
-    )
-    this.leaderElection = this.createLeaderElection()
     this.onlineDetector = new DefaultOnlineDetector()
 
-    this.setupEventListeners()
+    // Initialize as pending - will be set by async initialization
+    this.storage = null
+    this.outbox = null
+    this.executor = null
+    this.leaderElection = null
+
+    // Temporary diagnostic - will be updated by async initialization
+    this.mode = `offline`
+    this.storageDiagnostic = {
+      code: `STORAGE_AVAILABLE`,
+      mode: `offline`,
+      message: `Initializing storage...`,
+    }
+
+    // Create initialization promise
+    this.initPromise = new Promise((resolve, reject) => {
+      this.initResolve = resolve
+      this.initReject = reject
+    })
+
     this.initialize()
   }
 
-  private createStorage(): StorageAdapter {
+  /**
+   * Probe storage availability and create appropriate adapter.
+   * Returns null if no storage is available (online-only mode).
+   */
+  private async createStorage(): Promise<{
+    storage: StorageAdapter | null
+    diagnostic: StorageDiagnostic
+  }> {
+    // If user provided custom storage, use it without probing
     if (this.config.storage) {
-      return this.config.storage
+      return {
+        storage: this.config.storage,
+        diagnostic: {
+          code: `STORAGE_AVAILABLE`,
+          mode: `offline`,
+          message: `Using custom storage adapter`,
+        },
+      }
     }
 
-    try {
-      return new IndexedDBAdapter()
-    } catch (error) {
-      console.warn(
-        `IndexedDB not available, falling back to localStorage:`,
-        error
-      )
-      return new LocalStorageAdapter()
+    // Probe IndexedDB first
+    const idbProbe = await IndexedDBAdapter.probe()
+    if (idbProbe.available) {
+      return {
+        storage: new IndexedDBAdapter(),
+        diagnostic: {
+          code: `STORAGE_AVAILABLE`,
+          mode: `offline`,
+          message: `Using IndexedDB for offline storage`,
+        },
+      }
+    }
+
+    // IndexedDB failed, try localStorage
+    const lsProbe = LocalStorageAdapter.probe()
+    if (lsProbe.available) {
+      return {
+        storage: new LocalStorageAdapter(),
+        diagnostic: {
+          code: `INDEXEDDB_UNAVAILABLE`,
+          mode: `offline`,
+          message: `IndexedDB unavailable, using localStorage fallback`,
+          error: idbProbe.error,
+        },
+      }
+    }
+
+    // Both failed - determine the diagnostic code
+    const isSecurityError =
+      idbProbe.error?.name === `SecurityError` ||
+      lsProbe.error?.name === `SecurityError`
+    const isQuotaError =
+      idbProbe.error?.name === `QuotaExceededError` ||
+      lsProbe.error?.name === `QuotaExceededError`
+
+    let code: StorageDiagnostic[`code`]
+    let message: string
+
+    if (isSecurityError) {
+      code = `STORAGE_BLOCKED`
+      message = `Storage blocked (private mode or security restrictions). Running in online-only mode.`
+    } else if (isQuotaError) {
+      code = `QUOTA_EXCEEDED`
+      message = `Storage quota exceeded. Running in online-only mode.`
+    } else {
+      code = `UNKNOWN_ERROR`
+      message = `Storage unavailable due to unknown error. Running in online-only mode.`
+    }
+
+    return {
+      storage: null,
+      diagnostic: {
+        code,
+        mode: `online-only`,
+        message,
+        error: idbProbe.error || lsProbe.error,
+      },
     }
   }
 
@@ -110,22 +197,25 @@ export class OfflineExecutor {
   }
 
   private setupEventListeners(): void {
-    this.unsubscribeLeadership = this.leaderElection.onLeadershipChange(
-      (isLeader) => {
-        this.isLeaderState = isLeader
-
-        if (this.config.onLeadershipChange) {
-          this.config.onLeadershipChange(isLeader)
+    // Only set up leader election listeners if we have storage
+    if (this.leaderElection) {
+      this.unsubscribeLeadership = this.leaderElection.onLeadershipChange(
+        (isLeader) => {
+          this.isLeaderState = isLeader
+
+          if (this.config.onLeadershipChange) {
+            this.config.onLeadershipChange(isLeader)
+          }
+
+          if (isLeader) {
+            this.loadAndReplayTransactions()
+          }
         }
-
-        if (isLeader) {
-          this.loadAndReplayTransactions()
-        }
-      }
-    )
+      )
+    }
 
     this.unsubscribeOnline = this.onlineDetector.subscribe(() => {
-      if (this.isOfflineEnabled) {
+      if (this.isOfflineEnabled && this.executor) {
         // Reset retry delays so transactions can execute immediately when back online
         this.executor.resetRetryDelays()
         this.executor.executeAll().catch((error) => {
@@ -141,19 +231,65 @@ export class OfflineExecutor {
   private async initialize(): Promise<void> {
     return withSpan(`executor.initialize`, {}, async (span) => {
       try {
+        // Probe storage and create adapter
+        const { storage, diagnostic } = await this.createStorage()
+
+        // Cast to writable to set readonly properties
+        ;(this as any).storage = storage
+        ;(this as any).storageDiagnostic = diagnostic
+        ;(this as any).mode = diagnostic.mode
+
+        span.setAttribute(`storage.mode`, diagnostic.mode)
+        span.setAttribute(`storage.code`, diagnostic.code)
+
+        if (!storage) {
+          // Online-only mode - notify callback and skip offline setup
+          if (this.config.onStorageFailure) {
+            this.config.onStorageFailure(diagnostic)
+          }
+          span.setAttribute(`result`, `online-only`)
+          this.initResolve()
+          return
+        }
+
+        // Storage available - set up offline components
+        this.outbox = new OutboxManager(storage, this.config.collections)
+        this.executor = new TransactionExecutor(
+          this.scheduler,
+          this.outbox,
+          this.config,
+          this
+        )
+        this.leaderElection = this.createLeaderElection()
+
+        // Request leadership first
         const isLeader = await this.leaderElection.requestLeadership()
         span.setAttribute(`isLeader`, isLeader)
 
+        // Set up event listeners after leadership is established
+        // This prevents the callback from being called multiple times
+        this.setupEventListeners()
+
         if (isLeader) {
           await this.loadAndReplayTransactions()
         }
+        span.setAttribute(`result`, `offline-enabled`)
+        this.initResolve()
       } catch (error) {
         console.warn(`Failed to initialize offline executor:`, error)
+        span.setAttribute(`result`, `failed`)
+        this.initReject(
+          error instanceof Error ? error : new Error(String(error))
+        )
       }
     })
   }
 
   private async loadAndReplayTransactions(): Promise<void> {
+    if (!this.executor) {
+      return
+    }
+
     try {
       await this.executor.loadPendingTransactions()
       await this.executor.executeAll()
@@ -163,7 +299,7 @@ export class OfflineExecutor {
   }
 
   get isOfflineEnabled(): boolean {
-    return this.isLeaderState
+    return this.mode === `offline` && this.isLeaderState
   }
 
   createOfflineTransaction(
@@ -237,6 +373,9 @@ export class OfflineExecutor {
   private async persistTransaction(
     transaction: OfflineTransaction
   ): Promise<void> {
+    // Wait for initialization to complete
+    await this.initPromise
+
     return withNestedSpan(
       `executor.persistTransaction`,
       {
@@ -244,7 +383,7 @@ export class OfflineExecutor {
         "transaction.mutationFnName": transaction.mutationFnName,
       },
       async (span) => {
-        if (!this.isOfflineEnabled) {
+        if (!this.isOfflineEnabled || !this.outbox || !this.executor) {
           span.setAttribute(`result`, `skipped_not_leader`)
           this.resolveTransaction(transaction.id, undefined)
           return
@@ -307,14 +446,23 @@ export class OfflineExecutor {
   }
 
   async removeFromOutbox(id: string): Promise<void> {
+    if (!this.outbox) {
+      return
+    }
     await this.outbox.remove(id)
   }
 
   async peekOutbox(): Promise<Array<OfflineTransaction>> {
+    if (!this.outbox) {
+      return []
+    }
     return this.outbox.getAll()
   }
 
   async clearOutbox(): Promise<void> {
+    if (!this.outbox || !this.executor) {
+      return
+    }
     await this.outbox.clear()
     this.executor.clear()
   }
@@ -324,10 +472,16 @@ export class OfflineExecutor {
   }
 
   getPendingCount(): number {
+    if (!this.executor) {
+      return 0
+    }
     return this.executor.getPendingCount()
   }
 
   getRunningCount(): number {
+    if (!this.executor) {
+      return 0
+    }
     return this.executor.getRunningCount()
   }
 
@@ -346,12 +500,15 @@ export class OfflineExecutor {
       this.unsubscribeLeadership = null
     }
 
-    this.leaderElection.releaseLeadership()
-    this.onlineDetector.dispose()
+    if (this.leaderElection) {
+      this.leaderElection.releaseLeadership()
 
-    if (`dispose` in this.leaderElection) {
-      ;(this.leaderElection as any).dispose()
+      if (`dispose` in this.leaderElection) {
+        ;(this.leaderElection as any).dispose()
+      }
     }
+
+    this.onlineDetector.dispose()
   }
 }
 

package/src/api/OfflineAction.ts

@@ -1,4 +1,5 @@
 import { SpanStatusCode, context, trace } from "@opentelemetry/api"
+import { OnMutateMustBeSynchronousError } from "@tanstack/db"
 import { OfflineTransaction } from "./OfflineTransaction"
 import type { Transaction } from "@tanstack/db"
 import type {
@@ -7,6 +8,14 @@ import type {
   OfflineTransaction as OfflineTransactionType,
 } from "../types"
 
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    !!value &&
+    (typeof value === `object` || typeof value === `function`) &&
+    typeof (value as { then?: unknown }).then === `function`
+  )
+}
+
 export function createOfflineAction<T>(
   options: CreateOfflineActionOptions<T>,
   mutationFn: OfflineMutationFn,
@@ -29,7 +38,11 @@ export function createOfflineAction<T>(
 
     const transaction = offlineTransaction.mutate(() => {
       console.log(`mutate`)
-      onMutate(variables)
+      const maybePromise = onMutate(variables) as unknown
+
+      if (isPromiseLike(maybePromise)) {
+        throw new OnMutateMustBeSynchronousError()
+      }
     })
 
     // Immediately commit with span instrumentation

package/src/index.ts

@@ -5,7 +5,10 @@ export { OfflineExecutor, startOfflineExecutor } from "./OfflineExecutor"
 export type {
   OfflineTransaction,
   OfflineConfig,
+  OfflineMode,
   StorageAdapter,
+  StorageDiagnostic,
+  StorageDiagnosticCode,
   RetryPolicy,
   LeaderElection,
   OnlineDetector,

package/src/storage/IndexedDBAdapter.ts

@@ -11,6 +11,53 @@ export class IndexedDBAdapter extends BaseStorageAdapter {
     this.storeName = storeName
   }
 
+  /**
+   * Probe IndexedDB availability by attempting to open a test database.
+   * This catches private mode and other restrictions that block IndexedDB.
+   */
+  static async probe(): Promise<{ available: boolean; error?: Error }> {
+    // Check if IndexedDB exists
+    if (typeof indexedDB === `undefined`) {
+      return {
+        available: false,
+        error: new Error(`IndexedDB is not available in this environment`),
+      }
+    }
+
+    // Try to actually open a test database to verify it works
+    try {
+      const testDbName = `__offline-tx-probe__`
+      const request = indexedDB.open(testDbName, 1)
+
+      return new Promise((resolve) => {
+        request.onerror = () => {
+          const error = request.error || new Error(`IndexedDB open failed`)
+          resolve({ available: false, error })
+        }
+
+        request.onsuccess = () => {
+          // Clean up test database
+          const db = request.result
+          db.close()
+          indexedDB.deleteDatabase(testDbName)
+          resolve({ available: true })
+        }
+
+        request.onblocked = () => {
+          resolve({
+            available: false,
+            error: new Error(`IndexedDB is blocked`),
+          })
+        }
+      })
+    } catch (error) {
+      return {
+        available: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+      }
+    }
+  }
+
   private async openDB(): Promise<IDBDatabase> {
     if (this.db) {
       return this.db