@fluixi/storage 0.1.0-alpha.0

package/dist/browser/index.mjs

@@ -0,0 +1,187 @@
+/*! @fluixi/storage v0.1.0-alpha.0 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+
+// src/core/errors.ts
+var StorageError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.key = options.key;
+    if (options.cause !== void 0) this.cause = options.cause;
+  }
+};
+var StorageUnavailableError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("unavailable", message, options);
+  }
+};
+var StorageQuotaError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("quota", message, options);
+  }
+};
+var StorageSecurityError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("security", message, options);
+  }
+};
+var StorageAdapterError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("adapter", message, options);
+  }
+};
+
+// src/utils/environment.ts
+function hasWindow() {
+  return typeof window !== "undefined";
+}
+
+// src/browser/web-storage.ts
+function mapError(error, area, key) {
+  if (error instanceof StorageError) return error;
+  const name = error?.name;
+  const code = error?.code;
+  if (name === "QuotaExceededError" || name === "NS_ERROR_DOM_QUOTA_REACHED" || code === 22 || code === 1014) {
+    return new StorageQuotaError(`${area} is full${key ? ` writing ${key}` : ""}.`, { key, cause: error });
+  }
+  if (name === "SecurityError") {
+    return new StorageSecurityError(`${area} is blocked by the browser (privacy settings or a sandboxed frame).`, { key, cause: error });
+  }
+  return new StorageAdapterError(`${area} failed${key ? ` on ${key}` : ""}.`, { key, cause: error });
+}
+function webStorage(area, capabilities) {
+  const resolve = (key) => {
+    let storage;
+    try {
+      storage = globalThis[area];
+    } catch (error) {
+      throw mapError(error, area, key);
+    }
+    if (!storage) throw new StorageUnavailableError(`${area} is not available here (a server, a worker, or a browser without it).`, { key });
+    return storage;
+  };
+  const run = (key, fn) => {
+    const storage = resolve(key);
+    try {
+      return fn(storage);
+    } catch (error) {
+      throw mapError(error, area, key);
+    }
+  };
+  return {
+    name: area,
+    scope: area === "localStorage" ? "local" : "session",
+    capabilities,
+    get: (key) => run(key, (s) => s.getItem(key)),
+    set: (key, value) => run(key, (s) => s.setItem(key, value)),
+    remove: (key) => run(key, (s) => s.removeItem(key)),
+    has: (key) => run(key, (s) => s.getItem(key) !== null),
+    keys: () => run(void 0, (s) => {
+      const keys = [];
+      for (let i = 0; i < s.length; i++) {
+        const key = s.key(i);
+        if (key !== null) keys.push(key);
+      }
+      return keys;
+    }),
+    clear: () => run(void 0, (s) => s.clear()),
+    subscribe(listener) {
+      if (!hasWindow()) return () => {
+      };
+      const onStorage = (event) => {
+        let storage;
+        try {
+          storage = resolve();
+        } catch {
+          return;
+        }
+        if (event.storageArea !== storage) return;
+        listener({ key: event.key, value: event.newValue });
+      };
+      window.addEventListener("storage", onStorage);
+      return () => window.removeEventListener("storage", onStorage);
+    }
+  };
+}
+function localStorageAdapter() {
+  return webStorage("localStorage", {
+    synchronous: true,
+    persistent: true,
+    reactive: true,
+    crossContext: true,
+    expiration: false,
+    transactions: false
+  });
+}
+function sessionStorageAdapter() {
+  return webStorage("sessionStorage", {
+    synchronous: true,
+    persistent: false,
+    reactive: false,
+    crossContext: false,
+    expiration: false,
+    transactions: false
+  });
+}
+
+// src/browser/document-cookie.ts
+import { parseCookies, serializeCookie } from "@fluixi/utils/cookie";
+
+// src/utils/cookie-names.ts
+var encodeCookieName = (key) => encodeURIComponent(key).replace(/[()]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+var decodeCookieName = (name) => {
+  try {
+    return decodeURIComponent(name);
+  } catch {
+    return name;
+  }
+};
+var cookiePairSize = (header) => new TextEncoder().encode(header.slice(0, header.indexOf(";"))).length;
+var withEntryExpiry = (cookie, expiresAt) => expiresAt === void 0 ? cookie : { ...cookie, maxAge: void 0, expires: new Date(expiresAt) };
+
+// src/browser/document-cookie.ts
+function documentCookieAdapter(options = {}) {
+  const { maxSize = 4096, ...cookie } = options;
+  const doc = (key) => {
+    if (typeof document === "undefined") throw new StorageUnavailableError("document.cookie is not available here; on a server use cookieStorage.", { key });
+    return document;
+  };
+  const all = () => {
+    const out = /* @__PURE__ */ new Map();
+    for (const [name, value] of Object.entries(parseCookies(doc().cookie))) out.set(decodeCookieName(name), value);
+    return out;
+  };
+  const write = (key, header) => {
+    doc(key).cookie = header;
+  };
+  return {
+    name: "documentCookie",
+    scope: "cookie",
+    capabilities: {
+      synchronous: true,
+      persistent: true,
+      reactive: false,
+      crossContext: true,
+      expiration: false,
+      transactions: false
+    },
+    get: (key) => all().get(key) ?? null,
+    set(key, value, writeOptions) {
+      const header = serializeCookie(encodeCookieName(key), value, { ...withEntryExpiry(cookie, writeOptions?.expiresAt), httpOnly: false });
+      const size = cookiePairSize(header);
+      if (size > maxSize) throw new StorageQuotaError(`Cookie ${key} is ${size} bytes, over the ${maxSize} limit.`, { key });
+      write(key, header);
+    },
+    remove: (key) => write(key, serializeCookie(encodeCookieName(key), "", { ...cookie, httpOnly: false, maxAge: 0, expires: /* @__PURE__ */ new Date(0) })),
+    has: (key) => all().has(key),
+    keys: () => [...all().keys()],
+    clear() {
+      for (const key of all().keys()) this.remove(key);
+    }
+  };
+}
+export {
+  documentCookieAdapter,
+  localStorageAdapter,
+  sessionStorageAdapter
+};

