@pipelab/migration 1.0.1-beta.19

package/.turbo/turbo-build.log

@@ -0,0 +1,16 @@
+
+
+> @pipelab/migration@1.0.1-beta.17 build /run/media/armaldio/SSD/Projects/Pipelab/pipelab/packages/migration
+> tsdown
+
+ℹ tsdown v0.21.2 powered by rolldown v1.0.0-rc.9
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ Cleaning 4 files
+ℹ dist/index.mjs         4.05 kB │ gzip: 1.27 kB
+ℹ dist/index.mjs.map    10.50 kB │ gzip: 3.17 kB
+ℹ dist/index.d.mts.map   1.99 kB │ gzip: 0.69 kB
+ℹ dist/index.d.mts       3.40 kB │ gzip: 0.98 kB
+ℹ 4 files, total: 19.95 kB
+✔ Build complete in 1015ms

package/.turbo/turbo-lint.log

@@ -0,0 +1,18 @@
+
+
+> @pipelab/migration@1.0.1-beta.4 lint /run/media/armaldio/SSD/Projects/Pipelab/pipelab/packages/migration
+> oxlint .
+
+
+  ⚠ ]8;;https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-unused-vars.html\eslint(no-unused-vars)]8;;\: Variable 'InitialState' is declared but never used. Unused variables should start with a '_'.
+    ╭─[src/models/migration.ts:50:33]
+ 49 │ 
+ 50 │ export interface MigratorConfig<InitialState, FinalState> {
+    ·                                 ──────┬─────
+    ·                                       ╰── 'InitialState' is declared here
+ 51 │   migrations: MigrationClass<any, any, any>[];
+    ╰────
+  help: Consider removing this declaration.
+
+Found 1 warning and 0 errors.
+Finished in 17ms on 6 files with 93 rules using 16 threads.

package/CHANGELOG.md

@@ -0,0 +1,121 @@
+# @pipelab/migration
+
+## 1.0.1-beta.19
+
+### Patch Changes
+
+- azs
+
+## 1.0.1-beta.18
+
+### Patch Changes
+
+- sqqd
+
+## 1.0.1-beta.17
+
+### Patch Changes
+
+- sd
+
+## 1.0.1-beta.16
+
+### Patch Changes
+
+- sd
+
+## 1.0.1-beta.15
+
+### Patch Changes
+
+- wdf
+
+## 1.0.1-beta.14
+
+### Patch Changes
+
+- sdf
+
+## 1.0.1-beta.13
+
+### Patch Changes
+
+- sd
+
+## 1.0.1-beta.12
+
+### Patch Changes
+
+- rfg
+
+## 1.0.1-beta.11
+
+### Patch Changes
+
+- szd
+
+## 1.0.1-beta.10
+
+### Patch Changes
+
+- sd
+
+## 1.0.1-beta.9
+
+### Patch Changes
+
+- sd
+
+## 1.0.1-beta.8
+
+### Patch Changes
+
+- sd
+
+## 1.0.1-beta.7
+
+### Patch Changes
+
+- sd
+
+## 1.0.1-beta.6
+
+### Patch Changes
+
+- test
+
+## 1.0.1-beta.5
+
+### Patch Changes
+
+- test
+
+## 1.0.1-beta.4
+
+### Patch Changes
+
+- sd
+
+## 1.0.1-beta.3
+
+### Patch Changes
+
+- tesyt
+
+## 1.0.1-beta.2
+
+### Patch Changes
+
+- last test
+
+## 1.0.1-beta.1
+
+### Patch Changes
+
+- 9268b1e: test 3
+
+## 1.0.1-beta.0
+
+### Patch Changes
+
+- test

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 CynToolkit
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.md

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2024-present Quentin Goinaud - Armaldio
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @pipelab/migration
+
+Handles version migration for Pipelab project files and database schemas.

package/dist/index.d.mts

@@ -0,0 +1,66 @@
+import * as valibot from "valibot";
+import { InferOutput, ObjectEntries } from "valibot";
+
+//#region src/models/migration.d.ts
+type Awaitable<T> = Promise<T> | T;
+type MigrationFn<From, To> = (state: From, targetVersion: string) => Awaitable<To>;
+type MigrateOptions = {
+  debug?: boolean;
+  target?: SemVer;
+};
+declare const MigrationSchemaValidator: valibot.ObjectSchema<{
+  readonly version: valibot.CustomSchema<`${number}.${number}.${number}`, undefined>;
+}, undefined>;
+declare const createVersionSchema: <OBJECTENTRIES extends ObjectEntries>(schema: OBJECTENTRIES) => valibot.ObjectSchema<OBJECTENTRIES, undefined>;
+type MigrationSchema = InferOutput<typeof MigrationSchemaValidator>;
+type OmitVersion<T> = Omit<T, keyof MigrationSchema>;
+type SemVer = `${number}.${number}.${number}`;
+interface MigrationClass<Down, Current, Up> {
+  version: SemVer;
+  up: MigrationFn<Current, Up>;
+  down: MigrationFn<Current, Down>;
+}
+interface MigrationObjInput<Down, Current, Up> {
+  version: SemVer;
+  up: MigrationFn<OmitVersion<Current>, OmitVersion<Up>>;
+  down: MigrationFn<OmitVersion<Current>, OmitVersion<Down>>;
+}
+interface MigratorConfig<InitialState, FinalState> {
+  migrations: MigrationClass<any, any, any>[];
+  coerce?: boolean;
+  defaultValue?: FinalState;
+}
+declare class Migrator<InitialState extends MigrationSchema, OutputState extends MigrationSchema> {
+  current: SemVer;
+  migrations: Record<SemVer, MigrationClass<any, any, any>>;
+  coerce: boolean;
+  defaultValue: OutputState;
+  constructor(config: MigratorConfig<InitialState, OutputState>);
+  getVersions(): `${number}.${number}.${number}`[];
+  migrate(_state: MigrationSchema | undefined, options?: MigrateOptions): Promise<OutputState>;
+  tryCoerce(version: SemVer): SemVer;
+  needMigration(version: SemVer): boolean;
+}
+//#endregion
+//#region src/models/createMigration.d.ts
+declare function createMigration<Down extends MigrationSchema, Current extends MigrationSchema, Up extends MigrationSchema>(migration: MigrationObjInput<Down, Current, Up>): MigrationClass<Down, Current, Up>;
+declare const initialVersion: () => never;
+declare const finalVersion: () => never;
+/**
+ * @deprecated
+ * @param version
+ * @param migration
+ * @returns
+ */
+declare function initial<Current extends MigrationSchema, Up extends MigrationSchema>(version: SemVer, migration: MigrationFn<OmitVersion<Current>, OmitVersion<Up>>): MigrationClass<Current, Current, Up>;
+declare function final<Current extends MigrationSchema, Down extends MigrationSchema>(version: SemVer, migration: MigrationFn<OmitVersion<Current>, OmitVersion<Down>>): MigrationClass<Down, Current, Current>;
+//#endregion
+//#region src/models/createMigrator.d.ts
+declare const createMigrator: <InitialState extends MigrationSchema, FinalState extends MigrationSchema>() => {
+  createDefault(defaultState: FinalState): FinalState;
+  createMigrations(config: MigratorConfig<InitialState, FinalState>): Migrator<InitialState, FinalState>;
+};
+type MigratorFactory<InitialState extends MigrationSchema, FinalState extends MigrationSchema> = ReturnType<typeof createMigrator<InitialState, FinalState>>;
+//#endregion
+export { type MigrationFn, type MigrationSchema, type Migrator, type MigratorConfig, MigratorFactory, type OmitVersion, type SemVer, createMigration, createMigrator, createVersionSchema, final, finalVersion, initial, initialVersion };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/models/migration.ts","../src/models/createMigration.ts","../src/models/createMigrator.ts"],"mappings":";;;;KAMY,SAAA,MAAe,OAAA,CAAQ,CAAA,IAAK,CAAA;AAAA,KAE5B,WAAA,cAAyB,KAAA,EAAO,IAAA,EAAM,aAAA,aAA0B,SAAA,CAAU,EAAA;AAAA,KAE1E,cAAA;EACV,KAAA;EACA,MAAA,GAAS,MAAA;AAAA;AAAA,cAUE,wBAAA,EAEX,OAAA,CAFmC,YAAA;EAAA,kBAEnC,OAAA,CAAA,YAAA;AAAA;AAAA,cAEW,mBAAA,yBAA6C,aAAA,EAAe,MAAA,EAAQ,aAAA,KAAa,OAAA,CAAA,YAAA,CAAA,aAAA;AAAA,KAKlF,eAAA,GAAkB,WAAA,QAAmB,wBAAA;AAAA,KAErC,WAAA,MAAiB,IAAA,CAAK,CAAA,QAAS,eAAA;AAAA,KAE/B,MAAA;AAAA,UAEK,cAAA;EACf,OAAA,EAAS,MAAA;EACT,EAAA,EAAI,WAAA,CAAY,OAAA,EAAS,EAAA;EACzB,IAAA,EAAM,WAAA,CAAY,OAAA,EAAS,IAAA;AAAA;AAAA,UAGZ,iBAAA;EACf,OAAA,EAAS,MAAA;EACT,EAAA,EAAI,WAAA,CAAY,WAAA,CAAY,OAAA,GAAU,WAAA,CAAY,EAAA;EAClD,IAAA,EAAM,WAAA,CAAY,WAAA,CAAY,OAAA,GAAU,WAAA,CAAY,IAAA;AAAA;AAAA,UAGrC,cAAA;EACf,UAAA,EAAY,cAAA;EACZ,MAAA;EACA,YAAA,GAAe,UAAA;AAAA;AAAA,cAGJ,QAAA,sBAA8B,eAAA,sBAAqC,eAAA;EAC9E,OAAA,EAAS,MAAA;EAET,UAAA,EAAY,MAAA,CAAO,MAAA,EAAQ,cAAA;EAE3B,MAAA;EACA,YAAA,EAAc,WAAA;cAEF,MAAA,EAAQ,cAAA,CAAe,YAAA,EAAc,WAAA;EAYjD,WAAA,CAAA;EAKM,OAAA,CACJ,MAAA,EAAQ,eAAA,cACR,OAAA,GAAU,cAAA,GACT,OAAA,CAAQ,WAAA;EAiEX,SAAA,CAAU,OAAA,EAAS,MAAA,GAAS,MAAA;EAI5B,aAAA,CAAc,OAAA,EAAS,MAAA;AAAA;;;iBC/IT,eAAA,cACD,eAAA,kBACG,eAAA,aACL,eAAA,CAAA,CACX,SAAA,EAAW,iBAAA,CAAkB,IAAA,EAAM,OAAA,EAAS,EAAA,IAAM,cAAA,CAAe,IAAA,EAAM,OAAA,EAAS,EAAA;AAAA,cAgBrE,cAAA;AAAA,cAIA,YAAA;AD3Bb;;;;;;AAAA,iBCyCgB,OAAA,iBAAwB,eAAA,aAA4B,eAAA,CAAA,CAClE,OAAA,EAAS,MAAA,EACT,SAAA,EAAW,WAAA,CAAY,WAAA,CAAY,OAAA,GAAU,WAAA,CAAY,EAAA,KACxD,cAAA,CAAe,OAAA,EAAS,OAAA,EAAS,EAAA;AAAA,iBAUpB,KAAA,iBAAsB,eAAA,eAA8B,eAAA,CAAA,CAClE,OAAA,EAAS,MAAA,EACT,SAAA,EAAW,WAAA,CAAY,WAAA,CAAY,OAAA,GAAU,WAAA,CAAY,IAAA,KACxD,cAAA,CAAe,IAAA,EAAM,OAAA,EAAS,OAAA;;;cC7DpB,cAAA,wBACU,eAAA,qBACF,eAAA;8BAGW,UAAA,GAAa,UAAA;2BAI/B,cAAA,CAAe,YAAA,EAAc,UAAA,IACpC,QAAA,CAAS,YAAA,EAAc,UAAA;AAAA;AAAA,KAMlB,eAAA,sBACW,eAAA,qBACF,eAAA,IACjB,UAAA,QAAkB,cAAA,CAAe,YAAA,EAAc,UAAA"}

package/dist/index.mjs

@@ -0,0 +1,127 @@
+import * as semver from "semver";
+import { coerce } from "semver";
+import { klona } from "klona";
+import { custom, object } from "valibot";
+//#region src/models/createMigration.ts
+function createMigration(migration) {
+	return {
+		version: migration.version,
+		up: async (state, nextVersion) => {
+			const newState = await migration.up(state, nextVersion);
+			newState.version = nextVersion;
+			return newState;
+		},
+		down: async (state, nextVersion) => {
+			const newState = await migration.down(state, nextVersion);
+			newState.version = nextVersion;
+			return newState;
+		}
+	};
+}
+const initialVersion = () => {
+	throw new Error("Unable to go down on the initial version!");
+};
+const finalVersion = () => {
+	throw new Error("Unable to go up on the final version!");
+};
+/**
+* @deprecated
+* @param version
+* @param migration
+* @returns
+*/
+function initial(version, migration) {
+	return createMigration({
+		version,
+		up: migration,
+		down() {
+			throw new Error("Unable to go down on the initial version!");
+		}
+	});
+}
+function final(version, migration) {
+	return createMigration({
+		version,
+		up: () => {
+			throw new Error(`Unable to go up on the final version "${version}"!`);
+		},
+		down: migration
+	});
+}
+//#endregion
+//#region src/utils/object-keys.ts
+const objectKeys = Object.keys;
+object({ version: custom((input) => typeof input === "string" ? /^\d+\.\d+\.\d+$/.test(input) : false) });
+const createVersionSchema = (schema) => object({ ...schema });
+var Migrator = class {
+	current;
+	migrations = {};
+	coerce;
+	defaultValue;
+	constructor(config) {
+		config.migrations.forEach((migration) => {
+			this.migrations[migration.version] = migration;
+		});
+		this.defaultValue = config?.defaultValue ?? {};
+		const versions = this.getVersions();
+		this.current = versions[versions.length - 1];
+		this.coerce = config?.coerce ?? true;
+	}
+	getVersions() {
+		const keys = objectKeys(this.migrations);
+		return semver.sort(keys);
+	}
+	async migrate(_state, options) {
+		const state = _state ?? this.defaultValue;
+		const currentVersion = this.tryCoerce(state.version);
+		const targetVersion = this.tryCoerce(options?.target ?? this.current);
+		if (options?.debug) console.log("Migrating from", currentVersion, "to", targetVersion);
+		let finalState = klona(state);
+		const versions = this.getVersions();
+		const currentIndex = versions.indexOf(currentVersion);
+		const targetIndex = versions.indexOf(targetVersion);
+		if (currentIndex === -1) throw new Error(`Current version "${currentVersion}" not found in migrations`);
+		if (targetIndex === -1) throw new Error(`Target version "${targetVersion}" not found in migrations`);
+		if (currentIndex === targetIndex) return finalState;
+		const isUpgrade = currentIndex < targetIndex;
+		const increment = isUpgrade ? 1 : -1;
+		const direction = isUpgrade ? "up" : "down";
+		for (let i = currentIndex; isUpgrade ? i < targetIndex : i > targetIndex; i += increment) {
+			const currentVersion = versions[i];
+			const nextVersion = versions[i + increment];
+			if (options?.debug) console.log("	Migrating to version:", nextVersion);
+			const migrationVersion = currentVersion;
+			const migration = this.migrations[migrationVersion];
+			const { version: _, ...stateWithoutVersion } = finalState;
+			finalState = {
+				...await migration[direction](stateWithoutVersion, currentVersion),
+				version: nextVersion
+			};
+			if (options?.debug) console.log("	Migrated state:", finalState);
+		}
+		return finalState;
+	}
+	tryCoerce(version) {
+		return this.coerce ? coerce(version)?.version ?? version : version;
+	}
+	needMigration(version) {
+		const newVersion = this.tryCoerce(version);
+		return semver.lt(newVersion, this.current);
+	}
+};
+//#endregion
+//#region src/models/createMigrator.ts
+const createMigrator = () => {
+	return {
+		createDefault(defaultState) {
+			return defaultState;
+		},
+		createMigrations(config) {
+			return new Migrator(config);
+		}
+	};
+};
+//#endregion
+export { createMigration, createMigrator, createVersionSchema, final, finalVersion, initial, initialVersion };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/models/createMigration.ts","../src/utils/object-keys.ts","../src/models/migration.ts","../src/models/createMigrator.ts"],"sourcesContent":["import {\n  MigrationFn,\n  MigrationObjInput,\n  MigrationClass,\n  MigrationSchema,\n  OmitVersion,\n  SemVer,\n} from \"./migration\";\n\nexport function createMigration<\n  Down extends MigrationSchema,\n  Current extends MigrationSchema,\n  Up extends MigrationSchema,\n>(migration: MigrationObjInput<Down, Current, Up>): MigrationClass<Down, Current, Up> {\n  return {\n    version: migration.version,\n    up: async (state, nextVersion) => {\n      const newState = (await migration.up(state, nextVersion)) as unknown as Up;\n      newState.version = nextVersion as SemVer;\n      return newState;\n    },\n    down: async (state, nextVersion) => {\n      const newState = (await migration.down(state, nextVersion)) as unknown as Down;\n      newState.version = nextVersion as SemVer;\n      return newState;\n    },\n  };\n}\n\nexport const initialVersion = () => {\n  throw new Error(\"Unable to go down on the initial version!\");\n};\n\nexport const finalVersion = () => {\n  throw new Error(\"Unable to go up on the final version!\");\n};\n\n// export const finalVersion = <T>(state: T) => {\n//   return state\n// }\n\n/**\n * @deprecated\n * @param version\n * @param migration\n * @returns\n */\nexport function initial<Current extends MigrationSchema, Up extends MigrationSchema>(\n  version: SemVer,\n  migration: MigrationFn<OmitVersion<Current>, OmitVersion<Up>>,\n): MigrationClass<Current, Current, Up> {\n  return createMigration({\n    version,\n    up: migration,\n    down() {\n      throw new Error(\"Unable to go down on the initial version!\");\n    },\n  });\n}\n\nexport function final<Current extends MigrationSchema, Down extends MigrationSchema>(\n  version: SemVer,\n  migration: MigrationFn<OmitVersion<Current>, OmitVersion<Down>>,\n): MigrationClass<Down, Current, Current> {\n  return createMigration({\n    version,\n    up: () => {\n      throw new Error(`Unable to go up on the final version \"${version}\"!`);\n    },\n    down: migration,\n  });\n}\n","export type ObjectKeys<T extends object> = `${Exclude<keyof T, symbol>}`;\n\nexport const objectKeys = Object.keys as <Type extends object>(\n  value: Type,\n) => Array<ObjectKeys<Type>>;\nexport const objectEntries = Object.entries as <Type extends Record<PropertyKey, unknown>>(\n  value: Type,\n) => Array<[ObjectKeys<Type>, Type[ObjectKeys<Type>]]>;\n","import * as semver from \"semver\";\nimport { coerce } from \"semver\";\nimport { objectKeys } from \"../utils/object-keys\";\nimport { klona } from \"klona\";\nimport { custom, InferOutput, object, ObjectEntries } from \"valibot\";\n\nexport type Awaitable<T> = Promise<T> | T;\n\nexport type MigrationFn<From, To> = (state: From, targetVersion: string) => Awaitable<To>;\n\nexport type MigrateOptions = {\n  debug?: boolean;\n  target?: SemVer;\n};\n\nconst SemverValidator = custom<SemVer>((input) =>\n  typeof input === \"string\" ? /^\\d+\\.\\d+\\.\\d+$/.test(input) : false,\n);\n\nexport const SemverVersionValidator = SemverValidator;\n// export const SemverVersionValidator = optional(SemverValidator, '1.0.0')\n\nexport const MigrationSchemaValidator = object({\n  version: SemverVersionValidator,\n});\n\nexport const createVersionSchema = <OBJECTENTRIES extends ObjectEntries>(schema: OBJECTENTRIES) =>\n  object({\n    ...schema,\n  });\n\nexport type MigrationSchema = InferOutput<typeof MigrationSchemaValidator>;\n\nexport type OmitVersion<T> = Omit<T, keyof MigrationSchema>;\n\nexport type SemVer = `${number}.${number}.${number}`;\n\nexport interface MigrationClass<Down, Current, Up> {\n  version: SemVer;\n  up: MigrationFn<Current, Up>;\n  down: MigrationFn<Current, Down>;\n}\n\nexport interface MigrationObjInput<Down, Current, Up> {\n  version: SemVer;\n  up: MigrationFn<OmitVersion<Current>, OmitVersion<Up>>;\n  down: MigrationFn<OmitVersion<Current>, OmitVersion<Down>>;\n}\n\nexport interface MigratorConfig<InitialState, FinalState> {\n  migrations: MigrationClass<any, any, any>[];\n  coerce?: boolean;\n  defaultValue?: FinalState;\n}\n\nexport class Migrator<InitialState extends MigrationSchema, OutputState extends MigrationSchema> {\n  current: SemVer;\n\n  migrations: Record<SemVer, MigrationClass<any, any, any>> = {};\n\n  coerce: boolean;\n  defaultValue: OutputState;\n\n  constructor(config: MigratorConfig<InitialState, OutputState>) {\n    config.migrations.forEach((migration) => {\n      this.migrations[migration.version] = migration;\n    });\n\n    this.defaultValue = config?.defaultValue ?? ({} as OutputState);\n\n    const versions = this.getVersions();\n    this.current = versions[versions.length - 1];\n    this.coerce = config?.coerce ?? true;\n  }\n\n  getVersions() {\n    const keys = objectKeys(this.migrations);\n    return semver.sort(keys);\n  }\n\n  async migrate(\n    _state: MigrationSchema | undefined,\n    options?: MigrateOptions,\n  ): Promise<OutputState> {\n    const state = _state ?? this.defaultValue;\n    const currentVersion = this.tryCoerce(state.version);\n    const targetVersion = this.tryCoerce(options?.target ?? this.current);\n\n    if (options?.debug) {\n      console.log(\"Migrating from\", currentVersion, \"to\", targetVersion);\n    }\n\n    let finalState = klona(state) as any; // Using any here because we'll be transforming between versions\n    const versions = this.getVersions();\n    const currentIndex = versions.indexOf(currentVersion);\n    const targetIndex = versions.indexOf(targetVersion);\n\n    if (currentIndex === -1) {\n      throw new Error(`Current version \"${currentVersion}\" not found in migrations`);\n    }\n    if (targetIndex === -1) {\n      throw new Error(`Target version \"${targetVersion}\" not found in migrations`);\n    }\n\n    // If we're already at the target version, return the state\n    if (currentIndex === targetIndex) {\n      return finalState as OutputState;\n    }\n\n    // Get the migration path\n    const isUpgrade = currentIndex < targetIndex;\n    const increment = isUpgrade ? 1 : -1;\n    const direction = isUpgrade ? \"up\" : \"down\";\n\n    // Perform migrations\n    for (let i = currentIndex; isUpgrade ? i < targetIndex : i > targetIndex; i += increment) {\n      const currentVersion = versions[i];\n      const nextVersion = versions[i + increment];\n\n      if (options?.debug) {\n        console.log(\"\\tMigrating to version:\", nextVersion);\n      }\n\n      // For upgrades, use current version's migration\n      // For downgrades, use previous version's migration\n      const migrationVersion = currentVersion;\n      const migration = this.migrations[migrationVersion];\n\n      // Remove version before migration\n      const { version: _, ...stateWithoutVersion } = finalState;\n\n      // Perform migration\n      const migratedState = await migration[direction](stateWithoutVersion, currentVersion);\n\n      // Add new version\n      finalState = {\n        ...migratedState,\n        version: nextVersion,\n      };\n\n      if (options?.debug) {\n        console.log(\"\\tMigrated state:\", finalState);\n      }\n    }\n\n    return finalState as OutputState;\n  }\n\n  tryCoerce(version: SemVer): SemVer {\n    return this.coerce ? ((coerce(version)?.version as SemVer | undefined) ?? version) : version;\n  }\n\n  needMigration(version: SemVer) {\n    const newVersion = this.tryCoerce(version);\n    return semver.lt(newVersion, this.current);\n  }\n}\n","import { MigratorConfig, Migrator, MigrationSchema } from \"./migration\";\n\nexport const createMigrator = <\n  InitialState extends MigrationSchema,\n  FinalState extends MigrationSchema,\n>() => {\n  return {\n    createDefault(defaultState: FinalState): FinalState {\n      return defaultState;\n    },\n    createMigrations(\n      config: MigratorConfig<InitialState, FinalState>,\n    ): Migrator<InitialState, FinalState> {\n      return new Migrator<InitialState, FinalState>(config);\n    },\n  };\n};\n\nexport type MigratorFactory<\n  InitialState extends MigrationSchema,\n  FinalState extends MigrationSchema,\n> = ReturnType<typeof createMigrator<InitialState, FinalState>>;\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pipelab/migration",
+  "version": "1.0.1-beta.19",
+  "private": false,
+  "description": "Migration utilities for Pipelab data structures",
+  "license": "FSL-1.1-MIT",
+  "author": "CynToolkit",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CynToolkit/pipelab.git",
+    "directory": "packages/migration"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/node": "^24.12.2",
+    "klona": "2.0.6",
+    "semver": "^7.6.3",
+    "valibot": "0.42.1"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.5.8",
+    "tsdown": "0.21.2",
+    "typescript": "5.9.3",
+    "@pipelab/tsconfig": "1.0.1-beta.19"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "format": "oxfmt .",
+    "lint": "oxlint ."
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./models/createMigration";
+export * from "./models/createMigrator";
+export type {
+  MigrationSchema,
+  Migrator,
+  MigratorConfig,
+  MigrationFn,
+  SemVer,
+  OmitVersion,
+} from "./models/migration";
+export { createVersionSchema } from "./models/migration";

package/src/models/createMigration.ts

@@ -0,0 +1,72 @@
+import {
+  MigrationFn,
+  MigrationObjInput,
+  MigrationClass,
+  MigrationSchema,
+  OmitVersion,
+  SemVer,
+} from "./migration";
+
+export function createMigration<
+  Down extends MigrationSchema,
+  Current extends MigrationSchema,
+  Up extends MigrationSchema,
+>(migration: MigrationObjInput<Down, Current, Up>): MigrationClass<Down, Current, Up> {
+  return {
+    version: migration.version,
+    up: async (state, nextVersion) => {
+      const newState = (await migration.up(state, nextVersion)) as unknown as Up;
+      newState.version = nextVersion as SemVer;
+      return newState;
+    },
+    down: async (state, nextVersion) => {
+      const newState = (await migration.down(state, nextVersion)) as unknown as Down;
+      newState.version = nextVersion as SemVer;
+      return newState;
+    },
+  };
+}
+
+export const initialVersion = () => {
+  throw new Error("Unable to go down on the initial version!");
+};
+
+export const finalVersion = () => {
+  throw new Error("Unable to go up on the final version!");
+};
+
+// export const finalVersion = <T>(state: T) => {
+//   return state
+// }
+
+/**
+ * @deprecated
+ * @param version
+ * @param migration
+ * @returns
+ */
+export function initial<Current extends MigrationSchema, Up extends MigrationSchema>(
+  version: SemVer,
+  migration: MigrationFn<OmitVersion<Current>, OmitVersion<Up>>,
+): MigrationClass<Current, Current, Up> {
+  return createMigration({
+    version,
+    up: migration,
+    down() {
+      throw new Error("Unable to go down on the initial version!");
+    },
+  });
+}
+
+export function final<Current extends MigrationSchema, Down extends MigrationSchema>(
+  version: SemVer,
+  migration: MigrationFn<OmitVersion<Current>, OmitVersion<Down>>,
+): MigrationClass<Down, Current, Current> {
+  return createMigration({
+    version,
+    up: () => {
+      throw new Error(`Unable to go up on the final version "${version}"!`);
+    },
+    down: migration,
+  });
+}

package/src/models/createMigrator.ts

@@ -0,0 +1,22 @@
+import { MigratorConfig, Migrator, MigrationSchema } from "./migration";
+
+export const createMigrator = <
+  InitialState extends MigrationSchema,
+  FinalState extends MigrationSchema,
+>() => {
+  return {
+    createDefault(defaultState: FinalState): FinalState {
+      return defaultState;
+    },
+    createMigrations(
+      config: MigratorConfig<InitialState, FinalState>,
+    ): Migrator<InitialState, FinalState> {
+      return new Migrator<InitialState, FinalState>(config);
+    },
+  };
+};
+
+export type MigratorFactory<
+  InitialState extends MigrationSchema,
+  FinalState extends MigrationSchema,
+> = ReturnType<typeof createMigrator<InitialState, FinalState>>;

package/src/models/migration.spec.ts

@@ -0,0 +1,343 @@
+import { describe, test, expect, beforeAll, beforeEach, afterEach, vi } from "vitest";
+import { createMigration, final, finalVersion, initial, initialVersion } from "./createMigration";
+import { createMigrator, MigratorFactory } from "./createMigrator";
+import { Migrator, MigrationSchema } from "./migration";
+import { z } from "zod";
+
+export const withMigration = (obj: z.AnyZodObject) =>
+  z
+    .object({
+      version: z.string(),
+    })
+    .merge(obj);
+
+interface V1 extends MigrationSchema {
+  dummyV1: string;
+}
+
+interface V2 extends MigrationSchema {
+  dummyV2: string;
+}
+
+interface V3 extends MigrationSchema {
+  dummyV3: string;
+}
+
+interface V4 extends MigrationSchema {
+  dummy: string;
+}
+
+const outputV1: V1 = {
+  dummyV1: "aaa",
+  version: "1.0.0",
+};
+
+const outputV2: V2 = {
+  dummyV2: "aaa",
+  version: "2.0.0",
+};
+
+const outputV3: V3 = {
+  dummyV3: "aaa",
+  version: "3.0.0",
+};
+
+const outputV4: V4 = {
+  dummy: "aaa",
+  version: "4.0.0",
+};
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("migrator", () => {
+  let migratorInstance: MigratorFactory<V1, V4>;
+  let migratorMigrations: Migrator<V1, V4>;
+  beforeAll(() => {
+    // migratorInstance = createMigrator<V4>({
+    //   migrations: [
+    //     initial<V1, V2>('1.0.0', (state) => ({
+    //       dummyV2: state.dummyV1,
+    //     })),
+    //     createMigration<V1, V2, V3>({
+    //       version: '2.0.0',
+    //       up: (state) => ({
+    //         dummyV3: state.dummyV2,
+    //       }),
+    //       down: (state) => ({
+    //         dummyV1: state.dummyV2,
+    //       }),
+    //     }),
+    //     createMigration<V2, V3, V4>({
+    //       version: '3.0.0',
+    //       up: (state) => ({
+    //         dummy: state.dummyV3,
+    //       }),
+    //       down: (state) => ({
+    //         dummyV2: state.dummyV3,
+    //       }),
+    //     }),
+    //     final<V4, V3>('4.0.0', (state) => ({
+    //       dummyV3: state.dummy,
+    //     })),
+    //   ],
+    // });
+
+    migratorInstance = createMigrator<V1, V4>();
+    migratorMigrations = migratorInstance.createMigrations({
+      defaultValue: outputV1,
+      migrations: [
+        createMigration<never, V1, V2>({
+          version: "1.0.0",
+          up: (state) => ({
+            dummyV2: state.dummyV1,
+          }),
+          down: initialVersion,
+        }),
+        createMigration<V1, V2, V3>({
+          version: "2.0.0",
+          up: (state) => ({
+            dummyV3: state.dummyV2,
+          }),
+          down: (state) => ({
+            dummyV1: state.dummyV2,
+          }),
+        }),
+        createMigration<V2, V3, V4>({
+          version: "3.0.0",
+          up: (state) => ({
+            dummy: state.dummyV3,
+          }),
+          down: (state) => ({
+            dummyV2: state.dummyV3,
+          }),
+        }),
+        createMigration<V3, V4, never>({
+          version: "4.0.0",
+          up: finalVersion,
+          down: (state) => ({
+            dummyV3: state.dummy,
+          }),
+        }),
+      ],
+    });
+  });
+
+  test("should not need migration", () => {
+    expect(migratorMigrations.needMigration("4.0.0")).toBe(false);
+    expect(migratorMigrations.needMigration("5.0.0")).toBe(false);
+    expect(migratorMigrations.needMigration("4.1.0")).toBe(false);
+    expect(migratorMigrations.needMigration("4.0.1")).toBe(false);
+    expect(migratorMigrations.needMigration("5.0.1")).toBe(false);
+  });
+
+  test("should need migration", () => {
+    expect(migratorMigrations.needMigration("0.0.0")).toBe(true);
+    expect(migratorMigrations.needMigration("0.1.0")).toBe(true);
+    expect(migratorMigrations.needMigration("0.0.1")).toBe(true);
+    expect(migratorMigrations.needMigration("1.0.1")).toBe(true);
+    expect(migratorMigrations.needMigration("2.3.1")).toBe(true);
+    expect(migratorMigrations.needMigration("3.4.1")).toBe(true);
+  });
+
+  test("should migrate", async () => {
+    const input: V1 = {
+      dummyV1: "aaa",
+      version: "1.0.0",
+    };
+    const result = await migratorMigrations.migrate(input);
+    expect(result).toStrictEqual(outputV4);
+  });
+
+  test("should return instance if same target version", async () => {
+    const input: V4 = {
+      dummy: "aaa",
+      version: "4.0.0",
+    };
+    const result = await migratorMigrations.migrate(input);
+    expect(result).toStrictEqual(outputV4);
+  });
+
+  test("should not do anything if migrate up but nothing more", () => {
+    const input: V4 = {
+      dummy: "aaa",
+      version: "4.0.0",
+    };
+    return expect(migratorMigrations.migrate(input)).resolves.toStrictEqual(outputV4);
+  });
+
+  test("should downgrade", async () => {
+    const input: V4 = {
+      dummy: "aaa",
+      version: "4.0.0",
+    };
+    const result = await migratorMigrations.migrate(input);
+    expect(result).toEqual(outputV4);
+    const resultDown = await migratorMigrations.migrate(result, {
+      target: "3.0.0",
+    });
+    expect(resultDown).toEqual(outputV3);
+    const resultDown2 = await migratorMigrations.migrate(resultDown, {
+      target: "2.0.0",
+    });
+    expect(resultDown2).toEqual(outputV2);
+    const resultUp = await migratorMigrations.migrate(resultDown2, {
+      target: "3.0.0",
+    });
+    expect(resultUp).toEqual(outputV3);
+  });
+
+  test("should throw if target is not in migrations", async () => {
+    const input: V4 = {
+      dummy: "aaa",
+      version: "1.2.0",
+    };
+
+    const badMigratorInstance = createMigrator<V1, V4>().createMigrations({
+      migrations: [
+        initial<V1, V2>("1.0.0", (state) => ({
+          dummyV2: state.dummyV1,
+        })),
+        final<V4, V3>("4.0.0", (state) => ({
+          dummyV3: state.dummy,
+        })),
+      ],
+    });
+
+    return expect(badMigratorInstance.migrate(input)).rejects.toThrow();
+  });
+
+  test("should throw on migration not found", async () => {
+    const input: V4 = {
+      dummy: "aaa",
+      version: "1.2.0",
+    };
+
+    const badMigratorInstance = createMigrator<V1, V4>().createMigrations({
+      migrations: [
+        initial<V1, V2>("1.0.0", (state) => ({
+          dummyV2: state.dummyV1,
+        })),
+        final<V4, V3>("4.0.0", (state) => ({
+          dummyV3: state.dummy,
+        })),
+      ],
+    });
+
+    await expect(badMigratorInstance.migrate(input)).rejects.toThrow();
+  });
+
+  test("should migrate an incomplete version (loose)", async () => {
+    const input: V1 = {
+      dummyV1: "aaa",
+      // @ts-expect-error specific to the test
+      version: "1",
+    };
+
+    const migrator = createMigrator<V1, V4>().createMigrations({
+      migrations: [
+        createMigration<never, V1, V2>({
+          version: "1.0.0",
+          up: (state) => ({
+            dummyV2: state.dummyV1,
+          }),
+          down: initialVersion,
+        }),
+        createMigration<V1, V2, never>({
+          version: "2.0.0",
+          up: finalVersion,
+          down: (state) => ({
+            dummyV1: state.dummyV2,
+          }),
+        }),
+      ],
+    });
+
+    const result = await migrator.migrate(input);
+
+    expect(result).toEqual(expect.objectContaining({ version: "2.0.0" }));
+  });
+
+  test("should not migrate an incomplete version when coerce option disabled", async () => {
+    const input: V1 = {
+      dummyV1: "aaa",
+      // @ts-expect-error specific to the test
+      version: "1",
+    };
+
+    const migrator = createMigrator<V1, V2>().createMigrations({
+      migrations: [
+        createMigration<never, V1, V2>({
+          version: "1.0.0",
+          up: (state) => ({
+            dummyV2: state.dummyV1,
+          }),
+          down: initialVersion,
+        }),
+        createMigration<V1, V2, never>({
+          version: "2.0.0",
+          up: finalVersion,
+          down: (state) => ({
+            dummyV1: state.dummyV2,
+          }),
+        }),
+      ],
+      coerce: false,
+    });
+
+    await expect(migrator.migrate(input)).rejects.toThrow(
+      'Current version "1" not found in migrations',
+    );
+  });
+});
+
+describe("async", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("should support async migration", async () => {
+    const input: V1 = {
+      dummyV1: "aaa",
+      version: "1.0.0",
+    };
+
+    const migrator = createMigrator<V1, V2>().createMigrations({
+      migrations: [
+        createMigration<never, V1, V2>({
+          version: "1.0.0",
+          up: async (state) => {
+            await sleep(1000);
+            return {
+              dummyV2: state.dummyV1,
+            };
+          },
+          down: initialVersion,
+        }),
+        createMigration<V1, V2, never>({
+          version: "2.0.0",
+          up: finalVersion,
+          down: async (state) => {
+            await sleep(1000);
+            return {
+              dummyV1: state.dummyV2,
+            };
+          },
+        }),
+      ],
+    });
+
+    const promise = migrator.migrate(input);
+
+    vi.advanceTimersByTime(1000);
+
+    const result = await promise;
+
+    expect(result).toStrictEqual({
+      dummyV2: "aaa",
+      version: "2.0.0",
+    });
+  });
+});

