---
title: "@henryqw/pi-config-store"
seo:
  description: "Safe JSON configuration storage for Pi extensions."
---

<div class="not-prose my-6 flex flex-wrap items-center gap-3"><a href="https://www.npmjs.com/package/@henryqw/pi-config-store" aria-label="View @henryqw/pi-config-store version v1.0.4 on npm"><img alt="Version v1.0.4" height="20" src="https://img.shields.io/static/v1?cacheSeconds=7200&amp;color=1d4ed8&amp;label=version&amp;labelColor=6a7282&amp;style=flat-square&amp;message=v1.0.4" width="96"></a><div class="ml-auto flex flex-wrap items-center justify-end gap-3"><a href="https://www.npmjs.com/package/@henryqw/pi-config-store" aria-label="View @henryqw/pi-config-store on npm"><img alt="Monthly npm downloads" height="20" src="https://img.shields.io/npm/dm/%40henryqw%2Fpi-config-store?cacheSeconds=7200&amp;color=1d4ed8&amp;label=downloads&amp;labelColor=6a7282&amp;style=flat-square" width="144"></a><a href="https://github.com/HenryQW/pi-harness/blob/main/packages/pi-config-store/LICENSE" aria-label="View the MIT license for @henryqw/pi-config-store"><img alt="MIT license" height="20" src="https://img.shields.io/npm/l/%40henryqw%2Fpi-config-store?cacheSeconds=7200&amp;color=1d4ed8&amp;label=license&amp;labelColor=6a7282&amp;style=flat-square" width="78"></a></div></div>

Give extension authors one safe home for user-editable Pi extension JSON. Shared paths, validation, locking, and atomic writes avoid rebuilding storage behavior. End users do not install it directly in Pi.

## Install

```bash
npm install @henryqw/pi-config-store
```

Use your extension package's package manager. Do not run `pi install` for this library.

## Use

Create a JSON store with a default factory and an owner parser.

```ts
import {
  createConfigStore,
  extensionConfigDir,
  extensionConfigPath,
} from "@henryqw/pi-config-store";

type Config = { enabled: boolean };

const parseConfig = (value: unknown): Config => {
  if (
    typeof value !== "object" ||
    value === null ||
    !("enabled" in value) ||
    typeof value.enabled !== "boolean"
  ) {
    throw new Error("Invalid config");
  }
  return value as Config;
};

const home = extensionConfigDir("my-extension");
const path = extensionConfigPath("my-extension");

const store = createConfigStore({
  extensionId: "my-extension",
  defaults: () => ({ enabled: true }),
  parse: parseConfig,
});

const loaded = store.loadSync();
await store.save({ enabled: false });
const updated = await store.update((current) => ({
  ...current,
  enabled: !current.enabled,
}));
await store.remove();
```

`parseConfig` returns validated `Config` data or throws.

## API

| Surface | Type | Purpose |
| --- | --- | --- |
| `extensionConfigDir(extensionId, agentDir?)` | function | Returns an extension's config home. |
| `extensionConfigPath(extensionId, agentDir?)` | function | Returns the home’s `config.json` path. |
| `createConfigStore({ extensionId, agentDir?, defaults, parse })` | function | Creates a store. `defaults` is `() => T`; `parse` is `(value: unknown) => T`. |
| `store.path` | `string` | Gives the store's `config.json` path. |
| `store.loadSync()` | `{ source: 'file' \| 'missing'; value: T }` | Loads and validates the current value. |
| `store.save(value: T)` | `Promise<void>` | Validates and replaces the whole config under a lock. |
| `store.update(mutator: (current: T) => T)` | `Promise<T>` | Locks a read-modify-write operation and returns the updated value. |
| `store.remove()` | `Promise<void>` | Removes only the store's `config.json` file. |

By default, helpers use Pi's `getAgentDir()`. Pass `agentDir` to use another agent directory. Path helpers return paths without filesystem side effects.

For custom formats, call `extensionConfigDir(extensionId, agentDir?)`. Use the format's native library inside that directory.

Only the owning extension writes its config home. Consumers use the owner's API or namespaced Pi events. They do not read or write another extension's files directly.

## State and storage

- The config home is `getAgentDir()/config/<extension-id>/`.
- The default JSON file is `getAgentDir()/config/<extension-id>/config.json`.
- A valid file returns `{ source: 'file', value }` from `loadSync()`.
- A missing file returns `{ source: 'missing', value: defaults() }` without creating a file.

`save`, `update`, and `remove` are asynchronous. Every mutation uses a lock. Writes use a same-directory temporary file and atomic rename.

## Limits and recovery

An extension ID must be one lowercase path component. The helpers and store reject IDs with path separators or multiple components.

JSON reads and writes have a 64 KiB limit. UTF-8 decoding is strict. The `parse` function validates parsed `unknown` data. Values are validated before mutations are written.

A present malformed or schema-invalid file is not missing. Invalid UTF-8, oversized JSON, invalid JSON, and parser failures throw errors. Malformed and schema-invalid files remain unchanged.

Repository default: most extension owners may assume one active config writer. Under that assumption, reload the extension after a manual or external edit before its next write. A stale in-memory full replacement is outside the supported workflow.

`store.save(value)` locks and replaces the whole config. The lock serializes writes, but does not merge fields from stale values.

Use `store.update(mutator)` when an extension supports multiple processes, sessions, or writers. Use it also to preserve concurrent field changes. It reads the latest valid config under the store lock.