package/dist/browser/web-storage.cjs

@@ -0,0 +1,150 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/browser/web-storage.ts
+var web_storage_exports = {};
+__export(web_storage_exports, {
+  localStorageAdapter: () => localStorageAdapter,
+  sessionStorageAdapter: () => sessionStorageAdapter
+});
+module.exports = __toCommonJS(web_storage_exports);
+
+// src/core/errors.ts
+var StorageError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.key = options.key;
+    if (options.cause !== void 0) this.cause = options.cause;
+  }
+};
+var StorageUnavailableError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("unavailable", message, options);
+  }
+};
+var StorageQuotaError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("quota", message, options);
+  }
+};
+var StorageSecurityError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("security", message, options);
+  }
+};
+var StorageAdapterError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("adapter", message, options);
+  }
+};
+
+// src/utils/environment.ts
+function hasWindow() {
+  return typeof window !== "undefined";
+}
+
+// src/browser/web-storage.ts
+function mapError(error, area, key) {
+  if (error instanceof StorageError) return error;
+  const name = error?.name;
+  const code = error?.code;
+  if (name === "QuotaExceededError" || name === "NS_ERROR_DOM_QUOTA_REACHED" || code === 22 || code === 1014) {
+    return new StorageQuotaError(`${area} is full${key ? ` writing ${key}` : ""}.`, { key, cause: error });
+  }
+  if (name === "SecurityError") {
+    return new StorageSecurityError(`${area} is blocked by the browser (privacy settings or a sandboxed frame).`, { key, cause: error });
+  }
+  return new StorageAdapterError(`${area} failed${key ? ` on ${key}` : ""}.`, { key, cause: error });
+}
+function webStorage(area, capabilities) {
+  const resolve = (key) => {
+    let storage;
+    try {
+      storage = globalThis[area];
+    } catch (error) {
+      throw mapError(error, area, key);
+    }
+    if (!storage) throw new StorageUnavailableError(`${area} is not available here (a server, a worker, or a browser without it).`, { key });
+    return storage;
+  };
+  const run = (key, fn) => {
+    const storage = resolve(key);
+    try {
+      return fn(storage);
+    } catch (error) {
+      throw mapError(error, area, key);
+    }
+  };
+  return {
+    name: area,
+    scope: area === "localStorage" ? "local" : "session",
+    capabilities,
+    get: (key) => run(key, (s) => s.getItem(key)),
+    set: (key, value) => run(key, (s) => s.setItem(key, value)),
+    remove: (key) => run(key, (s) => s.removeItem(key)),
+    has: (key) => run(key, (s) => s.getItem(key) !== null),
+    keys: () => run(void 0, (s) => {
+      const keys = [];
+      for (let i = 0; i < s.length; i++) {
+        const key = s.key(i);
+        if (key !== null) keys.push(key);
+      }
+      return keys;
+    }),
+    clear: () => run(void 0, (s) => s.clear()),
+    subscribe(listener) {
+      if (!hasWindow()) return () => {
+      };
+      const onStorage = (event) => {
+        let storage;
+        try {
+          storage = resolve();
+        } catch {
+          return;
+        }
+        if (event.storageArea !== storage) return;
+        listener({ key: event.key, value: event.newValue });
+      };
+      window.addEventListener("storage", onStorage);
+      return () => window.removeEventListener("storage", onStorage);
+    }
+  };
+}
+function localStorageAdapter() {
+  return webStorage("localStorage", {
+    synchronous: true,
+    persistent: true,
+    reactive: true,
+    crossContext: true,
+    expiration: false,
+    transactions: false
+  });
+}
+function sessionStorageAdapter() {
+  return webStorage("sessionStorage", {
+    synchronous: true,
+    persistent: false,
+    reactive: false,
+    crossContext: false,
+    expiration: false,
+    transactions: false
+  });
+}

