@nice-code/util 0.2.9 → 0.2.11

package/README.md

@@ -1 +1,159 @@
-# @nice-code/utils
+# @nice-code/util
+
+Typed storage adapters for browser, Cloudflare Durable Objects, and in-memory use.
+
+## Install
+
+```bash
+bun add @nice-code/util
+```
+
+---
+
+## Typed storage
+
+`createTypedStorage` wraps a `StorageAdapter` and adds full TypeScript key and value inference based on a schema type parameter.
+
+```ts
+import { createTypedWebLocalStorage } from "@nice-code/util";
+
+// Define the shape of your storage
+interface IAppStorage {
+  user_id: string;
+  theme: "light" | "dark";
+  last_seen: number;
+}
+
+const storage = createTypedWebLocalStorage<IAppStorage>(localStorage, "app:");
+
+// All keys autocomplete; values are typed
+await storage.setJson("theme", "dark");
+const theme = await storage.getJson("theme");      // "light" | "dark" | undefined
+const userId = await storage.getJsonOrDef("user_id", "guest"); // string
+await storage.removeItem("last_seen");
+```
+
+All methods are async and key-prefixed if a prefix is provided.
+
+---
+
+## Available adapters
+
+### Browser — `localStorage` / `sessionStorage`
+
+```ts
+import {
+  createTypedWebLocalStorage,
+  createTypedWebSessionStorage,
+} from "@nice-code/util";
+
+const local = createTypedWebLocalStorage<IAppStorage>(localStorage, "prefix:");
+const session = createTypedWebSessionStorage<IAppStorage>(sessionStorage);
+```
+
+### Cloudflare Durable Objects
+
+```ts
+import { createDurableObjectTypedStorage } from "@nice-code/util";
+
+// Inside a Durable Object class
+export class MyDO {
+  private storage: ITypedStorage<IDOStorage>;
+
+  constructor(state: DurableObjectState) {
+    this.storage = createDurableObjectTypedStorage<IDOStorage>(state.storage, "do:");
+  }
+}
+```
+
+### In-memory (testing / SSR)
+
+```ts
+import {
+  createTypedMemoryStorage_string,
+  createTypedMemoryStorage_json,
+} from "@nice-code/util";
+
+// String-serialized (like localStorage)
+const store = createTypedMemoryStorage_string<IAppStorage>();
+
+// JSON-native (no serialization overhead)
+const jsonStore = createTypedMemoryStorage_json<IAppStorage>();
+
+// Pass in your own Map to share state between instances
+const shared = new Map<string, string>();
+const a = createTypedMemoryStorage_string<IAppStorage>(shared);
+const b = createTypedMemoryStorage_string<IAppStorage>(shared);
+```
+
+---
+
+## `ITypedStorage<T>` interface
+
+```ts
+interface ITypedStorage<T extends Record<string, any>> {
+  getJson<K extends keyof T & string>(key: K): Promise<T[K] | undefined>;
+  getJsonOrDef<K extends keyof T & string>(key: K, defVal: T[K]): Promise<T[K]>;
+  setJson<K extends keyof T & string>(key: K, val: T[K]): Promise<void>;
+  removeItem<K extends keyof T & string>(key: K): Promise<void>;
+}
+```
+
+---
+
+## `StorageAdapter` — low-level
+
+Use `StorageAdapter` directly when you need a getter/setter pair or want to build a custom typed storage on top.
+
+```ts
+import { StorageAdapter } from "@nice-code/util";
+import { createMemoryStorageMethods_string } from "@nice-code/util";
+
+const adapter = new StorageAdapter({
+  methods: createMemoryStorageMethods_string(),
+  keyPrefix: "myapp:",
+});
+
+await adapter.setJson("token", { value: "abc", exp: 9999 });
+const token = await adapter.getJson<{ value: string; exp: number }>("token");
+const safe = await adapter.getJsonOrDef("token", { value: "", exp: 0 });
+
+// Convenient getter/setter pair for a single key
+const { get, set } = adapter.createJsonGetterSetter<string>("theme");
+await set("dark");
+const theme = await get(); // string | undefined
+```
+
+---
+
+## Custom adapter
+
+Implement `TStorageAdapterMethods` to wrap any storage backend:
+
+```ts
+import type { IStorageAdapterMethods_String } from "@nice-code/util";
+import { EStorageAdapterType } from "@nice-code/util";
+
+const redisMethods: IStorageAdapterMethods_String = {
+  type: EStorageAdapterType.string,
+  getItem: async (key) => redis.get(key),
+  setItem: async (key, value) => { await redis.set(key, value); },
+  removeItem: async (key) => { await redis.del(key); },
+};
+
+const storage = createTypedStorage<IMySchema>({
+  storageAdapter: new StorageAdapter({ methods: redisMethods, keyPrefix: "app:" }),
+});
+```
+
+---
+
+## TypeScript utilities
+
+```ts
+import type { StringKeys } from "@nice-code/util";
+
+// Extracts string keys from a type
+type Keys = StringKeys<{ a: string; b: number; 0: boolean }>;
+// → "a" | "b"
+```

