@sweidos/eidos 1.0.22 → 1.0.24

package/dist/testing.d.ts

@@ -0,0 +1,98 @@
+import { EidosState, ReplayResult } from '@sweidos/eidos';
+
+export interface MockOfflineOptions {
+    /**
+     * Also stub `globalThis.fetch` to throw a TypeError (simulates a hard
+     * network failure for code that calls fetch directly, outside the Eidos
+     * resource layer). Default: false.
+     */
+    stubFetch?: boolean;
+}
+/**
+ * Put Eidos into offline mode. Actions with `reliability: 'neverLose'` will
+ * be queued instead of executed. Call `mockOnline()` to restore.
+ *
+ * @example
+ * beforeEach(() => mockOffline())
+ * afterEach(() => mockOnline())
+ */
+export declare function mockOffline(options?: MockOfflineOptions): void;
+/**
+ * Restore online mode. Removes any fetch stub installed by `mockOffline`.
+ */
+export declare function mockOnline(): void;
+/**
+ * Replay the action queue immediately and return the result.
+ * Forces `isOnline = true` first so the replay is never skipped.
+ *
+ * @example
+ * mockOffline()
+ * await savePost(draft)        // queued
+ * const result = await drainQueue()
+ * expect(result.succeeded).toBe(1)
+ */
+export declare function drainQueue(): Promise<ReplayResult>;
+export interface WaitForQueueDrainOptions {
+    /** Maximum wait in milliseconds. Default: 5000. */
+    timeout?: number;
+    /** Poll interval in milliseconds. Default: 50. */
+    interval?: number;
+}
+/**
+ * Wait until the action queue contains no pending or replaying items.
+ * Resolves immediately if the queue is already clear.
+ * Rejects with a timeout error if items remain after `timeout` ms.
+ *
+ * @example
+ * mockOnline()
+ * await waitForQueueDrain()
+ * expect(getEidosState().queue).toHaveLength(0)
+ */
+export declare function waitForQueueDrain(options?: WaitForQueueDrainOptions): Promise<void>;
+/** Default Eidos cache namespace written by the service worker. */
+export declare const EIDOS_CACHE_NAME = "eidos-resources-v1";
+/**
+ * Read a cached Response for a URL from Eidos Cache Storage.
+ * Returns `undefined` if the entry is not cached.
+ *
+ * Requires the Cache API (`caches` global). In jsdom, provide a mock (e.g.
+ * `vitest-fetch-mock`, `jest-fetch-mock`, or a custom `setupFiles` polyfill).
+ *
+ * @example
+ * const res = await getCachedEntry('/api/user/1')
+ * expect(res).toBeDefined()
+ * expect(await res!.json()).toMatchObject({ id: 1 })
+ */
+export declare function getCachedEntry(url: string, cacheName?: string): Promise<Response | undefined>;
+/**
+ * Delete all entries from an Eidos cache namespace.
+ * Call in `afterEach` to prevent cache state leaking between tests.
+ *
+ * @example
+ * afterEach(() => clearEidosCache())
+ */
+export declare function clearEidosCache(cacheName?: string): Promise<void>;
+/**
+ * Full reset — call in `beforeEach` to start each test from a clean slate.
+ *
+ * - Resets runtime initialisation flag (`_resetEidos`) so `initEidos()` can
+ *   be called again without the duplicate-init guard firing.
+ * - Clears IDB action queue and in-memory store queue.
+ * - Restores online state and removes any fetch stub from `mockOffline`.
+ * - Clears registered resource entries and resets SW status.
+ *
+ * @example
+ * beforeEach(async () => {
+ *   await resetEidos()
+ * })
+ */
+export declare function resetEidos(): Promise<void>;
+/**
+ * Return a plain-object snapshot of the current Eidos store state.
+ * Useful for assertions without importing `useEidosStore` directly.
+ *
+ * @example
+ * expect(getEidosState().isOnline).toBe(false)
+ * expect(getEidosState().queue).toHaveLength(1)
+ */
+export declare function getEidosState(): EidosState;

package/dist/testing.js

