@zucker-framework/fe-storage 1.0.0 → 1.0.5

package/README.md

@@ -0,0 +1,7 @@
+# Frontend storage
+
+`LocalStore` provides the shared browser storage and authentication-key contract, including best-effort handling of unavailable storage.
+
+`setCookie(name, value, options?)`, `getCookie(name)` and `removeCookie(name, options?)` manage browser-readable cookies with SSR-safe no-op writes/null reads. Values are percent-encoded; malformed legacy encoding is returned unchanged. Names and attributes are validated before writing. `CookieOptions` supports `path`, `domain`, `expires`, `maxAge` (seconds), `sameSite` and `secure`; no authentication key, lifetime, domain or SameSite policy is hard-coded. Deletion must supply the same path/domain. HttpOnly cookies must be issued by the server, never by this API. New exports require a released artifact before production consumers switch.
+
+`downloadBlob(blob, fileName, { revokeDelayMs? }?)` triggers a caller-requested browser download. It owns the temporary anchor and object URL, cleaning both after the click, including click failures. URL cleanup is immediate by default; a caller with an existing delayed-revocation requirement can provide that delay. Applications retain the filename, MIME type and when to download. This helper does not perform HTTP requests and throws outside a browser.

package/dist/index.d.mts

@@ -12,6 +12,7 @@ declare const REFRESH_TOKEN_KEY = "REFRESH_TOKEN";
  * All methods are static so the class can be used without instantiation.
  */
 declare class LocalStore {
+    private static attempt;
     /** Store a value under the given key. Non-string values are JSON-serialized. */
     static set(key: string, data: unknown): void;
     /** Retrieve and JSON-parse a value by key. Returns null if the key does not exist. */
@@ -35,9 +36,30 @@ declare class LocalStore {
     /** Retrieve the stored user profile object. */
     static getUserInfo<T = Record<string, unknown>>(): T | null;
     /** Persist a user profile object. */
-    static setUserInfo(userInfo: Record<string, unknown>): void;
+    static setUserInfo<TUser extends object>(userInfo: TUser): void;
     /** Remove all auth-related keys (token, refresh token, user info). */
     static clearAuth(): void;
 }
 
-export { LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY };
+/** Trigger an explicitly requested browser download and release its temporary DOM/URL resources. */
+declare function downloadBlob(blob: Blob, fileName: string, options?: {
+    revokeDelayMs?: number;
+}): void;
+
+interface CookieOptions {
+    path?: string;
+    domain?: string;
+    expires?: Date;
+    /** Lifetime in seconds, not milliseconds. */
+    maxAge?: number;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    secure?: boolean;
+}
+/** Browser-readable cookies only. HttpOnly credentials must be set by a server. */
+declare function setCookie(name: string, value: string, options?: CookieOptions): void;
+/** Exact-name lookup; malformed percent encoding is retained as a legacy raw value. */
+declare function getCookie(name: string): string | null;
+/** Deletion must use the same path/domain as the original cookie. */
+declare function removeCookie(name: string, options?: Omit<CookieOptions, 'expires' | 'maxAge'>): void;
+
+export { type CookieOptions, LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY, downloadBlob, getCookie, removeCookie, setCookie };

package/dist/index.d.ts

@@ -12,6 +12,7 @@ declare const REFRESH_TOKEN_KEY = "REFRESH_TOKEN";
  * All methods are static so the class can be used without instantiation.
  */
 declare class LocalStore {
+    private static attempt;
     /** Store a value under the given key. Non-string values are JSON-serialized. */
     static set(key: string, data: unknown): void;
     /** Retrieve and JSON-parse a value by key. Returns null if the key does not exist. */
@@ -35,9 +36,30 @@ declare class LocalStore {
     /** Retrieve the stored user profile object. */
     static getUserInfo<T = Record<string, unknown>>(): T | null;
     /** Persist a user profile object. */
-    static setUserInfo(userInfo: Record<string, unknown>): void;
+    static setUserInfo<TUser extends object>(userInfo: TUser): void;
     /** Remove all auth-related keys (token, refresh token, user info). */
     static clearAuth(): void;
 }
 
-export { LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY };
+/** Trigger an explicitly requested browser download and release its temporary DOM/URL resources. */
+declare function downloadBlob(blob: Blob, fileName: string, options?: {
+    revokeDelayMs?: number;
+}): void;
+
+interface CookieOptions {
+    path?: string;
+    domain?: string;
+    expires?: Date;
+    /** Lifetime in seconds, not milliseconds. */
+    maxAge?: number;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    secure?: boolean;
+}
+/** Browser-readable cookies only. HttpOnly credentials must be set by a server. */
+declare function setCookie(name: string, value: string, options?: CookieOptions): void;
+/** Exact-name lookup; malformed percent encoding is retained as a legacy raw value. */
+declare function getCookie(name: string): string | null;
+/** Deletion must use the same path/domain as the original cookie. */
+declare function removeCookie(name: string, options?: Omit<CookieOptions, 'expires' | 'maxAge'>): void;
+
+export { type CookieOptions, LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY, downloadBlob, getCookie, removeCookie, setCookie };

package/dist/index.js

@@ -23,7 +23,11 @@ __export(index_exports, {
   LocalStore: () => LocalStore,
   REFRESH_TOKEN_KEY: () => REFRESH_TOKEN_KEY,
   TOKEN_KEY: () => TOKEN_KEY,
-  USER_KEY: () => USER_KEY
+  USER_KEY: () => USER_KEY,
+  downloadBlob: () => downloadBlob,
+  getCookie: () => getCookie,
+  removeCookie: () => removeCookie,
+  setCookie: () => setCookie
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -34,14 +38,23 @@ var REFRESH_TOKEN_KEY = "REFRESH_TOKEN";
 
 // src/local-store.ts
 var LocalStore = class {
+  static attempt(operation, fallback) {
+    try {
+      return operation();
+    } catch {
+      return fallback;
+    }
+  }
   /** Store a value under the given key. Non-string values are JSON-serialized. */
   static set(key, data) {
-    const value = typeof data === "string" ? data : JSON.stringify(data);
-    localStorage.setItem(key, value);
+    this.attempt(() => {
+      const value = typeof data === "string" ? data : JSON.stringify(data);
+      localStorage.setItem(key, value);
+    }, void 0);
   }
   /** Retrieve and JSON-parse a value by key. Returns null if the key does not exist. */
   static get(key) {
-    const dataStr = localStorage.getItem(key);
+    const dataStr = this.attempt(() => localStorage.getItem(key), null);
     if (!dataStr) return null;
     try {
       return JSON.parse(dataStr);
@@ -51,19 +64,19 @@ var LocalStore = class {
   }
   /** Remove a single key from localStorage. */
   static remove(key) {
-    localStorage.removeItem(key);
+    this.attempt(() => localStorage.removeItem(key), void 0);
   }
   /** Clear all keys from localStorage. */
   static removeAll() {
-    localStorage.clear();
+    this.attempt(() => localStorage.clear(), void 0);
   }
   /** Check whether a key exists in localStorage. */
   static has(key) {
-    return localStorage.getItem(key) !== null;
+    return this.attempt(() => localStorage.getItem(key) !== null, false);
   }
   /** Return all keys currently stored in localStorage. */
   static keys() {
-    return Object.keys(localStorage);
+    return this.attempt(() => Object.keys(localStorage), []);
   }
   /** Retrieve the stored access token. */
   static getToken() {
@@ -96,10 +109,92 @@ var LocalStore = class {
     this.remove(USER_KEY);
   }
 };
+
+// src/download-blob.ts
+function downloadBlob(blob, fileName, options = {}) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    throw new Error("downloadBlob requires a browser");
+  }
+  const url = window.URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  try {
+    link.href = url;
+    link.download = fileName;
+    document.body.appendChild(link);
+    link.click();
+  } finally {
+    link.remove();
+    if (options.revokeDelayMs && options.revokeDelayMs > 0) {
+      setTimeout(() => window.URL.revokeObjectURL(url), options.revokeDelayMs);
+    } else {
+      window.URL.revokeObjectURL(url);
+    }
+  }
+}
+
+// src/cookies.ts
+function validateName(name) {
+  if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)) {
+    throw new TypeError("Invalid cookie name");
+  }
+}
+function setCookie(name, value, options = {}) {
+  validateName(name);
+  const parts = [`${name}=${encodeURIComponent(value)}`];
+  if (options.path !== void 0) {
+    if (!options.path.startsWith("/") || /[;\x00-\x1f\x7f]/.test(options.path)) {
+      throw new TypeError("Invalid cookie path");
+    }
+    parts.push(`Path=${options.path}`);
+  }
+  if (options.domain !== void 0) {
+    if (!/^\.?[a-z0-9-]+(?:\.[a-z0-9-]+)*$/i.test(options.domain)) {
+      throw new TypeError("Invalid cookie domain");
+    }
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (options.expires !== void 0) {
+    if (!Number.isFinite(options.expires.getTime())) throw new TypeError("Invalid cookie expiry");
+    parts.push(`Expires=${options.expires.toUTCString()}`);
+  }
+  if (options.maxAge !== void 0) {
+    if (!Number.isSafeInteger(options.maxAge)) throw new TypeError("Invalid cookie max age");
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+  if (options.sameSite !== void 0) {
+    if (!["Strict", "Lax", "None"].includes(options.sameSite)) throw new TypeError("Invalid cookie SameSite");
+    parts.push(`SameSite=${options.sameSite}`);
+  }
+  if (options.secure) parts.push("Secure");
+  if (typeof document !== "undefined") document.cookie = parts.join("; ");
+}
+function getCookie(name) {
+  validateName(name);
+  if (typeof document === "undefined") return null;
+  const prefix = `${name}=`;
+  for (const entry of document.cookie.split(";")) {
+    const cookie = entry.trimStart();
+    if (!cookie.startsWith(prefix)) continue;
+    const value = cookie.slice(prefix.length);
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+  return null;
+}
+function removeCookie(name, options = {}) {
+  setCookie(name, "", { ...options, expires: /* @__PURE__ */ new Date(0), maxAge: 0 });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LocalStore,
   REFRESH_TOKEN_KEY,
   TOKEN_KEY,
-  USER_KEY
+  USER_KEY,
+  downloadBlob,
+  getCookie,
+  removeCookie,
+  setCookie
 });

package/dist/index.mjs

@@ -5,14 +5,23 @@ var REFRESH_TOKEN_KEY = "REFRESH_TOKEN";
 
 // src/local-store.ts
 var LocalStore = class {
+  static attempt(operation, fallback) {
+    try {
+      return operation();
+    } catch {
+      return fallback;
+    }
+  }
   /** Store a value under the given key. Non-string values are JSON-serialized. */
   static set(key, data) {
-    const value = typeof data === "string" ? data : JSON.stringify(data);
-    localStorage.setItem(key, value);
+    this.attempt(() => {
+      const value = typeof data === "string" ? data : JSON.stringify(data);
+      localStorage.setItem(key, value);
+    }, void 0);
   }
   /** Retrieve and JSON-parse a value by key. Returns null if the key does not exist. */
   static get(key) {
-    const dataStr = localStorage.getItem(key);
+    const dataStr = this.attempt(() => localStorage.getItem(key), null);
     if (!dataStr) return null;
     try {
       return JSON.parse(dataStr);
@@ -22,19 +31,19 @@ var LocalStore = class {
   }
   /** Remove a single key from localStorage. */
   static remove(key) {
-    localStorage.removeItem(key);
+    this.attempt(() => localStorage.removeItem(key), void 0);
   }
   /** Clear all keys from localStorage. */
   static removeAll() {
-    localStorage.clear();
+    this.attempt(() => localStorage.clear(), void 0);
   }
   /** Check whether a key exists in localStorage. */
   static has(key) {
-    return localStorage.getItem(key) !== null;
+    return this.attempt(() => localStorage.getItem(key) !== null, false);
   }
   /** Return all keys currently stored in localStorage. */
   static keys() {
-    return Object.keys(localStorage);
+    return this.attempt(() => Object.keys(localStorage), []);
   }
   /** Retrieve the stored access token. */
   static getToken() {
@@ -67,9 +76,91 @@ var LocalStore = class {
     this.remove(USER_KEY);
   }
 };
+
+// src/download-blob.ts
+function downloadBlob(blob, fileName, options = {}) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    throw new Error("downloadBlob requires a browser");
+  }
+  const url = window.URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  try {
+    link.href = url;
+    link.download = fileName;
+    document.body.appendChild(link);
+    link.click();
+  } finally {
+    link.remove();
+    if (options.revokeDelayMs && options.revokeDelayMs > 0) {
+      setTimeout(() => window.URL.revokeObjectURL(url), options.revokeDelayMs);
+    } else {
+      window.URL.revokeObjectURL(url);
+    }
+  }
+}
+
+// src/cookies.ts
+function validateName(name) {
+  if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)) {
+    throw new TypeError("Invalid cookie name");
+  }
+}
+function setCookie(name, value, options = {}) {
+  validateName(name);
+  const parts = [`${name}=${encodeURIComponent(value)}`];
+  if (options.path !== void 0) {
+    if (!options.path.startsWith("/") || /[;\x00-\x1f\x7f]/.test(options.path)) {
+      throw new TypeError("Invalid cookie path");
+    }
+    parts.push(`Path=${options.path}`);
+  }
+  if (options.domain !== void 0) {
+    if (!/^\.?[a-z0-9-]+(?:\.[a-z0-9-]+)*$/i.test(options.domain)) {
+      throw new TypeError("Invalid cookie domain");
+    }
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (options.expires !== void 0) {
+    if (!Number.isFinite(options.expires.getTime())) throw new TypeError("Invalid cookie expiry");
+    parts.push(`Expires=${options.expires.toUTCString()}`);
+  }
+  if (options.maxAge !== void 0) {
+    if (!Number.isSafeInteger(options.maxAge)) throw new TypeError("Invalid cookie max age");
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+  if (options.sameSite !== void 0) {
+    if (!["Strict", "Lax", "None"].includes(options.sameSite)) throw new TypeError("Invalid cookie SameSite");
+    parts.push(`SameSite=${options.sameSite}`);
+  }
+  if (options.secure) parts.push("Secure");
+  if (typeof document !== "undefined") document.cookie = parts.join("; ");
+}
+function getCookie(name) {
+  validateName(name);
+  if (typeof document === "undefined") return null;
+  const prefix = `${name}=`;
+  for (const entry of document.cookie.split(";")) {
+    const cookie = entry.trimStart();
+    if (!cookie.startsWith(prefix)) continue;
+    const value = cookie.slice(prefix.length);
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+  return null;
+}
+function removeCookie(name, options = {}) {
+  setCookie(name, "", { ...options, expires: /* @__PURE__ */ new Date(0), maxAge: 0 });
+}
 export {
   LocalStore,
   REFRESH_TOKEN_KEY,
   TOKEN_KEY,
-  USER_KEY
+  USER_KEY,
+  downloadBlob,
+  getCookie,
+  removeCookie,
+  setCookie
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zucker-framework/fe-storage",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",