@nice-code/util 0.2.9 → 0.2.10

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/package.json

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