memorio 4.9.35 → 5.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorio",
   "codeName": "memorio",
-  "version": "4.9.35",
+  "version": "5.1.0",
   "description": "Memorio, State + Observer, Store and iDB for an easy life - Cross-platform compatible",
   "main": "./index.cjs",
   "browser": {
@@ -25,6 +25,13 @@
       "email": "valeriacalascaglitta@gmail.com"
     }
   ],
+  "bin": {
+    "memorio": "./bin/cli.js"
+  },
+  "workspaces": [
+    "tests",
+    "extension/vscode"
+  ],
   "keywords": [
     "memorio",
     "state",
@@ -40,6 +47,8 @@
     "sqlite",
     "sql.js",
     "wasm",
+    "bun",
+    "cross-runtime",
     "browser",
     "frontend"
   ],
@@ -50,24 +59,32 @@
     }
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0",
+    "bun": ">=1.4.0"
   },
   "files": [
+    "bin",
+    "vsix",
     "markdown/**/*",
     "types/**/*",
     "examples/**/*",
+    "modules/**/*",
+    "adr/**/*",
     "AGENTS.md",
     "COPYRIGHT.md",
     "README.md",
     "FUNDING.yml",
     "SECURITY.md",
+    "SECURITY-HARDENING.md",
     "SUMMARY.md",
     "LICENSE.md",
     "index.d.ts",
+    "global.d.ts",
+    "global.cjs",
+    "global.js",
     "index.cjs",
     "index.js",
-    "llms.txt",
-    "modules/**/*"
+    "llms.txt"
   ],
   "publishConfig": {
     "access": "public"
@@ -89,6 +106,11 @@
       "require": "./index.cjs",
       "types": "./index.d.ts"
     },
