kvozy 0.0.1 → 0.3.0

package/README.md

@@ -14,11 +14,14 @@ This architecture makes it easy to add connectors for other frameworks (Vue, Sve
 ## Features
 
 - Framework-agnostic core (bindValue)
+- Type-safe generic API with custom serialization/deserialization
+- Flexible storage support (localStorage, sessionStorage, in-memory)
+- Graceful fallback to in-memory storage when storage is unavailable
 - Thin React integration (useStorage)
-- String-only values (simple, predictable)
-- Real localStorage backend
+- Real localStorage/backend storage
 - Subscription-based reactivity
 - TypeScript support
+- Required default values for safety
 - Easy to extend to other frameworks
 
 ## Installation
@@ -29,81 +32,81 @@ npm install kvozy
 
 ## Quick Start
 
+> ⚠️ **Note:** `bindValue` is an internal API. Use `useStorage` for React components. Direct usage of `bindValue` is not recommended.
+
 ```typescript
 import { bindValue, useStorage } from 'kvozy';
 
-// Define the binding
-const myValue = bindValue({ key: 'my-key' });
+// Define the binding with type, serialize, deserialize, and defaultValue
+const myValue = bindValue<string>({
+  key: 'my-key',
+  defaultValue: '',
+  serialize: (v) => v,
+  deserialize: (s) => s,
+});
 
 // Use in component
 const Component = () => {
   const { value, setValue } = useStorage(myValue);
 
-  return <input value={value || ''} onChange={(e) => setValue(e.target.value)} />;
+  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
 };
 ```
 
-## API Reference
-
-### bindValue(options)
-
-Creates a storage binding to localStorage.
-
-**Parameters:**
-
-- `options` (object, required)
-  - `key` (string, required) - localStorage key
-
-**Returns:** `BindValue` instance
+## Why In-Memory Storage?
 
-**Methods:**
+In-memory storage provides a graceful fallback when persistent storage is unavailable, such as:
 
-- `getValue()` - returns `string | undefined`
-- `set(value: string)` - updates localStorage and notifies subscribers
-- `subscribe(callback)` - subscribe to value changes, returns unsubscribe function
+- **Incognito/Private Mode**: Some browsers disable localStorage in private browsing
+- **Storage Quota Exceeded**: When storage limits are reached
+- **Cookie/Storage Disabled**: When users have disabled cookies/storage
 
-**Behavior:**
+```typescript
+// This code works even if localStorage is unavailable (e.g., incognito mode)
+const bindedValue = bindValue({
+  key: "some-key",
+  storage: localStorage ?? undefined,
+});
+// Falls back to in-memory storage, so your code continues to work
+```
 
-- `subscribe()` does NOT call the callback immediately when subscribing
-- Callbacks are only invoked when value changes via `set()`
+The in-memory storage ensures your application remains functional, maintaining session state without throwing errors or breaking your user experience.
 
-**Example:**
+## API Reference
 
-```typescript
-const binding = bindValue({ key: "user-name" });
+> ⚠️ **Note:** `bindValue` is an internal API. Use `useStorage` for React components. Direct usage of `bindValue` is not recommended.
 
-// Get current value
-const currentValue = binding.getValue();
+### BindValueOptions<T>
 
-// Set new value
-binding.set("Alice");
+Options for creating a BindValue instance.
 
-// Subscribe to changes
-const unsubscribe = binding.subscribe((newValue) => {
-  console.log("Value changed:", newValue);
-});
+**Parameters:**
 
-// Unsubscribe when done
-unsubscribe();
-```
+- `key` (string, required) - Storage key
+- `defaultValue` (T, required) - Default value when key doesn't exist or deserialize fails
+- `serialize` (function, required) - Convert value to string: `(value: T) => string`
+- `deserialize` (function, required) - Convert string to value: `(serialized: string) => T`
+- `storage` (Storage, optional) - localStorage, sessionStorage, or undefined for in-memory
 
-### useStorage(binding)
+### useStorage<T>(binding)
 
 React hook that connects a BindValue instance to React state.
 
 **Parameters:**
 
-- `binding` (BindValue, required) - binding instance from bindValue
+- `binding` (BindValue<T>, required) - binding instance from bindValue
 
 **Returns:** `{ value, setValue }`
 
-- `value` - `string | undefined` - current value from localStorage
-- `setValue` - `(value: string) => void` - function to update value
+- `value` - `T` - current value from storage
+- `setValue` - `(value: T) => void` - function to update value
 
 **Behavior:**
 
 - `subscribe()` does NOT call the callback immediately when subscribing
 - Callbacks are only invoked when the value changes via `set()`
+- If `serialize()` fails, in-memory value is kept but storage is NOT updated
+- If `deserialize()` fails, `defaultValue` is returned
 
 **Example:**
 
@@ -112,7 +115,7 @@ const Component = () => {
   const { value, setValue } = useStorage(myBinding);
 
   return <div>
-    <p>Current value: {value || '(empty)'}</p>
+    <p>Current value: {value}</p>
     <button onClick={() => setValue('new value')}>
       Update Value
     </button>
@@ -127,7 +130,12 @@ const Component = () => {
 ```typescript
 import { bindValue, useStorage } from 'kvozy';
 
-const usernameBinding = bindValue({ key: 'username' });
+const usernameBinding = bindValue<string>({
+  key: 'username',
+  defaultValue: '',
+  serialize: (v) => v,
+  deserialize: (s) => s,
+});
 
 const LoginForm = () => {
   const { value, setValue } = useStorage(usernameBinding);
@@ -137,7 +145,7 @@ const LoginForm = () => {
       <label>
         Username:
         <input
-          value={value || ''}
+          value={value}
           onChange={(e) => setValue(e.target.value)}
         />
       </label>
@@ -151,7 +159,12 @@ const LoginForm = () => {
 ```typescript
 import { bindValue, useStorage } from 'kvozy';
 
-const themeBinding = bindValue({ key: 'theme' });
+const themeBinding = bindValue<string>({
+  key: 'theme',
+  defaultValue: 'light',
+  serialize: (v) => v,
+  deserialize: (s) => s,
+});
 
 const ThemeToggle = () => {
   const { value, setValue } = useStorage(themeBinding);
@@ -181,22 +194,81 @@ Both components stay in sync automatically!
 
 ### Handling Undefined Values
 
-When a localStorage key doesn't exist, `getValue()` and `useStorage` return `undefined`:
+When a localStorage key doesn't exist, `defaultValue` is returned:
 
 ```typescript
-const binding = bindValue({ key: 'non-existent-key' });
-console.log(binding.getValue()); // undefined
+const binding = bindValue<string>({
+  key: 'non-existent-key',
+  defaultValue: 'default value',
+  serialize: (v) => v,
+  deserialize: (s) => s,
+});
+console.log(binding.getValue()); // 'default value'
 
 const Component = () => {
   const { value } = useStorage(binding);
-  return <div>{value || 'No value set'}</div>;
+  return <div>{value}</div>;
+};
+```
+
+### Using Different Storage Types
+
+Kvozy supports localStorage, sessionStorage, and in-memory storage:
+
+```typescript
+import { bindValue, useStorage } from 'kvozy';
+
+// localStorage - persists across browser sessions
+const localBinding = bindValue<string>({
+  key: 'theme',
+  defaultValue: 'light',
+  serialize: (v) => v,
+  deserialize: (s) => s,
+  storage: localStorage,
+});
+
+// sessionStorage - persists within the same tab
+const sessionBinding = bindValue<string>({
+  key: 'form-data',
+  defaultValue: '',
+  serialize: (v) => v,
+  deserialize: (s) => s,
+  storage: sessionStorage,
+});
+
+// In-memory - no persistence, graceful fallback
+const memoryBinding = bindValue<string>({
+  key: 'temp-state',
+  defaultValue: '',
+  serialize: (v) => v,
+  deserialize: (s) => s,
+});
+
+const LocalComponent = () => {
+  const { value, setValue } = useStorage(localBinding);
+  return <div>Theme: {value}</div>;
+};
+
+const SessionComponent = () => {
+  const { value, setValue } = useStorage(sessionBinding);
+  return <div>Form data: {value || 'empty'}</div>;
+};
+
+const MemoryComponent = () => {
+  const { value, setValue } = useStorage(memoryBinding);
+  return <div>Temp: {value || 'empty'}</div>;
 };
 ```
 
 ### Persisting Form Data
 
 ```typescript
-const formBinding = bindValue({ key: 'form-data' });
+const formBinding = bindValue<string>({
+  key: 'form-data',
+  defaultValue: '',
+  serialize: (v) => v,
+  deserialize: (s) => s,
+});
 
 const Form = () => {
   const { value, setValue } = useStorage(formBinding);
@@ -223,22 +295,26 @@ const Form = () => {
 ### Counter Example
 
 ```typescript
-const counterBinding = bindValue({ key: 'counter' });
+const counterBinding = bindValue<number>({
+  key: 'counter',
+  defaultValue: 0,
+  serialize: (v) => String(v),
+  deserialize: (s) => Number(s),
+});
 
 const Counter = () => {
   const { value, setValue } = useStorage(counterBinding);
-  const count = parseInt(value || '0', 10);
 
   return (
     <div>
-      <p>Count: {count}</p>
-      <button onClick={() => setValue(String(count + 1))}>
+      <p>Count: {value}</p>
+      <button onClick={() => setValue(value + 1)}>
         Increment
       </button>
-      <button onClick={() => setValue(String(count - 1))}>
+      <button onClick={() => setValue(value - 1)}>
         Decrement
       </button>
-      <button onClick={() => setValue('0')}>
+      <button onClick={() => setValue(0)}>
         Reset
       </button>
     </div>
@@ -253,18 +329,19 @@ const Counter = () => {
 All storage logic lives in `bindValue` class:
 
 - Framework-agnostic
+- Type-safe generic API
 - Manages localStorage operations
 - Handles subscriptions
 - Can be used with any UI framework
 
 ```typescript
-class BindValue {
-  private value: string | undefined;
-  private subscribers: Set<(value: string | undefined) => void>;
+class BindValue<T> {
+  private value: T;
+  private subscribers: Set<(value: T) => void>;
 
-  getValue(): string | undefined;
-  set(value: string): void;
-  subscribe(callback): () => void;
+  getValue(): T;
+  set(value: T): void;
+  subscribe(callback: (value: T) => void): () => void;
 }
 ```
 
@@ -278,7 +355,7 @@ Thin wrapper that connects `bindValue` to React:
 - Returns `{ value, setValue }`
 
 ```typescript
-function useStorage(binding: BindValue): UseStorageReturn {
+function useStorage<T>(binding: BindValue<T>): UseStorageReturn<T> {
   const [value, setValue] = useState(binding.getValue());
 
   useEffect(() => {
@@ -286,62 +363,17 @@ function useStorage(binding: BindValue): UseStorageReturn {
     return unsubscribe;
   }, [binding]);
 
-  const set = (newValue: string) => binding.set(newValue);
+  const set = (newValue: T) => binding.set(newValue);
 
   return { value, setValue: set };
 }
 ```
 
-## Testing
-
-### Unit Tests (Node)
-
-Run unit tests for `bindValue`:
-
-```bash
-npm test
-```
-
-Tests are located in `unitTests/bindValue.test.ts` and use mocked localStorage.
-
-### Browser Tests (Playwright)
-
-Run browser tests for React integration:
-
-```bash
-npm run test:browser
-```
-
-Tests are located in `browserTests/useStorage.test.ts` and run on Chrome, Firefox, and Webkit.
-
-## Browser Support
-
-- Chrome >= 87
-- Firefox >= 78
-- Safari >= 15.4
-- Edge >= 88
-
-## TypeScript Support
-
-Kvozy is written in TypeScript and provides full type definitions:
-
-```typescript
-import {
-  bindValue,
-  useStorage,
-  type BindValue,
-  type UseStorageReturn,
-} from "kvozy";
-
-const binding: BindValue = bindValue({ key: "test" });
-const { value, setValue }: UseStorageReturn = useStorage(binding);
-```
-
 ## Limitations
 
-- **String-only values**: Kvozy only supports string values. For objects or arrays, serialize them as JSON.
 - **No SSR support**: Currently designed for client-side only (requires `window.localStorage`).
 - **No cross-tab sync**: Changes in one tab don't update other tabs automatically.
+- **Serialize failures**: If `serialize()` fails, the value is kept in memory but not persisted to storage (graceful degradation).
 
 ## Future Plans
 
@@ -350,11 +382,4 @@ const { value, setValue }: UseStorageReturn = useStorage(binding);
 - [ ] Angular connector
 - [ ] SSR support
 - [ ] Cross-tab synchronization
-
-## License
-
-ISC
-
-## Contributing
-
-Contributions are welcome! Please read `src/AGENTS.md` for development guidelines.
+- [ ] Console warnings on serialization/deserialization errors for debugging

package/__compiled__/cjs/src/bindValue.d.ts

@@ -1,16 +1,21 @@
-export interface BindValueOptions {
+export interface BindValueOptions<T> {
     key: string;
+    defaultValue: T;
+    serialize: (value: T) => string;
+    deserialize: (serialized: string) => T;
+    storage?: Storage;
 }
-export declare class BindValue {
+export declare class BindValue<T> {
     private options;
     private value;
     private subscribers;
-    constructor(options: BindValueOptions);
-    getValue(): string | undefined;
-    set(newValue: string): void;
-    subscribe(callback: (value: string | undefined) => void): () => void;
+    private storage;
+    constructor(options: BindValueOptions<T>);
+    getValue(): T;
+    set(newValue: T): void;
+    subscribe(callback: (value: T) => void): () => void;
     private loadFromStorage;
     private saveToStorage;
     private notifySubscribers;
 }
-export declare function bindValue(options: BindValueOptions): BindValue;
+export declare function bindValue<T>(options: BindValueOptions<T>): BindValue<T>;

package/__compiled__/cjs/src/bindValue.js

@@ -3,11 +3,35 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const memoryStorage = /* @__PURE__ */ new Map();
+const inMemoryStorage = {
+  get length() {
+    return memoryStorage.size;
+  },
+  clear() {
+    memoryStorage.clear();
+  },
+  getItem(key) {
+    return memoryStorage.get(key) ?? null;
+  },
+  key(index) {
+    const keys = Array.from(memoryStorage.keys());
+    return keys[index] ?? null;
+  },
+  removeItem(key) {
+    memoryStorage.delete(key);
+  },
+  setItem(key, value) {
+    memoryStorage.set(key, value);
+  }
+};
 class BindValue {
   constructor(options) {
     __publicField(this, "value");
     __publicField(this, "subscribers");
+    __publicField(this, "storage");
     this.options = options;
+    this.storage = options.storage ?? inMemoryStorage;
     this.subscribers = /* @__PURE__ */ new Set();
     this.value = this.loadFromStorage();
   }
@@ -26,11 +50,22 @@ class BindValue {
     };
   }
   loadFromStorage() {
-    const value = localStorage.getItem(this.options.key);
-    return value !== null ? value : void 0;
+    const rawValue = this.storage.getItem(this.options.key);
+    if (rawValue === null) {
+      return this.options.defaultValue;
+    }
+    try {
+      return this.options.deserialize(rawValue);
+    } catch {
+      return this.options.defaultValue;
+    }
   }
   saveToStorage(value) {
-    localStorage.setItem(this.options.key, value);
+    try {
+      const serialized = this.options.serialize(value);
+      this.storage.setItem(this.options.key, serialized);
+    } catch {
+    }
   }
   notifySubscribers() {
     for (const subscriber of this.subscribers) {

package/__compiled__/cjs/src/bindValue.js.map

@@ -1 +1 @@
-{"version":3,"file":"bindValue.js","sources":["../../../../src/bindValue.ts"],"sourcesContent":["export interface BindValueOptions {\n  key: string;\n}\n\nexport class BindValue {\n  private value: string | undefined;\n  private subscribers: Set<(value: string | undefined) => void>;\n\n  constructor(private options: BindValueOptions) {\n    this.subscribers = new Set();\n    this.value = this.loadFromStorage();\n  }\n\n  getValue(): string | undefined {\n    return this.value;\n  }\n\n  set(newValue: string): void {\n    this.value = newValue;\n    this.saveToStorage(newValue);\n    this.notifySubscribers();\n  }\n\n  subscribe(callback: (value: string | undefined) => void): () => void {\n    this.subscribers.add(callback);\n    return () => {\n      this.subscribers.delete(callback);\n    };\n  }\n\n  private loadFromStorage(): string | undefined {\n    const value = localStorage.getItem(this.options.key);\n    return value !== null ? value : undefined;\n  }\n\n  private saveToStorage(value: string): void {\n    localStorage.setItem(this.options.key, value);\n  }\n\n  private notifySubscribers(): void {\n    for (const subscriber of this.subscribers) {\n      subscriber(this.value);\n    }\n  }\n}\n\nexport function bindValue(options: BindValueOptions): BindValue {\n  return new BindValue(options);\n}\n"],"names":[],"mappings":";;;;;AAIO,MAAM,UAAU;AAAA,EAIrB,YAAoB,SAA2B;AAHvC;AACA;AAEY,SAAA,UAAA;AAClB,SAAK,kCAAkB,IAAA;AACvB,SAAK,QAAQ,KAAK,gBAAA;AAAA,EACpB;AAAA,EAEA,WAA+B;AAC7B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,UAAwB;AAC1B,SAAK,QAAQ;AACb,SAAK,cAAc,QAAQ;AAC3B,SAAK,kBAAA;AAAA,EACP;AAAA,EAEA,UAAU,UAA2D;AACnE,SAAK,YAAY,IAAI,QAAQ;AAC7B,WAAO,MAAM;AACX,WAAK,YAAY,OAAO,QAAQ;AAAA,IAClC;AAAA,EACF;AAAA,EAEQ,kBAAsC;AAC5C,UAAM,QAAQ,aAAa,QAAQ,KAAK,QAAQ,GAAG;AACnD,WAAO,UAAU,OAAO,QAAQ;AAAA,EAClC;AAAA,EAEQ,cAAc,OAAqB;AACzC,iBAAa,QAAQ,KAAK,QAAQ,KAAK,KAAK;AAAA,EAC9C;AAAA,EAEQ,oBAA0B;AAChC,eAAW,cAAc,KAAK,aAAa;AACzC,iBAAW,KAAK,KAAK;AAAA,IACvB;AAAA,EACF;AACF;AAEO,SAAS,UAAU,SAAsC;AAC9D,SAAO,IAAI,UAAU,OAAO;AAC9B;;;"}
+{"version":3,"file":"bindValue.js","sources":["../../../../src/bindValue.ts"],"sourcesContent":["export interface BindValueOptions<T> {\n  key: string;\n  defaultValue: T;\n  serialize: (value: T) => string;\n  deserialize: (serialized: string) => T;\n  storage?: Storage;\n}\n\nconst memoryStorage = new Map<string, string>();\n\nconst inMemoryStorage: Storage = {\n  get length() {\n    return memoryStorage.size;\n  },\n  clear() {\n    memoryStorage.clear();\n  },\n  getItem(key: string) {\n    return memoryStorage.get(key) ?? null;\n  },\n  key(index: number) {\n    const keys = Array.from(memoryStorage.keys());\n    return keys[index] ?? null;\n  },\n  removeItem(key: string) {\n    memoryStorage.delete(key);\n  },\n  setItem(key: string, value: string) {\n    memoryStorage.set(key, value);\n  },\n};\n\nexport class BindValue<T> {\n  private value: T;\n  private subscribers: Set<(value: T) => void>;\n  private storage: Storage;\n\n  constructor(private options: BindValueOptions<T>) {\n    this.storage = options.storage ?? inMemoryStorage;\n    this.subscribers = new Set();\n    this.value = this.loadFromStorage();\n  }\n\n  getValue(): T {\n    return this.value;\n  }\n\n  set(newValue: T): void {\n    this.value = newValue;\n    this.saveToStorage(newValue);\n    this.notifySubscribers();\n  }\n\n  subscribe(callback: (value: T) => void): () => void {\n    this.subscribers.add(callback);\n    return () => {\n      this.subscribers.delete(callback);\n    };\n  }\n\n  private loadFromStorage(): T {\n    const rawValue = this.storage.getItem(this.options.key);\n\n    if (rawValue === null) {\n      return this.options.defaultValue;\n    }\n\n    try {\n      return this.options.deserialize(rawValue);\n    } catch {\n      return this.options.defaultValue;\n    }\n  }\n\n  private saveToStorage(value: T): void {\n    try {\n      const serialized = this.options.serialize(value);\n      this.storage.setItem(this.options.key, serialized);\n    } catch {}\n  }\n\n  private notifySubscribers(): void {\n    for (const subscriber of this.subscribers) {\n      subscriber(this.value);\n    }\n  }\n}\n\nexport function bindValue<T>(options: BindValueOptions<T>): BindValue<T> {\n  return new BindValue(options);\n}\n"],"names":[],"mappings":";;;;;AAQA,MAAM,oCAAoB,IAAA;AAE1B,MAAM,kBAA2B;AAAA,EAC/B,IAAI,SAAS;AACX,WAAO,cAAc;AAAA,EACvB;AAAA,EACA,QAAQ;AACN,kBAAc,MAAA;AAAA,EAChB;AAAA,EACA,QAAQ,KAAa;AACnB,WAAO,cAAc,IAAI,GAAG,KAAK;AAAA,EACnC;AAAA,EACA,IAAI,OAAe;AACjB,UAAM,OAAO,MAAM,KAAK,cAAc,MAAM;AAC5C,WAAO,KAAK,KAAK,KAAK;AAAA,EACxB;AAAA,EACA,WAAW,KAAa;AACtB,kBAAc,OAAO,GAAG;AAAA,EAC1B;AAAA,EACA,QAAQ,KAAa,OAAe;AAClC,kBAAc,IAAI,KAAK,KAAK;AAAA,EAC9B;AACF;AAEO,MAAM,UAAa;AAAA,EAKxB,YAAoB,SAA8B;AAJ1C;AACA;AACA;AAEY,SAAA,UAAA;AAClB,SAAK,UAAU,QAAQ,WAAW;AAClC,SAAK,kCAAkB,IAAA;AACvB,SAAK,QAAQ,KAAK,gBAAA;AAAA,EACpB;AAAA,EAEA,WAAc;AACZ,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,UAAmB;AACrB,SAAK,QAAQ;AACb,SAAK,cAAc,QAAQ;AAC3B,SAAK,kBAAA;AAAA,EACP;AAAA,EAEA,UAAU,UAA0C;AAClD,SAAK,YAAY,IAAI,QAAQ;AAC7B,WAAO,MAAM;AACX,WAAK,YAAY,OAAO,QAAQ;AAAA,IAClC;AAAA,EACF;AAAA,EAEQ,kBAAqB;AAC3B,UAAM,WAAW,KAAK,QAAQ,QAAQ,KAAK,QAAQ,GAAG;AAEtD,QAAI,aAAa,MAAM;AACrB,aAAO,KAAK,QAAQ;AAAA,IACtB;AAEA,QAAI;AACF,aAAO,KAAK,QAAQ,YAAY,QAAQ;AAAA,IAC1C,QAAQ;AACN,aAAO,KAAK,QAAQ;AAAA,IACtB;AAAA,EACF;AAAA,EAEQ,cAAc,OAAgB;AACpC,QAAI;AACF,YAAM,aAAa,KAAK,QAAQ,UAAU,KAAK;AAC/C,WAAK,QAAQ,QAAQ,KAAK,QAAQ,KAAK,UAAU;AAAA,IACnD,QAAQ;AAAA,IAAC;AAAA,EACX;AAAA,EAEQ,oBAA0B;AAChC,eAAW,cAAc,KAAK,aAAa;AACzC,iBAAW,KAAK,KAAK;AAAA,IACvB;AAAA,EACF;AACF;AAEO,SAAS,UAAa,SAA4C;AACvE,SAAO,IAAI,UAAU,OAAO;AAC9B;;;"}

package/__compiled__/cjs/src/useStorage.d.ts

@@ -1,6 +1,6 @@
 import { type BindValue } from "./bindValue.js";
-export interface UseStorageReturn {
-    value: string | undefined;
-    setValue: (value: string) => void;
+export interface UseStorageReturn<T> {
+    value: T;
+    setValue: (value: T) => void;
 }
-export declare function useStorage(binding: BindValue): UseStorageReturn;
+export declare function useStorage<T>(binding: BindValue<T>): UseStorageReturn<T>;

package/__compiled__/cjs/src/useStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStorage.js","sources":["../../../../src/useStorage.ts"],"sourcesContent":["import { useState, useEffect } from \"react\";\nimport { type BindValue } from \"./bindValue.js\";\n\nexport interface UseStorageReturn {\n  value: string | undefined;\n  setValue: (value: string) => void;\n}\n\nexport function useStorage(binding: BindValue): UseStorageReturn {\n  const [value, setValue] = useState(binding.getValue());\n\n  useEffect(() => {\n    const unsubscribe = binding.subscribe(setValue);\n    return unsubscribe;\n  }, [binding]);\n\n  const set = (newValue: string) => {\n    binding.set(newValue);\n  };\n\n  return { value, setValue: set };\n}\n"],"names":["useState","useEffect"],"mappings":";;;AAQO,SAAS,WAAW,SAAsC;AAC/D,QAAM,CAAC,OAAO,QAAQ,IAAIA,MAAAA,SAAS,QAAQ,UAAU;AAErDC,QAAAA,UAAU,MAAM;AACd,UAAM,cAAc,QAAQ,UAAU,QAAQ;AAC9C,WAAO;AAAA,EACT,GAAG,CAAC,OAAO,CAAC;AAEZ,QAAM,MAAM,CAAC,aAAqB;AAChC,YAAQ,IAAI,QAAQ;AAAA,EACtB;AAEA,SAAO,EAAE,OAAO,UAAU,IAAA;AAC5B;;"}
+{"version":3,"file":"useStorage.js","sources":["../../../../src/useStorage.ts"],"sourcesContent":["import { useState, useEffect } from \"react\";\nimport { type BindValue } from \"./bindValue.js\";\n\nexport interface UseStorageReturn<T> {\n  value: T;\n  setValue: (value: T) => void;\n}\n\nexport function useStorage<T>(binding: BindValue<T>): UseStorageReturn<T> {\n  const [value, setValue] = useState(binding.getValue());\n\n  useEffect(() => {\n    const unsubscribe = binding.subscribe(setValue);\n    return unsubscribe;\n  }, [binding]);\n\n  const set = (newValue: T) => {\n    binding.set(newValue);\n  };\n\n  return { value, setValue: set };\n}\n"],"names":["useState","useEffect"],"mappings":";;;AAQO,SAAS,WAAc,SAA4C;AACxE,QAAM,CAAC,OAAO,QAAQ,IAAIA,MAAAA,SAAS,QAAQ,UAAU;AAErDC,QAAAA,UAAU,MAAM;AACd,UAAM,cAAc,QAAQ,UAAU,QAAQ;AAC9C,WAAO;AAAA,EACT,GAAG,CAAC,OAAO,CAAC;AAEZ,QAAM,MAAM,CAAC,aAAgB;AAC3B,YAAQ,IAAI,QAAQ;AAAA,EACtB;AAEA,SAAO,EAAE,OAAO,UAAU,IAAA;AAC5B;;"}

package/__compiled__/esm/src/bindValue.d.mts

@@ -1,16 +1,21 @@
-export interface BindValueOptions {
+export interface BindValueOptions<T> {
     key: string;
+    defaultValue: T;
+    serialize: (value: T) => string;
+    deserialize: (serialized: string) => T;
+    storage?: Storage;
 }
-export declare class BindValue {
+export declare class BindValue<T> {
     private options;
     private value;
     private subscribers;
-    constructor(options: BindValueOptions);
-    getValue(): string | undefined;
-    set(newValue: string): void;
-    subscribe(callback: (value: string | undefined) => void): () => void;
+    private storage;
+    constructor(options: BindValueOptions<T>);
+    getValue(): T;
+    set(newValue: T): void;
+    subscribe(callback: (value: T) => void): () => void;
     private loadFromStorage;
     private saveToStorage;
     private notifySubscribers;
 }
-export declare function bindValue(options: BindValueOptions): BindValue;
+export declare function bindValue<T>(options: BindValueOptions<T>): BindValue<T>;

package/__compiled__/esm/src/bindValue.mjs

@@ -1,11 +1,35 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+const memoryStorage = /* @__PURE__ */ new Map();
+const inMemoryStorage = {
+  get length() {
+    return memoryStorage.size;
+  },
+  clear() {
+    memoryStorage.clear();
+  },
+  getItem(key) {
+    return memoryStorage.get(key) ?? null;
+  },
+  key(index) {
+    const keys = Array.from(memoryStorage.keys());
+    return keys[index] ?? null;
+  },
+  removeItem(key) {
+    memoryStorage.delete(key);
+  },
+  setItem(key, value) {
+    memoryStorage.set(key, value);
+  }
+};
 class BindValue {
   constructor(options) {
     __publicField(this, "value");
     __publicField(this, "subscribers");
+    __publicField(this, "storage");
     this.options = options;
+    this.storage = options.storage ?? inMemoryStorage;
     this.subscribers = /* @__PURE__ */ new Set();
     this.value = this.loadFromStorage();
   }
@@ -24,11 +48,22 @@ class BindValue {
     };
   }
   loadFromStorage() {
-    const value = localStorage.getItem(this.options.key);
-    return value !== null ? value : void 0;
+    const rawValue = this.storage.getItem(this.options.key);
+    if (rawValue === null) {
+      return this.options.defaultValue;
+    }
+    try {
+      return this.options.deserialize(rawValue);
+    } catch {
+      return this.options.defaultValue;
+    }
   }
   saveToStorage(value) {
-    localStorage.setItem(this.options.key, value);
+    try {
+      const serialized = this.options.serialize(value);
+      this.storage.setItem(this.options.key, serialized);
+    } catch {
+    }
   }
   notifySubscribers() {
     for (const subscriber of this.subscribers) {

package/__compiled__/esm/src/bindValue.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"bindValue.mjs","sources":["../../../../src/bindValue.ts"],"sourcesContent":["export interface BindValueOptions {\n  key: string;\n}\n\nexport class BindValue {\n  private value: string | undefined;\n  private subscribers: Set<(value: string | undefined) => void>;\n\n  constructor(private options: BindValueOptions) {\n    this.subscribers = new Set();\n    this.value = this.loadFromStorage();\n  }\n\n  getValue(): string | undefined {\n    return this.value;\n  }\n\n  set(newValue: string): void {\n    this.value = newValue;\n    this.saveToStorage(newValue);\n    this.notifySubscribers();\n  }\n\n  subscribe(callback: (value: string | undefined) => void): () => void {\n    this.subscribers.add(callback);\n    return () => {\n      this.subscribers.delete(callback);\n    };\n  }\n\n  private loadFromStorage(): string | undefined {\n    const value = localStorage.getItem(this.options.key);\n    return value !== null ? value : undefined;\n  }\n\n  private saveToStorage(value: string): void {\n    localStorage.setItem(this.options.key, value);\n  }\n\n  private notifySubscribers(): void {\n    for (const subscriber of this.subscribers) {\n      subscriber(this.value);\n    }\n  }\n}\n\nexport function bindValue(options: BindValueOptions): BindValue {\n  return new BindValue(options);\n}\n"],"names":[],"mappings":";;;AAIO,MAAM,UAAU;AAAA,EAIrB,YAAoB,SAA2B;AAHvC;AACA;AAEY,SAAA,UAAA;AAClB,SAAK,kCAAkB,IAAA;AACvB,SAAK,QAAQ,KAAK,gBAAA;AAAA,EACpB;AAAA,EAEA,WAA+B;AAC7B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,UAAwB;AAC1B,SAAK,QAAQ;AACb,SAAK,cAAc,QAAQ;AAC3B,SAAK,kBAAA;AAAA,EACP;AAAA,EAEA,UAAU,UAA2D;AACnE,SAAK,YAAY,IAAI,QAAQ;AAC7B,WAAO,MAAM;AACX,WAAK,YAAY,OAAO,QAAQ;AAAA,IAClC;AAAA,EACF;AAAA,EAEQ,kBAAsC;AAC5C,UAAM,QAAQ,aAAa,QAAQ,KAAK,QAAQ,GAAG;AACnD,WAAO,UAAU,OAAO,QAAQ;AAAA,EAClC;AAAA,EAEQ,cAAc,OAAqB;AACzC,iBAAa,QAAQ,KAAK,QAAQ,KAAK,KAAK;AAAA,EAC9C;AAAA,EAEQ,oBAA0B;AAChC,eAAW,cAAc,KAAK,aAAa;AACzC,iBAAW,KAAK,KAAK;AAAA,IACvB;AAAA,EACF;AACF;AAEO,SAAS,UAAU,SAAsC;AAC9D,SAAO,IAAI,UAAU,OAAO;AAC9B;"}
+{"version":3,"file":"bindValue.mjs","sources":["../../../../src/bindValue.ts"],"sourcesContent":["export interface BindValueOptions<T> {\n  key: string;\n  defaultValue: T;\n  serialize: (value: T) => string;\n  deserialize: (serialized: string) => T;\n  storage?: Storage;\n}\n\nconst memoryStorage = new Map<string, string>();\n\nconst inMemoryStorage: Storage = {\n  get length() {\n    return memoryStorage.size;\n  },\n  clear() {\n    memoryStorage.clear();\n  },\n  getItem(key: string) {\n    return memoryStorage.get(key) ?? null;\n  },\n  key(index: number) {\n    const keys = Array.from(memoryStorage.keys());\n    return keys[index] ?? null;\n  },\n  removeItem(key: string) {\n    memoryStorage.delete(key);\n  },\n  setItem(key: string, value: string) {\n    memoryStorage.set(key, value);\n  },\n};\n\nexport class BindValue<T> {\n  private value: T;\n  private subscribers: Set<(value: T) => void>;\n  private storage: Storage;\n\n  constructor(private options: BindValueOptions<T>) {\n    this.storage = options.storage ?? inMemoryStorage;\n    this.subscribers = new Set();\n    this.value = this.loadFromStorage();\n  }\n\n  getValue(): T {\n    return this.value;\n  }\n\n  set(newValue: T): void {\n    this.value = newValue;\n    this.saveToStorage(newValue);\n    this.notifySubscribers();\n  }\n\n  subscribe(callback: (value: T) => void): () => void {\n    this.subscribers.add(callback);\n    return () => {\n      this.subscribers.delete(callback);\n    };\n  }\n\n  private loadFromStorage(): T {\n    const rawValue = this.storage.getItem(this.options.key);\n\n    if (rawValue === null) {\n      return this.options.defaultValue;\n    }\n\n    try {\n      return this.options.deserialize(rawValue);\n    } catch {\n      return this.options.defaultValue;\n    }\n  }\n\n  private saveToStorage(value: T): void {\n    try {\n      const serialized = this.options.serialize(value);\n      this.storage.setItem(this.options.key, serialized);\n    } catch {}\n  }\n\n  private notifySubscribers(): void {\n    for (const subscriber of this.subscribers) {\n      subscriber(this.value);\n    }\n  }\n}\n\nexport function bindValue<T>(options: BindValueOptions<T>): BindValue<T> {\n  return new BindValue(options);\n}\n"],"names":[],"mappings":";;;AAQA,MAAM,oCAAoB,IAAA;AAE1B,MAAM,kBAA2B;AAAA,EAC/B,IAAI,SAAS;AACX,WAAO,cAAc;AAAA,EACvB;AAAA,EACA,QAAQ;AACN,kBAAc,MAAA;AAAA,EAChB;AAAA,EACA,QAAQ,KAAa;AACnB,WAAO,cAAc,IAAI,GAAG,KAAK;AAAA,EACnC;AAAA,EACA,IAAI,OAAe;AACjB,UAAM,OAAO,MAAM,KAAK,cAAc,MAAM;AAC5C,WAAO,KAAK,KAAK,KAAK;AAAA,EACxB;AAAA,EACA,WAAW,KAAa;AACtB,kBAAc,OAAO,GAAG;AAAA,EAC1B;AAAA,EACA,QAAQ,KAAa,OAAe;AAClC,kBAAc,IAAI,KAAK,KAAK;AAAA,EAC9B;AACF;AAEO,MAAM,UAAa;AAAA,EAKxB,YAAoB,SAA8B;AAJ1C;AACA;AACA;AAEY,SAAA,UAAA;AAClB,SAAK,UAAU,QAAQ,WAAW;AAClC,SAAK,kCAAkB,IAAA;AACvB,SAAK,QAAQ,KAAK,gBAAA;AAAA,EACpB;AAAA,EAEA,WAAc;AACZ,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,UAAmB;AACrB,SAAK,QAAQ;AACb,SAAK,cAAc,QAAQ;AAC3B,SAAK,kBAAA;AAAA,EACP;AAAA,EAEA,UAAU,UAA0C;AAClD,SAAK,YAAY,IAAI,QAAQ;AAC7B,WAAO,MAAM;AACX,WAAK,YAAY,OAAO,QAAQ;AAAA,IAClC;AAAA,EACF;AAAA,EAEQ,kBAAqB;AAC3B,UAAM,WAAW,KAAK,QAAQ,QAAQ,KAAK,QAAQ,GAAG;AAEtD,QAAI,aAAa,MAAM;AACrB,aAAO,KAAK,QAAQ;AAAA,IACtB;AAEA,QAAI;AACF,aAAO,KAAK,QAAQ,YAAY,QAAQ;AAAA,IAC1C,QAAQ;AACN,aAAO,KAAK,QAAQ;AAAA,IACtB;AAAA,EACF;AAAA,EAEQ,cAAc,OAAgB;AACpC,QAAI;AACF,YAAM,aAAa,KAAK,QAAQ,UAAU,KAAK;AAC/C,WAAK,QAAQ,QAAQ,KAAK,QAAQ,KAAK,UAAU;AAAA,IACnD,QAAQ;AAAA,IAAC;AAAA,EACX;AAAA,EAEQ,oBAA0B;AAChC,eAAW,cAAc,KAAK,aAAa;AACzC,iBAAW,KAAK,KAAK;AAAA,IACvB;AAAA,EACF;AACF;AAEO,SAAS,UAAa,SAA4C;AACvE,SAAO,IAAI,UAAU,OAAO;AAC9B;"}

package/__compiled__/esm/src/useStorage.d.mts

@@ -1,6 +1,6 @@
 import { type BindValue } from "./bindValue.js";
-export interface UseStorageReturn {
-    value: string | undefined;
-    setValue: (value: string) => void;
+export interface UseStorageReturn<T> {
+    value: T;
+    setValue: (value: T) => void;
 }
-export declare function useStorage(binding: BindValue): UseStorageReturn;
+export declare function useStorage<T>(binding: BindValue<T>): UseStorageReturn<T>;

package/__compiled__/esm/src/useStorage.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"useStorage.mjs","sources":["../../../../src/useStorage.ts"],"sourcesContent":["import { useState, useEffect } from \"react\";\nimport { type BindValue } from \"./bindValue.js\";\n\nexport interface UseStorageReturn {\n  value: string | undefined;\n  setValue: (value: string) => void;\n}\n\nexport function useStorage(binding: BindValue): UseStorageReturn {\n  const [value, setValue] = useState(binding.getValue());\n\n  useEffect(() => {\n    const unsubscribe = binding.subscribe(setValue);\n    return unsubscribe;\n  }, [binding]);\n\n  const set = (newValue: string) => {\n    binding.set(newValue);\n  };\n\n  return { value, setValue: set };\n}\n"],"names":[],"mappings":";AAQO,SAAS,WAAW,SAAsC;AAC/D,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAS,QAAQ,UAAU;AAErD,YAAU,MAAM;AACd,UAAM,cAAc,QAAQ,UAAU,QAAQ;AAC9C,WAAO;AAAA,EACT,GAAG,CAAC,OAAO,CAAC;AAEZ,QAAM,MAAM,CAAC,aAAqB;AAChC,YAAQ,IAAI,QAAQ;AAAA,EACtB;AAEA,SAAO,EAAE,OAAO,UAAU,IAAA;AAC5B;"}
+{"version":3,"file":"useStorage.mjs","sources":["../../../../src/useStorage.ts"],"sourcesContent":["import { useState, useEffect } from \"react\";\nimport { type BindValue } from \"./bindValue.js\";\n\nexport interface UseStorageReturn<T> {\n  value: T;\n  setValue: (value: T) => void;\n}\n\nexport function useStorage<T>(binding: BindValue<T>): UseStorageReturn<T> {\n  const [value, setValue] = useState(binding.getValue());\n\n  useEffect(() => {\n    const unsubscribe = binding.subscribe(setValue);\n    return unsubscribe;\n  }, [binding]);\n\n  const set = (newValue: T) => {\n    binding.set(newValue);\n  };\n\n  return { value, setValue: set };\n}\n"],"names":[],"mappings":";AAQO,SAAS,WAAc,SAA4C;AACxE,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAS,QAAQ,UAAU;AAErD,YAAU,MAAM;AACd,UAAM,cAAc,QAAQ,UAAU,QAAQ;AAC9C,WAAO;AAAA,EACT,GAAG,CAAC,OAAO,CAAC;AAEZ,QAAM,MAAM,CAAC,aAAgB;AAC3B,YAAQ,IAAI,QAAQ;AAAA,EACtB;AAEA,SAAO,EAAE,OAAO,UAAU,IAAA;AAC5B;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kvozy",
   "type": "commonjs",
-  "version": "0.0.1",
+  "version": "0.3.0",
   "types": "./__compiled__/cjs/src/index.d.ts",
   "module": "./__compiled__/esm/src/index.mjs",
   "main": "./__compiled__/cjs/src/index.js",