@platforma-sdk/model 1.52.7 → 1.53.1

package/src/block_migrations.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DataModel,
+  defaultRecover,
+  defineDataVersions,
+  makeDataVersioned,
+} from './block_migrations';
+
+describe('defineDataVersions', () => {
+  it('throws on duplicate version values', () => {
+    expect(() =>
+      defineDataVersions({
+        V1: 'v1',
+        V2: 'v1', // duplicate!
+      }),
+    ).toThrow('Duplicate version values: v1');
+  });
+
+  it('throws on empty version values', () => {
+    expect(() =>
+      defineDataVersions({
+        V1: 'v1',
+        V2: '', // empty!
+      }),
+    ).toThrow('Version values must be non-empty strings (empty: V2)');
+  });
+
+  it('allows unique version values', () => {
+    const versions = defineDataVersions({
+      V1: 'v1',
+      V2: 'v2',
+    });
+    expect(versions.V1).toBe('v1');
+    expect(versions.V2).toBe('v2');
+  });
+});
+
+describe('makeDataVersioned', () => {
+  it('creates correct DataVersioned shape', () => {
+    const versioned = makeDataVersioned('v1', { count: 42 });
+    expect(versioned).toStrictEqual({ version: 'v1', data: { count: 42 } });
+  });
+});
+
+describe('DataModel migrations', () => {
+  it('resets to initial data on unknown version', () => {
+    const Version = {
+      V1: 'v1',
+      V2: 'v2',
+    } as const;
+
+    type VersionedData = {
+      [Version.V1]: { count: number };
+      [Version.V2]: { count: number; label: string };
+    };
+
+    const dataModel = DataModel
+      .from<VersionedData>(Version.V1)
+      .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+      .create(() => ({ count: 0, label: '' }));
+
+    const result = dataModel.migrate(makeDataVersioned('legacy', { count: 42 }));
+    expect(result.version).toBe('v2');
+    expect(result.data).toStrictEqual({ count: 0, label: '' });
+    expect(result.warning).toBe(`Unknown version 'legacy'`);
+  });
+
+  it('uses recover() for unknown versions', () => {
+    const Version = {
+      V1: 'v1',
+      V2: 'v2',
+    } as const;
+
+    type VersionedData = {
+      [Version.V1]: { count: number };
+      [Version.V2]: { count: number; label: string };
+    };
+
+    const dataModel = DataModel
+      .from<VersionedData>(Version.V1)
+      .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+      .recover((version, data) => {
+        if (version === 'legacy' && typeof data === 'object' && data !== null && 'count' in data) {
+          return { count: (data as { count: number }).count, label: 'recovered' };
+        }
+        return defaultRecover(version, data);
+      })
+      .create(() => ({ count: 0, label: '' }));
+
+    const result = dataModel.migrate(makeDataVersioned('legacy', { count: 7 }));
+    expect(result.version).toBe('v2');
+    expect(result.data).toStrictEqual({ count: 7, label: 'recovered' });
+    expect(result.warning).toBeUndefined();
+  });
+
+  it('allows recover() to delegate to defaultRecover', () => {
+    const Version = {
+      V1: 'v1',
+      V2: 'v2',
+    } as const;
+
+    type VersionedData = {
+      [Version.V1]: { count: number };
+      [Version.V2]: { count: number; label: string };
+    };
+
+    const dataModel = DataModel
+      .from<VersionedData>(Version.V1)
+      .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+      .recover((version, data) => defaultRecover(version, data))
+      .create(() => ({ count: 0, label: '' }));
+
+    const result = dataModel.migrate(makeDataVersioned('legacy', { count: 7 }));
+    expect(result.version).toBe('v2');
+    expect(result.data).toStrictEqual({ count: 0, label: '' });
+    expect(result.warning).toBe(`Unknown version 'legacy'`);
+  });
+
+  it('returns initial data on migration failure', () => {
+    const Version = {
+      V1: 'v1',
+      V2: 'v2',
+    } as const;
+
+    type VersionedData = {
+      [Version.V1]: { numbers: number[] };
+      [Version.V2]: { numbers: number[]; label: string };
+    };
+
+    const dataModel = DataModel
+      .from<VersionedData>(Version.V1)
+      .migrate(Version.V2, (v1) => {
+        if (v1.numbers.includes(666)) {
+          throw new Error('Forbidden number');
+        }
+        return { ...v1, label: 'ok' };
+      })
+      .create(() => ({ numbers: [], label: '' }));
+
+    const result = dataModel.migrate(makeDataVersioned('v1', { numbers: [666] }));
+    expect(result.version).toBe('v2');
+    expect(result.data).toStrictEqual({ numbers: [], label: '' });
+    expect(result.warning).toBe(`Migration v1→v2 failed: Forbidden number`);
+  });
+});
+
+// Compile-time typing checks
+const Version = defineDataVersions({
+  V1: 'v1',
+  V2: 'v2',
+});
+
+type VersionedData = {
+  [Version.V1]: { count: number };
+  [Version.V2]: { count: number; label: string };
+};
+
+DataModel
+  .from<VersionedData>(Version.V1)
+  .migrate(Version.V2, (v1) => ({ ...v1, label: '' }))
+  .create(() => ({ count: 0, label: '' }));
+
+// @ts-expect-error invalid initial version key
+DataModel.from<VersionedData>('v3');
+
+// @ts-expect-error invalid migration target key
+DataModel.from<VersionedData>(Version.V1).migrate('v3', (v1) => ({ ...v1, label: '' }));
+
+// @ts-expect-error migration return type must match target version
+DataModel.from<VersionedData>(Version.V1).migrate(Version.V2, (v1) => ({ ...v1, invalid: true }));

package/src/block_migrations.ts

@@ -1,43 +1,148 @@
 import { tryRegisterCallback } from './internal';
-import { createBlockStorage } from './block_storage';
+import { createBlockStorage, DATA_MODEL_DEFAULT_VERSION } from './block_storage';
 
-export type MigrationFn<From, To> = (prev: Readonly<From>) => To;
+export type DataVersionKey = string;
+export type DataVersionMap = Record<string, unknown>;
+export type DataMigrateFn<From, To> = (prev: Readonly<From>) => To;
+export type DataCreateFn<T> = () => T;
+export type DataRecoverFn<T> = (version: DataVersionKey, data: unknown) => T;
+
+/**
+ * Helper to define version keys with literal type inference and runtime validation.
+ * - Validates that all version values are unique
+ * - Eliminates need for `as const` assertion
+ *
+ * @throws Error if duplicate version values are found
+ *
+ * @example
+ * const Version = defineDataVersions({
+ *   Initial: 'v1',
+ *   AddedLabels: 'v2',
+ * });
+ *
+ * type VersionedData = {
+ *   [Version.Initial]: DataV1;
+ *   [Version.AddedLabels]: DataV2;
+ * };
+ */
+export function defineDataVersions<const T extends Record<string, string>>(versions: T): T {
+  const values = Object.values(versions);
+  const emptyKeys = Object.keys(versions).filter((key) => versions[key] === '');
+  if (emptyKeys.length > 0) {
+    throw new Error(`Version values must be non-empty strings (empty: ${emptyKeys.join(', ')})`);
+  }
+  const unique = new Set(values);
+  if (unique.size !== values.length) {
+    const duplicates = values.filter((v, i) => values.indexOf(v) !== i);
+    throw new Error(`Duplicate version values: ${[...new Set(duplicates)].join(', ')}`);
+  }
+  return versions;
+}
 
 /** Versioned data wrapper for persistence */
