@marianmeres/migrate

A general-purpose extensible versioning framework for managing incremental, bi-directional changes.

Possible use cases may include:

• db migrations,
• undo/redo systems,
• progress change tracking,
• install/uninstall systems...

How does it work?

Under the hood it is essentially an ordered collection of up and down callback pairs labeled with a semantic version string (and every upgrade or downgrade is then a serial execution of the relevant up's or down's).

Installation

deno add jsr:@marianmeres/migrate

npm install @marianmeres/migrate

Usage

import { Migrate } from "@marianmeres/migrate";

Main API

const m = new Migrate(options?, context?);

// add available versions with migration functions
m.addVersion('1.2.3', upFn, downFn, optionalComment);

// register an irreversible (one-way) migration with `null` for down
m.addVersion('1.2.4', upFn, null, 'one-way');

// get/set the system's current version (initially undefined)
await m.setActiveVersion('7.8.9');
const current = await m.getActiveVersion();

// migrate up or down (returns number of applied steps)
await m.up('latest' | 'major' | 'minor' | 'patch' | version);
await m.down('initial' | 'major' | 'minor' | 'patch' | version);

// complete removal (downgrades past initial version)
await m.uninstall();

// inspect without mutating state
const plan = await m.plan('up', 'latest');     // { direction, fromVersion, toVersion, steps }
const status = await m.status();                // { active, latest, isAtLatest, pending }

// recovery helper — write the active-version marker without
// validating against the registered set (e.g. after a partial failure)
await m.forceSetActiveVersion('1.2.3');

Concurrent calls to up(), down() and uninstall() on the same Migrate instance are automatically serialized.

For complete API reference including all methods, types, and semver utilities, see API.md.

DB migrate implementation example

See deno script example. Can be run as, for example:

deno run example/db-migrate.ts --up --target=latest
deno run example/db-migrate.ts --down --target=1.1.0
deno run example/db-migrate.ts --uninstall

Basic progress tracking (pseudo) example

const db = []; // simulate external store
let sequence = 1;

//
const app = new Migrate();

// creates wrapper which will do some work, and save progress
const work = async (thing: string) => {
    // "up" (do the work)
    const up = () => {
        db.push(thing);
    };

    // "down" (revert the work)
    const down = () => {
        db.pop();
    };

    // do the work now
    await up();

    // save progress: add the version into internal stack
    const ver = app.addVersion(`${sequence++}`, up, down);

    // mark current version as active
    await app.setActiveVersion(ver);
};

//
await work("hey");  // 1.0.0 (this will become the "initial" version)
await work("ho");   // 2.0.0
await work("lets"); // 3.0.0
await work("go");   // 4.0.0

// check if the work was done
assertEquals(db, ["hey", "ho", "lets", "go"]);
assertEquals(await app.getActiveVersion(), "4.0.0");

// undo all steps (one step at a time)
// this could be written as: `await progress.down("initial");`
let result = 0;
do {
    result = await app.down(); // one major step down
} while (result);

// we must be at the initial state (note, that this does not completely remove all artifacts)
assertEquals(await app.getActiveVersion(), "1.0.0");
assertEquals(db, ["hey"]);

// now redo all steps (upgrade to "latest")
await app.up("latest");
assertEquals(db, ["hey", "ho", "lets", "go"]);

// now go back to specific version
await app.down("v2"); // "v2" is semver normalized to "2.0.0"
assertEquals(await app.getActiveVersion(), "2.0.0");
assertEquals(db, ["hey", "ho"]);

// now try to upgrade to unknown version
assertRejects(() => app.up("12.34.56"), "Unable to find");

// we are still in the last version
assertEquals(await app.getActiveVersion(), "2.0.0");
assertEquals(db, ["hey", "ho"]);

// now remove altogether
await app.uninstall();
assertEquals(await app.getActiveVersion(), undefined);
assertEquals(db, []);

Package Identity

• Name: @marianmeres/migrate
• Author: Marian Meres
• Repository: https://github.com/marianmeres/migrate
• License: MIT