# API Reference

Complete API surface for `@agent-smith/tmem`.

## Factory Function: `useTmem`

```typescript
function useTmem<S extends Record<string, any> = Record<string, any>>(
    name: string,
    initial: S,
    verbose?: boolean
): Tmem<S>
```

Creates a new transient memory store.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `string` | The name of the localForage store instance. Determines the IndexedDB object store name. |
| `initial` | `S` (extends `Record<string, any>`) | An object containing initial key-value pairs. Written only if the store is empty. |
| `verbose` | `boolean` (optional) | If `true`, logs a message to `console` when initial data is populated. Default: `false`. |

### Return Value

Returns an object conforming to the `Tmem` interface (see below).

### Example

```typescript
import { useTmem } from "@agent-smith/tmem";

const store = useTmem("myStore", { key1: "value1", key2: 42 }, true);
```

## Interface: `Tmem<S>`

```typescript
interface Tmem<S extends Record<string, any>> {
    db: LocalForage;
    init(): Promise<void>;
    set<T extends keyof S>(k: T, v: S[T]): Promise<void>;
    get<T extends keyof S>(k: T): Promise<S[T]>;
    del<T extends keyof S>(k: T): Promise<void>;
    keys(): Promise<Array<string>>;
    all<T = any>(): Promise<Record<string, T>>;
}
```

All methods are **asynchronous** and return Promises.

### Property: `db`

| Property | Type | Description |
|----------|------|-------------|
| `db` | `LocalForage` | The underlying localForage instance. Use it for advanced operations like `clear()` or `iterate()`. |

### Method: `init()`

Initializes the store. Waits for IndexedDB readiness, then populates the store with the `initial` data if it is currently empty.

```typescript
await store.init();
```

### Method: `set<T extends keyof S>(k: T, v: S[T]): Promise<void>`

Stores a key-value pair in the IndexedDB object store. The type of `v` is inferred from the store's generic type `S`.

```typescript
await store.set("theme", "dark");
```

### Method: `get<T extends keyof S>(k: T): Promise<S[T]>`

Retrieves a value by key. The return type is inferred from the key's type in `S`. Throws an `Error` with message `"Key <key> not found"` if the key does not exist.

```typescript
const theme = await store.get("theme");
```

### Method: `del<T extends keyof S>(k: T): Promise<void>`

Removes a single key from the store.

```typescript
await store.del("theme");
```

### Method: `keys(): Promise<Array<string>>`

Returns an array of all keys currently stored.

```typescript
const keys = await store.keys();
console.log(keys); // ["key1", "key2"]
```

### Method: `all<T = any>(): Promise<Record<string, T>>`

Returns all key-value pairs as a plain object.

```typescript
const data = await store.all();
console.log(data); // { key1: "value1", key2: "value2" }
```

## Error Handling

The only method that throws is `get()`. If the requested key does not exist, it throws an `Error`:

```typescript
try {
    const value = await store.get("missing");
} catch (e) {
    console.error(e.message); // "Key missing not found"
}
```

All other methods (`init`, `set`, `del`, `keys`, `all`) do not throw — they resolve normally even if the store is empty.

## Method Summary Table

| Method | Signature | Returns | Async |
|--------|-----------|---------|-------|
| `init()` | `() => Promise<void>` | — | Yes |
| `set(k, v)` | `(k: keyof S, v: S[keyof S]) => Promise<void>` | — | Yes |
| `get(k)` | `(k: keyof S) => Promise<S[keyof S]>` | Inferred value type | Yes |
| `del(k)` | `(k: keyof S) => Promise<void>` | — | Yes |
| `keys()` | `() => Promise<string[]>` | Array of keys | Yes |
| `all()` | `() => Promise<Record<string, any>>` | Key-value object | Yes |

## Type Inference

The generic type parameter `<S>` on `useTmem()` enables TypeScript to infer types from your initial data:

```typescript
const store = useTmem("config", {
    count: 0,        // number
    name: "test",    // string
    enabled: true,   // boolean
});

// Types are automatically inferred
const count = await store.get("count");    // type: number
const name = await store.get("name");      // type: string

// Setting values also enforces types
await store.set("count", 42);              // OK
await store.set("count", "not a number"); // TypeScript error
```

<a href="javascript:openLink('/libraries/transient_memory/get_started')">Back: Get Started</a>