json-up

A fast, type-safe JSON migration tool with Zod schema validation.

Features

• Type-safe migrations for JSON with full TypeScript inference
• Zod schema validation at every step
• Fluent builder API for migration chains
• Async migration support for migrations that need async operations
• Automatic version tracking
• Zero runtime dependencies (only Zod as peer)

Installation

npm install @nanocollective/json-up zod

Quick Start

import { createMigrations, migrate } from "@nanocollective/json-up";
import { z } from "zod";

const migrations = createMigrations()
  .add({
    version: 1,
    schema: z.object({ name: z.string() }),
    up: (data) => ({ name: data.name ?? "Unknown" }),
  })
  .add({
    version: 2,
    schema: z.object({ firstName: z.string(), lastName: z.string() }),
    up: (data) => {
      const [firstName = "", lastName = ""] = data.name.split(" ");
      return { firstName, lastName };
    },
  })
  .build();

const result = migrate({
  state: { _version: 1, name: "Jane Doe" },
  migrations,
});

console.log(result);
// { _version: 2, firstName: "Jane", lastName: "Doe" }

Async migrations

When your migrations need to perform async operations, use the async API:

import { createAsyncMigrations, migrateAsync } from "@nanocollective/json-up";
import { z } from "zod";

const migrations = createAsyncMigrations()
  .add({
    version: 1,
    schema: z.object({ name: z.string() }),
    up: (data) => ({ name: data.name ?? "" }),
  })
  .add({
    version: 2,
    schema: z.object({ name: z.string(), key: z.string() }),
    up: async (data) => ({
      name: data.name,
      key: await generateKey(),
    }),
  })
  .build();

const result = await migrateAsync({ state, migrations });

Documentation

For full documentation, see docs/index.md:

• Getting Started
• API Reference
• Error Handling
• Examples

Community

We're a small community-led team building local and privacy-first AI solutions under the Nano Collective.

• Contributing Guide
• Discord Server
• GitHub Issues