@s-libs/js-core
    Preparing search index...

    Class MigrationManager<T>

    Use to migrate "versioned objects" from an old version to the latest. This is useful e.g. when keeping state in Persistence, and you release a new version of your app that changes its format.

    For example, say your app persists an object with the shape { _version: 3, key_1: string }. You change your code to remove the underscore from key_1, so you want to migrate data on users' machines accordingly. Bump your version to 4 and use MigrationManager like this:

    interface MyData extends VersionedObject {
      _version: number;
      key1: string;
    }

    // simulate old data in the previous format
    const persistence = new Persistence<MyData>('my key');
    persistence.put({ _version: 3, key_1: 'my string' } as any);

    const migrater = new MigrationManager<MyData>();
    migrater.registerMigration(3, (oldObject: any) => {
      return { _version: 4, key1: oldObject.key_1 };
    });

    const defaultData = { _version: 4, key1: 'default value' };
    migrater.run(persistence, defaultData);
    // ^ returns { _version: 4, key1: 'my string' }

    persistence.clear();
    migrater.run(persistence, defaultData);
    // ^ returns defaultData

    Type Parameters

    Index

    Constructors

    constructor

    Methods

    onError registerMigration run upgrade

    Constructors

    Methods

    • Handles errors thrown by a registered migration during run(). This is not used if upgrade() is called directly.

      This implementation simply rethrows the error so that it propagates out of run(). If overridden to return a value, that will be used as the result of run().

      You could use this to e.g. to provide a nice message to the user explaining that their data couldn't be recovered, and use the default value.

      Parameters

      • error: any
      • _object: unknown

        the object taken from persistence, before any migrations ran

      • _defaultValue: T

        the default value passed to run()

      Returns T

    • Registers a function to update an object that is currently at sourceVersion. The function must return a new object at a higher version number. Most commonly each migration will upgrade the object by only 1 version. The output of the older migrations will be passed in turn to newer migrations until the target version is reached.

      Use undefined as the sourceVersion to handle migrations from a legacy format that did not have the _version key.

      migrateFunction will be called with the migration manager itself as this. That allows subclasses to pass in methods as a migration function without any special binding. E.g.:

      class MigrationService extends MigrationManager<MyState> {
        constructor(private messaging: MessagingService) {
          super();
          this.registerMigration(1, this.#migrateFrom1); // no special binding
        }

        #migrateFrom1(source: MyState): MyState {
          this.messaging.show("You've been upgraded!"); // you can still use `this`
          return { ...source, _version: 2 };
        }
      }

      Parameters

      Returns void

    • Returns the value from persistence, upgraded to match the version in defaultValue. If persistence was empty, returns defaultValue directly. Updates peristence to reflect the returned value.

      If an error is thrown by a migration, see onError() for details.

      Parameters

      Returns T

    • Runs any registered migrations necessary to convert source to targetVersion. If it is already at targetVersion, no migrations run and it is returned unmodified.

      If you are using Persistence you will probably not call this directly; use .run() instead.

      Parameters

      • object: T
      • targetVersion: number

      Returns T

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods