@wemush/wols 0.1.0 → 1.3.0

package/dist/cjs/utils/environment.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * Environment Detection Utilities
+ *
+ * This module provides runtime environment detection for selecting
+ * appropriate crypto implementations and other environment-specific behavior.
+ *
+ * @module utils/environment
+ * @since 1.2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isServer = isServer;
+exports.isBrowser = isBrowser;
+exports.isWebWorker = isWebWorker;
+exports.isDeno = isDeno;
+exports.isBun = isBun;
+exports.getRuntimeEnvironment = getRuntimeEnvironment;
+exports.supportsWebCrypto = supportsWebCrypto;
+exports.supportsNodeCrypto = supportsNodeCrypto;
+exports.isCryptoSupported = isCryptoSupported;
+exports.supportsTextEncoding = supportsTextEncoding;
+exports.supportsURLAPIs = supportsURLAPIs;
+// =============================================================================
+// ENVIRONMENT DETECTION
+// =============================================================================
+/**
+ * Check if running in a server-side Node.js environment.
+ *
+ * @returns True if running in Node.js, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isServer()) {
+ *   // Use Node.js crypto module
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+function isServer() {
+    return (typeof globalThis !== 'undefined' &&
+        typeof globalThis.process
+            ?.versions?.node === 'string');
+}
+/**
+ * Check if running in a browser environment.
+ *
+ * @returns True if running in a browser, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isBrowser()) {
+ *   // Use Web Crypto API
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+function isBrowser() {
+    return (typeof globalThis !== 'undefined' &&
+        typeof globalThis.window !== 'undefined' &&
+        typeof globalThis.document !== 'undefined');
+}
+/**
+ * Check if running in a Web Worker environment.
+ *
+ * @returns True if running in a Web Worker, false otherwise
+ *
+ * @since 1.2.0
+ */
+function isWebWorker() {
+    // Check if WorkerGlobalScope exists and if self is an instance of it
+    // In a Web Worker, self instanceof WorkerGlobalScope is true
+    // In the main thread, WorkerGlobalScope doesn't exist or self is not an instance
+    if (typeof globalThis === 'undefined') {
+        return false;
+    }
+    const global = globalThis;
+    return (typeof global.WorkerGlobalScope !== 'undefined' &&
+        typeof global.self !== 'undefined' &&
+        global.self instanceof global.WorkerGlobalScope);
+}
+/**
+ * Check if running in Deno environment.
+ *
+ * @returns True if running in Deno, false otherwise
+ *
+ * @since 1.2.0
+ */
+function isDeno() {
+    return (typeof globalThis !== 'undefined' &&
+        typeof globalThis.Deno !== 'undefined');
+}
+/**
+ * Check if running in Bun environment.
+ *
+ * @returns True if running in Bun, false otherwise
+ *
+ * @since 1.2.0
+ */
+function isBun() {
+    return (typeof globalThis !== 'undefined' &&
+        typeof globalThis.Bun !== 'undefined');
+}
+/**
+ * Get the current runtime environment.
+ *
+ * @returns The detected runtime environment
+ *
+ * @example
+ * ```typescript
+ * const env = getRuntimeEnvironment();
+ * console.log(`Running in: ${env}`);
+ * ```
+ *
+ * @since 1.2.0
+ */
+function getRuntimeEnvironment() {
+    if (isBun())
+        return 'bun';
+    if (isDeno())
+        return 'deno';
+    if (isServer())
+        return 'node';
+    if (isWebWorker())
+        return 'webworker';
+    if (isBrowser())
+        return 'browser';
+    return 'unknown';
+}
+// =============================================================================
+// CRYPTO SUPPORT DETECTION
+// =============================================================================
+/**
+ * Check if Web Crypto API is available.
+ *
+ * @returns True if Web Crypto API is available, false otherwise
+ *
+ * @since 1.2.0
+ */
+function supportsWebCrypto() {
+    return (typeof globalThis !== 'undefined' &&
+        typeof globalThis.crypto?.subtle !==
+            'undefined');
+}
+/**
+ * Check if Node.js crypto module is available.
+ *
+ * Note: This performs a synchronous check and does not actually import the module.
+ *
+ * @returns True if likely running in Node.js with crypto support, false otherwise
+ *
+ * @since 1.2.0
+ */
+function supportsNodeCrypto() {
+    return isServer() || isBun();
+}
+/**
+ * Check if any cryptographic support is available.
+ *
+ * This is useful for determining if encryption/decryption features can be used.
+ *
+ * @returns True if crypto is supported, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isCryptoSupported()) {
+ *   const encrypted = await encryptSpecimen(specimen, { key: password });
+ * } else {
+ *   console.warn('Crypto not supported in this environment');
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+function isCryptoSupported() {
+    return supportsWebCrypto() || supportsNodeCrypto();
+}
+// =============================================================================
+// FEATURE DETECTION
+// =============================================================================
+/**
+ * Check if TextEncoder/TextDecoder are available.
+ *
+ * @returns True if text encoding is supported, false otherwise
+ *
+ * @since 1.2.0
+ */
+function supportsTextEncoding() {
+    return (typeof globalThis !== 'undefined' &&
+        typeof globalThis.TextEncoder !== 'undefined' &&
+        typeof globalThis.TextDecoder !== 'undefined');
+}
+/**
+ * Check if URL and URLSearchParams are available.
+ *
+ * @returns True if URL APIs are supported, false otherwise
+ *
+ * @since 1.2.0
+ */
+function supportsURLAPIs() {
+    return (typeof globalThis !== 'undefined' &&
+        typeof globalThis.URL !== 'undefined' &&
+        typeof globalThis.URLSearchParams !== 'undefined');
+}
+//# sourceMappingURL=environment.js.map

