memorio 5.0.0 → 5.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorio",
   "codeName": "memorio",
-  "version": "5.0.0",
+  "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,9 +59,12 @@
     }
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0",
+    "bun": ">=1.4.0"
   },
   "files": [
+    "bin",
+    "vsix",
     "markdown/**/*",
     "types/**/*",
     "examples/**/*",

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/exports.d.ts

@@ -21,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
@@ -31,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>
 
@@ -59,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']

package/types/memorio.d.ts

@@ -47,6 +47,7 @@ interface _memorio {
   isBrowser: () => boolean
   isNode: () => boolean
   isDeno: () => boolean
+  isBun: () => boolean
   isEdge: () => boolean
   getCapabilities: (...args: unknown[]) => any
   // Platform properties
@@ -55,21 +56,23 @@ 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
@@ -92,16 +95,16 @@ interface _memorio {
   trace?: () => _mutationRecord[]
   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
+  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
@@ -109,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

package/types/security.d.ts

@@ -0,0 +1,67 @@
+/*!
+  memorio
+  Copyright (c) 2025 Dario Passariello <dariopassariello@gmail.com>
+  Licensed under MIT License, see
+  dario.passariello.ca
+*/
+
+type Permission = 'read' | 'write' | 'delete' | 'admin'
+
+interface AccessRule {
+  pattern: string | ((key: string, userId?: string) => boolean)
+  permissions: Permission[]
+}
+
+type AccessRulesMap = Map<string | ((key: string, userId?: string) => boolean), Permission[]>
+
+interface AuditEntry {
+  timestamp: number
+  action: 'set' | 'get' | 'delete' | 'hydrate' | 'remove' | 'clearAll'
+  key: string
+  userId?: string
+  success: boolean
+  error?: string
+}
+
+interface ConsentRecord {
+  id: string
+  purpose: string
+  granted: boolean
+  timestamp: number
+}
+
+type ConsentsMap = Map<string, ConsentRecord[]>
+
+interface _security {
+  safeRandomUUID: () => string
+  safeRegexTest: (pattern: string, key: string) => boolean
+
+  addAccessRule: (rules: AccessRulesMap, pattern: string | ((key: string, userId?: string) => boolean), perms: Permission[]) => AccessRulesMap
+  hasPermission: (rules: AccessRulesMap, key: string, action: Permission, userId?: string) => boolean
+
+  isAuditActive: () => boolean
+  setAuditLogger: (logger: (entry: AuditEntry) => void) => void
+  logAudit: (entry: Partial<AuditEntry>) => void
+
+  sanitizeValue: (value: unknown) => unknown
+  validateKey: (key: string) => boolean
+
+  recordConsent: (consents: ConsentsMap, userId: string, purpose: string, granted: boolean) => ConsentRecord
+  hasConsent: (consents: ConsentsMap, userId: string, purpose: string) => boolean
+  revokeConsent: (consents: ConsentsMap, userId: string, purpose: string) => ConsentRecord | null
+  getConsents: (consents: ConsentsMap, userId: string) => ConsentRecord[]
+  exportUserData: (consents: ConsentsMap, userId: string) => { userId: string; exportedAt: number; consents: ConsentRecord[] }
+  deleteUserData: (consents: ConsentsMap, userId: string) => { success: boolean; deletedConsents: number }
+}
+
+declare var security: _security
+type security = _security
+
+export {
+  Permission,
+  AccessRule,
+  AccessRulesMap,
+  AuditEntry,
+  ConsentRecord,
+  ConsentsMap
+}

package/types/session.d.ts

@@ -10,24 +10,42 @@ interface _session {
     *
     * @example
     * session.set("test","example") // or Array, Object, Number, Functions...
+    * session.set("test", value, { encrypt: key })  // encrypt at rest
     *
     * @since memorio 0.0.1
     * @param name The String as name to define the session.
     * @param param The information taht you want to session (Any).
-    * @return boolean
-  */
-  set: (name: string, value: any) => void
+    * @param opts Optional { encrypt: key } to encrypt before storage.
+    * @return boolean | Promise<boolean>
+    */
+  set: (name: string, value: any, opts?: { encrypt?: any }) => boolean | Promise<boolean>
+
+  /**
+     * Configure session-wide behavior.
+     *
+     * @example
+     * session.config({ encryptionKey: derivedKey })
+     * session.config({ onError: (err, ctx) => console.error(err, ctx) })
+     * session.config({ maxObjectSize: 5 * 1024 * 1024 })
+     * session.config({ maxTotalSize: 50 * 1024 * 1024 })
+     *
+     * @since memorio 5.0
+     * @param opts { encryptionKey, onError, maxObjectSize, maxTotalSize }
+     */
+   config: (opts: { encryptionKey?: any; onError?: (err: unknown, ctx: { operation: string }) => void; maxObjectSize?: number; maxTotalSize?: number }) => void
 
   /**
     * Have back the data from a session.
     *
     * @example
     * session.get("test")
+    * session.get("test", { decrypt: key })  // decrypt an encrypted envelope
     *
     * @since memorio 0.0.1
     * @param name The String as name to define the session.
-  */
-  get: (name: string) => any
+    * @param opts Optional { decrypt: key } to decrypt an encrypted envelope.
+    */
+  get: (name: string, opts?: { decrypt?: any }) => any
 
   /**
     * Delete an existing session:

package/types/store.d.ts

@@ -14,18 +14,34 @@ interface _store {
      * @param value The information you want to store. Functions are blocked for security.
      * @return void
      */
-  set: (name: string, value: any) => void
+   set: (name: string, value: any, opts?: { encrypt?: any }) => boolean | Promise<boolean>
+  
+  /**
+    * Configure store-wide behavior.
+    *
+    * @example
+    * store.config({ encryptionKey: derivedKey })
+    * store.config({ onError: (err, ctx) => console.error(err, ctx) })
+    * store.config({ maxObjectSize: 5 * 1024 * 1024 })
+    * store.config({ maxTotalSize: 50 * 1024 * 1024 })
+    *
+    * @since memorio 5.0
+    * @param opts { encryptionKey, onError, maxObjectSize, maxTotalSize }
+   */
+  config: (opts: { encryptionKey?: any; onError?: (err: unknown, ctx: { operation: string }) => void; maxObjectSize?: number; maxTotalSize?: number }) => void
 
   /**
-    * Have back the data from a store.
+    * Gets a value from storage.
     *
     * @example
     * store.get("test")
+    * store.get("test", { decrypt: key })  // decrypt an encrypted envelope
     *
     * @since memorio 0.0.1
     * @param name The String as name to define the store.
+    * @param opts Optional { decrypt: key } to decrypt an encrypted envelope.
   */
-  get: (name: string) => any
+  get: (name: string, opts?: { decrypt?: any }) => any
 
   /**
     * Delete an existing store: