diff --git a/README.md b/README.md index ff1a250..e201830 100644 --- a/README.md +++ b/README.md @@ -268,7 +268,9 @@ try await StorageRouter.shared.forceMigration(for: StorageKey.modernToken) #### Automated Startup Sweep When registering a catalog, you can enable `migrateImmediately` to perform a global sweep of all legacy keys for every key in the catalog. -> [!NOTE] +> [!IMPORTANT] +> **Catalog Enforcement**: Once any catalog is registered, *all* storage operations require the key to be in a registered catalog. Any unregistered key will throw `StorageError.unregisteredKey`. +> > **Modular Registration**: `registerCatalog` is additive. You can call it multiple times from different modules to build an aggregate registry. The library will throw an error if multiple catalogs attempt to register the same key name. ```swift diff --git a/Sources/LocalData/Documentation.docc/GettingStarted.md b/Sources/LocalData/Documentation.docc/GettingStarted.md index fae9d78..e5541ee 100644 --- a/Sources/LocalData/Documentation.docc/GettingStarted.md +++ b/Sources/LocalData/Documentation.docc/GettingStarted.md @@ -35,6 +35,10 @@ await StorageRouter.shared.updateStorageConfiguration(storageConfig) Catalogs are mandatory if you want auditing and duplicate detection. +> [!IMPORTANT] +> Once any catalog is registered, *all* storage operations require the key to be present in a registered catalog. +> Unregistered keys will throw `StorageError.unregisteredKey`. + ```swift struct AuthCatalog: StorageKeyCatalog { let allKeys: [AnyStorageKey] = [ diff --git a/Sources/LocalData/Documentation.docc/KeyAndCatalogDiscipline.md b/Sources/LocalData/Documentation.docc/KeyAndCatalogDiscipline.md index f0e0c59..f473910 100644 --- a/Sources/LocalData/Documentation.docc/KeyAndCatalogDiscipline.md +++ b/Sources/LocalData/Documentation.docc/KeyAndCatalogDiscipline.md @@ -18,6 +18,10 @@ Catalog registration enforces correctness: - Duplicate key names across catalogs are rejected. - Unregistered keys throw ``StorageError/unregisteredKey(_:)`` at runtime. +> [!IMPORTANT] +> Once any catalog is registered, *all* storage operations require keys to be registered. +> If you add a new module or feature, you must register its catalog before using its keys. + If you skip catalog registration, LocalData cannot guarantee that all writes are auditable. ## Modular catalogs diff --git a/Sources/LocalData/Services/StorageRouter.swift b/Sources/LocalData/Services/StorageRouter.swift index 04817de..d6ceecc 100644 --- a/Sources/LocalData/Services/StorageRouter.swift +++ b/Sources/LocalData/Services/StorageRouter.swift @@ -89,7 +89,10 @@ public actor StorageRouter: StorageProviding { } /// Registers a catalog of known storage keys for audit and validation. - /// When registered, all storage operations will verify keys are listed. + /// + /// - Important: Once any catalog is registered, *all* storage operations require keys + /// to be present in a registered catalog. Unregistered keys throw + /// ``StorageError/unregisteredKey(_:)``. /// - Parameters: /// - catalog: The catalog type to register. /// - migrateImmediately: If true, triggers a proactive migration (sweep) for all keys in the catalog.