@flumens/utils 0.4.0 → 0.5.0

package/dist/MigrationManager.d.ts

@@ -0,0 +1,100 @@
+/** ****************************************************************************
+ * Internal state migration functionality.
+ *
+ * Cases:
+ * - First run - no migrations needed, just set the version.
+ * - Versions match - no migrations needed, the state was already migrated.
+ * - Versions differ - run all migrations in sequence, starting from the first
+ *   one that is greater than the current version.
+ * - If no migrations are found for the current version, just set the version.
+ *
+ * Each migration should be idempotent if possible, as it may be interrupted
+ * and re-run multiple times.
+ **************************************************************************** */
+export type Migration = {
+    /** Semver version when this migration becomes relevant (inclusive). */
+    version: string;
+    /** Optional descriptive name for logging. */
+    name?: string;
+    /** The migration script. Keep it idempotent if possible. */
+    up: () => void | Promise<void>;
+};
+export default class MigrationsManager {
+    private migrations;
+    private newVersion;
+    private currentVersion;
+    private updateVersion;
+    /**
+     * Creates a new MigrationsManager instance.
+     *
+     * @param migrations - Array of migration objects to be applied
+     * @param newVersion - A function that returns the target version we want to migrate to
+     * @param currentVersion - A function that returns the last migrated version
+     * @param updateVersion - A function to persist the version after each migration
+     */
+    constructor(migrations: Migration[], newVersion: () => string | Promise<string>, currentVersion: () => (string | null) | Promise<string | null>, updateVersion: (version: string) => Promise<void>);
+    /**
+     * Main update function.
+     *
+     * Flow:
+     * 1. If currentVersion === newVersion -> No migrations needed
+     * 2. If currentVersion is null -> First run, just set version
+     * 3. If currentVersion < newVersion -> Find and run applicable migrations
+     * 4. Each migration updates the version individually for interruption safety
+     */
+    run(): Promise<void>;
+    /**
+     * Returns the index of the first found update in sequence.
+     *
+     * Finds the first migration whose version is greater than currentVersion.
+     * Since migrations are sorted, this is the starting point for running updates.
+     *
+     * Example:
+     * - currentVersion: "3.5.0"
+     * - migrations: ["2.0.0", "3.0.0", "4.0.0", "5.0.0"]
+     * - returns: index 2 (migration "4.0.0")
+     *
+     * @returns Index of first migration to run, or -1 if none found
+     */
+    private findFirstMigrationIndex;
+    /**
+     * Recursively apply all updates.
+     *
+     * Runs migrations sequentially starting from migrationIndex.
+     * After each successful migration, the version is persisted immediately.
+     *
+     * Why persist after each migration?
+     * - If the app crashes or migration is interrupted, we don't re-run
+     *   already completed migrations on next startup
+     * - Each migration should be idempotent to handle this scenario
+     *
+     * @param migrationIndex - Index in migrations array to start from
+     * @throws Rethrows any error from migration.up() to halt the process
+     */
+    private applyUpdates;
+    /**
+     * https://gist.github.com/alexey-bass/1115557
+     * Simply compares left version to right one.
+     *
+     * Compares semantic version strings numerically, part by part.
+     * Handles versions with different segment counts (e.g., "1.2" vs "1.2.3").
+     *
+     * Examples:
+     * versionCompare('1.1', '1.2') => -1  (1.1 is lower)
+     * versionCompare('1.1', '1.1') =>  0  (equal)
+     * versionCompare('1.2', '1.1') =>  1  (1.2 is higher)
+     * versionCompare('2.23.3', '2.22.3') => 1
+     * versionCompare('1.0', '1.0.1') => -1  (missing segments treated as 0)
+     *
+     * Returns:
+     * -1 = left is LOWER than right
+     *  0 = they are equal (or invalid input)
+     *  1 = left is GREATER than right
+     *
+     * Note: Returns 0 for invalid input instead of throwing
+     *
+     * @param left - First version string (e.g., "1.2.3")
+     * @param right - Second version string (e.g., "1.2.4")
+     */
+    private static versionCompare;
+}

package/dist/MigrationManager.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const t=require("tslib");class i{constructor(t,e,r,s){this.migrations=t,this.newVersion=e,this.currentVersion=r,this.updateVersion=s;this.migrations.sort(((t,e)=>{const r=i.versionCompare(t.version,e.version);return 1===r?1:-1===r?-1:0}))}run(){return t.__awaiter(this,void 0,void 0,(function*(){const t=yield this.currentVersion(),i=yield this.newVersion();if(t!==i){if(!this.currentVersion)return console.log(`First run - setting version to ${i}`),void(yield this.updateVersion(i));const e=this.findFirstMigrationIndex(t);if(e<0)return;yield this.applyUpdates(e)}}))}findFirstMigrationIndex(t){if(!this.migrations.length)return-1;let e=-1;return this.migrations.some(((r,s)=>1===i.versionCompare(r.version,t)&&(e=s,!0))),e}applyUpdates(i){return t.__awaiter(this,void 0,void 0,(function*(){const t=this.migrations[i];try{console.log(`Update: ${t.version} ${t.name||""}`),yield t.up(),yield this.updateVersion(t.version)}catch(t){throw console.error(t),t}this.migrations.length-1<=i||(yield this.applyUpdates(i+1))}))}static versionCompare(t,i){if(typeof t+typeof i!="stringstring")return 0;const e=t.split("."),r=i.split("."),s=Math.max(e.length,r.length);for(let t=0;t<s;t++){if(e[t]&&!r[t]&&parseInt(e[t],10)>0||parseInt(e[t],10)>parseInt(r[t],10))return 1;if(r[t]&&!e[t]&&parseInt(r[t],10)>0||parseInt(e[t],10)<parseInt(r[t],10))return-1}return 0}}exports.default=i;

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './sentry.js';
 export * from './errors.js';
 export * from './platform.js';
 export * from './uuid.js';
+export * from './MigrationManager.js';

package/dist/index.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.device=exports.string=void 0;const e=require("tslib");var r=require("./string.js");Object.defineProperty(exports,"string",{enumerable:!0,get:function(){return e.__importDefault(r).default}});var t=require("./device.js");Object.defineProperty(exports,"device",{enumerable:!0,get:function(){return e.__importDefault(t).default}}),e.__exportStar(require("./deferred.js"),exports),e.__exportStar(require("./date.js"),exports),e.__exportStar(require("./image.js"),exports),e.__exportStar(require("./location.js"),exports),e.__exportStar(require("./type.js"),exports),e.__exportStar(require("./sentry.js"),exports),e.__exportStar(require("./errors.js"),exports),e.__exportStar(require("./platform.js"),exports),e.__exportStar(require("./uuid.js"),exports);
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.device=exports.string=void 0;const e=require("tslib");var r=require("./string.js");Object.defineProperty(exports,"string",{enumerable:!0,get:function(){return e.__importDefault(r).default}});var t=require("./device.js");Object.defineProperty(exports,"device",{enumerable:!0,get:function(){return e.__importDefault(t).default}}),e.__exportStar(require("./deferred.js"),exports),e.__exportStar(require("./date.js"),exports),e.__exportStar(require("./image.js"),exports),e.__exportStar(require("./location.js"),exports),e.__exportStar(require("./type.js"),exports),e.__exportStar(require("./sentry.js"),exports),e.__exportStar(require("./errors.js"),exports),e.__exportStar(require("./platform.js"),exports),e.__exportStar(require("./uuid.js"),exports),e.__exportStar(require("./MigrationManager.js"),exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumens/utils",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {