memorio 2.5.1 → 2.5.3

package/examples/cache.ts

@@ -0,0 +1,72 @@
+/**
+ * Memorio Cache Example
+ *
+ * This example demonstrates the cache module for in-memory storage.
+ * Cache is perfect for temporary data that doesn't need persistence.
+ *
+ * Run: npx ts-node examples/cache.ts
+ */
+
+import '../index'
+
+// ============================================
+// BASIC CACHE OPERATIONS
+// ============================================
+
+// Set values
+cache.set('username', 'Mario')
+cache.set('score', 1500)
+cache.set('player', { name: 'Mario', level: 5 })
+
+// Get values
+console.log('Username:', cache.get('username'))
+console.log('Score:', cache.get('score'))
+console.log('Player:', cache.get('player'))
+
+// Direct property access
+cache.tempData = 'Hello'
+console.log('Temp data:', cache.tempData)
+
+// ============================================
+// CACHE WITH OBJECTS
+// ============================================
+
+// Store complex objects
+cache.set('gameState', {
+  level: 3,
+  score: 2500,
+  inventory: ['sword', 'shield', 'potion'],
+  position: { x: 100, y: 200 }
+})
+
+const gameState = cache.get('gameState')
+console.log('Game level:', gameState?.level)
+console.log('Inventory:', gameState?.inventory)
+
+// ============================================
+// CACHE SIZE
+// ============================================
+
+// Add multiple items
+for (let i = 0; i < 10; i++) {
+  cache.set(`item_${i}`, { id: i, data: `item-${i}` })
+}
+
+console.log('Cache keys:', Object.keys(cache))
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Remove single item
+cache.remove('username')
+
+// Clear all cache
+cache.removeAll()
+
+// Or use clearAll alias
+// cache.clearAll()
+
+console.log('Cache after clear:', cache.get('score'))
+
+console.log('Cache example complete!')

package/examples/idb.ts

@@ -0,0 +1,109 @@
+/**
+ * Memorio IDB Example
+ *
+ * This example shows how to use IndexedDB for large data storage.
+ * IDB is perfect for caching, offline data, and large datasets.
+ *
+ * Run: npx ts-node examples/idb.ts
+ */
+
+import '../index'
+
+// ============================================
+// CHECK SUPPORT
+// ============================================
+
+if (!idb.db.support()) {
+  console.log('IndexedDB not supported')
+  process.exit(0)
+}
+
+// ============================================
+// CREATE DATABASE
+// ============================================
+
+// Create a new database
+idb.db.create('myApp')
+
+// Create tables (stores)
+idb.table.create('myApp', 'users')
+idb.table.create('myApp', 'products')
+
+// ============================================
+// ADD DATA
+// ============================================
+
+// Add user records
+idb.data.set('myApp', 'users', {
+  id: 1,
+  name: 'Mario',
+  email: 'mario@example.com',
+  role: 'admin'
+})
+
+idb.data.set('myApp', 'users', {
+  id: 2,
+  name: 'Luigi',
+  email: 'luigi@example.com',
+  role: 'user'
+})
+
+// Add product records
+idb.data.set('myApp', 'products', {
+  id: 1,
+  name: 'Super Mushroom',
+  price: 99,
+  inStock: true
+})
+
+idb.data.set('myApp', 'products', {
+  id: 2,
+  name: 'Fire Flower',
+  price: 199,
+  inStock: true
+})
+
+// ============================================
+// READ DATA
+// ============================================
+
+const user1 = idb.data.get('myApp', 'users', 1)
+console.log('User 1:', user1)
+
+const product1 = idb.data.get('myApp', 'products', 1)
+console.log('Product 1:', product1)
+
+// ============================================
+// DATABASE INFO
+// ============================================
+
+// List all databases
+const databases = idb.db.list()
+console.log('Databases:', databases)
+
+// Check if database exists
+const exists = idb.db.exist('myApp')
+console.log('myApp exists:', exists)
+
+// Get database version
+const version = idb.db.version('myApp')
+console.log('myApp version:', version)
+
+// Get database size
+const size = idb.db.size('myApp')
+console.log('myApp size:', size, 'bytes')
+
+// ============================================
+// DELETE DATA
+// ============================================
+
+// Delete a record
+idb.data.delete('myApp', 'users', 1)
+
+// Delete entire table
+// idb.table.delete('myApp', 'users');
+
+// Delete entire database
+// idb.db.delete('myApp');
+
+console.log('IDB example complete!')

