memorio 4.8.0 → 4.9.5

package/types/memorio.d.ts

@@ -10,7 +10,8 @@ import type {
   RecallOptions,
   ContextOptions,
   ContextEntry,
-  MemoryStats
+  MemoryStats,
+  PatchOperation
 } from './memory'
 
 /**
@@ -30,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
@@ -76,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
@@ -102,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 {
@@ -109,6 +112,7 @@ 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>
@@ -118,7 +122,7 @@ interface MemoryAPI {
    * 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
+   * operations. Memorio never handles credentials - auth lives in the
    * provider/backend.
    */
   configure(opts: SyncConfig): MemoryAPI
@@ -138,7 +142,7 @@ interface MemoryJournal {
   status(): Promise<'store'>
 }
 
-type memorio = _memorio
+type memorio = _memorio
 declare var memorio: _memorio
 
 interface GlobalMemorio {

package/types/memory.d.ts

@@ -9,9 +9,21 @@ 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 cloud side only ever sees operations — never a raw dump of a substrate.
+ * The `delete` operation creates an explicit tombstone entry so concurrent
+ * updates/replay do not resurrect deleted values.
  */
 export type MemoryOperation =
   | 'remember'
@@ -20,6 +32,8 @@ export type MemoryOperation =
   | 'expire'
   | 'confirm'
   | 'supersede'
+  | 'delete'
+  | 'patch'
 
 /**
  * Synchronization state of a journal entry against a remote/cloud backend.
@@ -39,8 +53,18 @@ export interface SyncProvider {
   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 hint: 'local' | 'remote' | 'merge' */
+  /**
+   * 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 {
@@ -56,6 +80,7 @@ export interface SyncAck {
   synced: string[]
   conflicts?: string[]
   error?: string
+  resolved?: { id: string; resolution: 'local' | 'remote' | 'merge' }[]
 }
 
 export interface MemoryEntry<T = any> {
@@ -80,6 +105,19 @@ export interface MemoryEntry<T = any> {
   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/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

package/markdown/DEVTOOLS.md

@@ -1,122 +0,0 @@
-# Memorio DevTools
-
-> 🖥️ **Browser Only**: This feature is only available in browser console
-
-Browser console debugging tools for inspecting and managing Memorio state.
-
-## Quick Start
-
-```javascript
-// Load memorio first
-import 'memorio'
-```
-
-## Available Methods
-
-### inspect()
-
-Inspect all Memorio modules in the console.
-
-```javascript
-memorio.devtools.inspect()
-```
-
-### stats()
-
-Get statistics about all modules.
-
-```javascript
-memorio.devtools.stats()
-// Returns: { stateKeys, storeKeys, sessionKeys, cacheKeys, idbDatabases, lastUpdate }
-```
-
-### clear(module)
-
-Clear data from a specific module.
-
-```javascript
-memorio.devtools.clear('state')
-memorio.devtools.clear('store')
-memorio.devtools.clear('session')
-memorio.devtools.clear('cache')
-```
-
-### clearAll()
-
-Clear all Memorio data.
-
-```javascript
-memorio.devtools.clearAll()
-```
-
-### watch(module, path)
-
-Watch a specific path for changes.
-
-```javascript
-memorio.devtools.watch('state', 'user.name')
-```
-
-### exportData()
-
-Export all data as JSON.
-
-```javascript
-const json = memorio.devtools.exportData()
-console.debug(json)
-```
-
-### importData(jsonString)
-
-Import data from JSON.
-
-```javascript
-memorio.devtools.importData('{"state":{"key":"value"}}')
-```
-
-### help()
-
-Show help information.
-
-```javascript
-memorio.devtools.help()
-```
-
-## Console Shortcuts
-
-Memorio provides global shortcuts for quick access:
-
-```javascript
-$state    // globalThis.state
-$store    // globalThis.store
-$session  // globalThis.session
-$cache    // globalThis.cache
-```
-
-## Examples
-
-### Inspect current state
-
-```javascript
-memorio.devtools.inspect()
-```
-
-### Export and restore state
-
-```javascript
-// Export
-const backup = memorio.devtools.exportData()
-
-// Later... import
-memorio.devtools.importData(backup)
-```
-
-### Monitor changes
-
-```javascript
-// Watch a specific path
-memorio.devtools.watch('state', 'counter')
-
-// Now changes will be logged to console
-state.counter = 42 // Console shows: 👁 Change: state.counter = 42
-```