memorio 2.8.0 → 2.9.1

package/docs/README.md

@@ -0,0 +1,432 @@
+# [memorio](https://npmjs.com/package/memorio)
+
+> A lightweight, type-safe state management library for JavaScript applications
+
+[![version](https://img.shields.io/npm/v/memorio.svg)](https://npmjs.org/package/memorio)
+[![install size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=memorio&query=$.install.pretty&label=install%20size&style=flat-square)](https://packagephobia.now.sh/result?p=memorio)
+[![downloads](https://img.shields.io/npm/dm/memorio.svg)](https://npmjs.org/package/memorio)
+
+![Node.js](https://img.shields.io/badge/Node.js-gray?logo=node.js)
+![React](https://img.shields.io/badge/React-gray?logo=React)
+![Javascript](https://img.shields.io/badge/Javascript-gray?logo=Javascript)
+![TypeScript](https://img.shields.io/badge/TypeScript-gray?logo=typescript)
+![esbuild](https://img.shields.io/badge/esbuild-gray?logo=esbuild)
+
+![Jest](https://img.shields.io/badge/Jest-gray?logo=jest)
+![ESLint](https://img.shields.io/badge/Eslint-gray?logo=eslint)
+![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
+
+[![GitBook](https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1)](https://a51.gitbook.io/memorio)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [State Management](#state-management)
+  - [Observer](#observer)
+  - [useObserver](#useobserver)
+  - [Store](#store)
+  - [Session](#session)
+  - [Cache](#cache)
+  - [idb](#idb)
+  - [DevTools](#devtools)
+  - [Logger](#logger)
+- [Testing](#testing)
+- [Security](#security)
+- [License](#license)
+- [Cross-Platform Support](#cross-platform-support)
+  - [Platform & Context Isolation](docs/markdown/PLATFORM.md)
+
+## Features
+
+- Reactive state management with observer pattern
+- Persistent storage with Store API
+- Session management for temporary data
+- Type-safe with full TypeScript support
+- Comprehensive test coverage
+- Easy debugging with proxy-based state
+- **Cross-platform**: Works in Browser, Node.js, Deno, and Edge Workers
+- **Session Isolation**: Each session/request gets isolated state namespace
+- **Context System**: Multi-tenant server-side isolation with `memorio.createContext()`
+- **DevTools**: Browser console debugging tools
+- **Logger**: Automatic logging of state changes
+
+## Installation
+
+```bash
+npm i -D memorio
+```
+
+### All test suites are passing
+
+- Basic functionality tests
+- State management tests
+- Store operations tests
+- Cache operations tests
+- Observer pattern tests
+- useObserver pattern tests
+- DevTools tests
+- Logger tests
+
+Total: 71 tests passed across 8 test suites
+
+## Quick Start
+
+```javascript
+/*
+  IMPORTANT!
+  Add import only at first start of your SPA. Became global!.
+  You don't need to import any time you need to use memorio
+*/
+
+import 'memorio';
+
+// State Management
+state.counter = 0;
+state.active = false;
+state.name = "john";
+state.user = { name: 'John', age: 30 };
+state.hours = [2,3,10,23]
+
+// useObserver Pattern for react app
+// Example: if you change the state.counter you get a console.log
+useObserver(
+    () => {
+      console.log(`Counter changed to ${state.counter}`);
+    },
+    [state.counter]
+);
+
+
+// Store (Persistent Storage)
+store.set('preferences', { theme: 'dark' });
+const preferences = store.get('preferences');
+
+// Session Storage
+session.set('token', 'user-jwt-token');
+const token = session.get('token');
+
+// DevTools
+memorio.devtools.inspect();
+
+// Logger
+memorio.logger.configure({ enabled: true, logToConsole: true })
+```
+
+## API Reference
+
+### State Management
+
+State in Memorio is globally accessible and reactive:
+
+```javascript
+// Setting state
+state.user = { name: 'John' };
+
+// Getting state
+const userName = state.user.name;
+
+// Listing all states
+console.log(state.list);
+
+// Removing state
+state.remove('user');
+
+// Clearing all states
+state.removeAll();
+```
+
+### useObserver
+
+useObserver is a React hook for observing Memorio state changes with auto-discovery:
+
+```js
+// Basic useObserver - array syntax with state path
+useObserver(
+  () => {
+    console.log('User updated:', state.user);
+  },
+  [state.user]
+);
+
+// Multiple states
+useObserver(
+  () => {
+    console.log('States changed:', state.user, state.counter, state.settings);
+  },
+  [state.user, state.counter, state.settings]
+);
+
+// With options
+useObserver(
+  () => {
+    console.log('Value changed');
+  },
+  [state.value],
+  { immediate: true }
+);
+```
+
+### Store
+
+Persistent storage for your application:
+
+```javascript
+// Setting values
+store.set('config', { theme: 'dark', language: 'en' });
+
+// Getting values
+const config = store.get('config');
+
+// Removing specific value
+store.remove('config');
+
+// Getting store size
+const size = store.size();
+
+// Clearing store
+store.removeAll();
+
+// Check if using persistent storage
+if (store.isPersistent) {
+  console.log('Using real localStorage');
+} else {
+  console.log('Using memory fallback (server environment)');
+}
+```
+
+### Session
+
+Temporary storage that persists during page sessions:
+
+```js
+// Setting session data
+session.set(
+  'userSession', {
+    id: 'user123',
+    lastActive: Date.now()
+  }
+);
+
+// Getting session data
+const userData = session.get('userSession');
+
+// Checking session size
+const activeItems = session.size();
+
+// Removing session data
+session.remove('userSession');
+
+// Clearing all session data
+session.removeAll();
+
+// Check if using persistent storage
+if (session.isPersistent) {
+  console.log('Using real sessionStorage');
+} else {
+  console.log('Using memory fallback (server environment)');
+}
+```
+
+### Cache
+
+In-memory cache for temporary data storage:
+
+```js
+// Setting cache data
+cache.set('tempData', { computed: true, value: 42 });
+
+// Getting cache data
+const cached = cache.get('tempData');
+
+// Checking cache size
+const cacheSize = cache.size();
+
+// Removing cache data
+cache.remove('tempData');
+
+// Clearing all cache data
+cache.removeAll();
+```
+
+**Note:** Cache data is stored in memory and will be lost on page refresh.
+
+### idb
+
+Permanent storage using browser database:
+
+#### Create database
+
+```js
+idb.db.create("Database");
+```
+
+#### Set data into table
+
+```js
+idb.data.set("Database","table", { id: 1, data:{...} } );
+```
+
+#### Get data from table
+
+> [in development]
+
+```js
+idb.data.get("Database","table", 1 );
+```
+
+#### Delete database / table
+
+> [in development]
+
+```js
+idb.db.delete("Database") // Remove DB
+idb.table.delete("Database","table") // Remove only "table"
+```
+
+### DevTools
+
+Browser console debugging tools for inspecting state, store, session, cache:
+
+```javascript
+// Inspect all state modules
+memorio.devtools.inspect();
+
+// Get statistics
+memorio.devtools.stats();
+
+// Clear specific module
+memorio.devtools.clear('state');
+
+// Clear all modules
+memorio.devtools.clearAll();
+
+// Watch a path for changes
+memorio.devtools.watch('state', 'user.name');
+
+// Export all data as JSON
+memorio.devtools.exportData();
+
+// Import data from JSON
+memorio.devtools.importData(jsonString);
+
+// Get help
+memorio.devtools.help();
+
+// Console shortcuts (available in browser console)
+$state  // globalThis.state
+$store  // globalThis.store
+$session // globalThis.session
+$cache  // globalThis.cache
+```
+
+### Logger
+
+Logging middleware for tracking all state changes:
+
+```javascript
+// Configure logger
+memorio.logger.configure({ enabled: true, logToConsole: true });
+
+// Enable/disable logging
+memorio.logger.enable();
+memorio.logger.disable();
+
+// Get log history
+memorio.logger.getHistory();
+
+// Get statistics
+memorio.logger.getStats();
+
+// Clear history
+memorio.logger.clearHistory();
+
+// Export logs as JSON
+memorio.logger.exportLogs();
+```
+
+## Testing
+
+All test suites are passing:
+
+- Basic functionality tests
+- State management tests
+- Store operations tests
+- Cache operations tests
+- Observer pattern tests
+- useObserver pattern tests
+- DevTools tests
+- Logger tests
+
+Total: 71 tests passed across 8 test suites
+
+## Security
+
+Security scans and reports are available at:
+
+- [Socket.dev](https://socket.dev/npm/package/memorio)
+- [Snyk.io](https://security.snyk.io/package/npm/memorio)
+
+## License
+
+MIT License
+
+Copyright (c) [Dario Passariello](https://dario.passariello.ca/)
+
+---
+
+## Cross-Platform Support
+
+Memorio is designed to work across multiple JavaScript environments:
+
+### Platform Compatibility
+
+| Feature | Browser | Node.js | Deno | Edge Workers |
+|---------|---------|---------|------|---------------|
+| `state` | ✅ | ✅ | ✅ | ✅ |
+| `observer` | ✅ | ✅ | ✅ | ✅ |
+| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
+| `idb` | ✅ | ❌ | ❌ | ⚠️ |
+| `devtools` | ✅ | ❌ | ❌ | ⚠️ |
+| `logger` | ✅ | ✅ | ✅ | ✅ |
+
+- ✅ Full support
+- ⚠️ Partial support (fallback to in-memory)
+- ❌ Not available
+
+### Session Isolation
+
+Memorio provides automatic session isolation to prevent state leakage between different requests or contexts:
+
+- **Unique Session IDs**: Each import gets a unique session identifier
+- **Namespaced Storage**: `store` and `session` keys are prefixed with session ID
+- **State Isolation**: `state` is isolated per-instance
+
+This ensures that in server-side environments (Node.js/Deno), different requests don't share state data.
+
+### Best Practices
+
+1. **For Client-Side**: Use all features freely - store, session, idb work with real browser storage
+2. **For Server-Side**: Use `state` and `cache` for in-memory data; store/session fall back to memory
+3. **For Edge Workers**: Same as browser; localStorage/sessionStorage available
+
+### Checking Platform
+
+```javascript
+import { isBrowser, isNode, isDeno, getCapabilities } from 'memorio';
+
+console.log('Browser:', isBrowser());      // true in browser
+console.log('Node.js:', isNode());          // true in Node.js
+console.log('Deno:', isDeno());             // true in Deno
+
+const caps = getCapabilities();
+console.log('Platform:', caps.platform);    // 'browser' | 'node' | 'deno' | 'edge'
+console.log('Persistent:', store.isPersistent); // true if using real storage
+```

package/docs/SUMMARY.md

@@ -0,0 +1,26 @@
+# Table of contents
+
+* [README](README.md)
+
+## Core Modules
+
+* [State](markdown/STATE.md) - Reactive global state management
+* [Observer](markdown/OBSERVER.md) - ⚠️ Deprecated (use useObserver)
+* [useObserver](markdown/USEOBSERVER.md) - React hook for state observation
+* [Cache](markdown/CACHE.md) - In-memory caching (lost on refresh)
+* [Store](markdown/STORE.md) - Persistent localStorage management
+* [Session](markdown/SESSION.md) - Temporary sessionStorage management
+* [IDB](markdown/IDB.md) - IndexedDB for large data storage
+
+## Platform & Compatibility
+
+* [Platform & Context Isolation](markdown/PLATFORM.md) - Cross-platform support, session isolation
+* [Security](markdown/SECURITY.md) - Security measures, vulnerability prevention
+* [Changelog](markdown/CHANGELOG.md) - Version history and migration guide
+
+## Additional Resources
+
+* [License](../LICENSE.md)
+* [Contributing](../CONTRIBUTING.md)
+* [Code of Conduct](../CODE_OF_CONDUCT.md)
+* [Security](../SECURITY.md)

package/docs/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-modernist

package/docs/markdown/CACHE.md

@@ -0,0 +1,90 @@
+# Cache - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Cache provides in-memory storage with a simple API. Data is lost on page refresh or process restart.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save data
+cache.set('username', 'Mario');
+cache.set('score', 1500);
+
+// Read data
+console.log(cache.get('username')); // "Mario"
+console.log(cache.get('score'));    // 1500
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Store objects
+cache.set('user', { name: 'Luigi', level: 5 });
+const user = cache.get('user');
+console.log(user.name); // "Luigi"
+
+// Remove single item
+cache.remove('username');
+
+// Clear all cache
+cache.removeAll();
+```
+
+---
+
+## API Reference
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `cache.get(name)` | `name: string` | `any` | Get value from cache |
+| `cache.set(name, value)` | `name: string, value: any` | `void` | Save value to cache |
+| `cache.remove(name)` | `name: string` | `boolean` | Remove single item |
+| `cache.removeAll()` | `none` | `boolean` | Clear all cache |
+
+---
+
+## Storage Comparison
+
+| Feature | Cache | Store | Session | IDB |
+|---------|-------|-------|---------|-----|
+| Platform Support | All (universal) | Browser/Edge | Browser/Edge | Browser only |
+| Lifetime | Until refresh | Forever | Until tab closes | Forever |
+| Capacity | Unlimited | ~5-10 MB | ~5-10 MB | 50+ MB |
+| Use case | Temporary data | User preferences | Auth tokens | Large data |
+
+---
+
+## Platform Support
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| Browser | ✅ Full | In-memory, lost on refresh |
+| Node.js | ✅ Full | In-memory, lost on restart |
+| Deno | ✅ Full | In-memory, lost on restart |
+| Edge Workers | ✅ Full | In-memory, lost on function cold start |
+
+---
+
+## Best Practices
+
+1. Use for temporary data that doesn't need persistence
+2. Great for computed values or API response caching
+3. Data is lost on page refresh - don't use for important data
+4. Clear with `cache.removeAll()` when no longer needed