memorio 4.7.3 → 4.9.5

package/types/memorio.d.ts

@@ -1,10 +1,17 @@
 import type {
   MemoryEntry,
+  MemorySync,
+  MemoryOperation,
+  SyncProvider,
+  SyncConfig,
+  SyncAck,
+  SyncDirection,
   RememberOptions,
   RecallOptions,
   ContextOptions,
   ContextEntry,
-  MemoryStats
+  MemoryStats,
+  PatchOperation
 } from './memory'
 
 /**
@@ -24,15 +31,10 @@ interface _memorio {
   array: unknown[]
   dispatch: _dispatch
   setDescription: (description: string) => void
-  logger?: {
-    log: (...args: unknown[]) => void
-    debug: (...args: unknown[]) => void
-    info: (...args: unknown[]) => void
-    warn: (...args: unknown[]) => void
-    error: (...args: unknown[]) => void
-  }
+  logger?: any
   objPath?: (prop: string, object: string[], separator?: string) => string
   propertyName?: string | ((container: any, object: any) => string | null)
+
   debug?: boolean
   // State management properties
   _tracking?: boolean
@@ -70,7 +72,9 @@ interface _memorio {
     cache: any
   }
    help?: () => void
-   // Schema validation
+   global?: () => void
+   env?: { isDev: boolean; isProd: boolean }
+  // Schema validation
   registerSchema?: (path: string, schema: any) => void
   validate?: (path: string, value: any) => { valid: boolean; errors?: string[] }
   unregisterSchema?: (path: string) => boolean
@@ -96,6 +100,11 @@ interface _memorio {
   stateGet?: (path: string) => any
   stateSchema?: () => Array<{ path: string; type: string; defined: boolean }>
   memory?: MemoryAPI
+  // Development-only surfaces (excluded from production builds via `if (DEV)`).
+  // Not a security boundary on its own - rely on your backend for auth.
+  devtools?: any
+  inspect?: () => string[]
+  [key: string]: any
 }
 
 interface MemoryAPI {
@@ -103,13 +112,37 @@ interface MemoryAPI {
   recall<T>(query: string, opts?: RecallOptions): Promise<T | null>
   update(key: string, value: any, opts?: Partial<RememberOptions>): Promise<void>
   forget(key: string): Promise<void>
+  patch(key: string, patches: PatchOperation[]): Promise<void>
   context(opts?: ContextOptions): Promise<ContextEntry[]>
   stats(): Promise<MemoryStats>
   forgetExpired(): Promise<number>
   clear(): Promise<void>
+  /**
+   * Configure the optional cloud-sync layer. Supplying a `provider` (an
+   * application-owned object that knows how to talk to your backend) enables
+   * the local operation journal. The `namespace` (tenant/user/device)
+   * partitions the journal so contexts/tenants cannot read each other's
+   * operations. Memorio never handles credentials - auth lives in the
+   * provider/backend.
+   */
+  configure(opts: SyncConfig): MemoryAPI
+  /** Local operation journal. Writes are namespaced and durable (SQLite when
+   * available, else localStorage). Use `replay()` to push `pending()` entries
+   * to the configured provider. */
+  journal: MemoryJournal
+}
+
+interface MemoryJournal {
+  append(entry: MemoryEntry, operation: MemoryOperation): Promise<MemoryEntry>
+  pending(): Promise<MemoryEntry[]>
+  markSynced(ids: string[]): Promise<number>
+  get(id: string): Promise<MemoryEntry | null>
+  clear(): Promise<void>
+  replay(): Promise<SyncAck>
+  status(): Promise<'store'>
 }
 
