native-document 1.0.166 → 1.0.168

package/docs/cache.md

@@ -1,888 +1,180 @@
-# Cache Utilities
+---
+title: Cache
+description: Lazy initialization, singleton patterns, and key-based memoization utilities
+---
 
-NativeDocument provides utility functions for optimizing function execution through lazy initialization, memoization, and singleton patterns. These utilities help improve performance by deferring execution and caching results.
+# Cache
 
-## Overview
+NativeDocument provides three caching utilities for optimizing function execution: lazy initialization, eager singletons, and key-based memoization.
 
-The Cache utilities include:
-- **`Cache.once(fn)`** - Lazy execution (via `autoOnce`) - executes on first property access
-- **`Cache.singleton(fn)`** - Eager singleton (via `once`) - executes immediately on first call
-- **`Cache.memoize(fn)`** - Lazy memoization (via `autoMemoize`) - proxy-based caching
-
-## Import
 ```javascript
-import { Cache } from 'native-document/utils';
+import { utils } from 'native-document';
+const { Cache } = utils;
 
-// Use Cache methods
-const lazyInit = Cache.once(() => { /* ... */ });
-const singleton = Cache.singleton(() => { /* ... */ });
-const memoized = Cache.memoize((key) => { /* ... */ });
+// Or
+import { Cache } from 'native-document/utils';
 ```
 
-## Cache.once() - Lazy Initialization
+---
 
-Lazy execution using `autoOnce`. The function is **not executed immediately** - it only runs when you access a property on the returned object.
+## `Cache.once(fn)` - Lazy Initialization
 
-### Basic Usage
-```javascript
-import { Cache } from 'native-document/utils';
+The function is **not executed immediately**. It runs only when you access a property on the returned Proxy object. The result is cached after the first access.
 
-const LazyConfig = Cache.once(() => {
+```javascript
+const Config = Cache.once(() => {
     console.log('Loading config...');
     return {
-        apiUrl: 'https://api.example.com',
-        timeout: 5000,
+        apiUrl:     'https://api.example.com',
+        timeout:    5000,
         maxRetries: 3
     };
 });
 
 // Function not executed yet
-console.log('Config created');
-
-// First property access triggers execution
-console.log(LazyConfig.apiUrl); 
-// Logs: "Loading config..."
-// Returns: "https://api.example.com"
-
-// Subsequent accesses use cached result
-console.log(LazyConfig.timeout); // No log, returns 5000
-console.log(LazyConfig.maxRetries); // No log, returns 3
+Config.apiUrl; // "Loading config..." -> "https://api.example.com"
+Config.timeout; // no log -> 5000 (cached)
 ```
 
-### Lazy Module Loading
-```javascript
-import { Cache } from 'native-document/utils';
-
-const Utils = Cache.once(() => {
-    console.log('Initializing utils...');
-    return {
-        formatDate: (date) => new Date(date).toLocaleDateString(),
-        capitalize: (str) => str.charAt(0).toUpperCase() + str.slice(1),
-        truncate: (str, len) => str.length > len ? str.slice(0, len) + '...' : str,
-        slugify: (str) => str.toLowerCase().replace(/\s+/g, '-')
-    };
-});
-
-// Utils not initialized yet
-console.log('App started');
-
-// First use initializes the module
-const formatted = Utils.formatDate(new Date());
-// Logs: "Initializing utils..."
+Use for optional features or heavy modules that may not always be needed:
 
-// Already initialized - no log
-const capitalized = Utils.capitalize('hello');
-const slug = Utils.slugify('Hello World');
-```
-
-### Lazy API Client
 ```javascript
