@nanocollective/json-up

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:

• Getting Started
• API Reference
• Error Handling
• Examples
• Community

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.