memorio 4.7.1 → 4.7.3

package/markdown/TYPED.md

@@ -0,0 +1,158 @@
+# Typed Stores - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+`memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, giving you **compile-time** type safety on every access and mutation.
+
+It's a **zero-runtime-cost** wrapper: the returned object is the *exact same* Proxy as `globalThis.state`, just with TypeScript types applied via a generic.
+
+---
+
+## Quick Start
+
+```typescript
+import 'memorio'
+
+interface AppState {
+  user: { name: string; age: number; email: string }
+  theme: 'light' | 'dark'
+  items: string[]
+}
+
+const app = memorio.typed<AppState>()
+
+// Type-checked at compile time:
+app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.theme = 'dark'
+
+// TypeScript errors:
+// app.user = { name: 42 }            // age missing, name wrong type
+// app.theme = 'purple'               // not a valid literal
+```
+
+---
+
+## Why use typed stores?
+
+| Without typed | With `memorio.typed<T>()` |
+|---|---|
+| `state.user = { name: 42 }` — runs silently, bug at runtime | `app.user = { name: 42 }` — TypeScript error at compile time |
+| No autocomplete on `state.user.email` | Full IntelliSense: properties, types, method suggestions |
+| Rename `user` to `profile` — no compiler warning anywhere | Every `app.user` access flagged as an error |
+| AI-generated code lacks guardrails | AI gets autocomplete and type feedback inline |
+
+---
+
+## Combine with Schema Validation
+
+Typed stores catch type errors at compile time; schema validation catches invalid values at runtime. Together they form a **defense-in-depth** strategy:
+
+```typescript
+import 'memorio'
+
+interface ProfileState {
+  profile: { bio: string; avatar?: string }
+}
+
+const app = memorio.typed<ProfileState>()
+
+memorio.registerSchema('profile', {
+  type: 'object',
+  required: ['bio'],
+  properties: {
+    bio: { type: 'string', min: 1 },
+    avatar: { type: 'string' }
+  }
+})
+
+app.profile = { bio: 'Developer', avatar: 'pic.png' } // ✅ type + schema pass
+app.profile = { avatar: 'pic.png' }                  // ❌ TypeScript: bio missing
+                                                     // ❌ Runtime: bio required
+```
+
+See [Schema Validation](SCHEMA.md) for runtime validation details.
+
+---
+
+## Named import variant
+
+`typed` is also available as a named export if you prefer explicit dependencies:
+
+```typescript
+import { typed } from 'memorio'
+
+const app = typed<AppState>()
+```
+
+The `memorio` namespace object is the same — `import 'memorio'` is the recommended entry, named exports are an alternative.
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.typed<T>()` | Generic type `T` | `T` | Returns the global `state` proxy cast to `T` |
+
+The returned object shares the same identity as `globalThis.state`:
+
+```typescript
+const app = memorio.typed<AppState>()
+console.debug(app === state) // true — same Proxy instance
+```
+
+---
+
+## React + typed stores
+
+Pair with the `useObserver` hook for type-safe, reactive React components:
+
+```tsx
+import 'memorio'
+import { useReducer } from 'react'
+
+interface AppState {
+  user: { name: string; age: number }
+  theme: 'light' | 'dark'
+}
+
+const app = memorio.typed<AppState>()
+
+function UserProfile() {
+  const [, forceUpdate] = useReducer(x => x + 1, 0)
+
+  useObserver(forceUpdate, [state.user.name])
+
+  return (
+    <div>
+      <h1>{app.user.name}</h1>
+      <span>Theme: {app.theme}</span>
+    </div>
+  )
+}
+```
+
+---
+
+## Best Practices
+
+1. **Define your AppState at the root** of your app and import it everywhere:
+
+   ```typescript
+   // types/app-state.ts
+   export interface AppState {
+     user: { name: string; email: string }
+     theme: 'light' | 'dark'
+   }
+   ```
+
+   ```typescript
+   // anywhere in your app
+   import 'memorio'
+   import type { AppState } from '../types/app-state'
+   const app = memorio.typed<AppState>()
+   ```
+
+2. **Layer schema validation on top** for runtime safety, especially for data coming from APIs or user input.
+
+3. **Use alongside `memorio.help()`** to list available globals during development.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorio",
   "codeName": "memorio",
-  "version": "4.7.1",
+  "version": "4.7.3",
   "description": "Memorio, State + Observer, Store and iDB for an easy life - Cross-platform compatible",
   "main": "./index.cjs",
   "browser": "./index.js",
@@ -52,15 +52,15 @@
     "markdown/**/*",
     "types/**/*",
     "COPYRIGHT.md",
-    "index.d.ts",
-    "index.cjs",
-    "index.js",
-    "LICENSE.md",
-    "llms.txt",
     "README.md",
     "FUNDING.yml",
     "SECURITY.md",
-    "SUMMARY.md"
+    "SUMMARY.md",
+    "LICENSE.md",
+    "index.d.ts",
+    "index.cjs",
+    "index.js",
+    "llms.txt"
   ],
   "publishConfig": {
     "access": "public"

package/types/exports.d.ts

@@ -8,6 +8,9 @@
  * @see index.ts (runtime re-export)
  */
 
+/// <reference path="./schema.d.ts" />
+/// <reference path="./history.d.ts" />
+/// <reference path="./inspect.d.ts" />
 /// <reference path="./memorio.d.ts" />
 /// <reference path="./state.d.ts" />
 /// <reference path="./store.d.ts" />
@@ -40,6 +43,28 @@ export const isolate: _memorio['isolate']
 export const message: (...args: unknown[]) => void
 export const help: () => void
 
+export const registerSchema: (path: string, schema: any) => void
+export const validate: (path: string, value: any) => { valid: boolean; errors?: string[] }
+export const unregisterSchema: (path: string) => boolean
+export const listSchemas: () => string[]
+export const typed: <T extends Record<string, any>>() => T
+export const snapshot: () => Record<string, any>
+export const diff: (snap: Record<string, any>) => Array<{ path: string; oldValue: any; newValue: any }>
+export const undo: () => any
+export const redo: () => any
+export const canUndo: () => boolean
+export const canRedo: () => boolean
+export const rollback: (snap: Record<string, any>) => void
+export const trace: () => any[]
+export const enableHistory: (enabled?: boolean) => void
+export const clearHistory: () => void
+export const clearRedo: () => void
+export const stateKeys: () => string[]
+export const pathExists: (path: string) => boolean
+export const stateType: (path: string) => string
+export const stateGet: (path: string) => any
+export const stateSchema: () => Array<{ path: string; type: string; defined: boolean }>
+
 export const propertyName: (container: any, object: any) => string | null
 export const internal: {
   debug: boolean

package/types/history.d.ts

@@ -0,0 +1,27 @@
+/// MEMORIO HISTORY TYPES
+/// Ambient declarations for the snapshot / undo / redo / trace API.
+
+///
+// A single recorded state mutation.
+///
+interface _mutationRecord {
+  /** Dotted state path (e.g. 'user.name'). */
+  path: string
+  /** 'set' or 'delete'. */
+  action: 'set' | 'delete'
+  /** The new value written (for 'set'), undefined for 'delete'. */
+  newValue: any
+  /** The previous value before the mutation. */
+  previousValue: any
+  /** Epoch timestamp (ms) when the mutation occurred. */
+  timestamp: number
+}
+
+///
+// Result of diffing a snapshot against current state.
+///
+interface _diffEntry {
+  path: string
+  oldValue: any
+  newValue: any
+}

package/types/inspect.d.ts

@@ -0,0 +1,14 @@
+/// MEMORIO INSPECT TYPES
+/// Ambient declarations for the state introspection API.
+
+///
+// Schema report entry describing a single state path.
+///
+interface _stateSchemaEntry {
+  /** Dotted path relative to `state`. */
+  path: string
+  /** Runtime type: 'string', 'number', 'boolean', 'object', 'array', 'undefined'. */
+  type: string
+  /** Whether the path resolves to a defined value. */
+  defined: boolean
+}

package/types/memorio.d.ts

@@ -1,3 +1,12 @@
+import type {
+  MemoryEntry,
+  RememberOptions,
+  RecallOptions,
+  ContextOptions,
+  ContextEntry,
+  MemoryStats
+} from './memory'
+
 /**
  * Environment capabilities
  */
@@ -60,10 +69,47 @@ interface _memorio {
     session: any
     cache: any
   }
-  help?: () => void
+   help?: () => void
+   // Schema validation
+  registerSchema?: (path: string, schema: any) => void
+  validate?: (path: string, value: any) => { valid: boolean; errors?: string[] }
+  unregisterSchema?: (path: string) => boolean
+  listSchemas?: () => string[]
+  // Typed store
+  typed?: <T extends Record<string, any>>() => T
+  // History / snapshot / undo / redo / trace
+  snapshot?: () => Record<string, any>
+  diff?: (snap: Record<string, any>) => Array<{ path: string; oldValue: any; newValue: any }>
+  undo?: () => _mutationRecord | undefined
+  redo?: () => _mutationRecord | undefined
+  canUndo?: () => boolean
+  canRedo?: () => boolean
+  rollback?: (snap: Record<string, any>) => void
+  trace?: () => _mutationRecord[]
+  enableHistory?: (enabled?: boolean) => void
+  clearHistory?: () => void
+  clearRedo?: () => void
+  // Introspection
+  stateKeys?: () => string[]
+  pathExists?: (path: string) => boolean
+  stateType?: (path: string) => string
+  stateGet?: (path: string) => any
+  stateSchema?: () => Array<{ path: string; type: string; defined: boolean }>
+  memory?: MemoryAPI
+}
+
+interface MemoryAPI {
+  remember<T>(key: string, value: T, opts?: RememberOptions<T>): Promise<void>
+  recall<T>(query: string, opts?: RecallOptions): Promise<T | null>
+  update(key: string, value: any, opts?: Partial<RememberOptions>): Promise<void>
+  forget(key: string): Promise<void>
+  context(opts?: ContextOptions): Promise<ContextEntry[]>
+  stats(): Promise<MemoryStats>
+  forgetExpired(): Promise<number>
+  clear(): Promise<void>
 }
 
-type memorio = _memorio
+type memorio = _memorio
 declare var memorio: _memorio
 
 interface GlobalMemorio {

package/types/memory.d.ts

@@ -0,0 +1,70 @@
+export type MemoryScope = 'hot' | 'session' | 'local' | 'durable'
+
+export type MemoryType =
+  | 'fact'
+  | 'preference'
+  | 'decision'
+  | 'task'
+  | 'context'
+
+export type MemoryStatus = 'active' | 'obsolete' | 'superseded'
+
+export interface MemoryEntry<T = any> {
+  id: string
+  key: string
+  value: T
+  type: MemoryType
+  confidence: number
+  scope: MemoryScope
+  ttl?: number | null
+  tags: string[]
+  source?: string
+  status: MemoryStatus
+  createdAt: number
+  lastConfirmedAt: number
+  supersededId?: string | null
+}
+
+export interface RememberOptions<T = any> {
+  id?: string
+  type?: MemoryType
+  confidence?: number
+  scope?: MemoryScope
+  ttl?: number | null
+  tags?: string | string[]
+  source?: string
+}
+
+export interface RecallOptions {
+  type?: MemoryType | MemoryType[]
+  tags?: string | string[]
+  minConfidence?: number
+  includeObsolete?: boolean
+}
+
+export interface ContextOptions {
+  tags?: string | string[]
+  types?: MemoryType | MemoryType[]
+  minConfidence?: number
+  maxEntries?: number
+  scopes?: MemoryScope[]
+}
+
+export interface ContextEntry {
+  key: string
+  value: any
+  type: MemoryType
+  confidence: number
+  scope: MemoryScope
+  tags: string[]
+  age: number
+  accessCount: number
+  lastAccessedAt: number
+}
+
+export interface MemoryStats {
+  total: number
+  byScope: Record<MemoryScope, number>
+  byType: Partial<Record<MemoryType, number>>
+  expired: number
+}

package/types/schema.d.ts

@@ -0,0 +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