package/src/models/migration.ts

@@ -0,0 +1,157 @@
+import * as semver from "semver";
+import { coerce } from "semver";
+import { objectKeys } from "../utils/object-keys";
+import { klona } from "klona";
+import { custom, InferOutput, object, ObjectEntries } from "valibot";
+
+export type Awaitable<T> = Promise<T> | T;
+
+export type MigrationFn<From, To> = (state: From, targetVersion: string) => Awaitable<To>;
+
+export type MigrateOptions = {
+  debug?: boolean;
+  target?: SemVer;
+};
+
+const SemverValidator = custom<SemVer>((input) =>
+  typeof input === "string" ? /^\d+\.\d+\.\d+$/.test(input) : false,
+);
+
+export const SemverVersionValidator = SemverValidator;
+// export const SemverVersionValidator = optional(SemverValidator, '1.0.0')
+
+export const MigrationSchemaValidator = object({
+  version: SemverVersionValidator,
+});
+
+export const createVersionSchema = <OBJECTENTRIES extends ObjectEntries>(schema: OBJECTENTRIES) =>
+  object({
+    ...schema,
+  });
+
+export type MigrationSchema = InferOutput<typeof MigrationSchemaValidator>;
+
+export type OmitVersion<T> = Omit<T, keyof MigrationSchema>;
+
+export type SemVer = `${number}.${number}.${number}`;
+
+export interface MigrationClass<Down, Current, Up> {
+  version: SemVer;
+  up: MigrationFn<Current, Up>;
+  down: MigrationFn<Current, Down>;
+}
+
+export interface MigrationObjInput<Down, Current, Up> {
+  version: SemVer;
+  up: MigrationFn<OmitVersion<Current>, OmitVersion<Up>>;
+  down: MigrationFn<OmitVersion<Current>, OmitVersion<Down>>;
+}
+
+export interface MigratorConfig<InitialState, FinalState> {
+  migrations: MigrationClass<any, any, any>[];
+  coerce?: boolean;
+  defaultValue?: FinalState;
+}
+
+export class Migrator<InitialState extends MigrationSchema, OutputState extends MigrationSchema> {
+  current: SemVer;
+
+  migrations: Record<SemVer, MigrationClass<any, any, any>> = {};
+
+  coerce: boolean;
+  defaultValue: OutputState;
+
+  constructor(config: MigratorConfig<InitialState, OutputState>) {
+    config.migrations.forEach((migration) => {
+      this.migrations[migration.version] = migration;
+    });
+
+    this.defaultValue = config?.defaultValue ?? ({} as OutputState);
+
+    const versions = this.getVersions();
+    this.current = versions[versions.length - 1];
+    this.coerce = config?.coerce ?? true;
+  }
+
+  getVersions() {
+    const keys = objectKeys(this.migrations);
+    return semver.sort(keys);
+  }
+
+  async migrate(
+    _state: MigrationSchema | undefined,
+    options?: MigrateOptions,
+  ): Promise<OutputState> {
+    const state = _state ?? this.defaultValue;
+    const currentVersion = this.tryCoerce(state.version);
+    const targetVersion = this.tryCoerce(options?.target ?? this.current);
+
+    if (options?.debug) {
+      console.log("Migrating from", currentVersion, "to", targetVersion);
+    }
+
+    let finalState = klona(state) as any; // Using any here because we'll be transforming between versions
+    const versions = this.getVersions();
+    const currentIndex = versions.indexOf(currentVersion);
+    const targetIndex = versions.indexOf(targetVersion);
+
+    if (currentIndex === -1) {
+      throw new Error(`Current version "${currentVersion}" not found in migrations`);
+    }
+    if (targetIndex === -1) {
+      throw new Error(`Target version "${targetVersion}" not found in migrations`);
+    }
+
+    // If we're already at the target version, return the state
+    if (currentIndex === targetIndex) {
+      return finalState as OutputState;
+    }
+
+    // Get the migration path
+    const isUpgrade = currentIndex < targetIndex;
+    const increment = isUpgrade ? 1 : -1;
+    const direction = isUpgrade ? "up" : "down";
+
+    // Perform migrations
+    for (let i = currentIndex; isUpgrade ? i < targetIndex : i > targetIndex; i += increment) {
+      const currentVersion = versions[i];
+      const nextVersion = versions[i + increment];
+
+      if (options?.debug) {
+        console.log("\tMigrating to version:", nextVersion);
+      }
+
+      // For upgrades, use current version's migration
+      // For downgrades, use previous version's migration
+      const migrationVersion = currentVersion;
+      const migration = this.migrations[migrationVersion];
+
+      // Remove version before migration
+      const { version: _, ...stateWithoutVersion } = finalState;
+
+      // Perform migration
+      const migratedState = await migration[direction](stateWithoutVersion, currentVersion);
+
+      // Add new version
+      finalState = {
+        ...migratedState,
+        version: nextVersion,
+      };
+
+      if (options?.debug) {
+        console.log("\tMigrated state:", finalState);
+      }
+    }
+
+    return finalState as OutputState;
+  }
+
+  tryCoerce(version: SemVer): SemVer {
+    return this.coerce ? ((coerce(version)?.version as SemVer | undefined) ?? version) : version;
+  }
+
+  needMigration(version: SemVer) {
+    const newVersion = this.tryCoerce(version);
+    return semver.lt(newVersion, this.current);
+  }
+}

package/src/utils/object-keys.ts

@@ -0,0 +1,8 @@
+export type ObjectKeys<T extends object> = `${Exclude<keyof T, symbol>}`;
+
+export const objectKeys = Object.keys as <Type extends object>(
+  value: Type,
+) => Array<ObjectKeys<Type>>;
+export const objectEntries = Object.entries as <Type extends Record<PropertyKey, unknown>>(
+  value: Type,
+) => Array<[ObjectKeys<Type>, Type[ObjectKeys<Type>]]>;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig/commonjs.json",
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {
+      "@pipelab/migration": ["./src"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}