# 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:
```swift
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:
```swift
struct MyNewKey: StorageKey {
    // ...
    var migrationSources: [AnyStorageKey] {
        [
            .key(LegacyKey(name: "old_key_name", domain: .userDefaults(suite: nil)))
        ]
    }
}
```