> **Status:** Published
> **Date:** 2026-09-12
> **Scope**: API Reference
> **Standard**: Memorio API Specification v5
>
---
# 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, state, typed } from 'memorio'
import { useObserver } from 'memorio/react'

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, state } from '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 across both usage styles - named imports and the `memorio/global` entrypoint share the same runtime instances.

---

## 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, state } from 'memorio'
import { useObserver } from 'memorio/react'
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 } from '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()`** (via `import 'memorio/global'`) to list available globals during development.
