@wemush/wols 0.1.0 → 1.2.0

package/dist/types/utils/migration.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Version Migration Utilities
+ *
+ * This module provides utilities for comparing WOLS versions and
+ * migrating specimens between versions.
+ *
+ * @module utils/migration
+ * @since 1.2.0
+ */
+import type { Specimen } from '../types.js';
+/**
+ * Version comparison result.
+ *
+ * - `-1`: First version is older than second
+ * - `0`: Versions are equal
+ * - `1`: First version is newer than second
+ *
+ * @since 1.2.0
+ */
+export type VersionComparison = -1 | 0 | 1;
+/**
+ * Migration handler function signature.
+ *
+ * @since 1.2.0
+ */
+export type MigrationHandler = (specimen: Specimen) => Specimen;
+/**
+ * Migration definition.
+ *
+ * @since 1.2.0
+ */
+interface MigrationDefinition {
+    from: string;
+    to: string;
+    handler: MigrationHandler;
+}
+/**
+ * Compare two semantic versions.
+ *
+ * @param a - First version string
+ * @param b - Second version string
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ *
+ * @example
+ * ```typescript
+ * compareVersions('1.0.0', '1.1.0') // Returns -1
+ * compareVersions('1.1.0', '1.1.0') // Returns 0
+ * compareVersions('2.0.0', '1.9.0') // Returns 1
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function compareVersions(a: string, b: string): VersionComparison;
+/**
+ * Check if a specimen is using an outdated WOLS version.
+ *
+ * @param specimen - Specimen object or version string
+ * @returns True if the specimen version is older than current library version
+ *
+ * @example
+ * ```typescript
+ * isOutdated(specimen) // True if specimen.version < WOLS_VERSION
+ * isOutdated('1.0.0')  // True (older than current)
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function isOutdated(specimen: Specimen | string): boolean;
+/**
+ * Check if a specimen is using a newer WOLS version than this library.
+ *
+ * This can happen when specimens are created by a newer library version.
+ *
+ * @param specimen - Specimen object or version string
+ * @returns True if the specimen version is newer than current library version
+ *
+ * @example
+ * ```typescript
+ * isNewer(specimen)  // True if specimen.version > WOLS_VERSION
+ * isNewer('2.0.0')   // True if library is 1.x
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function isNewer(specimen: Specimen | string): boolean;
+/**
+ * Get the current library WOLS version.
+ *
+ * @returns The WOLS version this library implements
+ *
+ * @since 1.2.0
+ */
+export declare function getCurrentVersion(): string;
+/**
+ * Register a migration handler for upgrading specimens between versions.
+ *
+ * Migrations are applied in order from oldest to newest when calling `migrate()`.
+ *
+ * @param from - Source version (e.g., "1.0.0")
+ * @param to - Target version (e.g., "1.1.0")
+ * @param handler - Function to transform the specimen
+ *
+ * @example
+ * ```typescript
+ * registerMigration('1.0.0', '1.1.0', (specimen) => {
+ *   // Add new required field with default value
+ *   return { ...specimen, newField: 'default' };
+ * });
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function registerMigration(from: string, to: string, handler: MigrationHandler): void;
+/**
+ * Check if a specimen can be migrated to the current version.
+ *
+ * @param specimen - Specimen to check
+ * @returns True if migration path exists, false otherwise
+ *
+ * @since 1.2.0
+ */
+export declare function canMigrate(specimen: Specimen): boolean;
+/**
+ * Migrate a specimen to the current WOLS version.
+ *
+ * Applies all registered migrations in order from the specimen's version
+ * to the current library version.
+ *
+ * @param specimen - Specimen to migrate
+ * @returns Migrated specimen with updated version
+ * @throws Error if no migration path exists
+ *
+ * @example
+ * ```typescript
+ * const oldSpecimen = parseSpecimen(oldJson);
+ * if (isOutdated(oldSpecimen)) {
+ *   const updated = migrate(oldSpecimen);
+ *   console.log('Migrated to:', updated.version);
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function migrate(specimen: Specimen): Specimen;
+/**
+ * Get all registered migrations.
+ *
+ * @returns Array of migration definitions
+ *
+ * @since 1.2.0
+ */
+export declare function getMigrations(): readonly MigrationDefinition[];
+/**
+ * Clear all registered migrations.
+ *
+ * Primarily useful for testing.
+ *
+ * @since 1.2.0
+ */
+export declare function clearMigrations(): void;
+export {};
+//# sourceMappingURL=migration.d.ts.map

package/dist/types/utils/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../src/utils/migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAO5C;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE3C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,QAAQ,CAAC;AAEhE;;;;GAIG;AACH,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAgCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAmBvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,CAG/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,CAG5D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAK3F;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAiBtD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAiCpD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,SAAS,mBAAmB,EAAE,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/types/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAGL,KAAK,QAAQ,EAGb,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAGtB,MAAM,YAAY,CAAC;AAmZpB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,GAAG,OAAO,EAC5B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CA+ClB"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAGL,KAAK,QAAQ,EAGb,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAGtB,MAAM,YAAY,CAAC;AAkepB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,GAAG,OAAO,EAC5B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAgDlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wemush/wols",
-  "version": "0.1.0",
+  "version": "1.2.0",
   "description": "Official WOLS (WeMush Open Labeling Standard) library for specimen labeling and traceability",
   "type": "module",
   "main": "./dist/cjs/index.js",