package/dist/cjs/utils/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../../src/utils/environment.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/iso8601.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ISO 8601 Date Utilities
+ *
+ * Provides parsing and formatting for ISO 8601 date strings
+ * as used in WOLS specimens.
+ *
+ * @module utils/iso8601
+ */
+/**
+ * Check if a string is a valid ISO 8601 date.
+ *
+ * @param value - The string to validate
+ * @returns true if valid ISO 8601 format
+ *
+ * @example
+ * ```typescript
+ * isValidISO8601('2025-12-16T10:30:00Z'); // true
+ * isValidISO8601('2025-12-16'); // false (date-only)
+ * isValidISO8601('invalid'); // false
+ * ```
+ */
+export declare function isValidISO8601(value: string): boolean;
+/**
+ * Check if a string is a valid date-only format (YYYY-MM-DD).
+ *
+ * @param value - The string to validate
+ * @returns true if valid date-only format
+ */
+export declare function isValidDateOnly(value: string): boolean;
+/**
+ * Get the current timestamp in ISO 8601 format.
+ *
+ * @returns Current time as ISO 8601 string
+ *
+ * @example
+ * ```typescript
+ * const now = getCurrentISO8601();
+ * // Returns: "2025-12-16T10:30:00.000Z"
+ * ```
+ */
+export declare function getCurrentISO8601(): string;
+/**
+ * Parse an ISO 8601 date string to a Date object.
+ *
+ * @param value - The ISO 8601 string to parse
+ * @returns The parsed Date, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const date = parseISO8601('2025-12-16T10:30:00Z');
+ * // Returns: Date object
+ *
+ * const invalid = parseISO8601('invalid');
+ * // Returns: null
+ * ```
+ */
+export declare function parseISO8601(value: string): Date | null;
+/**
+ * Format a Date object to ISO 8601 string.
+ *
+ * @param date - The Date to format
+ * @returns ISO 8601 string
+ */
+export declare function formatISO8601(date: Date): string;
+/**
+ * Get Unix timestamp (seconds since epoch) from ISO 8601 string.
+ *
+ * @param value - The ISO 8601 string
+ * @returns Unix timestamp in seconds, or null if invalid
+ */
+export declare function toUnixTimestamp(value: string): number | null;
+/**
+ * Convert Unix timestamp to ISO 8601 string.
+ *
+ * @param timestamp - Unix timestamp in seconds
+ * @returns ISO 8601 string
+ */
+export declare function fromUnixTimestamp(timestamp: number): string;
+//# sourceMappingURL=iso8601.d.ts.map

