typedstash

Typed JSON storage for app config, CLI state, and small local data stores.

typedstash writes one JSON file, validates data with zod, and migrates data with per-store numeric versions. It is a new package API, not a compatibility layer for conf.

Install

bun add typedstash zod

Schema

import Store from 'typedstash';
import {z} from 'zod';

const store = new Store({
	projectName: 'my-app',
	schema: z.object({
		volume: z.number().min(0).max(100).default(50),
		endpoint: z.string().url().optional(),
	}),
});

store.get('volume');
//=> 50

store.set('volume', 101);
//=> Error: Config schema violation

Zod required fields without .default() or .optional() must already exist in the config file, otherwise the initial load fails with a schema violation.

Migrations

schemas.length is the current data-format version. migrations[i] transforms data from version i + 1 to i + 2.

import Store from 'typedstash';
import {z} from 'zod';

const v1 = z.object({
	name: z.string(),
});

const v2 = z.object({
	name: z.string().default(''),
	count: z.number().default(0),
});

const store = new Store({
	projectName: 'my-app',
	schemas: [v1, v2] as const,
	migrations: [
		data => ({...data, count: 0}),
	],
});

store.get('count');
//=> 0

Each migration is a pure function. typedstash validates each result with the target zod schema and writes a checkpoint only after that step succeeds.

Reserved Field

__version at the top level of the config file is reserved and managed by typedstash. Do not use it in your zod schema or public writes.

__internal__ has no special meaning in typedstash and is treated as normal user data.

Tests

bun test
bun run test:e2e
bun run typecheck
bun run build
bun run publish:check

bun run test:e2e builds the package and imports typedstash through the package export, so it catches packaging/export issues that source-level tests cannot. bun run publish:check builds the package and runs publint --pack bun against the files that would be published.

License

MIT. Includes code derived from sindresorhus/conf; see LICENSE.