@getforma/core 0.9.0 → 1.0.0

package/dist/server.js

@@ -0,0 +1,166 @@
+import { batch } from './chunk-OUVOAYIO.js';
+import { createSignal } from './chunk-OZCHIVAZ.js';
+
+// src/server/action.ts
+function createAction(serverFn, options) {
+  const [pending, setPending] = createSignal(false);
+  const [error, setError] = createSignal(void 0);
+  const action = async (...args) => {
+    setPending(true);
+    setError(void 0);
+    if (options?.optimistic) {
+      try {
+        batch(() => options.optimistic(...args));
+      } catch {
+      }
+    }
+    try {
+      const result = await serverFn(...args);
+      if (options?.onSuccess) {
+        batch(() => options.onSuccess(result, ...args));
+      }
+      if (options?.invalidates) {
+        for (const resource of options.invalidates) {
+          resource.refetch();
+        }
+      }
+      setPending(false);
+      return result;
+    } catch (err) {
+      if (options?.onError) {
+        try {
+          batch(() => options.onError(err, ...args));
+        } catch {
+        }
+      }
+      setError(err);
+      setPending(false);
+      throw err;
+    }
+  };
+  const typedAction = action;
+  typedAction.pending = pending;
+  typedAction.error = error;
+  typedAction.clearError = () => setError(void 0);
+  return typedAction;
+}
+
+// src/server/mutation.ts
+var resourceRegistry = /* @__PURE__ */ new Map();
+function registerResource(key, resource) {
+  resourceRegistry.set(key, resource);
+}
+function unregisterResource(key) {
+  resourceRegistry.delete(key);
+}
+function applyRevalidation(revalidateData) {
+  for (const [key, freshData] of Object.entries(revalidateData)) {
+    const resource = resourceRegistry.get(key);
+    if (resource) {
+      resource.mutate(freshData);
+    }
+  }
+}
+function enableAutoRevalidation() {
+  if (typeof window === "undefined") {
+    return () => {
+    };
+  }
+  const handler = (event) => {
+    const detail = event.detail;
+    if (detail && typeof detail === "object") {
+      applyRevalidation(detail);
+    }
+  };
+  window.addEventListener("forma:revalidate", handler);
+  return () => window.removeEventListener("forma:revalidate", handler);
+}
+function withRevalidation(data, revalidate) {
+  return { data, __revalidate: revalidate };
+}
+
+// src/server/rpc-client.ts
+function $$serverFunction(endpoint) {
+  const rpcFn = async (...args) => {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Forma-RPC": "1"
+      },
+      body: JSON.stringify({ args })
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Server function failed (${response.status}): ${errorText}`);
+    }
+    const result = await response.json();
+    if (result && typeof result === "object" && "__revalidate" in result) {
+      if (typeof window !== "undefined") {
+        window.dispatchEvent(new CustomEvent("forma:revalidate", {
+          detail: result.__revalidate
+        }));
+      }
+      return result.data;
+    }
+    return result;
+  };
+  return rpcFn;
+}
+
+// src/server/rpc-handler.ts
+var registry = /* @__PURE__ */ new Map();
+function registerServerFunction(endpoint, fn) {
+  registry.set(endpoint, fn);
+}
+function getServerFunction(endpoint) {
+  return registry.get(endpoint);
+}
+function getRegisteredEndpoints() {
+  return [...registry.keys()];
+}
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+async function handleRPC(endpoint, body, revalidateData) {
+  const endpointName = endpoint.split("/").pop() ?? "";
+  if (FORBIDDEN_KEYS.has(endpointName)) {
+    return { error: "Forbidden endpoint name" };
+  }
+  const fn = registry.get(endpoint);
+  if (!fn) {
+    return { error: `Unknown server function: ${endpoint}` };
+  }
+  try {
+    const result = await fn(...body.args);
+    if (revalidateData) {
+      return { data: result, __revalidate: revalidateData };
+    }
+    return { data: result };
+  } catch (err) {
+    const isDev = typeof process !== "undefined" && process.env?.NODE_ENV === "development";
+    const message = isDev && err instanceof Error ? err.message : "Internal server error";
+    return { error: message };
+  }
+}
+function createRPCMiddleware() {
+  return async (req, res) => {
+    if (req.method !== "POST") {
+      res.status(405).json({ error: "Method not allowed" });
+      return;
+    }
+    const body = req.body;
+    if (!body || !Array.isArray(body.args)) {
+      res.status(400).json({ error: "Invalid RPC request: missing args array" });
+      return;
+    }
+    const result = await handleRPC(req.url, body);
+    if (result.error) {
+      res.status(500).json(result);
+    } else {
+      res.json(result);
+    }
+  };
+}
+
+export { $$serverFunction, applyRevalidation, createAction, createRPCMiddleware, enableAutoRevalidation, getRegisteredEndpoints, getServerFunction, handleRPC, registerResource, registerServerFunction, unregisterResource, withRevalidation };
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/action.ts","../src/server/mutation.ts","../src/server/rpc-client.ts","../src/server/rpc-handler.ts"],"names":[],"mappings":"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","file":"server.js","sourcesContent":["/**\n * FormaJS Server - Action\n *\n * Creates an action that wraps a server function with optimistic UI support.\n * The action immediately applies an optimistic update, then reconciles when\n * the server responds (or rolls back on error).\n */\n\nimport { createSignal, batch } from '../reactive/index.js';\nimport type { Resource } from '../reactive/resource.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface ActionOptions<Args extends unknown[], Result> {\n  /**\n   * Apply an optimistic update immediately when the action is called.\n   * This runs BEFORE the server function.\n   * Store whatever you need to roll back in the return value or via closures.\n   */\n  optimistic?: (...args: Args) => void;\n\n  /**\n   * Called when the server function resolves successfully.\n   * Use this to apply the server result to local state.\n   */\n  onSuccess?: (result: Result, ...args: Args) => void;\n\n  /**\n   * Called when the server function rejects.\n   * Use this to roll back the optimistic update.\n   */\n  onError?: (error: unknown, ...args: Args) => void;\n\n  /**\n   * Resources to refetch after the action completes successfully.\n   * Used with single-flight mutations: if the server response includes\n   * revalidation data, these resources are updated without a refetch.\n   */\n  invalidates?: Resource<unknown>[];\n}\n\nexport interface Action<Args extends unknown[], Result> {\n  /** Execute the action. */\n  (...args: Args): Promise<Result>;\n  /** Whether the action is currently in-flight. */\n  pending: () => boolean;\n  /** The last error from the action (or undefined). */\n  error: () => unknown;\n  /** Clear the error state. */\n  clearError: () => void;\n}\n\n/**\n * Create an action that wraps a server function with optimistic UI.\n *\n * ```ts\n * const addTodo = createAction(\n *   serverCreateTodo,\n *   {\n *     optimistic: (text) => {\n *       // Immediately add to local list\n *       setTodos(prev => [...prev, { text, done: false, id: 'temp' }]);\n *     },\n *     onSuccess: (result) => {\n *       // Replace temp item with server result\n *       setTodos(prev => prev.map(t => t.id === 'temp' ? result : t));\n *     },\n *     onError: (err, text) => {\n *       // Remove the optimistic item\n *       setTodos(prev => prev.filter(t => t.id !== 'temp'));\n *     },\n *     invalidates: [todosResource],\n *   },\n * );\n *\n * // Use:\n * await addTodo('Buy milk');\n * ```\n */\nexport function createAction<Args extends unknown[], Result>(\n  serverFn: (...args: Args) => Promise<Result>,\n  options?: ActionOptions<Args, Result>,\n): Action<Args, Result> {\n  const [pending, setPending] = createSignal(false);\n  const [error, setError] = createSignal<unknown>(undefined);\n\n  const action = async (...args: Args): Promise<Result> => {\n    setPending(true);\n    setError(undefined);\n\n    // Apply optimistic update immediately\n    if (options?.optimistic) {\n      try {\n        batch(() => options.optimistic!(...args));\n      } catch {\n        // Swallow errors in optimistic callback\n      }\n    }\n\n    try {\n      const result = await serverFn(...args);\n\n      // Apply success handler\n      if (options?.onSuccess) {\n        batch(() => options.onSuccess!(result, ...args));\n      }\n\n      // Revalidate dependent resources\n      if (options?.invalidates) {\n        for (const resource of options.invalidates) {\n          resource.refetch();\n        }\n      }\n\n      setPending(false);\n      return result;\n    } catch (err) {\n      // Apply error/rollback handler\n      if (options?.onError) {\n        try {\n          batch(() => options.onError!(err, ...args));\n        } catch {\n          // Swallow errors in rollback\n        }\n      }\n\n      setError(err);\n      setPending(false);\n      throw err;\n    }\n  };\n\n  // Attach signal accessors to the action function\n  const typedAction = action as Action<Args, Result>;\n  typedAction.pending = pending;\n  typedAction.error = error;\n  typedAction.clearError = () => setError(undefined);\n\n  return typedAction;\n}\n","/**\n * FormaJS Server - Mutation\n *\n * Single-flight mutation pattern: the server response carries both the\n * mutation result AND fresh data for dependent resources in one round trip.\n *\n * Without single-flight:\n *   Client -> Server: createTodo(\"Buy milk\")\n *   Server -> Client: { id: 1, text: \"Buy milk\" }\n *   Client -> Server: GET /api/todos (refetch to update list)\n *   Server -> Client: [all todos]\n *\n * With single-flight:\n *   Client -> Server: createTodo(\"Buy milk\")\n *   Server -> Client: { data: {...}, __revalidate: { \"/api/todos\": [all todos] } }\n *   (No second request needed!)\n */\n\nimport type { Resource } from '../reactive/resource.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface MutationResponse<T> {\n  /** The mutation result. */\n  data: T;\n  /**\n   * Fresh data for dependent resources, keyed by resource identifier.\n   * When present, the client updates these resources directly instead of refetching.\n   */\n  __revalidate?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Resource registry for revalidation\n// ---------------------------------------------------------------------------\n\nconst resourceRegistry = new Map<string, Resource<unknown>>();\n\n/**\n * Register a resource with a key so it can be revalidated by single-flight mutations.\n *\n * ```ts\n * const todos = createResource(\n *   () => true,\n *   () => fetch('/api/todos').then(r => r.json()),\n * );\n * registerResource('/api/todos', todos);\n * ```\n */\nexport function registerResource(key: string, resource: Resource<unknown>): void {\n  resourceRegistry.set(key, resource);\n}\n\n/**\n * Unregister a resource (call on cleanup/unmount).\n */\nexport function unregisterResource(key: string): void {\n  resourceRegistry.delete(key);\n}\n\n/**\n * Apply revalidation data from a single-flight mutation response.\n * For each key in the revalidate map, find the matching resource\n * and mutate it directly with the fresh data (skipping a refetch).\n */\nexport function applyRevalidation(revalidateData: Record<string, unknown>): void {\n  for (const [key, freshData] of Object.entries(revalidateData)) {\n    const resource = resourceRegistry.get(key);\n    if (resource) {\n      resource.mutate(freshData);\n    }\n  }\n}\n\n/**\n * Listen for revalidation events dispatched by $$serverFunction.\n * Call this once during app initialization to enable automatic\n * single-flight mutation handling.\n *\n * ```ts\n * // In your app entry:\n * import { enableAutoRevalidation } from 'forma/server/mutation';\n * enableAutoRevalidation();\n * ```\n */\nexport function enableAutoRevalidation(): () => void {\n  if (typeof window === 'undefined') {\n    // SSR/Node.js — no-op\n    return () => {};\n  }\n\n  const handler = (event: Event) => {\n    const detail = (event as CustomEvent).detail;\n    if (detail && typeof detail === 'object') {\n      applyRevalidation(detail as Record<string, unknown>);\n    }\n  };\n\n  window.addEventListener('forma:revalidate', handler);\n\n  // Return cleanup function\n  return () => window.removeEventListener('forma:revalidate', handler);\n}\n\n/**\n * Wrap a server function response to include revalidation data.\n * Use this on the server side to enable single-flight mutations.\n *\n * ```ts\n * // Server-side:\n * async function createTodo(text: string) {\n *   \"use server\";\n *   const newTodo = await db.insert('todos', { text, done: false });\n *   const allTodos = await db.query('todos');\n *   return withRevalidation(newTodo, {\n *     '/api/todos': allTodos,\n *   });\n * }\n * ```\n */\nexport function withRevalidation<T>(data: T, revalidate: Record<string, unknown>): MutationResponse<T> {\n  return { data, __revalidate: revalidate };\n}\n","/**\n * FormaJS Server - RPC Client\n *\n * Provides the client-side stub function that replaces \"use server\" function\n * bodies after compilation. Each call becomes a fetch POST to the server endpoint.\n */\n\n/**\n * Create an RPC stub function for a server function.\n * This replaces the original function body on the client side.\n *\n * @param endpoint - The RPC endpoint path (e.g. \"/rpc/createTodo_a1b2c3\")\n * @returns An async function that sends args to the server and returns the result\n */\nexport function $$serverFunction<T extends (...args: unknown[]) => Promise<unknown>>(\n  endpoint: string,\n): T {\n  const rpcFn = async (...args: unknown[]): Promise<unknown> => {\n    const response = await fetch(endpoint, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        'X-Forma-RPC': '1',\n      },\n      body: JSON.stringify({ args }),\n    });\n\n    if (!response.ok) {\n      const errorText = await response.text();\n      throw new Error(`Server function failed (${response.status}): ${errorText}`);\n    }\n\n    const result = await response.json();\n\n    // If the response includes revalidation data (single-flight mutations),\n    // return it alongside the result\n    if (result && typeof result === 'object' && '__revalidate' in result) {\n      // Dispatch a custom event so createAction can pick up the revalidation data\n      if (typeof window !== 'undefined') {\n        window.dispatchEvent(new CustomEvent('forma:revalidate', {\n          detail: result.__revalidate,\n        }));\n      }\n      return result.data;\n    }\n\n    return result;\n  };\n\n  return rpcFn as T;\n}\n","/**\n * FormaJS Server - RPC Handler\n *\n * Server-side registry and request handler for \"use server\" functions.\n * Framework-agnostic — works with any Node.js HTTP server, Express, Hono, etc.\n */\n\nexport type ServerFunction = (...args: unknown[]) => Promise<unknown>;\n\n/** Registry of server functions by endpoint path. */\nconst registry = new Map<string, ServerFunction>();\n\n/**\n * Register a server function at a specific endpoint.\n * Called by the server-side compiled output.\n */\nexport function registerServerFunction(endpoint: string, fn: ServerFunction): void {\n  registry.set(endpoint, fn);\n}\n\n/**\n * Get a registered server function by endpoint.\n */\nexport function getServerFunction(endpoint: string): ServerFunction | undefined {\n  return registry.get(endpoint);\n}\n\n/**\n * Get all registered server function endpoints.\n */\nexport function getRegisteredEndpoints(): string[] {\n  return [...registry.keys()];\n}\n\nexport interface RPCRequest {\n  args: unknown[];\n}\n\nexport interface RPCResponse {\n  data?: unknown;\n  error?: string;\n  __revalidate?: Record<string, unknown>;\n}\n\n/**\n * Handle an incoming RPC request.\n * Call this from your HTTP server's request handler.\n *\n * Usage with any HTTP framework:\n * ```ts\n * import { handleRPC } from 'forma/server/rpc-handler';\n *\n * // Express example:\n * app.post('/rpc/:endpoint', async (req, res) => {\n *   const result = await handleRPC(req.path, req.body);\n *   res.json(result);\n * });\n *\n * // Hono example:\n * app.post('/rpc/*', async (c) => {\n *   const body = await c.req.json();\n *   const result = await handleRPC(c.req.path, body);\n *   return c.json(result);\n * });\n * ```\n *\n * @param endpoint - The full endpoint path (e.g. \"/rpc/createTodo_a1b2c3\")\n * @param body - The parsed request body containing { args: [...] }\n * @param revalidateData - Optional revalidation data to include in the response\n *                         (for single-flight mutations)\n */\n/** \"Crash Barrier\": block prototype pollution attacks via endpoint names. */\nconst FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);\n\nexport async function handleRPC(\n  endpoint: string,\n  body: RPCRequest,\n  revalidateData?: Record<string, unknown>,\n): Promise<RPCResponse> {\n  // Security: prevent prototype pollution via crafted endpoint names\n  const endpointName = endpoint.split('/').pop() ?? '';\n  if (FORBIDDEN_KEYS.has(endpointName)) {\n    return { error: 'Forbidden endpoint name' };\n  }\n\n  const fn = registry.get(endpoint);\n  if (!fn) {\n    return { error: `Unknown server function: ${endpoint}` };\n  }\n\n  try {\n    const result = await fn(...body.args);\n\n    if (revalidateData) {\n      return { data: result, __revalidate: revalidateData };\n    }\n\n    return { data: result };\n  } catch (err) {\n    // Don't leak internal error details to clients\n    const isDev = typeof process !== 'undefined'\n      && process.env?.NODE_ENV === 'development';\n    const message = isDev && err instanceof Error\n      ? err.message\n      : 'Internal server error';\n    return { error: message };\n  }\n}\n\n/**\n * Create a middleware-style handler for use with Express-like frameworks.\n *\n * ```ts\n * import { createRPCMiddleware } from 'forma/server/rpc-handler';\n * app.use('/rpc', createRPCMiddleware());\n * ```\n */\nexport function createRPCMiddleware() {\n  return async (req: { url: string; method: string; body?: unknown }, res: { json: (data: unknown) => void; status: (code: number) => { json: (data: unknown) => void } }) => {\n    if (req.method !== 'POST') {\n      res.status(405).json({ error: 'Method not allowed' });\n      return;\n    }\n\n    const body = req.body as RPCRequest;\n    if (!body || !Array.isArray(body.args)) {\n      res.status(400).json({ error: 'Invalid RPC request: missing args array' });\n      return;\n    }\n\n    const result = await handleRPC(req.url, body);\n    if (result.error) {\n      res.status(500).json(result);\n    } else {\n      res.json(result);\n    }\n  };\n}\n"]}

package/dist/{signal-B4_wQJHs.d.cts → signal-YlS1kgfh.d.cts}

@@ -50,4 +50,4 @@ interface SignalOptions<T> {
  */
 declare function createSignal<T>(initialValue: T, options?: SignalOptions<T>): [get: SignalGetter<T>, set: SignalSetter<T>];
 
-export { type SignalGetter as S, type SignalOptions as a, createSignal as c };
+export { type SignalGetter as S, type SignalOptions as a, type SignalSetter as b, createSignal as c };

package/dist/{signal-B4_wQJHs.d.ts → signal-YlS1kgfh.d.ts}

@@ -50,4 +50,4 @@ interface SignalOptions<T> {
  */
 declare function createSignal<T>(initialValue: T, options?: SignalOptions<T>): [get: SignalGetter<T>, set: SignalSetter<T>];
 
-export { type SignalGetter as S, type SignalOptions as a, createSignal as c };
+export { type SignalGetter as S, type SignalOptions as a, type SignalSetter as b, createSignal as c };

package/dist/storage.cjs

@@ -0,0 +1,151 @@
+'use strict';
+
+// src/storage/local.ts
+function createLocalStorage(key, options) {
+  const serialize = options?.serialize ?? JSON.stringify;
+  const deserialize = options?.deserialize ?? JSON.parse;
+  const validate = options?.validate;
+  return {
+    key,
+    get() {
+      try {
+        const raw = localStorage.getItem(key);
+        if (raw === null) return null;
+        const value = deserialize(raw);
+        if (validate && !validate(value)) return null;
+        return value;
+      } catch {
+        return null;
+      }
+    },
+    set(value) {
+      try {
+        const serialized = serialize(value);
+        localStorage.setItem(key, serialized);
+      } catch {
+      }
+    },
+    remove() {
+      localStorage.removeItem(key);
+    }
+  };
+}
+
+// src/storage/session.ts
+function createSessionStorage(key, options) {
+  const serialize = options?.serialize ?? JSON.stringify;
+  const deserialize = options?.deserialize ?? JSON.parse;
+  const validate = options?.validate;
+  return {
+    key,
+    get() {
+      try {
+        const raw = sessionStorage.getItem(key);
+        if (raw === null) return null;
+        const value = deserialize(raw);
+        if (validate && !validate(value)) return null;
+        return value;
+      } catch {
+        return null;
+      }
+    },
+    set(value) {
+      try {
+        const serialized = serialize(value);
+        sessionStorage.setItem(key, serialized);
+      } catch {
+      }
+    },
+    remove() {
+      sessionStorage.removeItem(key);
+    }
+  };
+}
+
+// src/storage/indexed.ts
+var dbCache = /* @__PURE__ */ new Map();
+function openDB(dbName, storeName) {
+  const cacheKey = `${dbName}::${storeName}`;
+  const cached = dbCache.get(cacheKey);
+  if (cached) return cached;
+  const promise = new Promise((resolve, reject) => {
+    const probe = indexedDB.open(dbName);
+    probe.onerror = () => reject(probe.error);
+    probe.onsuccess = () => {
+      const db = probe.result;
+      if (db.objectStoreNames.contains(storeName)) {
+        resolve(db);
+        return;
+      }
+      const nextVersion = db.version + 1;
+      db.close();
+      const upgrade = indexedDB.open(dbName, nextVersion);
+      upgrade.onerror = () => reject(upgrade.error);
+      upgrade.onupgradeneeded = () => {
+        const upgradedDB = upgrade.result;
+        if (!upgradedDB.objectStoreNames.contains(storeName)) {
+          upgradedDB.createObjectStore(storeName);
+        }
+      };
+      upgrade.onsuccess = () => resolve(upgrade.result);
+    };
+    probe.onupgradeneeded = () => {
+      const db = probe.result;
+      if (!db.objectStoreNames.contains(storeName)) {
+        db.createObjectStore(storeName);
+      }
+    };
+  });
+  dbCache.set(cacheKey, promise);
+  promise.catch(() => {
+    dbCache.delete(cacheKey);
+  });
+  return promise;
+}
+function createIndexedDB(dbName, storeName = "default") {
+  function withStore(mode, fn) {
+    return openDB(dbName, storeName).then(
+      (db) => new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, mode);
+        const store = tx.objectStore(storeName);
+        const request = fn(store);
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+      })
+    );
+  }
+  return {
+    get(key) {
+      return withStore("readonly", (store) => store.get(key));
+    },
+    set(key, value) {
+      return withStore("readwrite", (store) => store.put(value, key)).then(
+        () => void 0
+      );
+    },
+    delete(key) {
+      return withStore("readwrite", (store) => store.delete(key)).then(
+        () => void 0
+      );
+    },
+    getAll() {
+      return withStore("readonly", (store) => store.getAll());
+    },
+    keys() {
+      return withStore("readonly", (store) => store.getAllKeys()).then(
+        (keys) => keys.map(String)
+      );
+    },
+    clear() {
+      return withStore("readwrite", (store) => store.clear()).then(
+        () => void 0
+      );
+    }
+  };
+}
+
+exports.createIndexedDB = createIndexedDB;
+exports.createLocalStorage = createLocalStorage;
+exports.createSessionStorage = createSessionStorage;
+//# sourceMappingURL=storage.cjs.map
+//# sourceMappingURL=storage.cjs.map

package/dist/storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage/local.ts","../src/storage/session.ts","../src/storage/indexed.ts"],"names":[],"mappings":"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","file":"storage.cjs","sourcesContent":["/**\n * Forma Storage - Local\n *\n * Typed localStorage wrapper with graceful error handling.\n * Zero dependencies — native browser APIs only.\n */\n\nimport { TypedStorage, StorageOptions } from './types.js';\n\n/**\n * Create a typed localStorage wrapper for the given key.\n *\n * ```ts\n * const store = createLocalStorage<{ name: string }>('user');\n * store.set({ name: 'Alice' });\n * store.get(); // { name: 'Alice' }\n * store.remove();\n * ```\n */\nexport function createLocalStorage<T>(\n  key: string,\n  options?: StorageOptions<T>,\n): TypedStorage<T> {\n  const serialize = options?.serialize ?? JSON.stringify;\n  const deserialize = options?.deserialize ?? JSON.parse;\n  const validate = options?.validate;\n\n  return {\n    key,\n\n    get(): T | null {\n      try {\n        const raw = localStorage.getItem(key);\n        if (raw === null) return null;\n        const value = deserialize(raw);\n        if (validate && !validate(value)) return null;\n        return value as T;\n      } catch {\n        return null;\n      }\n    },\n\n    set(value: T): void {\n      try {\n        const serialized = serialize(value);\n        localStorage.setItem(key, serialized);\n      } catch { /* QuotaExceededError or storage disabled — silently ignore */ }\n    },\n\n    remove(): void {\n      localStorage.removeItem(key);\n    },\n  };\n}\n","/**\n * Forma Storage - Session\n *\n * Typed sessionStorage wrapper with graceful error handling.\n * Zero dependencies — native browser APIs only.\n */\n\nimport { TypedStorage, StorageOptions } from './types.js';\n\n/**\n * Create a typed sessionStorage wrapper for the given key.\n *\n * ```ts\n * const store = createSessionStorage<{ token: string }>('auth');\n * store.set({ token: 'abc123' });\n * store.get(); // { token: 'abc123' }\n * store.remove();\n * ```\n */\nexport function createSessionStorage<T>(\n  key: string,\n  options?: StorageOptions<T>,\n): TypedStorage<T> {\n  const serialize = options?.serialize ?? JSON.stringify;\n  const deserialize = options?.deserialize ?? JSON.parse;\n  const validate = options?.validate;\n\n  return {\n    key,\n\n    get(): T | null {\n      try {\n        const raw = sessionStorage.getItem(key);\n        if (raw === null) return null;\n        const value = deserialize(raw);\n        if (validate && !validate(value)) return null;\n        return value as T;\n      } catch {\n        return null;\n      }\n    },\n\n    set(value: T): void {\n      try {\n        const serialized = serialize(value);\n        sessionStorage.setItem(key, serialized);\n      } catch { /* QuotaExceededError or storage disabled — silently ignore */ }\n    },\n\n    remove(): void {\n      sessionStorage.removeItem(key);\n    },\n  };\n}\n","/**\n * Forma Storage - IndexedDB\n *\n * Simplified IndexedDB wrapper with lazy connection and promise-based API.\n * Zero dependencies — native browser APIs only.\n */\n\nexport interface IDBStore<T> {\n  get(key: string): Promise<T | undefined>;\n  set(key: string, value: T): Promise<void>;\n  delete(key: string): Promise<void>;\n  getAll(): Promise<T[]>;\n  keys(): Promise<string[]>;\n  clear(): Promise<void>;\n}\n\n/** Cached database connections keyed by \"dbName::storeName\". */\nconst dbCache = new Map<string, Promise<IDBDatabase>>();\n\n/**\n * Open (or retrieve a cached) IndexedDB database, ensuring the\n * requested object store exists.\n */\nfunction openDB(dbName: string, storeName: string): Promise<IDBDatabase> {\n  const cacheKey = `${dbName}::${storeName}`;\n  const cached = dbCache.get(cacheKey);\n  if (cached) return cached;\n\n  const promise = new Promise<IDBDatabase>((resolve, reject) => {\n    // First, try opening at the current (or default) version.\n    const probe = indexedDB.open(dbName);\n\n    probe.onerror = () => reject(probe.error);\n\n    probe.onsuccess = () => {\n      const db = probe.result;\n      if (db.objectStoreNames.contains(storeName)) {\n        resolve(db);\n        return;\n      }\n      // Store doesn't exist yet — close and reopen with a version bump.\n      const nextVersion = db.version + 1;\n      db.close();\n\n      const upgrade = indexedDB.open(dbName, nextVersion);\n      upgrade.onerror = () => reject(upgrade.error);\n      upgrade.onupgradeneeded = () => {\n        const upgradedDB = upgrade.result;\n        if (!upgradedDB.objectStoreNames.contains(storeName)) {\n          upgradedDB.createObjectStore(storeName);\n        }\n      };\n      upgrade.onsuccess = () => resolve(upgrade.result);\n    };\n\n    probe.onupgradeneeded = () => {\n      const db = probe.result;\n      if (!db.objectStoreNames.contains(storeName)) {\n        db.createObjectStore(storeName);\n      }\n    };\n  });\n\n  dbCache.set(cacheKey, promise);\n\n  // If the open fails, remove from cache so the next call retries.\n  promise.catch(() => {\n    dbCache.delete(cacheKey);\n  });\n\n  return promise;\n}\n\n/**\n * Create a simplified IndexedDB store.\n *\n * ```ts\n * const store = createIndexedDB<User>('myApp', 'users');\n * await store.set('u1', { name: 'Alice' });\n * const user = await store.get('u1'); // { name: 'Alice' }\n * ```\n */\nexport function createIndexedDB<T>(\n  dbName: string,\n  storeName: string = 'default',\n): IDBStore<T> {\n  /** Helper: run a single read/write transaction and return the request result. */\n  function withStore<R>(\n    mode: IDBTransactionMode,\n    fn: (store: IDBObjectStore) => IDBRequest<R>,\n  ): Promise<R> {\n    return openDB(dbName, storeName).then(\n      (db) =>\n        new Promise<R>((resolve, reject) => {\n          const tx = db.transaction(storeName, mode);\n          const store = tx.objectStore(storeName);\n          const request = fn(store);\n          request.onsuccess = () => resolve(request.result);\n          request.onerror = () => reject(request.error);\n        }),\n    );\n  }\n\n  return {\n    get(key: string): Promise<T | undefined> {\n      return withStore('readonly', (store) => store.get(key)) as Promise<T | undefined>;\n    },\n\n    set(key: string, value: T): Promise<void> {\n      return withStore('readwrite', (store) => store.put(value, key)).then(\n        () => undefined,\n      );\n    },\n\n    delete(key: string): Promise<void> {\n      return withStore('readwrite', (store) => store.delete(key)).then(\n        () => undefined,\n      );\n    },\n\n    getAll(): Promise<T[]> {\n      return withStore('readonly', (store) => store.getAll()) as Promise<T[]>;\n    },\n\n    keys(): Promise<string[]> {\n      return withStore('readonly', (store) => store.getAllKeys()).then(\n        (keys) => keys.map(String),\n      );\n    },\n\n    clear(): Promise<void> {\n      return withStore('readwrite', (store) => store.clear()).then(\n        () => undefined,\n      );\n    },\n  };\n}\n"]}

package/dist/storage.d.cts

@@ -0,0 +1,77 @@
+interface TypedStorage<T> {
+    get(): T | null;
+    set(value: T): void;
+    remove(): void;
+    key: string;
+}
+interface StorageOptions<T> {
+    serialize?: (v: T) => string;
+    deserialize?: (s: string) => T;
+    /** Optional validator — return true if the deserialized value is valid. */
+    validate?: (v: unknown) => v is T;
+}
+
+/**
+ * Forma Storage - Local
+ *
+ * Typed localStorage wrapper with graceful error handling.
+ * Zero dependencies — native browser APIs only.
+ */
+
+/**
+ * Create a typed localStorage wrapper for the given key.
+ *
+ * ```ts
+ * const store = createLocalStorage<{ name: string }>('user');
+ * store.set({ name: 'Alice' });
+ * store.get(); // { name: 'Alice' }
+ * store.remove();
+ * ```
+ */
+declare function createLocalStorage<T>(key: string, options?: StorageOptions<T>): TypedStorage<T>;
+
+/**
+ * Forma Storage - Session
+ *
+ * Typed sessionStorage wrapper with graceful error handling.
+ * Zero dependencies — native browser APIs only.
+ */
+
+/**
+ * Create a typed sessionStorage wrapper for the given key.
+ *
+ * ```ts
+ * const store = createSessionStorage<{ token: string }>('auth');
+ * store.set({ token: 'abc123' });
+ * store.get(); // { token: 'abc123' }
+ * store.remove();
+ * ```
+ */
+declare function createSessionStorage<T>(key: string, options?: StorageOptions<T>): TypedStorage<T>;
+
+/**
+ * Forma Storage - IndexedDB
+ *
+ * Simplified IndexedDB wrapper with lazy connection and promise-based API.
+ * Zero dependencies — native browser APIs only.
+ */
+interface IDBStore<T> {
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    getAll(): Promise<T[]>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+/**
+ * Create a simplified IndexedDB store.
+ *
+ * ```ts
+ * const store = createIndexedDB<User>('myApp', 'users');
+ * await store.set('u1', { name: 'Alice' });
+ * const user = await store.get('u1'); // { name: 'Alice' }
+ * ```
+ */
+declare function createIndexedDB<T>(dbName: string, storeName?: string): IDBStore<T>;
+
+export { type IDBStore, type StorageOptions, type TypedStorage, createIndexedDB, createLocalStorage, createSessionStorage };

package/dist/storage.d.ts

@@ -0,0 +1,77 @@
+interface TypedStorage<T> {
+    get(): T | null;
+    set(value: T): void;
+    remove(): void;
+    key: string;
+}
+interface StorageOptions<T> {
+    serialize?: (v: T) => string;
+    deserialize?: (s: string) => T;
+    /** Optional validator — return true if the deserialized value is valid. */
+    validate?: (v: unknown) => v is T;
+}
+
+/**
+ * Forma Storage - Local
+ *
+ * Typed localStorage wrapper with graceful error handling.
+ * Zero dependencies — native browser APIs only.
+ */
+
+/**
+ * Create a typed localStorage wrapper for the given key.
+ *
+ * ```ts
+ * const store = createLocalStorage<{ name: string }>('user');
+ * store.set({ name: 'Alice' });
+ * store.get(); // { name: 'Alice' }
+ * store.remove();
+ * ```
+ */
+declare function createLocalStorage<T>(key: string, options?: StorageOptions<T>): TypedStorage<T>;
+
+/**
+ * Forma Storage - Session
+ *
+ * Typed sessionStorage wrapper with graceful error handling.
+ * Zero dependencies — native browser APIs only.
+ */
+
+/**
+ * Create a typed sessionStorage wrapper for the given key.
+ *
+ * ```ts
+ * const store = createSessionStorage<{ token: string }>('auth');
+ * store.set({ token: 'abc123' });
+ * store.get(); // { token: 'abc123' }
+ * store.remove();
+ * ```
+ */
+declare function createSessionStorage<T>(key: string, options?: StorageOptions<T>): TypedStorage<T>;
+
+/**
+ * Forma Storage - IndexedDB
+ *
+ * Simplified IndexedDB wrapper with lazy connection and promise-based API.
+ * Zero dependencies — native browser APIs only.
+ */
+interface IDBStore<T> {
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    getAll(): Promise<T[]>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+/**
+ * Create a simplified IndexedDB store.
+ *
+ * ```ts
+ * const store = createIndexedDB<User>('myApp', 'users');
+ * await store.set('u1', { name: 'Alice' });
+ * const user = await store.get('u1'); // { name: 'Alice' }
+ * ```
+ */
+declare function createIndexedDB<T>(dbName: string, storeName?: string): IDBStore<T>;
+
+export { type IDBStore, type StorageOptions, type TypedStorage, createIndexedDB, createLocalStorage, createSessionStorage };