kvozy 0.2.0 → 0.3.0

package/README.md

@@ -14,13 +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 storage
 - Subscription-based reactivity
 - TypeScript support
+- Required default values for safety
 - Easy to extend to other frameworks
 
 ## Installation
@@ -36,14 +37,19 @@ npm install kvozy
 ```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)} />;
 };
 ```
 
@@ -70,23 +76,37 @@ The in-memory storage ensures your application remains functional, maintaining s
 
 > ⚠️ **Note:** `bindValue` is an internal API. Use `useStorage` for React components. Direct usage of `bindValue` is not recommended.
 
-### useStorage(binding)
+### BindValueOptions<T>
+
+Options for creating a BindValue instance.
+
+**Parameters:**
+
+- `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<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:**
 
@@ -95,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>
@@ -110,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);
@@ -120,7 +145,7 @@ const LoginForm = () => {
       <label>
         Username:
         <input
-          value={value || ''}
+          value={value}
           onChange={(e) => setValue(e.target.value)}
         />
       </label>
@@ -134,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);
@@ -164,15 +194,20 @@ 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>;
 };
 ```
 
@@ -184,17 +219,34 @@ Kvozy supports localStorage, sessionStorage, and in-memory storage:
 import { bindValue, useStorage } from 'kvozy';
 
 // localStorage - persists across browser sessions
-const localBinding = bindValue({ key: 'theme', storage: localStorage });
+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({ key: 'form-data', storage: sessionStorage });
+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({ key: 'temp-state' });
+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 || 'light'}</div>;
+  return <div>Theme: {value}</div>;
 };
 
 const SessionComponent = () => {
@@ -211,7 +263,12 @@ const MemoryComponent = () => {
 ### 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);
@@ -238,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>
@@ -268,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;
 }
 ```
 
@@ -293,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(() => {
@@ -301,7 +363,7 @@ 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 };
 }
@@ -309,9 +371,9 @@ function useStorage(binding: BindValue): UseStorageReturn {
 
 ## 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
 
@@ -320,3 +382,4 @@ function useStorage(binding: BindValue): UseStorageReturn {
 - [ ] Angular connector
 - [ ] SSR support
 - [ ] Cross-tab synchronization
+- [ ] Console warnings on serialization/deserialization errors for debugging

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

@@ -1,18 +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;
     private storage;
-    constructor(options: BindValueOptions);
-    getValue(): string | undefined;
-    set(newValue: string): void;
-    subscribe(callback: (value: string | undefined) => void): () => void;
+    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

@@ -50,11 +50,22 @@ class BindValue {
     };
   }
   loadFromStorage() {
-    const value = this.storage.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) {
-    this.storage.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  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 {\n  private value: string | undefined;\n  private subscribers: Set<(value: string | undefined) => void>;\n  private storage: Storage;\n\n  constructor(private options: BindValueOptions) {\n    this.storage = options.storage ?? inMemoryStorage;\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 = this.storage.getItem(this.options.key);\n    return value !== null ? value : undefined;\n  }\n\n  private saveToStorage(value: string): void {\n    this.storage.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":";;;;;AAKA,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,UAAU;AAAA,EAKrB,YAAoB,SAA2B;AAJvC;AACA;AACA;AAEY,SAAA,UAAA;AAClB,SAAK,UAAU,QAAQ,WAAW;AAClC,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,KAAK,QAAQ,QAAQ,KAAK,QAAQ,GAAG;AACnD,WAAO,UAAU,OAAO,QAAQ;AAAA,EAClC;AAAA,EAEQ,cAAc,OAAqB;AACzC,SAAK,QAAQ,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,18 +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;
     private storage;
-    constructor(options: BindValueOptions);
-    getValue(): string | undefined;
-    set(newValue: string): void;
-    subscribe(callback: (value: string | undefined) => void): () => void;
+    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

@@ -48,11 +48,22 @@ class BindValue {
     };
   }
   loadFromStorage() {
-    const value = this.storage.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) {
-    this.storage.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  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 {\n  private value: string | undefined;\n  private subscribers: Set<(value: string | undefined) => void>;\n  private storage: Storage;\n\n  constructor(private options: BindValueOptions) {\n    this.storage = options.storage ?? inMemoryStorage;\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 = this.storage.getItem(this.options.key);\n    return value !== null ? value : undefined;\n  }\n\n  private saveToStorage(value: string): void {\n    this.storage.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":";;;AAKA,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,UAAU;AAAA,EAKrB,YAAoB,SAA2B;AAJvC;AACA;AACA;AAEY,SAAA,UAAA;AAClB,SAAK,UAAU,QAAQ,WAAW;AAClC,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,KAAK,QAAQ,QAAQ,KAAK,QAAQ,GAAG;AACnD,WAAO,UAAU,OAAO,QAAQ;AAAA,EAClC;AAAA,EAEQ,cAAc,OAAqB;AACzC,SAAK,QAAQ,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.2.0",
+  "version": "0.3.0",
   "types": "./__compiled__/cjs/src/index.d.ts",
   "module": "./__compiled__/esm/src/index.mjs",
   "main": "./__compiled__/cjs/src/index.js",