-type memorio = _memorio
+type memorio = _memorio
 declare var memorio: _memorio
 
 interface GlobalMemorio {

package/types/memory.d.ts

@@ -9,6 +9,80 @@ export type MemoryType =
 
 export type MemoryStatus = 'active' | 'obsolete' | 'superseded'
 
+/**
+ * A field-level patch operation recorded in the sync journal instead of
+ * recording the entire entity. Enables automatic merging when two devices
+ * edit different fields of the same object.
+ */
+export interface PatchOperation {
+  op: 'set' | 'delete'
+  path: string
+  value?: unknown
+}
+
+/**
+ * Logical operations recorded in the local sync journal.
+ * The `delete` operation creates an explicit tombstone entry so concurrent
+ * updates/replay do not resurrect deleted values.
+ */
+export type MemoryOperation =
+  | 'remember'
+  | 'update'
+  | 'forget'
+  | 'expire'
+  | 'confirm'
+  | 'supersede'
+  | 'delete'
+  | 'patch'
+
+/**
+ * Synchronization state of a journal entry against a remote/cloud backend.
+ */
+export type MemorySync = 'pending' | 'synced' | 'conflict' | 'error'
+
+export type SyncDirection = 'up' | 'down' | 'both'
+
+/**
+ * Pluggable cloud/sync transport. Memorio never ships a credential flow:
+ * the application supplies a `provider` that knows how to talk to its backend
+ * (REST, WebSocket, Supabase, a custom agent server, ...). Memorio owns the
+ * local journal, the provider only moves operations.
+ */
+export interface SyncProvider {
+  /** Pushes pending local operations; returns ids that were accepted */
+  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
+  /** Optional pull of remote operations newer than `since` (epoch ms) */
+  pull?(since?: number): Promise<MemoryEntry[]>
+  /**
+   * Optional conflict resolution for concurrent writes on the same path.
+   * Receives the local and remote entries; return 'local', 'remote', or 'merge'.
+   * Uses HLC timestamps for causal comparison when available.
+   */
+  resolve?(op: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
+  /**
+   * Optional conflict resolver with HLC context. Called when two devices
+   * wrote concurrently to the same key/path. Implementations can use
+   * `local.hlc` and `remote.hlc` for causal determination.
+   */
+  resolveConflict?(local: MemoryEntry, remote: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
+}
+
+export interface SyncConfig {
+  /** Sync provider implementation (application supplied) */
+  provider?: SyncProvider
+  /** Which direction to sync; 'both' is the default */
+  direction?: SyncDirection
+  /** Auto-sync on every local write? defaults to true */
+  auto?: boolean
+}
+
+export interface SyncAck {
+  synced: string[]
+  conflicts?: string[]
+  error?: string
+  resolved?: { id: string; resolution: 'local' | 'remote' | 'merge' }[]
+}
+
 export interface MemoryEntry<T = any> {
   id: string
   key: string
@@ -23,6 +97,27 @@ export interface MemoryEntry<T = any> {
   createdAt: number
   lastConfirmedAt: number
   supersededId?: string | null
+  /** Monotonic per-key write counter, used for last-writer / conflict resolution */
+  version?: number
+  /** Epoch ms of the last mutation that touched this entry */
+  updatedAt?: number
+  /** Last logical operation that produced this entry */
+  operation?: MemoryOperation
+  /** Local-cloud sync state of the entry (undefined => not tracked for sync) */
+  sync?: MemorySync
+  /**
+   * Hybrid Logical Clock timestamp for causal ordering across devices.
+   * Replaces wall-clock-only ordering which is vulnerable to clock drift.
+   */
+  hlc?: string
+  /**
+   * Field-level path for path-level journaling (e.g. "user.role").
+   * When set, the journal entry represents a patch to a sub-path
+   * rather than a full entity replacement.
+   */
+  path?: string
+  /** Array of JSON Patch-style operations for compound path-level mutations. */
+  patches?: PatchOperation[]
 }
 
 export interface RememberOptions<T = any> {

package/types/schema.d.ts

@@ -1,53 +1,53 @@
-/// MEMORIO SCHEMA TYPES
-/// Ambient declarations for the schema validation system.
-
-///
-// Schema type — describes the expected runtime shape of a value.
-///
-interface _schemaDef {
-  /** Expected runtime type of the value. */
-  type?: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'any'
-  /** Required property names when type is 'object'. */
-  required?: string[]
-  /** Nested property schemas (validated recursively). */
-  properties?: Record<string, _schemaDef>
-  /** Minimum: value for numbers, length for strings. */
-  min?: number
-  /** Maximum: value for numbers, length for strings. */
-  max?: number
-  /** Regex pattern a string value must match. */
-  pattern?: RegExp
-  /** Whitelist of allowed values. */
-  enum?: any[]
-  /** Custom validator: return true for pass, or a string describing the error. */
-  validator?: (value: any) => boolean | string
-}
-
-///
-// Result of a validation check.
-///
-interface _validationResult {
-  /** Whether the value passed all checks. */
-  valid: boolean
-  /** Array of human-readable error strings (present when valid is false). */
-  errors?: string[]
-}
-
-///
-// Schema namespace — the public `memorio.schema`-style helpers live on `memorio`.
-///
-interface _schemaHelpers {
-  /** Registers a schema (or custom validator) for a state path. */
-  register: (path: string, schema: _schemaDef | ((value: any) => boolean | string)) => void
-  /** Validates a value against a registered schema. */
-  validate: (path: string, value: any) => _validationResult
-  /** Removes a previously registered schema. */
-  unregister: (path: string) => boolean
-  /** Lists all registered schema paths. */
-  list: () => string[]
-  /** Retrieves the schema registered for a path. */
-  get: (path: string) => _schemaDef | undefined
-}
-
-declare var _schemaDef: _schemaDef
-declare var _validationResult: _validationResult
+/// MEMORIO SCHEMA TYPES
+/// Ambient declarations for the schema validation system.
+
+///
+// Schema type - describes the expected runtime shape of a value.
+///
+interface _schemaDef {
+  /** Expected runtime type of the value. */
+  type?: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'any'
+  /** Required property names when type is 'object'. */
+  required?: string[]
+  /** Nested property schemas (validated recursively). */
+  properties?: Record<string, _schemaDef>
+  /** Minimum: value for numbers, length for strings. */
+  min?: number
+  /** Maximum: value for numbers, length for strings. */
+  max?: number
+  /** Regex pattern a string value must match. */
+  pattern?: RegExp
+  /** Whitelist of allowed values. */
+  enum?: any[]
+  /** Custom validator: return true for pass, or a string describing the error. */
+  validator?: (value: any) => boolean | string
+}
+
+///
+// Result of a validation check.
+///
+interface _validationResult {
+  /** Whether the value passed all checks. */
+  valid: boolean
+  /** Array of human-readable error strings (present when valid is false). */
+  errors?: string[]
+}
+
+///
+// Schema namespace - the public `memorio.schema`-style helpers live on `memorio`.
+///
+interface _schemaHelpers {
+  /** Registers a schema (or custom validator) for a state path. */
+  register: (path: string, schema: _schemaDef | ((value: any) => boolean | string)) => void
+  /** Validates a value against a registered schema. */
+  validate: (path: string, value: any) => _validationResult
+  /** Removes a previously registered schema. */
+  unregister: (path: string) => boolean
+  /** Lists all registered schema paths. */
+  list: () => string[]
+  /** Retrieves the schema registered for a path. */
+  get: (path: string) => _schemaDef | undefined
+}
+
+declare var _schemaDef: _schemaDef
+declare var _validationResult: _validationResult

package/types/sqlite.d.ts

@@ -0,0 +1,35 @@
+/*!
+  memorio
+  Copyright (c) 2019 Dario Passariello <dariopassariello@gmail.com>
+  Licensed under MIT License, see
+  dario.passariello.ca
+*/
+
+/**
+ * Memorio SQLite module.
+ *
+ * Backed by the optional `sql.js` package (SQLite compiled to WebAssembly).
+ * Lazily loaded in the browser; disabled in non-browser environments.
+ */
+interface _sqlite {
+  /** Database connection tools (create, get, delete, list, size, export, import). */
+  db: any
+  /** SQL execution tools (run, select). */
+  query: any
+  /** CRUD shortcut helpers (set, get). */
+  data: any
+  /** Lazy-load / configure the sql.js engine (wasm loader, locateFile, etc.). */
+  config: (opts: any) => any
+  /** Promise that resolves once the sql.js engine has been initialized. */
+  ready: Promise<void> | null
+  /** True when running outside a supported browser environment. */
+  _disabled?: boolean
+  /** Human readable reason the module is disabled, when applicable. */
+  _warning?: string
+  [key: string]: any
+}
+
+declare var sqlite: _sqlite
+type sqlite = _sqlite
+
+declare var sqlbases: any[]

package/markdown/CACHE.md

@@ -1,90 +0,0 @@
-# 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.debug(cache.get('username')); // "Mario"
-console.debug(cache.get('score'));    // 1500
-```
-
-### Example 2: Intermediate
-
-```javascript
-// Store objects
-cache.set('user', { name: 'Luigi', level: 5 });
-const user = cache.get('user');
-console.debug(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

package/markdown/CHANGELOG.md

@@ -1,161 +0,0 @@
-# Changelog - Memorio
-
-All notable changes to this project will be documented in this file.
-
----
-
-## v4.6.1 (Security Patch) - 2026-08-14 - CRITICAL Security Fix
-
-### 🔐 Security NOTICE (v4.6.0)
-
-**CRITICAL**: A Gitea Personal Access Token was accidentally committed to `.npmrc` in v4.6.0
-
-**Affected**: `v4.6.0` tag and all builds from that version
-
-**Action Required**:
-- **IMMEDIATE**: Revoke ALL tokens on Gitea Packages by admin access
-- **GENERATE**: Create new PAT with scope `write:package` only
-- **CONFIGURE**: Add as secret `PAT` in GitHub Actions or Gitea Actions
-- **UPGRADE**: Use v4.6.1 where the token is replaced with `${PAT}` environment variable
-
-The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed in v4.6.1.
-
-### 🐛 Bug Fixes
-
-- **SECURITY**: Removed hardcoded Gitea PAT from `.npmrc` (exposed token remediated)
-- Replaced with environment variable `${PAT}` for secure authentication
-
-### 📝 Documentation Updates
-
-- `.npmrc`: Token replaced with environment variable reference
-- `.gitea/workflows/npm.yml`: Configured to use secrets `GITEA_USER` and `PAT`
-
----
-
-## v4.6.0 (Previous - SECURITY ISSUE) - 2026-08-13 - Refactoring & Documentation
-
-**⚠️ WARNING**: This version had a hardcoded PAT token that was later remediated in v4.6.1**
-
-### 🐛 Bug Fixes
-
-- Fixed circular import in `idb/index.ts` → `core/global`
-- Fixed dead `globalThis._propertyAccessLog` reference in `observer`
-- Fixed `dispatch.remove(f)` tuple bug in `functions/dispatch.ts`
-- Fixed `logger.isDebugEnabled` using wrong module reference
-- Removed dead `propertyAccessLog` / `pushPropertyAccess` from `core/internal.ts`
-- Removed duplicate path-tracking block in `state` get handler
-- Removed redundant `?? key` fallback in `state` set handler
-
-### 🔧 Code Refactoring
-
-- **Self-contained modules**: All modules now work independently without internal `globalThis.memorio.*` reads/writes
-- **Module-local state**: Created `core/internal.ts` for module-local singletons
-- **Bootstrap-only global**: `core/global.ts` now only publishes to `globalThis.memorio` at initialization
-- **Removed dead code**: `core/constructor.ts` deleted (unused)
-- **Extracted helpers**: `_read`/`_write`/`_remove` in `store` and `session` to eliminate duplication
-- **Fixed circular imports**: `dispatch` → `observer` via `globalThis.events`
-
-### 📝 Documentation Updates
-
-- `docs/README.md`: Added Classic `import { state } from 'memorio'` section, improved badges layout, enhanced "Why memorio?" comparison table
-- `docs/markdown/STORE.md`: Added classic import note
-- `docs/markdown/IMPORT.md`: New file for named export guide
-- `docs/SUMMARY.md`: Updated to include `IMPORT.md`
-- `README.md`: Badge corrections, header cleanup, removed unverified bundle size claims
-
-### 🆕 GitHub Actions / Gitea Workflows
-
-- Added `.gitea/workflows/npm.yml` for automatic npm package publishing to Gitea Packages on `v*` tags
-- Requires `GITEA_USER` and `PAT` secrets
-
-### 🧪 Tests
-
-- **Result: 9 suites · 101 passed · 4 skipped · 1 todo**
-- All lint and typecheck clean
-
----
-
-## v3.0.2 (Current) - 2026-05-19 - Bug Fix, Security & API Expansion
-
-### 🐛 Bug Fixes
-
-- Removed dead code: `buildPathTracker` from `functions/state/index.ts` (unused Proxy builder, exported nowhere)
-- Removed double `delete` in state `removeAll` handler (redundant null-check + delete on same key)
-- Removed unbound `globalThis.state` reference in state init (would throw `ReferenceError` in strict mode)
-- Removed `Object.freeze(observer)` referencing undeclared variable (`ReferenceError` on module load)
-- Removed `confirm()` synchronous blocking call from `idb.db.delete` (library must not block main thread)
-
-### 🔒 Security Improvements
-
-- Removed `esbuild-sass-plugin` and `esbuild-scss-modules-plugin` from `devDependencies` (unnecessary for a library with no styles)
-- Removed `injectStyle: true`, `sassPlugin()` and `.css` loader from `tsup.config.ts`
-- Deleted `tsup.plugin.injectCss.ts` (code injection vector completely removed from build pipeline)
-- `console.error`/`console.warn` → `console.debug` in `devtools` and `idb` error handlers (consistent debug-only logging policy)
-- `store.set()` now blocks function values instead of silently logging and continuing
-- All `PRIVATE License` headers in `functions/idb/` replaced with `MIT License`
-
-### 🔧 Code Quality
-
-- Added JSDoc to `observerFunction` in `functions/observer/index.ts`
-- Added JSDoc to `cache` global in `functions/cache/index.ts`
-- `lint` and `tsc` pass clean - 0 vulnerabilities from `npm audit`
-
-### 🆕 API - New in 3.0.2
-
-| Function | Description |
-|----------|-------------|
-| `memorio.isBrowser()` | Returns `true` when running in a browser |
-| `memorio.isNode()` | Returns `true` when running in Node.js |
-| `memorio.isDeno()` | Returns `true` when running in Deno |
-| `memorio.isEdge()` | Returns `true` in Cloudflare Workers, Vercel Edge, etc. |
-| `memorio.getCapabilities()` | Full capabilities object (`platform`, `hasLocalStorage`, `hasIndexedDB`, …) |
-| `memorio.createContext(name?)` | Create multi-tenant isolated context |
-| `memorio.listContexts()` | List all active isolated contexts |
-| `memorio.deleteContext(id)` | Delete isolated context by ID |
-| `memorio.isolate(name?)` | Shorthand alias for `createContext` |
-
-### 🧪 Tests
-- **Result: 8 suites · 95 passed · 3 skipped · 0 failed**
-
-### 🗑️ Dependency Changes
-
-| Removed | Reason |
-|---------|--------|
-| `esbuild-sass-plugin@3.7.0` | No SCSS in a library |
-| `esbuild-scss-modules-plugin@1.1.1` | No SCSS in a library |
-| 36 transitive packages | Removed from `node_modules` |
-
-### 📝 Documentation Updates
-
-- `docs/README.md`: replaced `console.debug` with `console.debug` in usage examples; fixed `esbuild` badge → `tsup`
-- `.github/CHANGELOG.md`: restructured with fix / security / changed sections
-- `.github/HISTORY.md`: complete rewrite through v3.0.2
-- `.github/SECURITY.md`: NIST/NSA standard + OWASP Top 10 mapping
-- `.github/CITATION.cff`: license PRIVATE → MIT to match `package.json`
-- `.project/*`: all context documents updated to v3.0.2
-
----
-
-## v2.9.0 - 2026-05-13
-
-### Added
-- DevTools - `memorio.devtools.inspect()`, `stats()`, `exportData()`
-- Logger with full history, stats and export
-- Platform detection (`isBrowser`, `isNode`, `isDeno`, `isEdge`, `getCapabilities`)
-- Session isolation via `crypto.randomUUID()`
-
-### Changed
-- Updated dependencies to latest versions
-- Improved cross-platform support (Deno, Edge Workers, Node.js)
-
-### Security
-- Secure random session IDs replaced `Math.random()`
-- Key validation (max 512 chars + character whitelist)
-
----
-
-## v2.5.0 - 2026-02-17
-
-- Initial release of memorio (state, store, session, cache, idb)
-- Observer pattern (`observer`)
-- `useObserver` React hook