semgrator

semgrator provides an utility to support backward compatibility when building frameworks and runtimes that do not introduce breaking changes via new options.

What is a compatibility option/flag/mode?

If you want to create a product that is configurable, but you do not want to break your users on behavior changes, you can introduce a new option that turns on and off the new behavior, and turn the new behavior by default. Users of the previous behavior would be required to change their configuration to keep using the software.

How semgrator helps

semgrator run migrations code based on semantic version rules. So on a breaking/behavior change that results in a new compatibility option in your configuration file, you can add a new migration rule that set the new option to false automatically.

Install

npm i semgrator

Usage

Writing migrations

import type { Migration } from 'semgrator'
import type { Config } from '../your-config-meta.js'

export const migration: Migration<Config> = {
  version: '1.0.0',
  toVersion: '1.42.0',
  up: (input: Config) => {
    // Do something with Config
    return input
  },
}

The version peroperty specifies the minimum version that do not need the change. In other terms, all versions before the specified one will trigger the migration.

The toVersion property will be used by semgrator as the resulting version after the change. This is useful in case you want to have a final version that is higher than version.

Running semgrator

import { semgrator } from 'semgrator'

type MyConfig = {
  result: unknown
}

const res = await semgrator<MyConfig, MyConfig>({
  version: '1.0.0',
  path: 'path/to/migrations',
  input: {
    result: { foo: 'bar' } as unknown,
  },
})

console.log(res.result)
console.log(res.changed)
console.log(res.version)

Getting intermediate results

import { semgrator } from 'semgrator'

type MyConfig = {
  result: unknown
}

const iterator = semgrator<MyConfig, MyConfig>({
  version: '1.0.0',
  path: 'path/to/migrations',
  input: {
    result: { foo: 'bar' } as unknown,
  },
})

for await (const res of iterator) {
  console.log(res.version, res.result)
}

License

Apache-2.0

platformatic/semgrator