@zucker-framework/fe-storage 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,5 @@
+# Frontend storage
+
+`LocalStore` provides the shared browser storage and authentication-key contract, including best-effort handling of unavailable storage.
+
+`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,14 @@ 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;
+
+export { LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY, downloadBlob };

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,14 @@ 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;
+
+export { LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY, downloadBlob };

package/dist/index.js

@@ -23,7 +23,8 @@ __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
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -34,14 +35,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 +61,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 +106,33 @@ 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);
+    }
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LocalStore,
   REFRESH_TOKEN_KEY,
   TOKEN_KEY,
-  USER_KEY
+  USER_KEY,
+  downloadBlob
 });

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,32 @@ 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);
+    }
+  }
+}
 export {
   LocalStore,
   REFRESH_TOKEN_KEY,
   TOKEN_KEY,
-  USER_KEY
+  USER_KEY,
+  downloadBlob
 };

package/package.json

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