Merge pull request #4 from script-development/feat/fs-storage

feat(storage): add fs-storage package

Author: Goosterhof

package-lock.json

@@ -0,0 +1,7 @@
+# @script-development/fs-storage
+
+## 0.1.0
+
+### Minor Changes
+
+- aafcb7a: Add fs-storage package — framework-agnostic localStorage service factory with prefix namespacing, JSON serialization, and QuotaExceededError handling.

packages/storage/CHANGELOG.md

@@ -0,0 +1,44 @@
+{
+  "name": "@script-development/fs-storage",
+  "version": "0.1.0",
+  "description": "Framework-agnostic localStorage service factory with prefix namespacing",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/script-development/fs-packages.git",
+    "directory": "packages/storage"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint:pkg": "publint && attw --pack",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "jsdom": "^29.0.1"
+  }
+}

packages/storage/package.json

@@ -0,0 +1,2 @@
+export { createStorageService } from "./storage";
+export type { StorageService, Get } from "./types";

packages/storage/src/index.ts

@@ -0,0 +1,66 @@
+import type { StorageService, Get } from "./types";
+
+export const createStorageService = (prefix: string): StorageService => {
+  const prefixKey = (key: string): string => `${prefix}:${key}`;
+
+  const put = (key: string, value: unknown): void => {
+    const valueToStore = typeof value === "string" ? value : JSON.stringify(value);
+
+    try {
+      localStorage.setItem(prefixKey(key), valueToStore);
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "QuotaExceededError") {
+        console.error("localStorage quota exceeded");
+        return;
+      }
+      console.error(error);
+    }
+  };
+
+  const get: Get = <T>(key: string, defaultValue?: T): T | undefined => {
+    let storedValue: string | null;
+    try {
+      storedValue = localStorage.getItem(prefixKey(key));
+    } catch (error) {
+      console.error(error);
+      return defaultValue;
+    }
+
+    if (storedValue === null) return defaultValue;
+
+    if (typeof defaultValue === "string") return storedValue as T;
+
+    try {
+      return JSON.parse(storedValue) as T;
+    } catch {
+      return storedValue as unknown as T;
+    }
+  };
+
+  const remove = (key: string): void => {
+    try {
+      localStorage.removeItem(prefixKey(key));
+    } catch (error) {
+      console.error(error);
+    }
+  };
+
+  const clear = (): void => {
+    const keysToRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(`${prefix}:`)) {
+        keysToRemove.push(key);
+      }
+    }
+    for (const key of keysToRemove) {
+      try {
+        localStorage.removeItem(key);
+      } catch (error) {
+        console.error(error);
+      }
+    }
+  };
+
+  return { put, get, remove, clear };
+};

packages/storage/src/storage.ts

@@ -0,0 +1,28 @@
+/**
+ * Retrieve a value from storage.
+ *
+ * @remarks
+ * Parsing behavior depends on the default value type:
+ * - No default or non-string default: Attempts JSON.parse, falls back to raw string on failure
+ * - String default: Returns the raw stored string without JSON parsing
+ *
+ * This prevents unintended conversions (e.g., stored "5e3" becoming number 5000).
+ *
+ * @example
+ * ```ts
+ * storage.put('key', '5e3');
+ * storage.get('key');           // Returns number 5000 (JSON parsed)
+ * storage.get('key', '');       // Returns string "5e3" (raw)
+ * ```
+ */
+export interface Get {
+  <T>(key: string): T | undefined;
+  <T>(key: string, defaultValue: T): T;
+}
+
+export interface StorageService {
+  put: (key: string, value: unknown) => void;
+  get: Get;
+  remove: (key: string) => void;
+  clear: () => void;
+}