package/examples/observer.ts

@@ -0,0 +1,60 @@
+/**
+ * Memorio Observer Example
+ *
+ * This example demonstrates the observer pattern for reactive state changes.
+ * Perfect for logging, analytics, auto-save, and UI updates.
+ *
+ * Run: npx ts-node examples/observer.ts
+ */
+
+import '../index'
+
+// ============================================
+// SIMPLE OBSERVER
+// ============================================
+
+// Watch a single value
+observer('state.counter', (newValue, oldValue) => {
+  console.log(`Counter: ${oldValue} → ${newValue}`)
+})
+
+state.counter = 0
+state.counter = 1
+state.counter = 2
+
+// ============================================
+// OBJECT OBSERVER
+// ============================================
+
+// Watch entire objects
+observer('state.user', (newUser, oldUser) => {
+  console.log(`User changed: ${oldUser?.name} → ${newUser?.name}`)
+})
+
+state.user = { name: 'Mario', level: 1 }
+state.user = { name: 'Luigi', level: 2 }
+
+// ============================================
+// MULTIPLE OBSERVERS
+// ============================================
+
+// Multiple observers on same path
+observer('state.notifications', (count) => {
+  console.log(`New notification count: ${count}`)
+})
+
+// List all observers
+console.log('Active observers:', observer.list)
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Remove specific observer
+observer.remove('state.counter')
+
+// Remove all observers - call remove for each path
+// observer.remove('state.counter')
+// observer.remove('state.notifications')
+
+console.log('Observer example complete!')

package/examples/session-advanced.ts

