LocalData/Documentation/Migration.md

LocalData Migration Guide

Overview

LocalData provides built-in support for migrating data from legacy storage locations or keys to modern StorageKey definitions.

Automatic Migration

When calling get(_:) on a key, the StorageRouter automatically:

1. Checks the primary location.
2. If not found, iterates through migrationSources defined on the key.
3. If data is found in a source:
   • Unsecures it using the source's old policy.
   • Re-secures it using the new key's policy.
   • Stores it in the new location.
   • Deletes the legacy data.
   • Returns the value.

Proactive Migration (Sweep)

You can trigger a sweep of all registered keys at app launch:

try await StorageRouter.shared.registerCatalog(MyCatalog.self, migrateImmediately: true)

This iterates through all keys in the catalog and calls migrate(for:) on each, ensuring all legacy data is consolidated.

Defining Migration Sources

When defining a StorageKey, add legacy descriptors to the migrationSources array:

struct MyNewKey: StorageKey {
    // ...
    var migrationSources: [AnyStorageKey] {
        [
            .key(LegacyKey(name: "old_key_name", domain: .userDefaults(suite: nil)))
        ]
    }
}