package/dist/cjs/utils/iso8601.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iso8601.d.ts","sourceRoot":"","sources":["../../../src/utils/iso8601.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAKvD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM5D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/cjs/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/cjs/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/cjs/utils/migration.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * Version Migration Utilities
+ *
+ * This module provides utilities for comparing WOLS versions and
+ * migrating specimens between versions.
+ *
+ * @module utils/migration
+ * @since 1.2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareVersions = compareVersions;
+exports.isOutdated = isOutdated;
+exports.isNewer = isNewer;
+exports.getCurrentVersion = getCurrentVersion;
+exports.registerMigration = registerMigration;
+exports.canMigrate = canMigrate;
+exports.migrate = migrate;
+exports.getMigrations = getMigrations;
+exports.clearMigrations = clearMigrations;
+const types_js_1 = require("../types.js");
+// =============================================================================
+// INTERNAL STATE
+// =============================================================================
+/**
+ * Registered migration handlers.
+ */
+const MIGRATION_REGISTRY = [];
+// =============================================================================
+// VERSION UTILITIES
+// =============================================================================
+/**
+ * Parse a semantic version string into components.
+ *
+ * @param version - Semantic version string (e.g., "1.2.0")
+ * @returns Array of [major, minor, patch] or null if invalid
+ */
+function parseVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+    if (!match)
+        return null;
+    const major = parseInt(match[1], 10);
+    const minor = parseInt(match[2], 10);
+    const patch = parseInt(match[3], 10);
+    return [major, minor, patch];
+}
+/**
+ * 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
+ */
+function compareVersions(a, b) {
+    const parsedA = parseVersion(a);
+    const parsedB = parseVersion(b);
+    if (!parsedA || !parsedB) {
+        // Fallback to string comparison for invalid versions
+        if (a < b)
+            return -1;
+        if (a > b)
+            return 1;
+        return 0;
+    }
+    const [majorA, minorA, patchA] = parsedA;
+    const [majorB, minorB, patchB] = parsedB;
+    if (majorA !== majorB)
+        return majorA < majorB ? -1 : 1;
+    if (minorA !== minorB)
+        return minorA < minorB ? -1 : 1;
+    if (patchA !== patchB)
+        return patchA < patchB ? -1 : 1;
+    return 0;
+}
+/**
+ * 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
+ */
+function isOutdated(specimen) {
+    const version = typeof specimen === 'string' ? specimen : specimen.version;
+    return compareVersions(version, types_js_1.WOLS_VERSION) < 0;
+}
+/**
+ * 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
+ */
+function isNewer(specimen) {
+    const version = typeof specimen === 'string' ? specimen : specimen.version;
+    return compareVersions(version, types_js_1.WOLS_VERSION) > 0;
+}
+/**
+ * Get the current library WOLS version.
+ *
+ * @returns The WOLS version this library implements
+ *
+ * @since 1.2.0
+ */
+function getCurrentVersion() {
+    return types_js_1.WOLS_VERSION;
+}
+// =============================================================================
+// MIGRATION REGISTRATION
+// =============================================================================
+/**
+ * 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
+ */
+function registerMigration(from, to, handler) {
+    MIGRATION_REGISTRY.push({ from, to, handler });
+    // Keep migrations sorted by source version
+    MIGRATION_REGISTRY.sort((a, b) => compareVersions(a.from, b.from));
+}
+/**
+ * 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
+ */
+function canMigrate(specimen) {
+    if (!isOutdated(specimen)) {
+        return false; // Already current or newer
+    }
+    // Check if we have a migration path
+    let currentVersion = specimen.version;
+    while (compareVersions(currentVersion, types_js_1.WOLS_VERSION) < 0) {
+        const migration = MIGRATION_REGISTRY.find(m => m.from === currentVersion);
+        if (!migration) {
+            return false; // No migration from this version
+        }
+        currentVersion = migration.to;
+    }
+    return true;
+}
+/**
+ * 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
+ */
+function migrate(specimen) {
+    if (!isOutdated(specimen)) {
+        return specimen; // Already current or newer
+    }
+    let current = specimen;
+    let currentVersion = specimen.version;
+    while (compareVersions(currentVersion, types_js_1.WOLS_VERSION) < 0) {
+        const migration = MIGRATION_REGISTRY.find(m => m.from === currentVersion);
+        if (!migration) {
+            throw new Error(`No migration path from version ${currentVersion} to ${types_js_1.WOLS_VERSION}. ` +
+                `Register a migration using registerMigration().`);
+        }
+        current = migration.handler(current);
+        currentVersion = migration.to;
+    }
+    // Ensure version is updated and consistent with the migration chain
+    if (currentVersion !== types_js_1.WOLS_VERSION) {
+        throw new Error(`Migration ended at version ${currentVersion}, but expected ${types_js_1.WOLS_VERSION}. ` +
+            `Check the registered migrations for incorrect target versions.`);
+    }
+    return {
+        ...current,
+        version: currentVersion,
+    };
+}
+/**
+ * Get all registered migrations.
+ *
+ * @returns Array of migration definitions
+ *
+ * @since 1.2.0
+ */
+function getMigrations() {
+    return MIGRATION_REGISTRY;
+}
+/**
+ * Clear all registered migrations.
+ *
+ * Primarily useful for testing.
+ *
+ * @since 1.2.0
+ */
+function clearMigrations() {
+    MIGRATION_REGISTRY.length = 0;
+}
+//# sourceMappingURL=migration.js.map