+    "./global": {
+      "import": "./global.js",
+      "require": "./global.cjs",
+      "types": "./global.d.ts"
+    },
     "./types/*": "./types/*",
     "./redux": {
       "import": "./modules/redux.js",

package/types/broadcast.d.ts

@@ -0,0 +1,61 @@
+/*!
+  memorio
+  Copyright (c) 2025 Dario Passariello <dariopassariello@gmail.com>
+  Licensed under MIT License, see
+  dario.passariello.ca
+*/
+
+type SyncTarget = 'store' | 'session' | 'state' | 'all'
+
+interface BroadcastConfig {
+  channelName?: string
+  targets?: SyncTarget
+}
+
+interface BroadcastMessage {
+  __memorio_sync: true
+  target: SyncTarget
+  action: 'set' | 'remove' | 'delete' | 'clearAll'
+  path: string
+  value?: any
+  oldValue?: any
+  timestamp: number
+}
+
+interface _broadcast {
+  /**
+   * Install cross-tab synchronization.
+   *
+   * @param channelName Name for the BroadcastChannel (default: `memorio_sync`).
+   * @param opts    Optional configuration.
+   * @param opts.targets Which layers to sync: `store`, `session`, `state`, or `all` (default).
+   *
+   * @since memorio 5.1
+   */
+  install: (channelName?: string, opts?: BroadcastConfig) => void
+
+  /**
+   * Uninstall cross-tab synchronization and close the channel.
+   * @since memorio 5.1
+   */
+  uninstall: () => void
+
+  /**
+   * Whether cross-tab sync is currently installed.
+   * @since memorio 5.1
+   */
+  isInstalled: () => boolean
+
+  /**
+   * Broadcast a message to all other tabs (internal / advanced use).
+   * @since memorio 5.1
+   */
+  broadcast: (msg: Omit<BroadcastMessage, 'timestamp'>) => void
+}
+
+declare var broadcast: _broadcast | undefined
+type broadcast = _broadcast
+
+declare global {
+  var broadcast: _broadcast | undefined
+}

package/types/computed.d.ts

@@ -0,0 +1,96 @@
+/*!
+  memorio
+  Copyright (c) 2025 Dario Passariello <dariopassariello@gmail.com>
+  Licensed under MIT License, see
+  dario.passariello.ca
+*/
+
+type ComputeGetter = (path: string) => any
+type ComputeSelector = (get: ComputeGetter) => any
+type EqualityFn = (prev: any, next: any) => boolean
+
+interface ComputedEntry {
+  selector: ComputeSelector
+  lastValue: any
+  deps: Set<string>
+  equality: EqualityFn
+  subscribers: Set<(value: any) => void>
+}
+
+interface ComputeOptions {
+  /**
+   * Custom equality function to determine if the computed value changed.
+   * Defaults to deep equality (JSON.stringify comparison).
+   */
+  equality?: EqualityFn
+  /**
+   * Custom cache key (for multiple computations of the same path
+   * with different selectors).
+   */
+  equalityKey?: string
+}
+
+interface _computed {
+  /**
+   * Register a computed/derived value.
+   *
+   * @example
+   * memorio.computed.compute('state.user.fullName', (get) => {
+   *   const first = get('state.user.firstName')
+   *   const last  = get('state.user.lastName')
+   *   return `${first} ${last}`
+   * })
+   *
+   * @since memorio 5.1
+   */
+  compute: (
+    key: string,
+    selector: ComputeSelector,
+    opts?: ComputeOptions
+  ) => any
+
+  /**
+   * Retrieve the cached value of a computed key.
+   * Recomputes lazily if dependencies have changed.
+   *
+   * @since memorio 5.1
+   */
+  getValue: (key: string) => any
+
+  /**
+   * Subscribe to changes on a computed key.
+   *
+   * @param key The state path of the computed value.
+   * @param cb  Callback invoked with the new value when it changes.
+   * @returns   Unsubscribe function.
+   *
+   * @since memorio 5.1
+   */
+  subscribe: (key: string, cb: (value: any) => void) => (() => void)
+
+  /**
+   * Remove a computed value registration and clean up its dependency listeners.
+   *
+   * @since memorio 5.1
+   */
+  remove: (key: string) => boolean
+
+  /**
+   * List all registered computed keys.
+   * @since memorio 5.1
+   */
+  list: () => string[]
+
+  /**
+   * Clear all computed registrations and their dependency listeners.
+   * @since memorio 5.1
+   */
+  clear: () => void
+}
+
+declare var computed: _computed
+type computed = _computed
+
+declare global {
+  var computed: _computed | undefined
+}

package/types/encryption.d.ts

@@ -0,0 +1,129 @@
+/*!
+  memorio
+  Copyright (c) 2025 Dario Passariello <dariopassariello@gmail.com>
+  Licensed under MIT License, see
+  dario.passariello.ca
+*/
+
+interface EncryptedEnvelope {
+  __memorio_encrypted: true
+  v: number
+  alg: 'AES-GCM'
+  iv: string
+  data: string
+  keyId?: string
+}
+
+interface _encryption {
+  /** Check whether the Web Crypto API is available in this environment. */
+  isAvailable: () => boolean
+
+   /**
+    * Derive a CryptoKey from a password using PBKDF2.
+    * @param password The password to derive the key from.
+    * @param salt     Optional salt (string or Uint8Array).
+    * @param alg      Key algorithm: `'AES-GCM'` (default) or `'AES-CBC'`.
+    * @param iterations PBKDF2 iteration count (default 600000, NIST SP 800-132).
+    * @returns        A Promise that resolves to a CryptoKey.
+    */
+   deriveKey: (
+     password: string,
+     salt?: string | Uint8Array,
+     alg?: 'AES-GCM' | 'AES-CBC'
+     iterations?: number
+   ) => Promise<CryptoKey>
+
+   /**
+    * Generate a fresh random CryptoKey (AES-GCM, 256-bit).
+    * @param alg `'AES-GCM'` (default) or `'AES-CBC'`.
+    */
+   generateKey: (alg?: 'AES-GCM' | 'AES-CBC') => Promise<CryptoKey>
+
+   /**
+    * Generate a random salt string (base64-encoded).
+    * @param bytes Number of random bytes (default 16).
+    */
+   generateSalt: (bytes?: number) => string
+
+   /**
+    * Export a CryptoKey to portable base64 strings for secure storage.
+    * @param cryptoKey A raw CryptoKey (not a password string).
+    * @returns { key, iv } base64-encoded key material and IV (if any).
+    */
+   exportKey: (cryptoKey: CryptoKey) => Promise<{ key: string; iv: string }>
+
+   /**
+    * Import a CryptoKey from base64 strings produced by exportKey().
+    * @param keyData  Base64-encoded raw key bytes.
+    * @param _ivData  Ignored (kept for API compatibility).
+    * @returns        A Promise that resolves to a CryptoKey.
+    */
+   importKey: (keyData: string, _ivData?: string) => Promise<CryptoKey>
+
+  /**
+   * Encrypt a value with AES-GCM.
+   * @param value Any JSON-serializable value.
+   * @param key   A CryptoKey or a password string (derived via PBKDF2).
+   * @param keyId Optional label for key rotation.
+   * @returns     An EncryptedEnvelope object.
+   */
+  encrypt: (value: any, key: CryptoKey | string, keyId?: string) => Promise<EncryptedEnvelope>
+
+  /**
+   * Decrypt an EncryptedEnvelope.
+   * @param envelope The envelope returned by encrypt().
+   * @param key      A CryptoKey or a password string.
+   * @returns        The original decrypted value.
+   */
+  decrypt: (envelope: EncryptedEnvelope, key: CryptoKey | string) => Promise<any>
+
+  /**
+   * Encrypt with a password and return a JSON string (for direct persistence).
+   * @param value   The value to encrypt.
+   * @param password The password to derive the key from.
+   * @param salt    Optional salt string.
+   * @param keyId   Optional key label.
+   */
+  encryptWithPassword: (
+    value: any,
+    password: string,
+    salt?: string,
+    keyId?: string
+  ) => Promise<string>
+
+  /**
+   * Decrypt a JSON envelope string with a password.
+   * @param envelopeJson The JSON string from encryptWithPassword().
+   * @param password     The password to derive the key from.
+   * @param salt        Optional salt (must match the one used for encryption).
+   */
+  decryptWithPassword: (
+    envelopeJson: string,
+    password: string,
+    salt?: string
+  ) => Promise<any>
+
+  /**
+   * Type guard: check whether a value is an encrypted envelope.
+   */
+  isEncrypted: (value: any) => boolean
+
+  /**
+   * Configure a default encryption key for auto-encrypt mode.
+   * When a default key is set, store/session operations automatically
+   * encrypt on write and attempt decryption on read.
+   */
+  config: (opts: { key?: CryptoKey | string; keyId?: string }) => _encryption
+
+  /** Internal: the configured default key. */
+  _key?: CryptoKey | string | null
+  /** Internal: the configured default key ID. */
+  _keyId?: string
+}
+
+declare var encryption: _encryption
+type encryption = _encryption
+
+declare global {
+  var encryption: _encryption | null | undefined
+}

package/types/env.d.ts

@@ -1,9 +1,19 @@
-/**
- * Runtime environment detection.
- *
- * `DEV` and `PROD` are derived at runtime from `process.env.NODE_ENV`
- * (polyfilled by Vite/Webpack in browsers). No build-time environment
- * constant is required. Import from `core/env.ts`:
- *
- *   import { DEV, PROD } from './core/env'
- */
+/**
+ * Runtime environment detection.
+ *
+ * `DEV` and `PROD` are derived from a build-time `__DEV__` constant
+ * (injected by tsup/esbuild via `define`) when available, falling back
+ * to `process.env.NODE_ENV` for raw source imports in Node.js, and
+ * defaulting to `true` for raw browser environments.
+ * Import from `core/env.ts`:
+ *
+ *   import { DEV, PROD } from './core/env'
+ */
+
+/**
+ * Build-time constant injected by tsup/esbuild. When present, it's a
+ * boolean literal that enables dead-code elimination of dev-only blocks
+ * (devtools, introspection, etc.). Not defined for raw source imports
+ * (no build step) - falls back to runtime detection.
+ */
+declare const __DEV__: boolean | undefined

package/types/exports.d.ts

@@ -10,6 +10,7 @@
 
 /// <reference path="./schema.d.ts" />
 /// <reference path="./history.d.ts" />
+/// <reference path="./mutation.d.ts" />
 /// <reference path="./inspect.d.ts" />
 /// <reference path="./memorio.d.ts" />
 /// <reference path="./state.d.ts" />
@@ -20,6 +21,10 @@
 /// <reference path="./sqlite.d.ts" />
 /// <reference path="./observer.d.ts" />
 /// <reference path="./useObserver.d.ts" />
+/// <reference path="./encryption.d.ts" />
+/// <reference path="./computed.d.ts" />
+/// <reference path="./broadcast.d.ts" />
+/// <reference path="./security.d.ts" />
 
 export const memorio: _memorio
 export const state: _state
@@ -30,6 +35,10 @@ export const idb: _idb
 export const sqlite: _sqlite
 export const observer: _observer
 export const useObserver: _useObserver
+export const encryption: _encryption
+export const computed: _computed
+export const broadcast: _broadcast
+export const security: _security
 export const dispatch: _dispatch
 export const events: Record<string, any>
 
@@ -58,6 +67,7 @@ export const fractional: {
 export const isBrowser: () => boolean
 export const isNode: () => boolean
 export const isDeno: () => boolean
+export const isBun: () => boolean
 export const isEdge: () => boolean
 export const getCapabilities: (...args: unknown[]) => any
 export const createContext: _memorio['createContext']
@@ -110,6 +120,25 @@ export const enableHistory: (enabled?: boolean) => void
 export const clearHistory: () => void
 export const clearRedo: () => void
 
+// ── Mutation Engine (Memorio 5) ───────────────────────────────────────
+export const createMutation: (path: string, operation: _operation, before: any, after: any, opts?: { context?: string; source?: string; transactionId?: string }) => _mutation
+export const recordMutation: (mutation: _mutation) => void
+export const toPatch: (mutation: _mutation) => _patch | null
+export const mutate: (path: string, value: any, opts?: { source?: string; transactionId?: string }) => _mutation
+export const beginTransaction: (source?: string, message?: string, metadata?: Record<string, any>) => _transaction
+export const transaction: (source?: string, message?: string, metadata?: Record<string, any>) => _transaction
+export const commitTransaction: () => _transaction | null
+export const abortTransaction: () => _transaction | null
+export const currentTransaction: () => _transaction | null
+export const listTransactions: () => _transaction[]
+export const generateMutationId: () => string
+export const generateTransactionId: () => string
+export const generateCommitId: () => string
+export const mutationToPatch: (mutation: _mutation) => _patch | null
+export const diffToPatch: (path: string, before: any, after: any) => _patch | null
+export const canMerge: (p1: _patch, p2: _patch) => boolean
+export const mergePatches: (p1: _patch, p2: _patch) => _patch
+
 // ── Introspection (development-only) ─────────────────────────────────
 export const stateKeys: () => string[]
 export const pathExists: (path: string) => boolean

package/types/history.d.ts

@@ -2,7 +2,7 @@
 /// Ambient declarations for the snapshot / undo / redo / trace API.
 
 ///
-// A single recorded state mutation.
+// A single recorded state mutation (extended for Memorio 5).
 ///
 interface _mutationRecord {
   /** Dotted state path (e.g. 'user.name'). */
@@ -15,6 +15,18 @@ interface _mutationRecord {
   previousValue: any
   /** Epoch timestamp (ms) when the mutation occurred. */
   timestamp: number
+  /** Unique mutation ID (Memorio 5). */
+  id?: string
+  /** Normalized operation type (Memorio 5). */
+  operation?: 'set' | 'delete' | 'insert' | 'remove' | 'replace' | 'length'
+  /** HLC timestamp string for causal ordering (Memorio 5). */
+  hlc?: string
+  /** Context ID for server-side isolation (Memorio 5). */
+  context?: string
+  /** Source attribution (Memorio 5). */
+  source?: string
+  /** Transaction group ID (Memorio 5). */
+  transactionId?: string
 }
 
 ///

package/types/memorio.d.ts

@@ -20,7 +20,7 @@ import type {
 
 interface _dispatch {
   set: (name: string, value?: any) => void
-   listen: (name: string, cb?: ((e: Event) => void) | null, flag?: boolean) => (() => void) | void
+  listen: (name: string, cb?: ((e: Event) => void) | null, flag?: boolean) => (() => void) | void
   remove: (name: string, cb?: any, flag?: boolean) => void
 }
 
@@ -47,6 +47,7 @@ interface _memorio {
   isBrowser: () => boolean
   isNode: () => boolean
   isDeno: () => boolean
+  isBun: () => boolean
   isEdge: () => boolean
   getCapabilities: (...args: unknown[]) => any
   // Platform properties
@@ -55,25 +56,27 @@ interface _memorio {
   _sessionId?: string
   _currentContext?: string
   // Context management (for server-side isolation)
-  createContext?: (name?: string) => {
+  createContext?: (name?: string, opts?: { encryptionKey?: any }) => {
     id: string
     state: any
     store: any
     session: any
     cache: any
+    encryptionKey?: any
   }
   listContexts?: () => string[]
   deleteContext?: (id: string) => boolean
-  isolate?: (name?: string) => {
+  isolate?: (name?: string, opts?: { encryptionKey?: any }) => {
     id: string
     state: any
     store: any
     session: any
     cache: any
+    encryptionKey?: any
   }
-   help?: () => void
-   global?: () => void
-   env?: { isDev: boolean; isProd: boolean }
+  help?: () => void
+  global?: () => void
+  env?: { isDev: boolean; isProd: boolean }
   // Schema validation
   registerSchema?: (path: string, schema: any) => void
   validate?: (path: string, value: any) => { valid: boolean; errors?: string[] }
@@ -93,6 +96,15 @@ interface _memorio {
   enableHistory?: (enabled?: boolean) => void
   clearHistory?: () => void
   clearRedo?: () => void
+  // Mutation Engine (Memorio 5)
+  mutate?: (path: string, value: any, opts?: { source?: string; transactionId?: string }) => _mutation
+  createMutation?: (path: string, operation: _operation, before: any, after: any, opts?: { context?: string; source?: string; transactionId?: string }) => _mutation
+  recordMutation?: (mutation: _mutation) => void
+  toPatch?: (mutation: _mutation) => _patch | null
+  transaction?: (source?: string, message?: string, metadata?: Record<string, any>) => _transaction
+  commitTransaction?: () => _transaction | null
+  abortTransaction?: () => _transaction | null
+  currentTransaction?: () => _transaction | null
   // Introspection
   stateKeys?: () => string[]
   pathExists?: (path: string) => boolean
@@ -100,6 +112,10 @@ interface _memorio {
   stateGet?: (path: string) => any
   stateSchema?: () => Array<{ path: string; type: string; defined: boolean }>
   memory?: MemoryAPI
+  encryption?: _encryption
+  computed?: _computed
+  broadcast?: _broadcast
+  security?: _security
   // 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
@@ -166,4 +182,7 @@ interface globalThis {
   [key: string]: any
 }
 
+declare var memorio: memorio
+type memorio = memorio
+
 export { }

package/types/mutation.d.ts

@@ -0,0 +1,75 @@
+/// MEMORIO MUTATION ENGINE TYPES
+/// Ambient declarations for the Memorio 5 mutation pipeline.
+
+///
+// Normalized mutation operations.
+///
+type _operation = 'set' | 'delete' | 'insert' | 'remove' | 'replace' | 'length'
+
+///
+// RFC 6902 patch operations.
+///
+type _patchOp = 'replace' | 'remove' | 'add' | 'test'
+
+///
+// A single mutation as recorded by the engine (extends MutationRecord).
+///
+interface _mutation {
+  id: string
+  path: string
+  operation: _operation
+  after: any
+  before: any
+  timestamp: number
+  hlc: string
+  context?: string
+  source?: string
+  transactionId?: string
+  action?: 'set' | 'delete'
+  newValue?: any
+  previousValue?: any
+}
+
+///
+// Compact patch representation.
+///
+interface _patch {
+  op: _patchOp
+  path: string
+  value?: any
+  oldValue?: any
+}
+
+///
+// A transaction grouping related mutations.
+///
+interface _transaction {
+  id: string
+  mutations: string[]
+  startedAt: string
+  committedAt?: string
+  source?: string
+  message?: string
+  metadata?: Record<string, any>
+}
+
+///
+// A commit - immutable record of a logical state change.
+///
+interface _commit {
+  id: string
+  parent: string | null
+  timestamp: string
+  patches: _patch[]
+  source?: string
+  message?: string
+  metadata?: Record<string, any>
+}
+
+///
+// Options for explicit mutation.
+///
+interface _mutateOptions {
+  source?: string
+  transactionId?: string
+}