Nano-Collective/json-up

README

json-up

A fast, type-safe JSON migration tool with Zod schema validation — built by the Nano Collective, a community collective building AI tooling not for profit, but for the community. Everything we build is open, transparent, and driven by the people who use it.

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:

Community

The Nano Collective is a community collective building AI tooling for the community, not for profit. We'd love your help.

Contribute: See CONTRIBUTING.md for development setup and guidelines.
The collective: nanocollective.org · docs · GitHub · Discord
Support the work: The Support page covers donations and sponsorship.
Paid contribution: The Economics Charter sets out how scoped paid bounties work.