memorio 4.7.3 → 4.9.5

package/markdown/STORE.md

@@ -1,164 +0,0 @@
-# Store - Memorio
-
-> 🖥️ **Browser & Edge**: Uses localStorage for persistence
-> ⚙️ **Node.js/Deno**: Falls back to in-memory storage (not persistent)
-
-Store provides persistent localStorage management with a simple API. Data survives page refreshes and browser restarts.
-
-## Installation
-
-```bash
-npm install memorio
-```
-
-```javascript
-import 'memorio';
-```
-
-> **Classic `import`**: `store` is also a named export.
-> `import { store } from 'memorio'` returns the exact same instance as `globalThis.store`.
-
----
-
-## Quick Examples
-
-### Example 1: Basic Usage
-
-```javascript
-// Save data
-store.set('username', 'Mario');
-store.set('score', 1500);
-
-// Read data
-console.debug(store.get('username')); // "Mario"
-console.debug(store.get('score'));    // 1500
-
-// Check if using real persistence
-console.debug(store.isPersistent); // true in browser, false in Node.js/Deno
-```
-
-### Example 2: Intermediate
-
-```javascript
-// Store objects
-store.set('user', { name: 'Luigi', level: 5 });
-const user = store.get('user');
-console.debug(user.name); // "Luigi"
-
-// Remove single item
-store.remove('username');
-
-// Check size
-const totalSize = store.size();
-console.debug(`${totalSize} bytes`);
-```
-
-### Example 3: Advanced
-
-```javascript
-// Get storage quota (returns Promise<[usage, quota]> in KB)
-const [used, total] = await store.quota();
-console.debug(`Using ${used} out of ${total} KB`);
-
-// Get total size in characters
-const size = store.size();
-console.debug(`${size} bytes`);
-
-// Clear all data
-store.removeAll();
-// or use alias
-store.clearAll();
-
-// Handle errors gracefully
-try {
-  store.set('largeData', hugeObject);
-} catch (err) {
-  console.error('Storage full:', err);
-}
-```
-
----
-
-## API Reference
-
-### Methods
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `store.get(name)` | `name: string` | `any` | Get value from storage |
-| `store.set(name, value)` | `name: string, value: any` | `void` | Save value to storage |
-| `store.remove(name)` | `name: string` | `boolean` | Remove single item |
-| `store.delete(name)` | `name: string` | `boolean` | Alias for remove |
-| `store.removeAll()` | none | `boolean` | Clear all storage |
-| `store.clearAll()` | none | `boolean` | Alias for removeAll |
-| `store.size()` | none | `number` | Get total size in characters |
-| `store.quota()` | none | `Promise<[number, number]>` | Get storage usage/quota in KB |
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `store.isPersistent` | `boolean` | `true` if using real localStorage, `false` if in-memory fallback |
-
-### Supported Types
-
-```javascript
-// All JSON-serializable types work
-store.set('string', 'hello');
-store.set('number', 42);
-store.set('boolean', true);
-store.set('array', [1, 2, 3]);
-store.set('object', { key: 'value' });
-store.set('null', null);
-store.set('undefined', null); // converted to null
-```
-
-### Not Supported
-
-```javascript
-// Functions will log an error
-store.set('myFunc', () => {});
-// Output: "It's not secure to store functions."
-```
-
----
-
-## Platform Comparison
-
-| Feature | Store | Session | Cache | IDB |
-|---------|-------|---------|-------|-----|
-| **Storage** | localStorage | sessionStorage | Memory | IndexedDB |
-| **Lifetime** | Forever | Until tab closes | Until refresh | Forever |
-| **Capacity** | ~5-10 MB | ~5-10 MB | Unlimited | 50+ MB |
-| **Platform** | Browser/Edge | Browser/Edge | All | Browser |
-| **Persistence** | ✅ true | N/A | ❌ false | ✅ true |
-
----
-
-## How It Works
-
-Store wraps the browser's `localStorage` API with:
-
-- Automatic JSON serialization/deserialization
-- Error handling for parse failures
-- Size calculation
-- Quota monitoring
-
----
-
-## Storage Limits
-
-- **Chrome/Safari**: ~5-10 MB
-- **Firefox**: ~10 MB
-- **Edge**: ~5-10 MB
-
-Use `store.quota()` to monitor usage.
-
----
-
-## Best Practices
-
-1. Prefix keys: `store.set('app_username', '...')`
-2. Check before set: `if (store.get('key')) { ... }`
-3. Handle quota: Try/catch around large data
-4. Clean up: `store.removeAll()` on logout

package/markdown/TYPED.md