package/build/index.js

@@ -1,8 +1,204 @@
-// src/index.ts
-export * from "./storage_adapter/StorageAdapter";
-export * from "./storage_adapter/specific/browser/browser_storage";
-export * from "./storage_adapter/specific/durable_object/durable_object_storage";
-export * from "./storage_adapter/specific/memory/memory_storage";
-export * from "./storage_adapter/storage_adapter.types";
-export * from "./storage_adapter/typed_storage/createTypedStorage";
-export * from "./typescript/special_typescript_types";
+// src/storage_adapter/storage_adapter.types.ts
+var EStorageAdapterType;
+((EStorageAdapterType2) => {
+  EStorageAdapterType2["string"] = "string";
+  EStorageAdapterType2["json"] = "json";
+})(EStorageAdapterType ||= {});
+
+// src/storage_adapter/StorageAdapter.ts
+class StorageAdapter {
+  implementation;
+  keyPrefix;
+  constructor({ methods, keyPrefix }) {
+    this.implementation = methods;
+    this.keyPrefix = keyPrefix ?? "";
+  }
+  getPrefixedKey(key) {
+    return `${this.keyPrefix}${key}`;
+  }
+  async removeItem(key) {
+    await this.implementation.removeItem(this.getPrefixedKey(key));
+  }
+  async setJson(key, value) {
+    if (this.implementation.type === "string" /* string */) {
+      await this.implementation.setItem(this.getPrefixedKey(key), JSON.stringify(value));
+    } else {
+      await this.implementation.setItem(this.getPrefixedKey(key), value);
+    }
+  }
+  async getJson(key) {
+    if (this.implementation.type === "string" /* string */) {
+      const val = await this.implementation.getItem(this.getPrefixedKey(key));
+      if (val == null || val === "undefined" || val === "null") {
+        return;
+      }
+      return JSON.parse(val);
+    } else {
+      const val = await this.implementation.getItem(this.getPrefixedKey(key));
+      if (val == null || val === "undefined" || val === "null") {
+        return;
+      }
+      return val;
+    }
+  }
+  async getJsonOrDef(key, defVal) {
+    if (this.implementation.type === "string" /* string */) {
+      const val2 = await this.implementation.getItem(this.getPrefixedKey(key));
+      if (val2 == null || val2 === "undefined" || val2 === "null") {
+        return defVal;
+      }
+      return JSON.parse(val2);
+    }
+    const val = await this.implementation.getItem(this.getPrefixedKey(key));
+    if (val == null || val === "undefined" || val === "null") {
+      return defVal;
+    }
+    return val;
+  }
+  createJsonGetterSetter(key) {
+    return {
+      get: () => this.getJson(key),
+      set: (value) => this.setJson(key, value)
+    };
+  }
+}
+// src/storage_adapter/typed_storage/createTypedStorage.ts
+function createTypedStorage({
+  storageAdapter
+}) {
+  const getJson = async (key) => {
+    return storageAdapter.getJson(key);
+  };
+  const getJsonOrDef = async (key, defVal) => {
+    return await storageAdapter.getJson(key) ?? defVal;
+  };
+  const setJson = async (key, val) => {
+    return storageAdapter.setJson(key, val);
+  };
+  const removeItem = async (key) => {
+    await storageAdapter.removeItem(key);
+  };
+  return {
+    getJson,
+    getJsonOrDef,
+    setJson,
+    removeItem
+  };
+}
+
+// src/storage_adapter/specific/browser/browser_storage.ts
+function createWebLocalStorageMethods(_localStorage) {
+  return {
+    type: "string" /* string */,
+    getItem: async (key) => _localStorage.getItem(key),
+    setItem: async (key, value) => {
+      _localStorage.setItem(key, value);
+    },
+    removeItem: async (key) => {
+      _localStorage.removeItem(key);
+    }
+  };
+}
+function createTypedWebLocalStorage(_localStorage, keyPrefix) {
+  return createTypedStorage({
+    storageAdapter: new StorageAdapter({
+      methods: createWebLocalStorageMethods(_localStorage),
+      keyPrefix
+    })
+  });
+}
+function createWebSessionStorageMethods(_sessionStorage) {
+  return {
+    type: "string" /* string */,
+    getItem: async (key) => _sessionStorage.getItem(key),
+    setItem: async (key, value) => {
+      _sessionStorage.setItem(key, value);
+    },
+    removeItem: async (key) => {
+      _sessionStorage.removeItem(key);
+    }
+  };
+}
+function createTypedWebSessionStorage(_sessionStorage, keyPrefix) {
+  return createTypedStorage({
+    storageAdapter: new StorageAdapter({
+      methods: createWebSessionStorageMethods(_sessionStorage),
+      keyPrefix
+    })
+  });
+}
+// src/storage_adapter/specific/durable_object/durable_object_storage.ts
+function createDurableObjectStorageMethods(durableObjectStorage) {
+  return {
+    type: "json" /* json */,
+    getItem: (key) => durableObjectStorage.get(key),
+    setItem: (key, value) => durableObjectStorage.put(key, value),
+    removeItem: async (key) => {
+      await durableObjectStorage.delete(key);
+    }
+  };
+}
+function createDurableObjectTypedStorage(durableObjectStorage, keyPrefix) {
+  return createTypedStorage({
+    storageAdapter: new StorageAdapter({
+      methods: createDurableObjectStorageMethods(durableObjectStorage),
+      keyPrefix
+    })
+  });
+}
+// src/storage_adapter/specific/memory/memory_storage.ts
+function createMemoryStorageMethods_string(memoryStorageMap = new Map) {
+  return {
+    type: "string" /* string */,
+    getItem: async (key) => memoryStorageMap.get(key) ?? null,
+    setItem: async (key, value) => {
+      memoryStorageMap.set(key, value);
+    },
+    removeItem: async (key) => {
+      memoryStorageMap.delete(key);
+    }
+  };
+}
+function createTypedMemoryStorage_string(memoryStorageMap = new Map, keyPrefix) {
+  return createTypedStorage({
+    storageAdapter: new StorageAdapter({
+      methods: createMemoryStorageMethods_string(memoryStorageMap),
+      keyPrefix
+    })
+  });
+}
+function createMemoryStorageMethods_json(memoryStorageMap = new Map) {
+  return {
+    type: "json" /* json */,
+    getItem: async (key) => memoryStorageMap.get(key),
+    setItem: async (key, value) => {
+      memoryStorageMap.set(key, value);
+    },
+    removeItem: async (key) => {
+      memoryStorageMap.delete(key);
+    }
+  };
+}
+function createTypedMemoryStorage_json(memoryStorageMap = new Map, keyPrefix) {
+  return createTypedStorage({
+    storageAdapter: new StorageAdapter({
+      methods: createMemoryStorageMethods_json(memoryStorageMap),
+      keyPrefix
+    })
+  });
+}
+export {
+  createWebSessionStorageMethods,
+  createWebLocalStorageMethods,
+  createTypedWebSessionStorage,
+  createTypedWebLocalStorage,
+  createTypedStorage,
+  createTypedMemoryStorage_string,
+  createTypedMemoryStorage_json,
+  createMemoryStorageMethods_string,
+  createMemoryStorageMethods_json,
+  createDurableObjectTypedStorage,
+  createDurableObjectStorageMethods,
+  StorageAdapter,
+  EStorageAdapterType
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/util",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "private": false,
   "type": "module",
   "exports": {