package/dist/browser/web-storage.d.ts

@@ -0,0 +1,6 @@
+import type { StorageAdapter } from '../core/types.js';
+/** Survives a browser restart; shared by every tab of the origin, which see each other's writes. */
+export declare function localStorageAdapter(): StorageAdapter;
+/** One tab's storage: survives a reload of that tab, not its closing. Not shared between tabs. */
+export declare function sessionStorageAdapter(): StorageAdapter;
+//# sourceMappingURL=web-storage.d.ts.map

package/dist/browser/web-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-storage.d.ts","sourceRoot":"","sources":["../../src/browser/web-storage.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAiB,cAAc,EAAuB,MAAM,kBAAkB,CAAC;AA6E3F,oGAAoG;AACpG,wBAAgB,mBAAmB,IAAI,cAAc,CASpD;AAED,kGAAkG;AAClG,wBAAgB,qBAAqB,IAAI,cAAc,CAStD"}

package/dist/browser/web-storage.js

@@ -0,0 +1,105 @@
+/**
+ * localStorage and sessionStorage. The browser global is read when the adapter is first used,
+ * never when it is created or imported, so a module that builds one is safe to load on a server;
+ * using it there throws `StorageUnavailableError`.
+ */
+import { StorageAdapterError, StorageError, StorageQuotaError, StorageSecurityError, StorageUnavailableError } from '../core/errors.js';
+import { hasWindow } from '../utils/environment.js';
+/** The browser's own exception, as one of ours. */
+function mapError(error, area, key) {
+    if (error instanceof StorageError)
+        return error;
+    const name = error?.name;
+    const code = error?.code;
+    if (name === 'QuotaExceededError' || name === 'NS_ERROR_DOM_QUOTA_REACHED' || code === 22 || code === 1014) {
+        return new StorageQuotaError(`${area} is full${key ? ` writing ${key}` : ''}.`, { key, cause: error });
+    }
+    if (name === 'SecurityError') {
+        return new StorageSecurityError(`${area} is blocked by the browser (privacy settings or a sandboxed frame).`, { key, cause: error });
+    }
+    return new StorageAdapterError(`${area} failed${key ? ` on ${key}` : ''}.`, { key, cause: error });
+}
+function webStorage(area, capabilities) {
+    const resolve = (key) => {
+        let storage;
+        try {
+            storage = globalThis[area];
+        }
+        catch (error) {
+            // Some browsers throw on the property access itself when storage is disabled.
+            throw mapError(error, area, key);
+        }
+        if (!storage)
+            throw new StorageUnavailableError(`${area} is not available here (a server, a worker, or a browser without it).`, { key });
+        return storage;
+    };
+    const run = (key, fn) => {
+        const storage = resolve(key);
+        try {
+            return fn(storage);
+        }
+        catch (error) {
+            throw mapError(error, area, key);
+        }
+    };
+    return {
+        name: area,
+        scope: area === 'localStorage' ? 'local' : 'session',
+        capabilities,
+        get: (key) => run(key, (s) => s.getItem(key)),
+        set: (key, value) => run(key, (s) => s.setItem(key, value)),
+        remove: (key) => run(key, (s) => s.removeItem(key)),
+        has: (key) => run(key, (s) => s.getItem(key) !== null),
+        keys: () => run(undefined, (s) => {
+            const keys = [];
+            for (let i = 0; i < s.length; i++) {
+                const key = s.key(i);
+                if (key !== null)
+                    keys.push(key);
+            }
+            return keys;
+        }),
+        clear: () => run(undefined, (s) => s.clear()),
+        subscribe(listener) {
+            // The browser reports a write from another tab of the same origin; never this tab's own.
+            if (!hasWindow())
+                return () => { };
+            const onStorage = (event) => {
+                let storage;
+                try {
+                    storage = resolve();
+                }
+                catch {
+                    return;
+                }
+                if (event.storageArea !== storage)
+                    return;
+                listener({ key: event.key, value: event.newValue });
+            };
+            window.addEventListener('storage', onStorage);
+            return () => window.removeEventListener('storage', onStorage);
+        },
+    };
+}
+/** Survives a browser restart; shared by every tab of the origin, which see each other's writes. */
+export function localStorageAdapter() {
+    return webStorage('localStorage', {
+        synchronous: true,
+        persistent: true,
+        reactive: true,
+        crossContext: true,
+        expiration: false,
+        transactions: false,
+    });
+}
+/** One tab's storage: survives a reload of that tab, not its closing. Not shared between tabs. */
+export function sessionStorageAdapter() {
+    return webStorage('sessionStorage', {
+        synchronous: true,
+        persistent: false,
+        reactive: false,
+        crossContext: false,
+        expiration: false,
+        transactions: false,
+    });
+}