@@ -0,0 +1,86 @@
+import { useEidosStore, replayQueue, _resetEidos, clearQueue } from "@sweidos/eidos";
+let _originalFetch = null;
+function mockOffline(options = {}) {
+  useEidosStore.getState().setOnline(false);
+  if (options.stubFetch && _originalFetch === null) {
+    _originalFetch = globalThis.fetch;
+    globalThis.fetch = () => Promise.reject(
+      new TypeError("Network request failed (stubbed by @sweidos/eidos/testing)")
+    );
+  }
+}
+function mockOnline() {
+  useEidosStore.getState().setOnline(true);
+  if (_originalFetch !== null) {
+    globalThis.fetch = _originalFetch;
+    _originalFetch = null;
+  }
+}
+async function drainQueue() {
+  useEidosStore.getState().setOnline(true);
+  return replayQueue();
+}
+function waitForQueueDrain(options = {}) {
+  const timeout = options.timeout ?? 5e3;
+  const interval = options.interval ?? 50;
+  const deadline = Date.now() + timeout;
+  return new Promise((resolve, reject) => {
+    function check() {
+      const { queue } = useEidosStore.getState();
+      const active = queue.filter(
+        (q) => q.status === "pending" || q.status === "replaying"
+      );
+      if (active.length === 0) {
+        resolve();
+        return;
+      }
+      if (Date.now() >= deadline) {
+        reject(
+          new Error(
+            `[eidos/testing] waitForQueueDrain timed out after ${timeout}ms. ${active.length} item(s) still active (statuses: ${active.map((q) => q.status).join(", ")}).`
+          )
+        );
+        return;
+      }
+      setTimeout(check, interval);
+    }
+    check();
+  });
+}
+const EIDOS_CACHE_NAME = "eidos-resources-v1";
+async function getCachedEntry(url, cacheName = EIDOS_CACHE_NAME) {
+  if (typeof caches === "undefined") return void 0;
+  const cache = await caches.open(cacheName);
+  const match = await cache.match(url);
+  return match ?? void 0;
+}
+async function clearEidosCache(cacheName = EIDOS_CACHE_NAME) {
+  if (typeof caches === "undefined") return;
+  await caches.delete(cacheName);
+}
+async function resetEidos() {
+  _resetEidos();
+  await clearQueue();
+  mockOnline();
+  useEidosStore.setState((s) => ({
+    ...s,
+    resources: {},
+    swStatus: "idle",
+    swError: void 0
+  }));
+}
+function getEidosState() {
+  const { isOnline, swStatus, swError, resources, queue } = useEidosStore.getState();
+  return { isOnline, swStatus, swError, resources, queue };
+}
+export {
+  EIDOS_CACHE_NAME,
+  clearEidosCache,
+  drainQueue,
+  getCachedEntry,
+  getEidosState,
+  mockOffline,
+  mockOnline,
+  resetEidos,
+  waitForQueueDrain
+};

package/dist/version.js

@@ -1,4 +1,4 @@
-const o = "1.0.12";
+const o = "1.0.24";
 export {
   o as VERSION
 };

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sources":["../src/version.ts"],"sourcesContent":["export const VERSION = '1.0.12'\n"],"names":["VERSION"],"mappings":"AAAO,MAAMA,IAAU;"}
+{"version":3,"file":"version.js","sources":["../src/version.ts"],"sourcesContent":["export const VERSION = '1.0.24'\n"],"names":["VERSION"],"mappings":"AAAO,MAAMA,IAAU;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweidos/eidos",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "Describe intent. The runtime figures out how. An abstraction layer for offline-first web apps.",
   "author": "Aditya Raj",
   "license": "MIT",
@@ -43,6 +43,11 @@
       "import": "./dist/query.js",
       "require": "./dist/query.cjs.js",
       "types": "./dist/query.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs.js",
+      "types": "./dist/testing.d.ts"
     }
   },
   "files": [
@@ -83,7 +88,7 @@
     "vitest": "^2.1.9"
   },
   "scripts": {
-    "build": "vite build && vite build --config vite.cjs.config.ts && vite build --config vite.plugin.config.ts && vite build --config vite.query.config.ts && node scripts/copy-sw.mjs",
+    "build": "vite build && vite build --config vite.cjs.config.ts && vite build --config vite.plugin.config.ts && vite build --config vite.query.config.ts && vite build --config vite.testing.config.ts && node scripts/copy-sw.mjs",
     "dev": "vite build --watch",
     "type-check": "tsc --noEmit",
     "test": "vitest run",