# Usage

This page demonstrates practical usage patterns for the transient memory module.

## Creating a Store

Use the `useTmem` factory function to create a named store with optional initial data:

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

// Create a store named "userPrefs" with initial values
const prefs = useTmem("userPrefs", {
    theme: "dark",
    language: "en",
    fontSize: 14,
});
```

The `initial` object is only written if the store is currently empty (i.e., `keys()` returns zero entries). Subsequent calls to `init()` will not overwrite existing data.

## Initialization

Always call `init()` before performing any read or write operations:

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

`init()` does the following:
1. Waits for the underlying IndexedDB instance to be ready via `localForage.ready()`.
2. If the store is empty, populates it with the `initial` data provided at creation time.
3. Logs a message to `console` if `verbose` was set to `true`.

## Verbose Mode

Enable logging during initialization:

```typescript
const prefs = useTmem("userPrefs", { theme: "dark" }, true);
await prefs.init();
// Console: Tmem: setting initial data for store userPrefs
```

## Reading and Writing

All read and write operations are asynchronous. Use `await` with every call:

```typescript
// Write
await prefs.set("theme", "light");

// Read (throws if key is missing)
const theme = await prefs.get("theme");
console.log(theme); // "light"

// Get all values at once
const allPrefs = await prefs.all();
console.log(allPrefs);
// { theme: "light", language: "en", fontSize: 14 }
```

### Type Inference

The `get()` and `set()` methods use TypeScript generics to infer types from the store's key definitions:

```typescript
const store = useTmem("data", { count: 0, name: "test" });

// Types are inferred from the initial object
const count = await store.get("count");    // inferred as number
const name = await store.get("name");      // inferred as string

await store.set("count", 42);              // value must be number
await store.set("name", "updated");        // value must be string
```

## Error Handling

The `get()` method throws an `Error` when the requested key does not exist:

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

## Deleting Keys

Remove a single key from the store:

```typescript
await prefs.del("fontSize");
```

## Accessing the Underlying localForage Instance

The returned `Tmem` object exposes the `db` property, which is the underlying `localForage` instance. Use it for advanced operations not covered by the `Tmem` interface:

```typescript
// Clear the entire store
await prefs.db.clear();

// Iterate over all items
await prefs.db.iterate((value, key) => {
    console.log(key, value);
});
```

## Complete Example

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

async function main() {
    // 1. Create and initialize
    const store = useTmem("appState", { version: 1, tokens: [] });
    await store.init();

    // 2. Write values
    await store.set("version", 2);
    await store.set("tokens", ["abc", "def"]);

    // 3. Read values (types inferred from keys)
    const version = await store.get("version");
    const tokens = await store.get("tokens");
    console.log(`Version: ${version}, Tokens: ${tokens.join(", ")}`);

    // 4. List all keys
    const keys = await store.keys();
    console.log("Keys:", keys); // ["version", "tokens"]

    // 5. Get everything
    const allData = await store.all();
    console.log(allData);
}

main();
```

<a href="javascript:openLink('/libraries/transient_memory/api')">Next: API Reference</a>