GitHub - Nano-Collective/json-up: TypeScript JSON migration tool with Zod schema validation

2 min read Original article ↗

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.

Build Status Coverage Version NPM Downloads NPM License Repo Size Stars Forks

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.