@@ -0,0 +1,78 @@
+/**
+ * Memorio Session Advanced Example
+ *
+ * This example shows advanced session (sessionStorage) operations.
+ * Session data is cleared when the browser tab closes.
+ *
+ * Run: npx ts-node examples/session-advanced.ts
+ */
+
+import '../index'
+
+// ============================================
+// AUTHENTICATION
+// ============================================
+
+// Store auth token (temporary - cleared when tab closes)
+session.set('authToken', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...')
+session.set('userId', 12345)
+
+// Check if user is logged in
+const token = session.get('authToken')
+if (token) {
+  console.log('User is logged in, token:', token.substring(0, 20) + '...')
+}
+
+// ============================================
+// FORM PROGRESS
+// ============================================
+
+// Save form draft
+session.set('formDraft', {
+  name: 'Mario',
+  email: 'mario@example.com',
+  message: 'Hello world!'
+})
+
+// Restore on page refresh
+const draft = session.get('formDraft')
+if (draft) {
+  console.log('Restored draft:', draft)
+}
+
+// ============================================
+// SHOPPING CART
+// ============================================
+
+// Store cart items (temporary)
+session.set('cart', [
+  { id: 1, name: 'Super Mushroom', price: 99, qty: 2 },
+  { id: 2, name: 'Fire Flower', price: 199, qty: 1 }
+])
+
+// Calculate total
+const cart = session.get('cart') || []
+const total = cart.reduce((sum, item) => sum + (item.price * item.qty), 0)
+console.log('Cart total:', total)
+
+// ============================================
+// SESSION SIZE
+// ============================================
+
+// Get session storage size
+console.log('Session size:', session.size(), 'bytes')
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Remove specific item
+session.remove('formDraft')
+
+// Clear all session data (logout)
+// session.removeAll()
+
+// Or use alias
+// session.clearAll()
+
+console.log('Session advanced example complete!')

package/examples/state-advanced.ts

@@ -0,0 +1,89 @@
+/**
+ * Memorio State Advanced Example
+ *
+ * This example shows advanced state features: locking, path tracking, and nesting.
+ *
+ * Run: npx ts-node examples/state-advanced.ts
+ */
+
+import '../index'
+
+// ============================================
+// NESTED OBJECTS
+// ============================================
+
+// Create nested state
+state.user = {
+  name: 'Mario',
+  profile: {
+    email: 'mario@example.com',
+    settings: {
+      theme: 'dark',
+      notifications: true
+    }
+  }
+}
+
+// Access nested values
+console.log('User name:', state.user.name)
+console.log('Email:', state.user.profile.email)
+console.log('Theme:', state.user.profile.settings.theme)
+
+// ============================================
+// ARRAYS
+// ============================================
+
+// State arrays work like regular arrays
+state.items = [1, 2, 3]
+state.items.push(4)
+console.log('Items:', state.items) // [1, 2, 3, 4]
+
+state.users = [
+  { name: 'Mario', id: 1 },
+  { name: 'Luigi', id: 2 }
+]
+state.users.push({ name: 'Peach', id: 3 })
+console.log('Users:', state.users)
+
+// ============================================
+// LOCKING STATE
+// ============================================
+
+// Lock a value to prevent modifications
+state.config = { maxUsers: 100, timeout: 30 }
+state.config.lock()
+
+// This will fail:
+// state.config.maxUsers = 200 // Error: state 'config' is locked
+
+console.log('Config locked:', state.config)
+
+// ============================================
+// PATH TRACKING
+// ============================================
+
+// Get path information
+console.log('Path:', state.user.__path) // "state.user"
+
+// Use path tracker for debugging
+const path = state.user.profile
+console.log('Profile path:', path.email.toString()) // "state.user.profile.email"
+
+// ============================================
+// LIST ALL STATES
+// ============================================
+
+// Get all current state keys
+console.log('All states:', state.list)
+
+// ============================================
+// REMOVE STATE
+// ============================================
+
+// Remove specific state
+state.remove('items')
+
+// Remove all states
+// state.removeAll()
+
+console.log('State advanced example complete!')

package/examples/store-advanced.ts

@@ -0,0 +1,104 @@
+/**
+ * Memorio Store Advanced Example
+ *
+ * This example shows advanced store (localStorage) operations.
+ *
+ * Run: npx ts-node examples/store-advanced.ts
+ */
+
+import '../index'
+
+// ============================================
+// PERSIST USER PREFERENCES
+// ============================================
+
+// Save user preferences
+store.set('preferences', {
+  theme: 'dark',
+  language: 'en',
+  notifications: true,
+  fontSize: 16
+})
+
+// ============================================
+// CHECK AND LOAD PREFERENCES
+// ============================================
+
+const savedPrefs = store.get('preferences')
+if (savedPrefs) {
+  console.log('Loaded preferences:', savedPrefs)
+} else {
+  console.log('No preferences found, using defaults')
+  store.set('preferences', { theme: 'light', language: 'en' })
+}
+
+// ============================================
+// STORAGE QUOTA
+// ============================================
+
+// Get storage size
+const currentSize = store.size()
+console.log('Current storage size:', currentSize, 'bytes')
+
+// ============================================
+// ALIAS METHODS
+// ============================================
+
+// store.delete() is alias for store.remove()
+store.set('temp', 'value')
+store.delete('temp')
+
+// store.clearAll() is alias for store.removeAll()
+// store.clearAll()
+
+// ============================================
+// ERROR HANDLING
+// ============================================
+
+// Try-catch for large data
+try {
+  // Store large data
+  const largeData = {
+    items: Array(1000).fill(null).map((_, i) => ({ id: i, data: 'x'.repeat(100) }))
+  }
+  store.set('largeData', largeData)
+  console.log('Large data stored successfully')
+} catch (error) {
+  console.error('Storage full:', error)
+}
+
+// ============================================
+// DATA SERIALIZATION
+// ============================================
+
+// Store supports all JSON-serializable types
+store.set('string', 'hello')
+store.set('number', 42)
+store.set('boolean', true)
+store.set('array', [1, 2, 3])
+store.set('object', { nested: { value: 'deep' } })
+store.set('null', null)
+
+// Functions are not supported (logged as error)
+store.set('function', () => { }) // logs: "It's not secure to store functions."
+
+// ============================================
+// PRACTICAL EXAMPLE: APP STATE
+// ============================================
+
+// Save app state
+const appState = {
+  lastPage: '/dashboard',
+  sidebarOpen: true,
+  recentFiles: ['file1.txt', 'file2.pdf'],
+  lastSaved: Date.now()
+}
+store.set('appState', appState)
+
+// Load on next visit
+const restored = store.get('appState')
+if (restored) {
+  console.log('Restored app state:', restored.lastPage)
+}
+
+console.log('Store advanced example complete!')

package/examples/useObserver.ts

@@ -0,0 +1,141 @@
+/**
+ * Memorio useObserver Example
+ *
+ * This example demonstrates the useObserver hook for React.
+ * useObserver automatically tracks state changes and triggers re-renders.
+ *
+ * Note: This example requires React to be present in the environment.
+ * Run in a React environment.
+ */
+
+import '../index'
+
+// ============================================
+// BASIC USEOBSERVER
+// ============================================
+
+// Example 1: Watch single value
+useObserver(callback, [state.value])
+
+function Counter() {
+  useObserver(() => {
+    console.debug('Count changed:', state.count)
+  }, [state.count])
+
+  return <div>{ state.count } </div>
+}
+
+// ============================================
+// MULTIPLE DEPENDENCIES
+// ============================================
+
+// Example 2: Watch multiple values
+function UserProfile() {
+  useObserver(() => {
+    console.debug('User or theme changed')
+  }, [state.user, state.theme])
+
+  return <div>{ state.user.name } </div>
+}
+
+// ============================================
+// AUTO-DISCOVERY
+// ============================================
+
+// Example 3: No dependencies - auto-discovers all state access
+function AutoDiscovery() {
+  useObserver(() => {
+    // Automatically tracks state.user, state.items, state.count
+    console.debug('Changed:', state.user.name, state.items.length, state.count)
+  })
+
+  return <div>{ state.user.name } </div>
+}
+
+// ============================================
+// SYNC WITH USESTATE
+// ============================================
+
+// Example 4: Sync with useState
+function SyncedComponent() {
+  const [localData, setLocalData] = useState(null)
+
+  useObserver((newValue) => {
+    setLocalData(newValue)
+  }, [state.data])
+
+  return <div>{ localData } </div>
+}
+
+// ============================================
+// PRACTICAL EXAMPLE
+// ============================================
+
+// Real-world React component example:
+import { useObserver } from 'memorio'
+
+function TodoApp() {
+  // Track todos
+  useObserver(() => {
+    console.debug('Todos updated:', state.todos)
+    // Optionally save to store
+    store.set('todos', state.todos)
+  }, [state.todos])
+
+  // Track filter
+  useObserver(() => {
+    console.debug('Filter changed:', state.filter)
+  }, [state.filter])
+
+  const addTodo = (text) => {
+    state.todos = [...(state.todos || []), { text, done: false }]
+  }
+
+  const toggleTodo = (index) => {
+    const todos = [...state.todos]
+    todos[index].done = !todos[index].done
+    state.todos = todos
+  }
+
+  const filteredTodos = (state.todos || []).filter(t =>
+    state.filter === 'all' ||
+    (state.filter === 'done' && t.done) ||
+    (state.filter === 'todo' && !t.done)
+  )
+
+  return (
+    <div>
+    <select
+        value= { state.filter }
+  onChange = { e => state.filter = e.target.value }
+    >
+    <option value="all" > All </option>
+      < option value = "done" > Done </option>
+        < option value = "todo" > Todo </option>
+          </select>
+          <ul>
+  {
+    filteredTodos.map((todo, i) => (
+      <li
+            key= { i }
+            onClick = {() => toggleTodo(i)}
+  style = {{ textDecoration: todo.done ? 'line-through' : 'none' }
+}
+          >
+  { todo.text }
+  </li>
+        ))}
+</ul>
+  < input
+onKeyDown = { e => {
+  if (e.key === 'Enter') {
+    addTodo(e.target.value)
+    e.target.value = ''
+  }
+}}
+      />
+  </div>
+  )
+}
+
+console.log('useObserver example - run in React environment!')