package/dist/browser/web-storage.mjs

@@ -0,0 +1,127 @@
+// src/core/errors.ts
+var StorageError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.key = options.key;
+    if (options.cause !== void 0) this.cause = options.cause;
+  }
+};
+var StorageUnavailableError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("unavailable", message, options);
+  }
+};
+var StorageQuotaError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("quota", message, options);
+  }
+};
+var StorageSecurityError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("security", message, options);
+  }
+};
+var StorageAdapterError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("adapter", message, options);
+  }
+};
+
+// src/utils/environment.ts
+function hasWindow() {
+  return typeof window !== "undefined";
+}
+
+// src/browser/web-storage.ts
+function mapError(error, area, key) {
+  if (error instanceof StorageError) return error;
+  const name = error?.name;
+  const code = error?.code;
+  if (name === "QuotaExceededError" || name === "NS_ERROR_DOM_QUOTA_REACHED" || code === 22 || code === 1014) {
+    return new StorageQuotaError(`${area} is full${key ? ` writing ${key}` : ""}.`, { key, cause: error });
+  }
+  if (name === "SecurityError") {
+    return new StorageSecurityError(`${area} is blocked by the browser (privacy settings or a sandboxed frame).`, { key, cause: error });
+  }
+  return new StorageAdapterError(`${area} failed${key ? ` on ${key}` : ""}.`, { key, cause: error });
+}
+function webStorage(area, capabilities) {
+  const resolve = (key) => {
+    let storage;
+    try {
+      storage = globalThis[area];
+    } catch (error) {
+      throw mapError(error, area, key);
+    }
+    if (!storage) throw new StorageUnavailableError(`${area} is not available here (a server, a worker, or a browser without it).`, { key });
+    return storage;
+  };
+  const run = (key, fn) => {
+    const storage = resolve(key);
+    try {
+      return fn(storage);
+    } catch (error) {
+      throw mapError(error, area, key);
+    }
+  };
+  return {
+    name: area,
+    scope: area === "localStorage" ? "local" : "session",
+    capabilities,
+    get: (key) => run(key, (s) => s.getItem(key)),
+    set: (key, value) => run(key, (s) => s.setItem(key, value)),
+    remove: (key) => run(key, (s) => s.removeItem(key)),
+    has: (key) => run(key, (s) => s.getItem(key) !== null),
+    keys: () => run(void 0, (s) => {
+      const keys = [];
+      for (let i = 0; i < s.length; i++) {
+        const key = s.key(i);
+        if (key !== null) keys.push(key);
+      }
+      return keys;
+    }),
+    clear: () => run(void 0, (s) => s.clear()),
+    subscribe(listener) {
+      if (!hasWindow()) return () => {
+      };
+      const onStorage = (event) => {
+        let storage;
+        try {
+          storage = resolve();
+        } catch {
+          return;
+        }
+        if (event.storageArea !== storage) return;
+        listener({ key: event.key, value: event.newValue });
+      };
+      window.addEventListener("storage", onStorage);
+      return () => window.removeEventListener("storage", onStorage);
+    }
+  };
+}
+function localStorageAdapter() {
+  return webStorage("localStorage", {
+    synchronous: true,
+    persistent: true,
+    reactive: true,
+    crossContext: true,
+    expiration: false,
+    transactions: false
+  });
+}
+function sessionStorageAdapter() {
+  return webStorage("sessionStorage", {
+    synchronous: true,
+    persistent: false,
+    reactive: false,
+    crossContext: false,
+    expiration: false,
+    transactions: false
+  });
+}
+export {
+  localStorageAdapter,
+  sessionStorageAdapter
+};