@@ -1,158 +0,0 @@
-# Typed Stores - Memorio
-
-> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
-
-`memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, giving you **compile-time** type safety on every access and mutation.
-
-It's a **zero-runtime-cost** wrapper: the returned object is the *exact same* Proxy as `globalThis.state`, just with TypeScript types applied via a generic.
-
----
-
-## Quick Start
-
-```typescript
-import 'memorio'
-
-interface AppState {
-  user: { name: string; age: number; email: string }
-  theme: 'light' | 'dark'
-  items: string[]
-}
-
-const app = memorio.typed<AppState>()
-
-// Type-checked at compile time:
-app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
-app.theme = 'dark'
-
-// TypeScript errors:
-// app.user = { name: 42 }            // age missing, name wrong type
-// app.theme = 'purple'               // not a valid literal
-```
-
----
-
-## Why use typed stores?
-
-| Without typed | With `memorio.typed<T>()` |
-|---|---|
-| `state.user = { name: 42 }` — runs silently, bug at runtime | `app.user = { name: 42 }` — TypeScript error at compile time |
-| No autocomplete on `state.user.email` | Full IntelliSense: properties, types, method suggestions |
-| Rename `user` to `profile` — no compiler warning anywhere | Every `app.user` access flagged as an error |
-| AI-generated code lacks guardrails | AI gets autocomplete and type feedback inline |
-
----
-
-## Combine with Schema Validation
-
-Typed stores catch type errors at compile time; schema validation catches invalid values at runtime. Together they form a **defense-in-depth** strategy:
-
-```typescript
-import 'memorio'
-
-interface ProfileState {
-  profile: { bio: string; avatar?: string }
-}
-
-const app = memorio.typed<ProfileState>()
-
-memorio.registerSchema('profile', {
-  type: 'object',
-  required: ['bio'],
-  properties: {
-    bio: { type: 'string', min: 1 },
-    avatar: { type: 'string' }
-  }
-})
-
-app.profile = { bio: 'Developer', avatar: 'pic.png' } // ✅ type + schema pass
-app.profile = { avatar: 'pic.png' }                  // ❌ TypeScript: bio missing
-                                                     // ❌ Runtime: bio required
-```
-
-See [Schema Validation](SCHEMA.md) for runtime validation details.
-
----
-
-## Named import variant
-
-`typed` is also available as a named export if you prefer explicit dependencies:
-
-```typescript
-import { typed } from 'memorio'
-
-const app = typed<AppState>()
-```
-
-The `memorio` namespace object is the same — `import 'memorio'` is the recommended entry, named exports are an alternative.
-
----
-
-## Full API
-
-| Method | Parameters | Returns | Description |
-|--------|-----------|---------|-------------|
-| `memorio.typed<T>()` | Generic type `T` | `T` | Returns the global `state` proxy cast to `T` |
-
-The returned object shares the same identity as `globalThis.state`:
-
-```typescript
-const app = memorio.typed<AppState>()
-console.debug(app === state) // true — same Proxy instance
-```
-
----
-
-## React + typed stores
-
-Pair with the `useObserver` hook for type-safe, reactive React components:
-
-```tsx
-import 'memorio'
-import { useReducer } from 'react'
-
-interface AppState {
-  user: { name: string; age: number }
-  theme: 'light' | 'dark'
-}
-
-const app = memorio.typed<AppState>()
-
-function UserProfile() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
-
-  useObserver(forceUpdate, [state.user.name])
-
-  return (
-    <div>
-      <h1>{app.user.name}</h1>
-      <span>Theme: {app.theme}</span>
-    </div>
-  )
-}
-```
-
----
-
-## Best Practices
-
-1. **Define your AppState at the root** of your app and import it everywhere:
-
-   ```typescript
-   // types/app-state.ts
-   export interface AppState {
-     user: { name: string; email: string }
-     theme: 'light' | 'dark'
-   }
-   ```
-
-   ```typescript
-   // anywhere in your app
-   import 'memorio'
-   import type { AppState } from '../types/app-state'
-   const app = memorio.typed<AppState>()
-   ```
-
-2. **Layer schema validation on top** for runtime safety, especially for data coming from APIs or user input.
-
-3. **Use alongside `memorio.help()`** to list available globals during development.

package/markdown/USEOBSERVER.md

@@ -1,259 +0,0 @@
-# useObserver - Memorio
-
-> ⚛️ **React Only**: This is a React hook and only works within React components
-
-useObserver is a React hook for observing state changes. It automatically subscribes to state changes and includes powerful auto-discovery features.
-
-## Installation
-
-```bash
-npm install memorio
-```
-
-```javascript
-import 'memorio';
-```
-
----
-
-## Quick Examples
-
-### Example 1: Basic Usage
-
-```javascript
-import 'memorio';
-
-function Counter() {
-  // Direct values work! ✅
-  useObserver(() => {
-    console.debug('Counter changed:', state.counter);
-  }, [state.counter]);
-
-  return <div>{state.counter}</div>;
-}
-```
-
-### Auto-Discovery (Magic Mode)
-
-```javascript
-// Pass your callback WITHOUT dependencies - it auto-discovers!
-function MyComponent() {
-  useObserver(() => {
-    // This will automatically track ALL state properties used inside
-    console.debug('Something changed:', state.user.name, state.items.length);
-  });
-
-  return <div>{state.user.name}</div>;
-}
-```
-
-### Example 2: Intermediate
-
-```javascript
-function UserProfile() {
-  const [localState, setLocalState] = useState(null);
-
-  useObserver(() => {
-    setLocalState(state.user);
-  }, [state.user]);
-
-  return <div>{localState?.name}</div>;
-}
-```
-
-### Example 3: Advanced
-
-```javascript
-// Multiple watchers with array - works with direct values
-function MultiWatch() {
-  useObserver(() => {
-    console.debug('A or B changed:', state.a, state.b);
-  }, [state.a, state.b]); // Direct values work!
-  
-  return <div>{state.a} - {state.b}</div>;
-}
-
-// With string path (for store)
-function StoreWatcher() {
-  useObserver(() => {
-    console.debug('Store changed');
-  }, 'store.userPreferences');
-
-  return <div />;
-}
-```
-// With string path (for store)
-function StoreWatcher() {
-  useObserver(() => {
-    console.debug('Store changed');
-  }, 'store.userPreferences');
-
-  return <div />;
-}
-```
-
----
-
-## API Reference
-
-### useObserver(callback, deps)
-
-| Parameter | Type | Description |
-| --------- | ---- | ----------- |
-| `callback` | `function` | Function to run on change |
-| `deps` | `function \| string \| array \| proxy` | State path(s) to watch. Supports: |
-| | | - Direct values: `state.counter` |
-| | | - String paths: `'state.counter'` |
-| | | - Arrow functions: `() => state.counter` |
-| | | - Arrays: `[state.a, state.b]` or `['state.a', 'state.b']` |
-| | | - Optional chaining: `[state?.one]` |
-
-### Primitive Values
-
-Direct primitive values are now fully supported:
-
-```javascript
-// Direct values work with primitives ✅
-useObserver(() => { console.debug('changed') }, [state.counter])
-
-// Arrays of primitives work ✅
-useObserver(() => { console.log(state.a, state.b) }, [state.a, state.b])
-
-// Optional chaining works ✅
-useObserver(() => { console.log(state?.one) }, [state?.one])
-
-// Strings still work ✅
-useObserver(() => { console.debug('changed') }, ['state.counter'])
-
-// Functions still work ✅
-useObserver(() => { console.debug('changed') }, [() => state.counter])
-```
-
-### Callback Parameters
-
-```javascript
-// Single value (no array needed)
-useObserver(
-  () => {
-    console.debug('Changed:', state.key);
-  }, state.key  // Single value works!
-);
-
-// Array of values
-useObserver(
-  () => {
-    console.debug('Changed:', state.key);
-  }, [state.key]  // Array also works!
-);
-```
-
-### Auto-Discovery Mode
-
-When `deps` is omitted, useObserver automatically discovers all state properties accessed inside the callback:
-
-```javascript
-// No deps needed - magic auto-discovery!
-useObserver(() => {
-  // Automatically tracks state.user, state.items, state.counter
-  console.debug(state.user.name, state.items.length, state.counter);
-},[]);
-```
-
-Returns a cleanup function:
-
-## useObserver vs observer
-
-| Feature | observer | useObserver |
-| ------- | -------- | ----------- |
-| Framework | Vanilla JS | React |
-| Auto-cleanup | Manual | Auto |
-| React lifecycle | No | Yes |
-
----
-
-## Common Patterns
-
-### Sync with useState (Recommended for Primitives)
-
-```javascript
-function CounterComponent() {
-  // Sync memorio state with React state
-  const [counter, setCounter] = useState(state.counter)
-  
-  // React useEffect works correctly with primitive values
-  useEffect(() => {
-    console.log('Counter changed:', counter)
-  }, [counter])
-  
-  // Direct values now work with primitives!
-  useObserver(() => {
-    setCounter(state.counter)
-  }, [state.counter])  // ✅ Works now!
-  
-  return (
-    <div>
-      <button onClick={() => { state.counter++ }}>Increment</button>
-      <span>{counter}</span>
-    </div>
-  )
-}
-```
-
-### Safe Access with Optional Chaining (Protection)
-
-```javascript
-// Optional chaining is supported - protects against errors
-useObserver(() => {
-  if (test?.one) {
-    console.log(test.one)
-  }
-}, [test?.one])
-
-// Works with objects
-function SafeComponent() {
-  const [test, setTest] = useState(state.test)
-  
-  useEffect(() => {
-    if (test?.one) {
-      console.log('test.one:', test.one)
-    }
-  }, [test?.one])
-  
-  useObserver(() => {
-    if (state.test?.one) {
-      setTest(state.test)
-    }
-  }, ['state.test.one'])
-  
-  return <div>{test?.one || 'Loading...'}</div>
-}
-```
-
-### Multiple Watchers
-
-```javascript
-// Watch multiple properties with strings
-useObserver(() => {
-  console.log(state.a, state.b)
-}, ['state.a', 'state.b'])
-
-// Watch multiple properties with functions
-useObserver(() => {
-  console.log(state.a, state.b)
-}, [() => state.a, () => state.b])
-
-// Watch with auto-discovery
-useObserver(() => {
-  console.log(state.a, state.b) // Automatically tracks both
-}, [])
-```
-
----
-
-## Best Practices
-
-1. Always use in React components
-2. Use auto-discovery for simpler code: `useObserver(() => { ... })`
-3. No manual cleanup needed - returns cleanup function automatically
-4. Use with state for reactive UI
-5. Check console for auto-discovery logs