Gud JSON Store

A TypeScript-first JSON key-value store with Zod schema validation.

✨ Features

• Type-safe - Full TypeScript support with Zod schema validation
• File-based persistence - Automatically saves data to JSON files
• Schema validation - Ensure data integrity with Zod schemas
• Always up-to-date - Reads directly from file to ensure fresh data
• Auto-recovery - Backs up corrupted files and resets to defaults
• Simple API - Intuitive get/set interface with key-value operations
• Zero dependencies - Only requires Zod as a peer dependency
• Project-aware - Automatically detects project root for default storage

Installing

npm install @gud/json-store zod

Quick Start

import { JsonStore } from '@gud/json-store';
import { z } from 'zod';

// Create a simple store
const store = new JsonStore();

// Set some values
store.set('name', 'John Doe');
store.set('age', 30);

// Get values
const name = store.get('name'); // "John Doe"
const data = store.get('name', 'age'); // { name: "John Doe", age: 30 }

// With schema validation
const userSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email().optional(),
});

const userStore = new JsonStore({
  name: 'users',
  schema: userSchema,
  defaults: {
    name: '',
    age: 0,
  },
});

userStore.set('email', '[email protected]');

API Reference

JsonStore Class

Properties

• path: string - Full path to the JSON file
• schema: z.ZodObject - The Zod schema used for validation
• defaults: TData - Default values for the store

Methods

read(): TData

Read and return all data from the store.

set(key, value) / set(values)

Set a single key-value pair or multiple values at once.

store.set('key', 'value');
store.set({ key1: 'value1', key2: 'value2' });

get(key) / get(...keys)

Get a single value or multiple values by key(s).

const value = store.get('key');
const values = store.get('key1', 'key2'); // Returns object

has(...keys): boolean

Check if all specified keys exist in the store.

if (store.has('name', 'email')) {
  // Both keys exist
}

delete(...keys): void

Delete one or more keys from the store.

store.delete('key1', 'key2');

reset(): TData

Reset the store to its default values.

rm(): void

Delete the JSON file from disk.

getProjectRoot() Util

Get the path to the nearest app root directory, determined by the presence of a package.json file.

import { getProjectRoot } from '@gud/json-store';
import { join } from 'node:path';

const rootPath = getProjectRoot();
const packageJsonPath = join(rootPath, 'package.json');
console.log(`package.json path: ${packageJsonPath}`);

getOSConfigDir() Util

Get the path to an app specific config directory based on operating system standards.

import { getOSConfigDir } from '@gud/json-store';

const configDir = getOSConfigDir('app-name');
console.log(`Config directory: ${configDir}`);
// e.g. ~/Library/Application Support/app-name on macOS

Error Handling

JsonStore automatically handles common errors:

• Corrupted JSON: Creates a backup and resets to defaults
• Invalid schema: Throws validation errors with detailed messages
• Missing directories: Automatically creates parent directories
• Non-serializable values: Throws TypeError for functions, symbols, etc.

License

Apache-2.0