-import { Cache } from 'native-document/utils';
-import { NativeFetch } from 'native-document/utils';
-
 const API = Cache.once(() => {
-    console.log('Setting up API client...');
     const client = new NativeFetch('https://api.example.com');
-    
-    client.interceptors.request((config) => {
+    client.interceptors.request(config => {
         config.headers['Authorization'] = `Bearer ${getToken()}`;
         return config;
     });
-    
     return {
         users: {
-            get: (id) => client.get(`/users/${id}`),
-            list: () => client.get('/users')
-        },
-        posts: {
-            get: (id) => client.get(`/posts/${id}`),
-            create: (data) => client.post('/posts', data)
+            list: ()   => client.get('/users'),
+            get:  (id) => client.get(`/users/${id}`)
         }
     };
 });
 
-// Client not created yet
-console.log('Starting app...');
-
-// Client created on first API call
+// Client created only on first use
 const users = await API.users.list();
-// Logs: "Setting up API client..."
-
-// Client already created
-const user = await API.users.get('123');
 ```
 
-## Cache.singleton() - Eager Singleton
+---
 
-Eager execution using `once`. The function executes **on the first call** and caches the result for subsequent calls.
+## `Cache.singleton(fn)` - Eager Singleton
 
-### Basic Usage
-```javascript
-import { Cache } from 'native-document/utils';
+The function executes on the **first call** and caches the result. All subsequent calls return the same instance.
 
+```javascript
 const getLogger = Cache.singleton(() => {
-    console.log('Creating logger instance...');
+    console.log('Creating logger...');
     return {
-        log: (msg) => console.log(`[LOG] ${msg}`),
-        error: (msg) => console.error(`[ERROR] ${msg}`),
-        warn: (msg) => console.warn(`[WARN] ${msg}`),
-        info: (msg) => console.info(`[INFO] ${msg}`)
+        log:   msg => console.log(`[LOG] ${msg}`),
+        error: msg => console.error(`[ERROR] ${msg}`)
     };
 });
 
-// First call creates the logger
-const logger = getLogger();
-// Logs: "Creating logger instance..."
-
-logger.log('Application started');
-
-// Subsequent calls return cached instance
-const logger2 = getLogger();
-// No log - returns cached instance
-
-console.log(logger === logger2); // true - same reference
+const logger  = getLogger(); // "Creating logger..."
+const logger2 = getLogger(); // no log
+console.log(logger === logger2); // true
 ```
 
-### Application Configuration
-```javascript
-import { Cache } from 'native-document/utils';
-
-const getConfig = Cache.singleton(() => {
-    console.log('Loading configuration...');
-    return {
-        apiUrl: import.meta.env.VITE_API_URL || 'https://api.example.com',
-        debug: import.meta.env.DEV,
-        version: '1.0.0',
-        features: {
-            analytics: true,
-            darkMode: true
-        }
-    };
-});
-
-// First call loads config
-const config = getConfig();
-// Logs: "Loading configuration..."
-
-console.log(config.apiUrl);
+Use for core services that must exist exactly once:
 
-// Returns same config instance
-const config2 = getConfig();
-console.log(config === config2); // true
-```
-
-### Event Bus Singleton
 ```javascript
-import { Cache } from 'native-document/utils';
+const getConfig = Cache.singleton(() => ({
+    apiUrl:  import.meta.env.VITE_API_URL,
+    debug:   import.meta.env.DEV,
+    version: '1.0.0'
+}));
 
-const getEventBus = Cache.singleton(() => {
-    console.log('Creating event bus...');
-    const listeners = new Map();
-    
-    return {
-        on: (event, callback) => {
-            if (!listeners.has(event)) {
-                listeners.set(event, []);
-            }
-            listeners.get(event).push(callback);
-        },
-        off: (event, callback) => {
-            const eventListeners = listeners.get(event);
-            if (eventListeners) {
-                const index = eventListeners.indexOf(callback);
-                if (index > -1) {
-                    eventListeners.splice(index, 1);
-                }
-            }
-        },
-        emit: (event, data) => {
-            const eventListeners = listeners.get(event);
-            if (eventListeners) {
-                eventListeners.forEach(callback => callback(data));
-            }
+const getAPI = Cache.singleton(() => {
+    const config = getConfig();
+    const client = new NativeFetch(config.apiUrl);
+    client.interceptors.request(req => {
+        const token = localStorage.getItem('token');
+        if (token) {
+            req.headers['Authorization'] = `Bearer ${token}`;
         }
-    };
+        return req;
+    });
+    return client;
 });
-
-// Create event bus
-const bus = getEventBus();
-// Logs: "Creating event bus..."
-
-bus.on('user:login', (user) => console.log('User logged in:', user));
-bus.emit('user:login', { id: 1, name: 'John' });
-
-// Same event bus everywhere
-const bus2 = getEventBus();
-console.log(bus === bus2); // true
 ```
 
-## Cache.memoize() - Lazy Memoization with Key-Based Instances
+---
 
-Lazy memoization using `autoMemoize`. Each property access creates and caches a **separate instance** of the function result, using the property name as the key parameter.
+## `Cache.memoize(fn)` - Key-Based Memoization
 
-### How It Works
-```javascript
-import { Cache } from 'native-document/utils';
+Each property access creates and caches a **separate instance** using the property name as the key argument.
 
-const API = Cache.memoize((key) => {
-    console.log(`Creating API for: ${key}`);
-    return {
-        async list() {
-            return await fetch('/' + key);
-        },
-        async get(id) {
-            return await fetch('/' + key + '/' + id);
-        }
-    };
-});
-
-// First access to 'users' - executes function with key='users'
-await API.users.list();
-// Logs: "Creating API for: users"
-// Fetch: '/users'
-
-// Second access to 'users' - returns cached instance
-await API.users.get('123');
-// No log - cached instance
-// Fetch: '/users/123'
-
-// First access to 'posts' - executes function with key='posts'
-await API.posts.list();
-// Logs: "Creating API for: posts"
-// Fetch: '/posts'
-
-// Cached instance for 'posts'
-await API.posts.get('456');
-// No log - cached instance
-// Fetch: '/posts/456'
-```
-
-### Key Concepts
-
-1. **Property name becomes the key**: `API.users` -> `key = 'users'`
-2. **Function executed per unique key**: First access creates instance
-3. **Results cached by key**: Subsequent accesses return same instance
-4. **Each key has its own instance**: `API.users` ≠ `API.posts`
-
-### Basic Resource Providers
 ```javascript
-import { Cache } from 'native-document/utils';
-
-const Resources = Cache.memoize((resource) => {
-    console.log(`Loading ${resource}...`);
-    
-    return {
-        data: `${resource} data`,
-        load: () => console.log(`Reloading ${resource}`),
-        save: (content) => console.log(`Saving to ${resource}:`, content)
-    };
-});
-
-// First access - creates 'icons' instance
-Resources.icons.load();
-// Logs: "Loading icons..."
-// Logs: "Reloading icons"
-
-// Cached instance
-Resources.icons.save('new-icon.svg');
-// Logs: "Saving to icons: new-icon.svg"
-
-// Different key - creates 'fonts' instance
-Resources.fonts.load();
-// Logs: "Loading fonts..."
-// Logs: "Reloading fonts"
-```
-
-### API Endpoint Collections
-```javascript
-import { Cache } from 'native-document/utils';
-import { NativeFetch } from 'native-document/utils';
-
-const api = new NativeFetch('https://api.example.com');
-
 const Endpoints = Cache.memoize((resource) => {
-    console.log(`Creating endpoint for: ${resource}`);
-    
+    console.log(`Creating endpoint: ${resource}`);
+    const api = getAPI();
     return {
-        list: () => api.get(`/${resource}`),
-        get: (id) => api.get(`/${resource}/${id}`),
-        create: (data) => api.post(`/${resource}`, data),
-        update: (id, data) => api.put(`/${resource}/${id}`, data),
-        delete: (id) => api.delete(`/${resource}/${id}`)
+        list:   (params = {}) => api.get(`/${resource}`, params),
+        get:    (id)          => api.get(`/${resource}/${id}`),
+        create: (data)        => api.post(`/${resource}`, data),
+        update: (id, data)    => api.put(`/${resource}/${id}`, data),
+        delete: (id)          => api.delete(`/${resource}/${id}`)
     };
 });
 
-// Create 'users' endpoint instance
-const users = await Endpoints.users.list();
-// Logs: "Creating endpoint for: users"
-// GET: /users
-
-const user = await Endpoints.users.get('123');
-// GET: /users/123 (cached instance)
-
-// Create 'posts' endpoint instance
-const posts = await Endpoints.posts.list();
-// Logs: "Creating endpoint for: posts"
-// GET: /posts
-
-await Endpoints.posts.create({ title: 'New Post' });
-// POST: /posts (cached instance)
+await Endpoints.users.list();    // "Creating endpoint: users"
+await Endpoints.users.get('1');  // no log - cached
+await Endpoints.posts.list();    // "Creating endpoint: posts"
 ```
 
-### Store Providers
-```javascript
-import { Cache } from 'native-document/utils';
-import { Store } from 'native-document';
+Use for resources that share the same structure but need separate instances per key:
 
-const Stores = Cache.memoize((storeName) => {
-    console.log(`Creating store: ${storeName}`);
-    
-    // Create store if it doesn't exist
-    if (!Store.get(storeName)) {
-        Store.create(storeName, {
-            items: [],
-            loading: false,
-            error: null
-        });
-    }
-    
-    return {
-        get: () => Store.use(storeName),
-        setLoading: (value) => {
-            /*...*/
-        },
-        addItem: (items) => {
-            /*...*/
-        },
-        setItems: (items) => {
-            /*...*/
-        },
-        setError: (error) => {
-            /*...*/
-        }
-    };
-});
-
-// Create 'products' store
-const productsStore = Stores.products.get();
-// Logs: "Creating store: products"
-
-Stores.products.setLoading(true);
-Stores.products.addItem({ id: 1, name: 'Product 1' });
-
-// Create 'users' store
-const usersStore = Stores.users.get();
-// Logs: "Creating store: users"
-
-Stores.users.setItems([{ id: 1, name: 'Alice' }]);
-```
-
-### LocalStorage Namespaces
 ```javascript
-import { Cache } from 'native-document/utils';
-
-const Storage = Cache.memoize((namespace) => {
-    console.log(`Creating storage for namespace: ${namespace}`);
+// Namespaced localStorage
+const Storage = Cache.memoize((namespace) => ({
+    get:    (key) => JSON.parse(localStorage.getItem(`${namespace}:${key}`)),
     
-    const prefix = `${namespace}:`;
+    set:    (key, val) => localStorage.setItem(`${namespace}:${key}`, JSON.stringify(val)),
     
-    return {
-        get: (key) => {
-            try {
-                const item = localStorage.getItem(prefix + key);
-                return item ? JSON.parse(item) : null;
-            } catch {
-                return null;
-            }
-        },
-        set: (key, value) => {
-            try {
-                localStorage.setItem(prefix + key, JSON.stringify(value));
-                return true;
-            } catch {
-                return false;
-            }
-        },
-        remove: (key) => {
-            localStorage.removeItem(prefix + key);
-        },
-        clear: () => {
-            // Clear all keys with this namespace
-            Object.keys(localStorage)
-                .filter(key => key.startsWith(prefix))
-                .forEach(key => localStorage.removeItem(key));
-        }
-    };
-});
+    remove: (key) => localStorage.removeItem(`${namespace}:${key}`)
+}));
 
-// User preferences namespace
 Storage.user.set('theme', 'dark');
-// Logs: "Creating storage for namespace: user"
-// localStorage: "user:theme" = "dark"
-
-Storage.user.set('language', 'en');
-// localStorage: "user:language" = "en"
-
-const theme = Storage.user.get('theme');
-// Returns: "dark"
-
-// App settings namespace (different instance)
 Storage.app.set('version', '1.0.0');
-// Logs: "Creating storage for namespace: app"
-// localStorage: "app:version" = "1.0.0"
-```
-
-### Event Handlers by Type
-```javascript
-import { Cache } from 'native-document/utils';
-
-const EventHandlers = Cache.memoize((eventType) => {
-    console.log(`Creating handler for: ${eventType}`);
-    const listeners = [];
-    
-    return {
-        add: (callback) => {
-            listeners.push(callback);
-        },
-        remove: (callback) => {
-            const index = listeners.indexOf(callback);
-            if (index > -1) {
-                listeners.splice(index, 1);
-            }
-        },
-        emit: (data) => {
-            listeners.forEach(callback => callback(data));
-        },
-        count: () => listeners.length
-    };
-});
-
-// Create 'click' event handler
-EventHandlers.click.add((data) => console.log('Clicked:', data));
-// Logs: "Creating handler for: click"
-
-EventHandlers.click.emit({ x: 100, y: 200 });
-// Logs: "Clicked: { x: 100, y: 200 }"
-
-// Create 'scroll' event handler (different instance)
-EventHandlers.scroll.add((data) => console.log('Scrolled:', data));
-// Logs: "Creating handler for: scroll"
-
-EventHandlers.scroll.emit({ top: 500 });
-// Logs: "Scrolled: { top: 500 }"
-
-console.log(EventHandlers.click.count()); // 1
-console.log(EventHandlers.scroll.count()); // 1
-```
-
-### Validation Rules by Type
-```javascript
-import { Cache } from 'native-document/utils';
 
-const Validators = Cache.memoize((fieldType) => {
-    console.log(`Creating validators for: ${fieldType}`);
-    
-    const rules = {
-        email: {
-            required: (value) => !!value || 'Email is required',
-            format: (value) => /\S+@\S+\.\S+/.test(value) || 'Invalid email format'
-        },
-        password: {
-            required: (value) => !!value || 'Password is required',
-            minLength: (value) => value.length >= 8 || 'Password must be at least 8 characters',
-            hasNumber: (value) => /\d/.test(value) || 'Password must contain a number'
-        },
-        phone: {
-            required: (value) => !!value || 'Phone is required',
-            format: (value) => /^\d{10}$/.test(value) || 'Phone must be 10 digits'
-        }
-    };
-    
-    return {
-        validate: (value) => {
-            const fieldRules = rules[fieldType];
-            if (!fieldRules) return [];
-            
-            const errors = [];
-            for (const [ruleName, rule] of Object.entries(fieldRules)) {
-                const result = rule(value);
-                if (result !== true) {
-                    errors.push(result);
-                }
-            }
-            return errors;
-        },
-        isValid: (value) => {
-            return Validators[fieldType].validate(value).length === 0;
-        }
-    };
-});
-
-// Validate email
-const emailErrors = Validators.email.validate('invalid-email');
-// Logs: "Creating validators for: email"
-// Returns: ['Invalid email format']
-
-const isEmailValid = Validators.email.isValid('test@example.com');
-// Returns: true (cached instance)
-
-// Validate password
-const passwordErrors = Validators.password.validate('weak');
-// Logs: "Creating validators for: password"
-// Returns: ['Password must be at least 8 characters', 'Password must contain a number']
-```
-
-### Chart Instances by Type
-```javascript
-import { Cache } from 'native-document/utils';
-
-const Charts = Cache.memoize((chartType) => {
-    console.log(`Creating ${chartType} chart instance...`);
-    
-    return {
-        render: (container, data, options = {}) => {
-            console.log(`Rendering ${chartType} chart`);
-            
-            // Simplified chart rendering
-            const canvas = document.createElement('canvas');
-            container.appendChild(canvas);
-            
-            // Chart-specific rendering logic
-            switch (chartType) {
-                case 'bar':
-                    renderBarChart(canvas, data, options);
-                    break;
-                case 'line':
-                    renderLineChart(canvas, data, options);
-                    break;
-                case 'pie':
-                    renderPieChart(canvas, data, options);
-                    break;
-            }
-            
-            return canvas;
-        },
-        update: (canvas, data) => {
-            console.log(`Updating ${chartType} chart`);
-            // Update logic
-        }
-    };
-});
-
-// Create bar chart instance
-const barContainer = document.querySelector('#bar-chart');
-Charts.bar.render(barContainer, [10, 20, 30]);
-// Logs: "Creating bar chart instance..."
-// Logs: "Rendering bar chart"
-
-// Create line chart instance (different from bar)
-const lineContainer = document.querySelector('#line-chart');
-Charts.line.render(lineContainer, [5, 15, 25]);
-// Logs: "Creating line chart instance..."
-// Logs: "Rendering line chart"
-
-// Reuse bar chart instance
-Charts.bar.update(barCanvas, [15, 25, 35]);
-// Logs: "Updating bar chart"
-```
-
-### Form Field Managers
-```javascript
-import { Cache } from 'native-document/utils';
-import { Observable } from 'native-document';
-
-const FormFields = Cache.memoize((fieldName) => {
-    console.log(`Creating field manager for: ${fieldName}`);
-    
-    const value = Observable('');
-    const errors = Observable([]);
-    const touched = Observable(false);
-    
-    return {
-        value,
-        errors,
-        touched,
-        setValue: (newValue) => {
-            value.set(newValue);
-            touched.set(true);
-        },
-        setErrors: (newErrors) => {
-            errors.set(newErrors);
-        },
-        reset: () => {
-            value.set('');
-            errors.set([]);
-            touched.set(false);
-        },
-        isValid: () => errors.val().length === 0
-    };
-});
-
-// Create email field
-FormFields.email.setValue('test@example.com');
-// Logs: "Creating field manager for: email"
-
-FormFields.email.setErrors([]);
-console.log(FormFields.email.isValid()); // true
-
-// Create password field (different instance)
-FormFields.password.setValue('weak');
-// Logs: "Creating field manager for: password"
-
-FormFields.password.setErrors(['Too short']);
-console.log(FormFields.password.isValid()); // false
-```
-
-## Comparison: once vs singleton vs memoize
-
-| Feature | `Cache.once()` | `Cache.singleton()` | `Cache.memoize()` |
-|---------|------------------|------------------------|---------------------|
-| **Execution** | Lazy (on property access) | Eager (on first call) | Lazy (per key on property access) |
-| **Implementation** | `autoOnce` | `once` | `autoMemoize` |
-| **Access Pattern** | `obj.property` | `fn()` | `obj[key].method()` |
-| **Instances Created** | 1 (single instance) | 1 (single instance) | N (one per key) |
-| **Cache Strategy** | Properties from result | Entire result | Result per property key |
-| **Use Case** | Lazy modules | Eager singletons | Multiple instances by key |
-
-### Visual Comparison
-```javascript
-import { Cache } from 'native-document/utils';
-
-// Cache.once() - Single lazy instance
-const LazyUtils = Cache.once(() => {
-    console.log('Init utils');
-    return { 
-        format: () => 'formatted',
-        parse: () => 'parsed'
-    };
-});
-
-LazyUtils.format(); // Logs: "Init utils"
-LazyUtils.parse();  // No log - same instance
-
-// Cache.singleton() - Single eager instance
-const getConfig = Cache.singleton(() => {
-    console.log('Init config');
-    return { api: 'url', debug: true };
-});
-
-const config = getConfig(); // Logs: "Init config"
-const config2 = getConfig(); // No log - same instance
-
-// Cache.memoize() - Multiple instances by key
-const API = Cache.memoize((resource) => {
-    console.log(`Init ${resource}`);
-    return { 
-        list: () => `List ${resource}`,
-        get: (id) => `Get ${resource}/${id}`
-    };
-});
-
-API.users.list();  // Logs: "Init users"
-API.users.get(1);  // No log - cached 'users' instance
-API.posts.list();  // Logs: "Init posts" - new key, new instance
-API.posts.get(2);  // No log - cached 'posts' instance
-```
-
-## When to Use Cache.memoize()
-
-### ✅ Good Use Cases
-```javascript
-import { Cache } from 'native-document/utils';
-
-// Multiple API endpoints with same structure
-const API = Cache.memoize((resource) => ({
-    list: () => fetch(`/${resource}`),
-    get: (id) => fetch(`/${resource}/${id}`)
-}));
-
-// Multiple storage namespaces
-const Storage = Cache.memoize((namespace) => ({
-    get: (key) => localStorage.getItem(`${namespace}:${key}`),
-    set: (key, val) => localStorage.setItem(`${namespace}:${key}`, val)
+// Form fields with observables
+const Fields = Cache.memoize(name => ({
+    value:  Observable(''),
+    error:  Observable(null),
+    reset:  () => { Fields[name].value.set(''); Fields[name].error.set(null); }
 }));
 
-// Multiple event types with same handler structure
-const Events = Cache.memoize((type) => {
-    const listeners = [];
-    return {
-        on: (cb) => listeners.push(cb),
-        emit: (data) => listeners.forEach(cb => cb(data))
-    };
-});
-
-// Multiple form fields with same structure
-const Fields = Cache.memoize((name) => ({
-    value: Observable(''),
-    error: Observable(null),
-    validate: () => { /* ... */ }
-}));
+Fields.email.value.set('alice@example.com');
+Fields.password.value.set('secret');
 ```
 
-### ❌ Bad Use Cases
-```javascript
-import { Cache } from 'native-document/utils';
+---
 
-// ❌ Don't use for single instance
-const Config = Cache.memoize(() => loadConfig());
-// Use Cache.singleton() instead
+## Comparison
 
-// ❌ Don't use when keys are unpredictable
-const RandomData = Cache.memoize((timestamp) => generateData());
-// Each call has unique timestamp - cache never hits
+| | `Cache.once()` | `Cache.singleton()` | `Cache.memoize()` |
+|---|---|---|---|
+| **Execution** | Lazy - on property access | Eager - on first call | Lazy - per key on property access |
+| **Access** | `obj.property` | `fn()` | `obj.key.method()` |
+| **Instances** | 1 | 1 | 1 per key |
+| **Best for** | Optional modules | Core services | Resources by type |
 
-// ❌ Don't use for simple property access
-const Constants = Cache.memoize(() => ({
-    PI: 3.14159,
-    E: 2.71828
-}));
-// Use Cache.once() instead
-```
+---
 
 ## Best Practices
 
-### 1. Use Descriptive Keys
-```javascript
-import { Cache } from 'native-document/utils';
-
-// ✅ Good: Clear, predictable keys
-const Endpoints = Cache.memoize((resource) => createAPI(resource));
-Endpoints.users.list();
-Endpoints.posts.list();
-
-// ❌ Bad: Dynamic, unpredictable keys
-const DynamicAPI = Cache.memoize((timestamp) => createAPI(timestamp));
-DynamicAPI[Date.now()].list(); // New instance every time
-```
-
-### 2. Document Key-Based Behavior
-```javascript
-import { Cache } from 'native-document/utils';
-
-/**
- * API endpoints by resource type
- * @memoized Each resource type gets its own instance
- * @param {string} resource - Resource name (e.g., 'users', 'posts')
- */
-const API = Cache.memoize((resource) => ({
-    list: () => fetch(`/${resource}`),
-    get: (id) => fetch(`/${resource}/${id}`)
-}));
-```
-
-### 3. Keep Keys Simple
-```javascript
-import { Cache } from 'native-document/utils';
-
-// ✅ Good: Simple string keys
-const Stores = Cache.memoize((name) => Store.create(name, {}));
-Stores.user;
-Stores.settings;
-
-// ❌ Bad: Complex keys (won't work as expected)
-const BadCache = Cache.memoize((config) => createThing(config));
-BadCache[{ type: 'user' }]; // Object as key - problematic
-```
-
-### 4. Combine with Other Patterns
-```javascript
-import { Cache } from 'native-document/utils';
-
-// Eager config + Memoized resources
-const getConfig = Cache.singleton(() => loadConfig());
-
-const Resources = Cache.memoize((type) => {
-    const config = getConfig(); // Config already loaded
-    return createResource(type, config);
-});
-```
-
-## Performance Considerations
-
-### Memory Usage
-```javascript
-import { Cache } from 'native-document/utils';
-
-// ⚠️ Each key creates a new cached instance
-const API = Cache.memoize((resource) => createAPI(resource));
-
-API.users;     // Instance 1
-API.posts;     // Instance 2
-API.comments;  // Instance 3
-// All instances stay in memory
-
-// Consider: Do you need separate instances per key?
-```
-
-### Cache Growth
-```javascript
-import { Cache } from 'native-document/utils';
-
-// ⚠️ Warning: Unbounded cache growth
-const DynamicCache = Cache.memoize((id) => createInstance(id));
-
-// If IDs keep changing, cache grows indefinitely
-for (let i = 0; i < 1000; i++) {
-    DynamicCache[`user-${i}`]; // 1000 cached instances
-}
-
-// ✅ Better: Limited, predictable keys
-const ResourceCache = Cache.memoize((type) => createResource(type));
-ResourceCache.users;    // Only a few known types
-ResourceCache.posts;
-ResourceCache.comments;
-```
-
-## Summary
-
-### Quick Reference
-
-| Pattern | Syntax | When to Use |
-|---------|--------|-------------|
-| **Lazy Module** | `Cache.once(() => {...})` | Optional features, heavy resources |
-| **Eager Singleton** | `Cache.singleton(() => {...})` | Core services, configuration |
-| **Multi-Instance** | `Cache.memoize((key) => {...})` | Resources by type, namespaced data |
-
-### Key Differences
-```javascript
-import { Cache } from 'native-document/utils';
-
-// Cache.once() - Single lazy instance via autoOnce
-const Lazy = Cache.once(() => ({ value: 1 }));
-Lazy.value; // Creates instance on property access
-
-// Cache.singleton() - Single eager instance via once
-const Eager = Cache.singleton(() => ({ value: 1 }));
-Eager(); // Creates instance on function call
-
-// Cache.memoize() - Multiple instances by key via autoMemoize
-const Multi = Cache.memoize((key) => ({ value: key }));
-Multi.a; // Creates instance for key 'a'
-Multi.b; // Creates instance for key 'b'
-```
-
-## Next Steps
+1. Use `Cache.singleton()` for core services (API client, config, logger)
+2. Use `Cache.once()` for optional or heavy modules that may not be needed
+3. Use `Cache.memoize()` for resources that share structure but need separate instances
+4. Keep memoize keys simple and predictable - avoid dynamic or timestamp-based keys
+5. Be aware that `Cache.memoize()` instances stay in memory - use only for a finite set of keys
 
-Explore related utilities and concepts:
+---
 
 ## Next Steps
 
-- **[Getting Started](getting-started.md)** - Installation and first steps
-- **[Core Concepts](core-concepts.md)** - Understanding the fundamentals
-- **[Observables](observables.md)** - Reactive state management
-- **[Elements](elements.md)** - Creating and composing UI
-- **[Conditional Rendering](conditional-rendering.md)** - Dynamic content
-- **[List Rendering](list-rendering.md)** - (ForEach | ForEachArray) and dynamic lists
-- **[Routing](routing.md)** - Navigation and URL management
-- **[State Management](state-management.md)** - Global state patterns
-- **[NDElement](native-document-element.md)** - Native Document Element
-- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
-- **[Advanced Components](advanced-components.md)** - Template caching and singleton views
-- **[Args Validation](validation.md)** - Function Argument Validation
-- **[Memory Management](memory-management.md)** - Memory management
-
-## Utilities
-
-- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
-- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
-- **[Filters](docs/utils/filters.md)** - Data filtering helpers
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[State Management](./state-management.md)** - Global state with Store
+- **[Observables](./observables.md)** - Reactive state management