yuppee

library1.0.0jsnpmunverified

yuppee v1.0.0 is a lightweight, zero-dependency migration utility for migrating JSON objects between schema versions. It provides type-safe migrations using TypeScript generics, allowing developers to define incremental migrations from one version to the next. The library is designed for small state or settings objects stored as JSON, and is suitable for Node.js environments (requires Node >=22). Unlike heavier migration tools for databases, yuppee focuses on client-side or edge-case schema evolution with minimal overhead. It ships with TypeScript definitions and is ESM-only.

storage

npm install yuppee

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · YUPPEE

yuppee

storagejavascriptv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createMigrator

✓ import { createMigrator } from 'yuppee'

✗ const { createMigrator } = require('yuppee')

yuppee is ESM-only and does not support CommonJS require(). Use import statements.

createMigration

✓ import { createMigration } from 'yuppee'

✗ const createMigration = require('yuppee').createMigration

Named import only; no default export.

MigrationDefinition

✓ import type { MigrationDefinition } from 'yuppee'

Type imports should use 'import type' for better tree-shaking in TypeScript.

default

✓ import yuppee from 'yuppee'

✗ const yuppee = require('yuppee')

There is no default export; this import would yield undefined. Use named imports.

Shows how to create a type-safe migration chain from version 1 to 3 using createMigrator and createMigration.

import { createMigration, createMigrator } from 'yuppee'; type StateV1 = { version: 1; name?: string }; type StateV2 = { version: 2; names: string[] }; type StateV3 = { version: 3; data: { names: string[] } }; type State = StateV3; const migrate = createMigrator<State, StateV1 | StateV2>({ init: () => ({ name: 'baz' }), migrations: [ createMigration<StateV1, StateV2>({ from: 1, to: 2, migrate: (state) => ({ names: state.name ? [state.name] : [] }), }), createMigration<StateV2, StateV3>({ from: 2, to: 3, migrate: (state) => ({ data: { names: state.names } }), }), ], }); console.log(migrate()); // { version: 3, data: { names: ['baz'] } } console.log(migrate({ version: 1, name: 'foo' })); // { version: 3, data: { names: ['foo'] } }

Debug

Known issues

breakingRequires Node >=22 (engines field in package.json).

fix

Upgrade Node.js to version 22 or later.

affects: >=1.0.0

gotchaNo CommonJS support; ESM-only package. Using require() will fail.

fix

Use import statements and ensure your project is configured for ESM (e.g., type: 'module' in package.json).

affects: >=1.0.0

gotchaThe init function is required even if you always provide a starting state; it is used when no input is given to migrate().

fix

Provide an init function that returns a valid state for the earliest version.

affects: >=1.0.0

gotchaMigration from and to versions must be consecutive; gaps or duplicate version numbers cause undefined behavior.

fix

Ensure migrations form a linear chain: 1->2, 2->3, etc.

affects: >=1.0.0

gotchaTypeScript generics require careful alignment: the second type parameter to createMigrator must be a union of all possible input state types.

fix

Define a union type of all versions that can be passed to migrate().

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported.

Attempting to use require() to load yuppee, which is ESM-only.

fix

Use import instead: import { createMigrator } from 'yuppee';

TypeScript error: Type 'StateV1' is not assignable to type 'StateV2'.

Incorrect type arguments in createMigrator or createMigration.

fix

Ensure the generic types match the actual migration chain: the output of one migration must be compatible with the input of the next.

TypeError: migrate is not a function

Forgot to call createMigrator; assigned result of createMigrator (which returns a function) incorrectly.

fix

const migrate = createMigrator(...); then call migrate(state).

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/simonwep/yuppee ↗

packageyuppee ↗

homepagehttps://github.com/simonwep/yuppee#readme ↗