-export type Versioned<T> = {
-  version: number;
+export type DataVersioned<T> = {
+  version: DataVersionKey;
   data: T;
 };
 
-/** Result of upgrade operation, may include warning if migration failed */
-export type UpgradeResult<T> = Versioned<T> & {
+/** Create a DataVersioned wrapper with correct shape */
+export function makeDataVersioned<T>(version: DataVersionKey, data: T): DataVersioned<T> {
+  return { version, data };
+}
+
+/** Result of migration operation, may include warning if migration failed */
+export type DataMigrationResult<T> = DataVersioned<T> & {
   warning?: string;
 };
 
+/** Thrown by recover() to signal unrecoverable data. */
+export class DataUnrecoverableError extends Error {
+  name = 'DataUnrecoverableError';
+  constructor(dataVersion: DataVersionKey) {
+    super(`Unknown version '${dataVersion}'`);
+  }
+}
+
+export function isDataUnrecoverableError(error: unknown): error is DataUnrecoverableError {
+  return error instanceof Error && error.name === 'DataUnrecoverableError';
+}
+
+type MigrationStep = {
+  fromVersion: DataVersionKey;
+  toVersion: DataVersionKey;
+  migrate: (data: unknown) => unknown;
+};
+
+/** Default recover function for unknown versions */
+export const defaultRecover: DataRecoverFn<never> = (version, _data) => {
+  throw new DataUnrecoverableError(version);
+};
+
 /** Internal builder for chaining migrations */
-class DataModelBuilder<State> {
-  private readonly migrationSteps: Array<(x: unknown) => unknown>;
+class DataModelBuilder<
+  VersionedData extends DataVersionMap,
+  CurrentVersion extends keyof VersionedData & string,
+> {
+  private readonly versionChain: DataVersionKey[];
+  private readonly migrationSteps: MigrationStep[];
+  private readonly recoverFn?: DataRecoverFn<VersionedData[CurrentVersion]>;
 
-  private constructor(steps: Array<(x: unknown) => unknown> = []) {
+  private constructor(
+    versionChain: DataVersionKey[],
+    steps: MigrationStep[] = [],
+    recoverFn?: DataRecoverFn<VersionedData[CurrentVersion]>,
+  ) {
+    this.versionChain = versionChain;
     this.migrationSteps = steps;
+    this.recoverFn = recoverFn;
   }
 
-  /** Start a migration chain from an initial type */
-  static from<T = unknown>(): DataModelBuilder<T> {
-    return new DataModelBuilder<T>();
+  /** Start a migration chain from an initial version */
+  static from<
+    VersionedData extends DataVersionMap,
+    InitialVersion extends keyof VersionedData & string = keyof VersionedData & string,
+  >(initialVersion: InitialVersion): DataModelBuilder<VersionedData, InitialVersion> {
+    return new DataModelBuilder<VersionedData, InitialVersion>([initialVersion]);
   }
 
-  /** Add a migration step */
-  migrate<Next>(fn: MigrationFn<State, Next>): DataModelBuilder<Next> {
-    return new DataModelBuilder<Next>([...this.migrationSteps, fn as any]);
+  /** Add a migration step to the target version */
+  migrate<NextVersion extends keyof VersionedData & string>(
+    nextVersion: NextVersion,
+    fn: DataMigrateFn<VersionedData[CurrentVersion], VersionedData[NextVersion]>,
+  ): DataModelBuilder<VersionedData, NextVersion> {
+    if (this.versionChain.includes(nextVersion)) {
+      throw new Error(`Duplicate version '${nextVersion}' in migration chain`);
+    }
+    const fromVersion = this.versionChain[this.versionChain.length - 1];
+    const step: MigrationStep = { fromVersion, toVersion: nextVersion, migrate: fn as (data: unknown) => unknown };
+    return new DataModelBuilder<VersionedData, NextVersion>(
+      [...this.versionChain, nextVersion],
+      [...this.migrationSteps, step],
+    );
+  }
+
+  /** Set recovery handler for unknown or unsupported versions */
+  recover(
+    fn: DataRecoverFn<VersionedData[CurrentVersion]>,
+  ): DataModelBuilder<VersionedData, CurrentVersion> {
+    return new DataModelBuilder<VersionedData, CurrentVersion>(
+      [...this.versionChain],
+      [...this.migrationSteps],
+      fn,
+    );
   }
 
   /** Finalize with initial data, creating the DataModel */
-  create<S>(
-    initialData: () => S,
-    ..._: [State] extends [S] ? [] : [never]
+  create<S extends VersionedData[CurrentVersion]>(
+    initialData: DataCreateFn<S>,
+    ..._: [VersionedData[CurrentVersion]] extends [S] ? [] : [never]
   ): DataModel<S> {
-    return DataModel._fromBuilder<S>(this.migrationSteps, initialData);
+    return DataModel._fromBuilder<S>(
+      this.versionChain,
+      this.migrationSteps,
+      initialData,
+      this.recoverFn as DataRecoverFn<S> | undefined,
+    );
   }
 }
 
@@ -53,45 +158,79 @@ class DataModelBuilder<State> {
  * }));
  *
  * // Data model with migrations
+ * const Version = defineDataVersions({
+ *   V1: 'v1',
+ *   V2: 'v2',
+ *   V3: 'v3',
+ * });
+ *
+ * type VersionedData = {
+ *   [Version.V1]: { numbers: number[] };
+ *   [Version.V2]: { numbers: number[]; labels: string[] };
+ *   [Version.V3]: { numbers: number[]; labels: string[]; description: string };
+ * };
+ *
  * const dataModel = DataModel
- *   .from<V1>()
- *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2
- *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3
- *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));
+ *   .from<VersionedData>(Version.V1)
+ *   .migrate(Version.V2, (data) => ({ ...data, labels: [] }))
+ *   .migrate(Version.V3, (data) => ({ ...data, description: '' }))
+ *   .recover((version, data) => {
+ *     if (version === 'legacy' && typeof data === 'object' && data !== null && 'numbers' in data) {
+ *       return { numbers: (data as { numbers: number[] }).numbers, labels: [], description: '' };
+ *     }
+ *     return defaultRecover(version, data);
+ *   })
+ *   .create(() => ({ numbers: [], labels: [], description: '' }));
  */
 export class DataModel<State> {
-  private readonly steps: Array<(x: unknown) => unknown>;
-  private readonly _initialData: () => State;
+  private readonly versionChain: DataVersionKey[];
+  private readonly steps: MigrationStep[];
+  private readonly initialDataFn: () => State;
+  private readonly recoverFn: DataRecoverFn<State>;
 
-  private constructor(steps: Array<(x: unknown) => unknown>, initialData: () => State) {
+  private constructor(
+    versionChain: DataVersionKey[],
+    steps: MigrationStep[],
+    initialData: () => State,
+    recover: DataRecoverFn<State> = defaultRecover as DataRecoverFn<State>,
+  ) {
+    if (versionChain.length === 0) {
+      throw new Error('DataModel requires at least one version key');
+    }
+    this.versionChain = versionChain;
     this.steps = steps;
-    this._initialData = initialData;
+    this.initialDataFn = initialData;
+    this.recoverFn = recover;
   }
 
   /** Start a migration chain from an initial type */
-  static from<S>(): DataModelBuilder<S> {
-    return DataModelBuilder.from<S>();
+  static from<
+    VersionedData extends DataVersionMap,
+    InitialVersion extends keyof VersionedData & string = keyof VersionedData & string,
+  >(initialVersion: InitialVersion): DataModelBuilder<VersionedData, InitialVersion> {
+    return DataModelBuilder.from<VersionedData, InitialVersion>(initialVersion);
   }
 
   /** Create a data model with just initial data (no migrations) */
-  static create<S>(initialData: () => S): DataModel<S> {
-    return new DataModel<S>([], initialData);
+  static create<S>(initialData: () => S, version: DataVersionKey = DATA_MODEL_DEFAULT_VERSION): DataModel<S> {
+    return new DataModel<S>([version], [], initialData);
   }
 
   /** Create from builder (internal use) */
   static _fromBuilder<S>(
-    steps: Array<(x: unknown) => unknown>,
+    versionChain: DataVersionKey[],
+    steps: MigrationStep[],
     initialData: () => S,
+    recover?: DataRecoverFn<S>,
   ): DataModel<S> {
-    return new DataModel<S>(steps, initialData);
+    return new DataModel<S>(versionChain, steps, initialData, recover);
   }
 
   /**
-   * Latest version number.
-   * Version 1 = initial state, each migration adds 1.
+   * Latest version key.
    */
-  get version(): number {
-    return this.steps.length + 1;
+  get version(): DataVersionKey {
+    return this.versionChain[this.versionChain.length - 1];
   }
 
   /** Number of migration steps */
@@ -101,50 +240,56 @@ export class DataModel<State> {
 
   /** Get initial data */
   initialData(): State {
-    return this._initialData();
+    return this.initialDataFn();
   }
 
   /** Get default data wrapped with current version */
-  getDefaultData(): Versioned<State> {
-    return { version: this.version, data: this._initialData() };
+  getDefaultData(): DataVersioned<State> {
+    return makeDataVersioned(this.version, this.initialDataFn());
+  }
+
+  private recoverFrom(data: unknown, version: DataVersionKey): DataMigrationResult<State> {
+    try {
+      return { version: this.version, data: this.recoverFn(version, data) };
+    } catch (error) {
+      if (isDataUnrecoverableError(error)) {
+        return { ...this.getDefaultData(), warning: error.message };
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        ...this.getDefaultData(),
+        warning: `Recover failed for version '${version}': ${errorMessage}`,
+      };
+    }
   }
 
   /**
-   * Upgrade versioned data from any version to the latest.
+   * Migrate versioned data from any version to the latest.
    * Applies only the migrations needed (skips already-applied ones).
    * If a migration fails, returns default data with a warning.
    */
-  upgrade(versioned: Versioned<unknown>): UpgradeResult<State> {
+  migrate(versioned: DataVersioned<unknown>): DataMigrationResult<State> {
     const { version: fromVersion, data } = versioned;
 
-    if (fromVersion > this.version) {
-      throw new Error(
-        `Cannot downgrade from version ${fromVersion} to ${this.version}`,
-      );
-    }
-
     if (fromVersion === this.version) {
       return { version: this.version, data: data as State };
     }
 
-    // Apply migrations starting from (fromVersion - 1) index
-    // Version 1 -> no migrations applied yet -> start at index 0
-    // Version 2 -> migration[0] already applied -> start at index 1
-    const startIndex = fromVersion - 1;
-    const migrationsToApply = this.steps.slice(startIndex);
+    const startIndex = this.versionChain.indexOf(fromVersion);
+    if (startIndex < 0) {
+      return this.recoverFrom(data, fromVersion);
+    }
 
     let currentData: unknown = data;
-    for (let i = 0; i < migrationsToApply.length; i++) {
-      const stepIndex = startIndex + i;
-      const fromVer = stepIndex + 1;
-      const toVer = stepIndex + 2;
+    for (let i = startIndex; i < this.steps.length; i++) {
+      const step = this.steps[i];
       try {
-        currentData = migrationsToApply[i](currentData);
+        currentData = step.migrate(currentData);
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         return {
           ...this.getDefaultData(),
-          warning: `Migration v${fromVer}→v${toVer} failed: ${errorMessage}`,
+          warning: `Migration ${step.fromVersion}→${step.toVersion} failed: ${errorMessage}`,
         };
       }
     }
@@ -158,12 +303,12 @@ export class DataModel<State> {
    *
    * All callbacks are prefixed with `__pl_` to indicate internal SDK use:
    * - `__pl_data_initial`: returns initial data for new blocks
-   * - `__pl_data_upgrade`: upgrades versioned data from any version to latest
+   * - `__pl_data_migrate`: migrates versioned data from any version to latest
    * - `__pl_storage_initial`: returns initial BlockStorage as JSON string
    */
   registerCallbacks(): void {
-    tryRegisterCallback('__pl_data_initial', () => this._initialData());
-    tryRegisterCallback('__pl_data_upgrade', (versioned: Versioned<unknown>) => this.upgrade(versioned));
+    tryRegisterCallback('__pl_data_initial', () => this.initialDataFn());
+    tryRegisterCallback('__pl_data_migrate', (versioned: DataVersioned<unknown>) => this.migrate(versioned));
     tryRegisterCallback('__pl_storage_initial', () => {
       const { version, data } = this.getDefaultData();
       const storage = createBlockStorage(data, version);