@mudlet/mudlet-web 0.4.5 → 1.0.0

package/dist-lib/storage/storageMigration.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Renaming the browser storage namespace from `mudix_*` to `mudlet_*`.
+ *
+ * The project was donated to Mudlet and renamed, but its storage kept the old
+ * name for one reason: the keys *are* the user's data. Change `mudix_v1` to
+ * `mudlet_v1` with nothing else, and every existing profile becomes unreachable
+ * — the app looks at the new name, finds nothing, and presents itself as a fresh
+ * install while the real data sits in the old keys until the browser evicts it.
+ * That is why CLAUDE.md forbade renaming these opportunistically.
+ *
+ * This module is what lifts that: it moves the data to the new names before
+ * anything reads them, once, per browser. What it covers:
+ *
+ *   localStorage   mudix_v1, mudix_vault_v1, mudix_analytics_opt_out,
+ *                  mudix_profile_migration_v21, mudix_stopwatches_<id>,
+ *                  mudix.debug*, and cmd.history.<id> (never prefixed at all)
+ *   IndexedDB      mudix_vfs_<connectionId> (one per profile), mudix_maps,
+ *                  mudix_logs, mudix_folder_handles
+ *
+ * The `.mudix/` directory *inside* each profile's filesystem is not here. It can
+ * only be touched with the profile mounted, so it is migrated lazily on open —
+ * see profileVfsData.ts.
+ *
+ * ## Ordering
+ *
+ * The two halves run at different times because they are read at different
+ * times, and both have to be in place before their first reader:
+ *
+ *   - **localStorage is synchronous and is read during module evaluation.**
+ *     Zustand's `persist` hydrates the store when appStore.ts is imported, and
+ *     the vault and analytics read their keys just as eagerly. So
+ *     {@link migrateLocalStorageNames} is synchronous and is called at the top
+ *     of each of those modules, before the read. It is memoised, so the call is
+ *     free after the first. Getting this wrong is not a cosmetic bug: the store
+ *     would hydrate empty and then persist that emptiness over the real data.
+ *
+ *   - **IndexedDB is asynchronous and is never read during import.** Every
+ *     database in the app is opened through one `openDb()` per module, so those
+ *     await {@link whenIdbNamesMigrated} and the rename lands before any reader.
+ *
+ * Doing it this way rather than in `main.tsx` is deliberate: branded builds
+ * import `MudletWebApp` directly and never run that entry, and they have the
+ * same data to protect.
+ *
+ * ## Interruption
+ *
+ * A copy is not a move, and a browser tab can close mid-way. Each database is
+ * therefore copied, verified, and only then is the original deleted — and the
+ * target is deleted before the copy starts, so a half-finished attempt from a
+ * previous run cannot be mistaken for a good one. Interrupted at any point, the
+ * next run either redoes that database or finds it already done. The completion
+ * markers are written last.
+ */
+/**
+ * Move every legacy localStorage key to its new name. Synchronous, idempotent
+ * and memoised — call it at the top of any module that reads storage during
+ * import, and as often as you like.
+ *
+ * A key already present under the new name wins: it is the live one, and an
+ * abandoned legacy key left over from an older build must not overwrite it.
+ */
+export declare function migrateLocalStorageNames(): void;
+/**
+ * Resolves once every legacy database has been renamed. Awaited by each module's
+ * `openDb()`, so no reader can see the old names.
+ *
+ * Never rejects: a browser that cannot complete the rename should still open the
+ * app. A database that failed to move keeps its old name and is retried on the
+ * next load, because the marker is only written on a clean pass.
+ */
+export declare function whenIdbNamesMigrated(): Promise<void>;
+/** Test seam: forget that the migration has run. */
+export declare function resetStorageMigrationForTests(): void;
+/**
+ * Test seam: declare the rename already done.
+ *
+ * Every `openDb()` in the app now waits on this migration, so a test that hands
+ * the code a stand-in IndexedDB would otherwise have to satisfy the migration's
+ * schema-reading and copying as well as whatever it is actually testing. Tests
+ * that are not about the rename say so with this.
+ */
+export declare function markStorageMigrationDoneForTests(): void;