npm - @metamask/keyring-sdk - Versions diffs - 3.1.0 → 4.0.0 - Mend

@metamask/keyring-sdk 3.1.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [4.0.0]
+### Changed
+- **BREAKING:** Remove envelope from migration framework ([#619](https://github.com/MetaMask/accounts/pull/619))
+  - The envelope made it harder to integrate with existing state.
+  - We still keep the requirement of having a `version` field to be declared, but the state can be "flatten" instead of living inside the `data` (envelope) field.
+- Bump `@metamask/keyring-api` from `^24.0.0` to `^24.2.0` ([#620](https://github.com/MetaMask/accounts/pull/620), [#660](https://github.com/MetaMask/accounts/pull/660))
+- Bump `@metamask/eth-sig-util` from `^8.2.0` to `^9.0.0` ([#626](https://github.com/MetaMask/accounts/pull/626))
 ## [3.1.0]
 ### Added
@@ -120,7 +130,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial release, extracted from `@metamask/keyring-api` ([#478](https://github.com/MetaMask/accounts/pull/478), [#482](https://github.com/MetaMask/accounts/pull/482))
-[Unreleased]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@3.1.0...HEAD
+[Unreleased]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@4.0.0...HEAD
+[4.0.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@3.1.0...@metamask/keyring-sdk@4.0.0
 [3.1.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@3.0.0...@metamask/keyring-sdk@3.1.0
 [3.0.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@2.3.0...@metamask/keyring-sdk@3.0.0
 [2.3.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@2.2.0...@metamask/keyring-sdk@2.3.0

package/dist/migration.cjs CHANGED Viewed

@@ -1,35 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createMigrations = exports.isVersionedState = exports.VersionedStateStruct = void 0;
+exports.createMigrations = exports.isVersionedState = exports.VersionedStateStruct = exports.JsonObjectStruct = void 0;
 const superstruct_1 = require("@metamask/superstruct");
 const utils_1 = require("@metamask/utils");
 /**
- * Superstruct schema for the versioned state envelope.
+ * Superstruct schema for a plain JSON object (`Record<string, Json>`).
+ *
+ * Used as the default fallback schema for step input/output validation when no
+ * explicit schema is provided.
+ */
+// `record(string(), JsonStruct)` alone would accept arrays: `typeof [] === 'object'`
+// satisfies superstruct's `isObject` check, and `Object.entries(['a', 'b'])` yields
+// valid string keys with JSON values. The refinement makes the array rejection explicit.
+exports.JsonObjectStruct = (0, superstruct_1.refine)((0, superstruct_1.record)((0, superstruct_1.string)(), utils_1.JsonStruct), 'JsonObject', (value) => typeof value === 'object' && value !== null && !Array.isArray(value));
+/**
+ * Superstruct schema for an exact `{ version: integer }` object with no other
+ * fields.
+ *
+ * Use this struct when you need to validate a pure version token. To check
+ * whether arbitrary flat state carries a version field, use
+ * {@link isVersionedState} instead.
  */
-exports.VersionedStateStruct = (0, superstruct_1.object)({
+exports.VersionedStateStruct = (0, superstruct_1.type)({
     version: (0, superstruct_1.integer)(),
-    data: utils_1.JsonStruct,
 });
 /**
- * Type guard to check if a value is a {@link VersionedState} envelope.
+ * Type guard to check if a value is a plain JSON object.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a non-null, non-array object.
+ */
+function isJsonObject(value) {
+    return (0, superstruct_1.is)(value, exports.JsonObjectStruct);
+}
+/**
+ * Type guard to check if a value is a {@link VersionedState}.
+ *
+ * Returns `true` for any plain object that carries a `version: integer` field,
+ * regardless of what other fields are present.
  *
  * @param state - The value to check.
- * @returns `true` if the value is a versioned state envelope.
+ * @returns `true` if the value has a `version: integer` field.
  */
 function isVersionedState(state) {
     return (0, superstruct_1.is)(state, exports.VersionedStateStruct);
 }
 exports.isVersionedState = isVersionedState;
 /**
- * Get the version and data from state, treating unversioned state as version 0.
+ * Extract the version and inner data from state.
  *
- * @param state - The state to check.
- * @returns The version and data.
+ * For versioned state (`isVersionedState` returns true), strips the `version`
+ * field and returns the rest as data. For unversioned legacy state (plain
+ * object with no `version` field), returns version 0 and the object as-is.
+ *
+ * @param state - The state to decompose.
+ * @returns The version number and the inner data object.
  */
 function getVersionAndData(state) {
-    return isVersionedState(state)
-        ? { version: state.version, data: state.data }
-        : { version: 0, data: state };
+    if (!isJsonObject(state)) {
+        throw new Error('Unversioned state must be a plain object');
+    }
+    if (isVersionedState(state)) {
+        const { version, ...data } = state;
+        return { version, data };
+    }
+    return { version: 0, data: state };
 }
 /**
  * Apply the pending steps of a chain to `state`.
@@ -38,7 +73,7 @@ function getVersionAndData(state) {
  *
  * @param steps - All steps of the chain.
  * @param state - The serialized keyring state.
- * @returns The migrated state wrapped in a versioned envelope, plus a `migrated` flag.
+ * @returns The migrated state in a {@link MigrationResult}.
  */
 async function applySteps(steps, state) {
     const latestVersion = steps.length;
@@ -52,13 +87,16 @@ async function applySteps(steps, state) {
     const pendingSteps = steps.slice(version);
     let data = initialData;
     for (const step of pendingSteps) {
-        (0, superstruct_1.assert)(data, step.inputSchema ?? utils_1.JsonStruct);
+        (0, superstruct_1.assert)(data, step.inputSchema ?? exports.JsonObjectStruct);
         data = await step.migrate(data);
-        (0, superstruct_1.assert)(data, step.outputSchema ?? utils_1.JsonStruct);
+        (0, superstruct_1.assert)(data, step.outputSchema ?? exports.JsonObjectStruct);
     }
     return {
         version: latestVersion,
-        data,
+        state: {
+            ...data,
+            version: latestVersion,
+        },
         migrated: pendingSteps.length > 0,
     };
 }
@@ -84,9 +122,10 @@ function buildChain(steps) {
  *   .add({ migrate: (data) => ({ count: data.numberOfItems }) })
  *   .add({ migrate: (data) => ({ ...data, createdAt: Date.now() }) }); // data typed as the first step's output, no cast
  *
- * const { data } = await migrations.apply(state);
+ * const { state, migrated } = await migrations.apply(serializedState);
+ * // Persist `state`; re-save if `migrated` is true.
  * ```
- * @returns An empty chain, typed to accept `Json` as its first step's input.
+ * @returns An empty chain typed to `JsonObject`.
  */
 function createMigrations() {
     return buildChain([]);

package/dist/migration.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"migration.cjs","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":";;;AACA,uDAAoE;AACpE,2CAA6C;AAG7C;;GAEG;AACU,QAAA,oBAAoB,GAAG,IAAA,oBAAM,EAAC;IACzC,OAAO,EAAE,IAAA,qBAAO,GAAE;IAClB,IAAI,EAAE,kBAAU;CACjB,CAAC,CAAC;AA4BH;;;;;GAKG;AACH,SAAgB,gBAAgB,CAC9B,KAAoC;IAEpC,OAAO,IAAA,gBAAE,EAAC,KAAK,EAAE,4BAAoB,CAAC,CAAC;AACzC,CAAC;AAJD,4CAIC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CACxB,KAAoC;IAEpC,OAAO,gBAAgB,CAAC,KAAK,CAAC;QAC5B,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;QAC9C,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC;AA8ED;;;;;;;;GAQG;AACH,KAAK,UAAU,UAAU,CACvB,KAA+B,EAC/B,KAAW;IAEX,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC;IACnC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAEhE,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,iBAAiB,OAAO,oCAAoC,CAC7D,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,GAAG,aAAa,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,iBAAiB,OAAO,+CAA+C,aAAa,EAAE,CACvF,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,IAAI,GAAG,WAAW,CAAC;IAEvB,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAA,oBAAM,EAAC,IAAI,EAAE,IAAI,CAAC,WAAW,IAAI,kBAAU,CAAC,CAAC;QAC7C,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,IAAA,oBAAM,EAAC,IAAI,EAAE,IAAI,CAAC,YAAY,IAAI,kBAAU,CAAC,CAAC;IAChD,CAAC;IAED,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,IAAI;QACJ,QAAQ,EAAE,YAAY,CAAC,MAAM,GAAG,CAAC;KACT,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CACjB,KAA+B;IAE/B,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,MAAM;QACrB,GAAG,EAAE,CACH,IAAkC,EAClC,EAAE,CAAC,UAAU,CAAS,CAAC,GAAG,KAAK,EAAE,IAAgC,CAAC,CAAC;QACrE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,UAAU,CAAO,KAAK,EAAE,KAAK,CAAC;KACvD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,gBAAgB;IAC9B,OAAO,UAAU,CAAO,EAAE,CAAC,CAAC;AAC9B,CAAC;AAFD,4CAEC","sourcesContent":["import type { Infer, Struct } from '@metamask/superstruct';\nimport { assert, integer, is, object } from '@metamask/superstruct';\nimport { JsonStruct } from '@metamask/utils';\nimport type { Json } from '@metamask/utils';\n\n/*\n Superstruct schema for the versioned state envelope.\n /\nexport const VersionedStateStruct = object({\n version: integer(),\n data: JsonStruct,\n});\n\n/\n Versioned state envelope wrapping the actual keyring data.\n \n After migrations are applied, state is always wrapped in this format. `serialize()`\n * should produce this envelope so that subsequent `deserialize()` calls can detect the\n * version.\n /\nexport type VersionedState<Data extends Json = Json> = Omit<\n Infer<typeof VersionedStateStruct>,\n 'data'\n> & {\n data: Data;\n};\n\n/\n Return value of {@link MigrationChain.apply}.\n \n Extends {@link VersionedState} with a `migrated` flag that is `true` when at least\n * one step was applied during the call. Callers can use this to detect that the\n * in-memory state has been upgraded and schedule a persist so the new version is\n * written to storage, even when no other state change happens in the session.\n /\nexport type MigrationResult<Data extends Json = Json> = VersionedState<Data> & {\n migrated: boolean;\n};\n\n/\n Type guard to check if a value is a {@link VersionedState} envelope.\n \n @param state - The value to check.\n * @returns `true` if the value is a versioned state envelope.\n /\nexport function isVersionedState<State extends Json = Json>(\n state: State \| VersionedState<State>,\n): state is VersionedState<State> {\n return is(state, VersionedStateStruct);\n}\n\n/\n Get the version and data from state, treating unversioned state as version 0.\n \n @param state - The state to check.\n * @returns The version and data.\n /\nfunction getVersionAndData<State extends Json = Json>(\n state: State \| VersionedState<State>,\n): VersionedState<State> {\n return isVersionedState(state)\n ? { version: state.version, data: state.data }\n : { version: 0, data: state };\n}\n\n/\n A single migration step, added to a {@link MigrationChain} via `.add()`.\n \n `Input` is bound automatically to the chain's current data type when the step is\n * passed to `.add()`, so `migrate` receives a correctly typed argument with no manual\n * cast.\n /\nexport type MigrationStep<\n Input extends Json = Json,\n Output extends Json = Json,\n> = {\n /\n Transform state from the previous step's output to this step's output.\n \n Receives the raw inner data (not the versioned envelope). May be sync or async to\n * support complex operations like re-deriving data from secrets.\n \n @param data - The state data from the previous step.\n * @returns The migrated data.\n /\n migrate(data: Input): Output \| Promise<Output>;\n /\n Optional schema validating this step's input before `migrate` is called. Defaults\n * to a generic JSON-shape check when omitted.\n /\n inputSchema?: Struct<Input>;\n /\n Optional schema validating this step's output at runtime.\n /\n outputSchema?: Struct<Output>;\n};\n\n/\n A chain of migration steps for evolving keyring serialized state across versions.\n \n Steps are versioned by position: the first `.add()` call produces version 1, the\n * second version 2, and so on. Create one with {@link createMigrations}.\n /\nexport type MigrationChain<Data extends Json = Json> = {\n /\n The number of steps added so far. Since steps are versioned by position starting at\n * 1, this also doubles as \"the latest version\" (use it in `serialize()`).\n /\n readonly version: number;\n /\n Append a step to the chain.\n \n Returns a new chain typed to `Output`. It does not mutate the chain it's called on,\n * so branching from a shared base chain is safe.\n \n `Input` defaults to the chain's current `Data` type. Providing `inputSchema` lets\n * TypeScript infer a narrower `Input` (bounded to extend `Data`), so `migrate`\n * receives a schema-typed argument when narrowing raw state into a specific shape,\n * typically on a chain's first step, where `Data` is `Json`.\n \n @param step - The migration step to append.\n * @returns A new chain whose data type is the step's `Output`.\n /\n add<Input extends Data = Data, Output extends Json = Json>(\n step: MigrationStep<Input, Output>,\n ): MigrationChain<Output>;\n /\n Apply all pending steps to `state`.\n \n Handles both versioned state (wrapped in `{ version, data }` envelope) and\n * unversioned legacy state (treated as version 0).\n \n @param state - The serialized keyring state (from vault or previous serialize).\n * @returns The migrated state wrapped in a versioned envelope, plus a `migrated`\n * flag.\n * @throws If `state`'s version is newer than this chain's latest version, or if a\n * step's `inputSchema`/`outputSchema` validation fails.\n /\n apply(state: Json): Promise<MigrationResult<Data>>;\n};\n\n/\n Apply the pending steps of a chain to `state`.\n \n Implements {@link MigrationChain.apply} for the chain built from `steps`.\n \n @param steps - All steps of the chain.\n * @param state - The serialized keyring state.\n * @returns The migrated state wrapped in a versioned envelope, plus a `migrated` flag.\n /\nasync function applySteps<Data extends Json>(\n steps: readonly MigrationStep[],\n state: Json,\n): Promise<MigrationResult<Data>> {\n const latestVersion = steps.length;\n const { version, data: initialData } = getVersionAndData(state);\n\n if (version < 0) {\n throw new Error(\n `State version ${version} is invalid; it cannot be negative`,\n );\n }\n\n if (version > latestVersion) {\n throw new Error(\n `State version ${version} is newer than the latest migration version ${latestVersion}`,\n );\n }\n\n const pendingSteps = steps.slice(version);\n let data = initialData;\n\n for (const step of pendingSteps) {\n assert(data, step.inputSchema ?? JsonStruct);\n data = await step.migrate(data);\n assert(data, step.outputSchema ?? JsonStruct);\n }\n\n return {\n version: latestVersion,\n data,\n migrated: pendingSteps.length > 0,\n } as MigrationResult<Data>;\n}\n\n/\n Build a {@link MigrationChain} wrapping the given internal steps.\n \n @param steps - The steps accumulated so far.\n * @returns A chain exposing `add`, `version`, and `apply`.\n /\nfunction buildChain<Data extends Json>(\n steps: readonly MigrationStep[],\n): MigrationChain<Data> {\n return {\n version: steps.length,\n add: <Input extends Data, Output extends Json>(\n step: MigrationStep<Input, Output>,\n ) => buildChain<Output>([...steps, step as unknown as MigrationStep]),\n apply: async (state) => applySteps<Data>(steps, state),\n };\n}\n\n/\n Start a new, empty migration chain.\n \n @example\n * ```typescript\n * const migrations = createMigrations()\n * .add({ migrate: (data) => ({ count: data.numberOfItems }) })\n * .add({ migrate: (data) => ({ ...data, createdAt: Date.now() }) }); // data typed as the first step's output, no cast\n \n const { data } = await migrations.apply(state);\n * ```\n * @returns An empty chain, typed to accept `Json` as its first step's input.\n */\nexport function createMigrations(): MigrationChain<Json> {\n return buildChain<Json>([]);\n}\n"]}
1	+ {"version":3,"file":"migration.cjs","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Infer, Struct } from '@metamask/superstruct';\nimport {\n assert,\n integer,\n is,\n record,\n refine,\n string,\n type,\n} from '@metamask/superstruct';\nimport { JsonStruct } from '@metamask/utils';\nimport type { Json } from '@metamask/utils';\n\n/*\n Constraint for flat migration state: must be a plain JSON object so that the\n * `version` field can be inlined alongside its other fields.\n /\nexport type JsonObject = Record<string, Json>;\n\n/\n Superstruct schema for a plain JSON object (`Record<string, Json>`).\n \n Used as the default fallback schema for step input/output validation when no\n * explicit schema is provided.\n /\n// `record(string(), JsonStruct)` alone would accept arrays: `typeof [] === 'object'`\n// satisfies superstruct's `isObject` check, and `Object.entries(['a', 'b'])` yields\n// valid string keys with JSON values. The refinement makes the array rejection explicit.\nexport const JsonObjectStruct: Struct<JsonObject> = refine(\n record(string(), JsonStruct),\n 'JsonObject',\n (value) =>\n typeof value === 'object' && value !== null && !Array.isArray(value),\n);\n\n/\n Superstruct schema for an exact `{ version: integer }` object with no other\n * fields.\n \n Use this struct when you need to validate a pure version token. To check\n * whether arbitrary flat state carries a version field, use\n * {@link isVersionedState} instead.\n /\nexport const VersionedStateStruct = type({\n version: integer(),\n});\n\n/\n Flat versioned state: the keyring state with `version` inlined alongside its\n * own fields.\n \n This is the format that `serialize()` should produce and `deserialize()` will\n * consume. The `version` field is managed by the migration framework; every\n * other field belongs to the keyring.\n \n Do not use `version` or `migrated` as field names in keyring state, as the\n * framework writes both at the top level when constructing a\n * {@link MigrationResult}.\n \n @example\n * const state: VersionedState<{ accounts: string[] }> = {\n * version: 3,\n * accounts: [],\n * };\n /\nexport type VersionedState<Data extends JsonObject = JsonObject> = Data &\n Infer<typeof VersionedStateStruct>;\n\n/\n Return value of {@link MigrationChain.apply}.\n \n `state` is the flat {@link VersionedState} to persist. `migrated` is a\n * runtime-only flag that is never written to storage. `version` duplicates\n * `state.version` for convenience.\n /\nexport type MigrationResult<Data extends JsonObject = JsonObject> = {\n /* Convenience alias for `state.version`. /\n version: number;\n /* The migrated flat state to persist. /\n state: VersionedState<Data>;\n /* `true` when at least one migration step was applied during this call. /\n migrated: boolean;\n};\n\n/\n Type guard to check if a value is a plain JSON object.\n \n @param value - The value to check.\n * @returns `true` if the value is a non-null, non-array object.\n /\nfunction isJsonObject(value: Json): value is JsonObject {\n return is(value, JsonObjectStruct);\n}\n\n/\n Type guard to check if a value is a {@link VersionedState}.\n \n Returns `true` for any plain object that carries a `version: integer` field,\n * regardless of what other fields are present.\n \n @param state - The value to check.\n * @returns `true` if the value has a `version: integer` field.\n /\nexport function isVersionedState<State extends JsonObject = JsonObject>(\n state: State \| VersionedState<State>,\n): state is VersionedState<State> {\n return is(state, VersionedStateStruct);\n}\n\n/\n Extract the version and inner data from state.\n \n For versioned state (`isVersionedState` returns true), strips the `version`\n * field and returns the rest as data. For unversioned legacy state (plain\n * object with no `version` field), returns version 0 and the object as-is.\n \n @param state - The state to decompose.\n * @returns The version number and the inner data object.\n /\nfunction getVersionAndData(state: Json): { version: number; data: JsonObject } {\n if (!isJsonObject(state)) {\n throw new Error('Unversioned state must be a plain object');\n }\n\n if (isVersionedState(state)) {\n const { version, ...data } = state;\n return { version, data };\n }\n\n return { version: 0, data: state };\n}\n\n/\n A single migration step, added to a {@link MigrationChain} via `.add()`.\n \n `Input` is bound automatically to the chain's current data type when the\n * step is passed to `.add()`, so `migrate` receives a correctly typed argument\n * with no manual cast.\n /\nexport type MigrationStep<\n Input extends JsonObject = JsonObject,\n Output extends JsonObject = JsonObject,\n> = {\n /\n Transform state from the previous step's output to this step's output.\n \n Receives the raw inner data (not the versioned envelope). May be sync or\n * async to support complex operations like re-deriving data from secrets.\n \n @param data - The state data from the previous step.\n * @returns The migrated data.\n /\n migrate(data: Input): Output \| Promise<Output>;\n /\n Optional schema validating this step's input before `migrate` is called.\n /\n inputSchema?: Struct<Input>;\n /\n Optional schema validating this step's output at runtime.\n /\n outputSchema?: Struct<Output>;\n};\n\n/\n A chain of migration steps for evolving keyring serialized state across\n * versions.\n \n Steps are versioned by position: the first `.add()` call produces version 1,\n * the second version 2, and so on. Create one with {@link createMigrations}.\n /\nexport type MigrationChain<Data extends JsonObject = JsonObject> = {\n /\n The number of steps added so far. Also the latest version number (use it\n * in `serialize()`).\n /\n readonly version: number;\n /\n Append a step to the chain.\n \n Returns a new chain typed to `Output`. Does not mutate the chain it is\n * called on, so branching from a shared base chain is safe.\n \n @param step - The migration step to append.\n * @returns A new chain whose data type is the step's `Output`.\n /\n add<Input extends Data = Data, Output extends JsonObject = JsonObject>(\n step: MigrationStep<Input, Output>,\n ): MigrationChain<Output>;\n /\n Apply all pending steps to `state`.\n \n Handles both flat versioned state (with a `version` field) and unversioned\n * legacy state (plain object without `version`, treated as version 0).\n \n @param state - The serialized keyring state (from vault or previous\n * serialize).\n * @returns The migrated state wrapped in a {@link MigrationResult}.\n * @throws If `state` is not a plain object, if its version is newer than the\n * chain's latest version, or if a step's `inputSchema`/`outputSchema`\n * validation fails.\n /\n apply(state: Json): Promise<MigrationResult<Data>>;\n};\n\n/\n Apply the pending steps of a chain to `state`.\n \n Implements {@link MigrationChain.apply} for the chain built from `steps`.\n \n @param steps - All steps of the chain.\n * @param state - The serialized keyring state.\n * @returns The migrated state in a {@link MigrationResult}.\n /\nasync function applySteps<Data extends JsonObject>(\n steps: readonly MigrationStep[],\n state: Json,\n): Promise<MigrationResult<Data>> {\n const latestVersion = steps.length;\n const { version, data: initialData } = getVersionAndData(state);\n\n if (version < 0) {\n throw new Error(\n `State version ${version} is invalid; it cannot be negative`,\n );\n }\n\n if (version > latestVersion) {\n throw new Error(\n `State version ${version} is newer than the latest migration version ${latestVersion}`,\n );\n }\n\n const pendingSteps = steps.slice(version);\n let data: JsonObject = initialData;\n\n for (const step of pendingSteps) {\n assert(data, step.inputSchema ?? JsonObjectStruct);\n data = await step.migrate(data);\n assert(data, step.outputSchema ?? JsonObjectStruct);\n }\n\n return {\n version: latestVersion,\n state: {\n ...data,\n version: latestVersion,\n },\n migrated: pendingSteps.length > 0,\n } as MigrationResult<Data>;\n}\n\n/\n Build a {@link MigrationChain} wrapping the given internal steps.\n \n @param steps - The steps accumulated so far.\n * @returns A chain exposing `add`, `version`, and `apply`.\n /\nfunction buildChain<Data extends JsonObject>(\n steps: readonly MigrationStep[],\n): MigrationChain<Data> {\n return {\n version: steps.length,\n add: <Input extends Data, Output extends JsonObject>(\n step: MigrationStep<Input, Output>,\n ) => buildChain<Output>([...steps, step as unknown as MigrationStep]),\n apply: async (state) => applySteps<Data>(steps, state),\n };\n}\n\n/\n Start a new, empty migration chain.\n \n @example\n * ```typescript\n * const migrations = createMigrations()\n * .add({ migrate: (data) => ({ count: data.numberOfItems }) })\n * .add({ migrate: (data) => ({ ...data, createdAt: Date.now() }) }); // data typed as the first step's output, no cast\n \n const { state, migrated } = await migrations.apply(serializedState);\n * // Persist `state`; re-save if `migrated` is true.\n * ```\n * @returns An empty chain typed to `JsonObject`.\n */\nexport function createMigrations(): MigrationChain<JsonObject> {\n return buildChain<JsonObject>([]);\n}\n"]}

package/dist/migration.d.cts CHANGED Viewed

@@ -1,64 +1,94 @@
 import type { Infer, Struct } from "@metamask/superstruct";
 import type { Json } from "@metamask/utils";
 /**
- * Superstruct schema for the versioned state envelope.
+ * Constraint for flat migration state: must be a plain JSON object so that the
+ * `version` field can be inlined alongside its other fields.
+ */
+export type JsonObject = Record<string, Json>;
+/**
+ * Superstruct schema for a plain JSON object (`Record<string, Json>`).
+ *
+ * Used as the default fallback schema for step input/output validation when no
+ * explicit schema is provided.
+ */
+export declare const JsonObjectStruct: Struct<JsonObject>;
+/**
+ * Superstruct schema for an exact `{ version: integer }` object with no other
+ * fields.
+ *
+ * Use this struct when you need to validate a pure version token. To check
+ * whether arbitrary flat state carries a version field, use
+ * {@link isVersionedState} instead.
  */
 export declare const VersionedStateStruct: Struct<{
-    data: Json;
     version: number;
 }, {
     version: Struct<number, null>;
-    data: Struct<Json, unknown>;
 }>;
 /**
- * Versioned state envelope wrapping the actual keyring data.
+ * Flat versioned state: the keyring state with `version` inlined alongside its
+ * own fields.
+ *
+ * This is the format that `serialize()` should produce and `deserialize()` will
+ * consume. The `version` field is managed by the migration framework; every
+ * other field belongs to the keyring.
  *
- * After migrations are applied, state is always wrapped in this format. `serialize()`
- * should produce this envelope so that subsequent `deserialize()` calls can detect the
- * version.
+ * Do not use `version` or `migrated` as field names in keyring state, as the
+ * framework writes both at the top level when constructing a
+ * {@link MigrationResult}.
+ *
+ * @example
+ * const state: VersionedState<{ accounts: string[] }> = {
+ *   version: 3,
+ *   accounts: [],
+ * };
  */
-export type VersionedState<Data extends Json = Json> = Omit<Infer<typeof VersionedStateStruct>, 'data'> & {
-    data: Data;
-};
+export type VersionedState<Data extends JsonObject = JsonObject> = Data & Infer<typeof VersionedStateStruct>;
 /**
  * Return value of {@link MigrationChain.apply}.
  *
- * Extends {@link VersionedState} with a `migrated` flag that is `true` when at least
- * one step was applied during the call. Callers can use this to detect that the
- * in-memory state has been upgraded and schedule a persist so the new version is
- * written to storage, even when no other state change happens in the session.
+ * `state` is the flat {@link VersionedState} to persist. `migrated` is a
+ * runtime-only flag that is never written to storage. `version` duplicates
+ * `state.version` for convenience.
  */
-export type MigrationResult<Data extends Json = Json> = VersionedState<Data> & {
+export type MigrationResult<Data extends JsonObject = JsonObject> = {
+    /** Convenience alias for `state.version`. */
+    version: number;
+    /** The migrated flat state to persist. */
+    state: VersionedState<Data>;
+    /** `true` when at least one migration step was applied during this call. */
     migrated: boolean;
 };
 /**
- * Type guard to check if a value is a {@link VersionedState} envelope.
+ * Type guard to check if a value is a {@link VersionedState}.
+ *
+ * Returns `true` for any plain object that carries a `version: integer` field,
+ * regardless of what other fields are present.
  *
  * @param state - The value to check.
- * @returns `true` if the value is a versioned state envelope.
+ * @returns `true` if the value has a `version: integer` field.
  */
-export declare function isVersionedState<State extends Json = Json>(state: State | VersionedState<State>): state is VersionedState<State>;
+export declare function isVersionedState<State extends JsonObject = JsonObject>(state: State | VersionedState<State>): state is VersionedState<State>;
 /**
  * A single migration step, added to a {@link MigrationChain} via `.add()`.
  *
- * `Input` is bound automatically to the chain's current data type when the step is
- * passed to `.add()`, so `migrate` receives a correctly typed argument with no manual
- * cast.
+ * `Input` is bound automatically to the chain's current data type when the
+ * step is passed to `.add()`, so `migrate` receives a correctly typed argument
+ * with no manual cast.
  */
-export type MigrationStep<Input extends Json = Json, Output extends Json = Json> = {
+export type MigrationStep<Input extends JsonObject = JsonObject, Output extends JsonObject = JsonObject> = {
     /**
      * Transform state from the previous step's output to this step's output.
      *
-     * Receives the raw inner data (not the versioned envelope). May be sync or async to
-     * support complex operations like re-deriving data from secrets.
+     * Receives the raw inner data (not the versioned envelope). May be sync or
+     * async to support complex operations like re-deriving data from secrets.
      *
      * @param data - The state data from the previous step.
      * @returns The migrated data.
      */
     migrate(data: Input): Output | Promise<Output>;
     /**
-     * Optional schema validating this step's input before `migrate` is called. Defaults
-     * to a generic JSON-shape check when omitted.
+     * Optional schema validating this step's input before `migrate` is called.
      */
     inputSchema?: Struct<Input>;
     /**
@@ -67,43 +97,40 @@ export type MigrationStep<Input extends Json = Json, Output extends Json = Json>
     outputSchema?: Struct<Output>;
 };
 /**
- * A chain of migration steps for evolving keyring serialized state across versions.
+ * A chain of migration steps for evolving keyring serialized state across
+ * versions.
  *
- * Steps are versioned by position: the first `.add()` call produces version 1, the
- * second version 2, and so on. Create one with {@link createMigrations}.
+ * Steps are versioned by position: the first `.add()` call produces version 1,
+ * the second version 2, and so on. Create one with {@link createMigrations}.
  */
-export type MigrationChain<Data extends Json = Json> = {
+export type MigrationChain<Data extends JsonObject = JsonObject> = {
     /**
-     * The number of steps added so far. Since steps are versioned by position starting at
-     * 1, this also doubles as "the latest version" (use it in `serialize()`).
+     * The number of steps added so far. Also the latest version number (use it
+     * in `serialize()`).
      */
     readonly version: number;
     /**
      * Append a step to the chain.
      *
-     * Returns a new chain typed to `Output`. It does not mutate the chain it's called on,
-     * so branching from a shared base chain is safe.
-     *
-     * `Input` defaults to the chain's current `Data` type. Providing `inputSchema` lets
-     * TypeScript infer a narrower `Input` (bounded to extend `Data`), so `migrate`
-     * receives a schema-typed argument when narrowing raw state into a specific shape,
-     * typically on a chain's first step, where `Data` is `Json`.
+     * Returns a new chain typed to `Output`. Does not mutate the chain it is
+     * called on, so branching from a shared base chain is safe.
      *
      * @param step - The migration step to append.
      * @returns A new chain whose data type is the step's `Output`.
      */
-    add<Input extends Data = Data, Output extends Json = Json>(step: MigrationStep<Input, Output>): MigrationChain<Output>;
+    add<Input extends Data = Data, Output extends JsonObject = JsonObject>(step: MigrationStep<Input, Output>): MigrationChain<Output>;
     /**
      * Apply all pending steps to `state`.
      *
-     * Handles both versioned state (wrapped in `{ version, data }` envelope) and
-     * unversioned legacy state (treated as version 0).
+     * Handles both flat versioned state (with a `version` field) and unversioned
+     * legacy state (plain object without `version`, treated as version 0).
      *
-     * @param state - The serialized keyring state (from vault or previous serialize).
-     * @returns The migrated state wrapped in a versioned envelope, plus a `migrated`
-     * flag.
-     * @throws If `state`'s version is newer than this chain's latest version, or if a
-     * step's `inputSchema`/`outputSchema` validation fails.
+     * @param state - The serialized keyring state (from vault or previous
+     * serialize).
+     * @returns The migrated state wrapped in a {@link MigrationResult}.
+     * @throws If `state` is not a plain object, if its version is newer than the
+     * chain's latest version, or if a step's `inputSchema`/`outputSchema`
+     * validation fails.
      */
     apply(state: Json): Promise<MigrationResult<Data>>;
 };
@@ -116,9 +143,10 @@ export type MigrationChain<Data extends Json = Json> = {
  *   .add({ migrate: (data) => ({ count: data.numberOfItems }) })
  *   .add({ migrate: (data) => ({ ...data, createdAt: Date.now() }) }); // data typed as the first step's output, no cast
  *
- * const { data } = await migrations.apply(state);
+ * const { state, migrated } = await migrations.apply(serializedState);
+ * // Persist `state`; re-save if `migrated` is true.
  * ```
- * @returns An empty chain, typed to accept `Json` as its first step's input.
+ * @returns An empty chain typed to `JsonObject`.
  */
-export declare function createMigrations(): MigrationChain<Json>;
+export declare function createMigrations(): MigrationChain<JsonObject>;
 //# sourceMappingURL=migration.d.cts.map

package/dist/migration.d.cts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"migration.d.cts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B;~~AAG3D~~,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C~~;;GAEG~~;AACH,eAAO,MAAM,oBAAoB~~;;;;;;EAG~~/B,CAAC;AAEH~~;;;;;;GAMG~~;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,~~IAAI~~,GAAG,~~IAAI~~,IAAI,IAAI,~~CACzD~~,KAAK,CAAC,OAAO,oBAAoB,CAAC,~~EAClC,MAAM,CACP,GAAG;IACF,IAAI,EAAE,IAAI,~~CAAC;~~CACZ,CAAC~~;~~AAEF;;;;;;;GAOG;~~AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,~~IAAI~~,GAAG,~~IAAI~~,IAAI,cAAc,CAAC,IAAI,CAAC,~~GAAG~~;~~IAC7E~~,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;~~AAEF;;;;;GAKG~~;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,~~IAAI~~,GAAG,~~IAAI~~,~~EACxD~~,KAAK,EAAE,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,GACnC,KAAK,IAAI,cAAc,CAAC,KAAK,CAAC,CAEhC;~~AAgBD~~;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CACvB,KAAK,SAAS,~~IAAI~~,GAAG,~~IAAI~~,~~EACzB~~,MAAM,SAAS,~~IAAI~~,GAAG,~~IAAI~~,~~IACxB~~;IACF;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C~~;;;OAGG~~;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF~~;;;;;GAKG~~;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,~~IAAI~~,GAAG,~~IAAI~~,IAAI;~~IACrD~~;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB~~;;;;;;;;;;;;;OAaG~~;IACH,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,IAAI,EAAE,MAAM,SAAS,~~IAAI~~,GAAG,~~IAAI~~,~~EACvD~~,IAAI,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,GACjC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC1B~~;;;;;;;;;;;OAWG~~;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;CACpD,CAAC;~~AAgEF;;;;;;;;;;;;GAYG~~;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAAC,~~IAAI~~,CAAC,~~CAEvD~~"}
1	+ {"version":3,"file":"migration.d.cts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B;AAW3D,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE9C;;;;;GAKG;AAIH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAK/C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;EAE/B,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,UAAU,GAAG,UAAU,IAAI,IAAI,GACrE,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,UAAU,GAAG,UAAU,IAAI;IAClE,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAYF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU,EACpE,KAAK,EAAE,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,GACnC,KAAK,IAAI,cAAc,CAAC,KAAK,CAAC,CAEhC;AAyBD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CACvB,KAAK,SAAS,UAAU,GAAG,UAAU,EACrC,MAAM,SAAS,UAAU,GAAG,UAAU,IACpC;IACF;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,UAAU,GAAG,UAAU,IAAI;IACjE;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,IAAI,EAAE,MAAM,SAAS,UAAU,GAAG,UAAU,EACnE,IAAI,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,GACjC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;CACpD,CAAC;AAmEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAAC,UAAU,CAAC,CAE7D"}

package/dist/migration.d.mts CHANGED Viewed

@@ -1,64 +1,94 @@
 import type { Infer, Struct } from "@metamask/superstruct";
 import type { Json } from "@metamask/utils";
 /**
- * Superstruct schema for the versioned state envelope.
+ * Constraint for flat migration state: must be a plain JSON object so that the
+ * `version` field can be inlined alongside its other fields.
+ */
+export type JsonObject = Record<string, Json>;
+/**
+ * Superstruct schema for a plain JSON object (`Record<string, Json>`).
+ *
+ * Used as the default fallback schema for step input/output validation when no
+ * explicit schema is provided.
+ */
+export declare const JsonObjectStruct: Struct<JsonObject>;
+/**
+ * Superstruct schema for an exact `{ version: integer }` object with no other
+ * fields.
+ *
+ * Use this struct when you need to validate a pure version token. To check
+ * whether arbitrary flat state carries a version field, use
+ * {@link isVersionedState} instead.
  */
 export declare const VersionedStateStruct: Struct<{
-    data: Json;
     version: number;
 }, {
     version: Struct<number, null>;
-    data: Struct<Json, unknown>;
 }>;
 /**
- * Versioned state envelope wrapping the actual keyring data.
+ * Flat versioned state: the keyring state with `version` inlined alongside its
+ * own fields.
+ *
+ * This is the format that `serialize()` should produce and `deserialize()` will
+ * consume. The `version` field is managed by the migration framework; every
+ * other field belongs to the keyring.
  *
- * After migrations are applied, state is always wrapped in this format. `serialize()`
- * should produce this envelope so that subsequent `deserialize()` calls can detect the
- * version.
+ * Do not use `version` or `migrated` as field names in keyring state, as the
+ * framework writes both at the top level when constructing a
+ * {@link MigrationResult}.
+ *
+ * @example
+ * const state: VersionedState<{ accounts: string[] }> = {
+ *   version: 3,
+ *   accounts: [],
+ * };
  */
-export type VersionedState<Data extends Json = Json> = Omit<Infer<typeof VersionedStateStruct>, 'data'> & {
-    data: Data;
-};
+export type VersionedState<Data extends JsonObject = JsonObject> = Data & Infer<typeof VersionedStateStruct>;
 /**
  * Return value of {@link MigrationChain.apply}.
  *
- * Extends {@link VersionedState} with a `migrated` flag that is `true` when at least
- * one step was applied during the call. Callers can use this to detect that the
- * in-memory state has been upgraded and schedule a persist so the new version is
- * written to storage, even when no other state change happens in the session.
+ * `state` is the flat {@link VersionedState} to persist. `migrated` is a
+ * runtime-only flag that is never written to storage. `version` duplicates
+ * `state.version` for convenience.
  */
-export type MigrationResult<Data extends Json = Json> = VersionedState<Data> & {
+export type MigrationResult<Data extends JsonObject = JsonObject> = {
+    /** Convenience alias for `state.version`. */
+    version: number;
+    /** The migrated flat state to persist. */
+    state: VersionedState<Data>;
+    /** `true` when at least one migration step was applied during this call. */
     migrated: boolean;
 };
 /**
- * Type guard to check if a value is a {@link VersionedState} envelope.
+ * Type guard to check if a value is a {@link VersionedState}.
+ *
+ * Returns `true` for any plain object that carries a `version: integer` field,
+ * regardless of what other fields are present.
  *
  * @param state - The value to check.
- * @returns `true` if the value is a versioned state envelope.
+ * @returns `true` if the value has a `version: integer` field.
  */
-export declare function isVersionedState<State extends Json = Json>(state: State | VersionedState<State>): state is VersionedState<State>;
+export declare function isVersionedState<State extends JsonObject = JsonObject>(state: State | VersionedState<State>): state is VersionedState<State>;
 /**
  * A single migration step, added to a {@link MigrationChain} via `.add()`.
  *
- * `Input` is bound automatically to the chain's current data type when the step is
- * passed to `.add()`, so `migrate` receives a correctly typed argument with no manual
- * cast.
+ * `Input` is bound automatically to the chain's current data type when the
+ * step is passed to `.add()`, so `migrate` receives a correctly typed argument
+ * with no manual cast.
  */
-export type MigrationStep<Input extends Json = Json, Output extends Json = Json> = {
+export type MigrationStep<Input extends JsonObject = JsonObject, Output extends JsonObject = JsonObject> = {
     /**
      * Transform state from the previous step's output to this step's output.
      *
-     * Receives the raw inner data (not the versioned envelope). May be sync or async to
-     * support complex operations like re-deriving data from secrets.
+     * Receives the raw inner data (not the versioned envelope). May be sync or
+     * async to support complex operations like re-deriving data from secrets.
      *
      * @param data - The state data from the previous step.
      * @returns The migrated data.
      */
     migrate(data: Input): Output | Promise<Output>;
     /**
-     * Optional schema validating this step's input before `migrate` is called. Defaults
-     * to a generic JSON-shape check when omitted.
+     * Optional schema validating this step's input before `migrate` is called.
      */
     inputSchema?: Struct<Input>;
     /**
@@ -67,43 +97,40 @@ export type MigrationStep<Input extends Json = Json, Output extends Json = Json>
     outputSchema?: Struct<Output>;
 };
 /**
- * A chain of migration steps for evolving keyring serialized state across versions.
+ * A chain of migration steps for evolving keyring serialized state across
+ * versions.
  *
- * Steps are versioned by position: the first `.add()` call produces version 1, the
- * second version 2, and so on. Create one with {@link createMigrations}.
+ * Steps are versioned by position: the first `.add()` call produces version 1,
+ * the second version 2, and so on. Create one with {@link createMigrations}.
  */
-export type MigrationChain<Data extends Json = Json> = {
+export type MigrationChain<Data extends JsonObject = JsonObject> = {
     /**
-     * The number of steps added so far. Since steps are versioned by position starting at
-     * 1, this also doubles as "the latest version" (use it in `serialize()`).
+     * The number of steps added so far. Also the latest version number (use it
+     * in `serialize()`).
      */
     readonly version: number;
     /**
      * Append a step to the chain.
      *
-     * Returns a new chain typed to `Output`. It does not mutate the chain it's called on,
-     * so branching from a shared base chain is safe.
-     *
-     * `Input` defaults to the chain's current `Data` type. Providing `inputSchema` lets
-     * TypeScript infer a narrower `Input` (bounded to extend `Data`), so `migrate`
-     * receives a schema-typed argument when narrowing raw state into a specific shape,
-     * typically on a chain's first step, where `Data` is `Json`.
+     * Returns a new chain typed to `Output`. Does not mutate the chain it is
+     * called on, so branching from a shared base chain is safe.
      *
      * @param step - The migration step to append.
      * @returns A new chain whose data type is the step's `Output`.
      */
-    add<Input extends Data = Data, Output extends Json = Json>(step: MigrationStep<Input, Output>): MigrationChain<Output>;
+    add<Input extends Data = Data, Output extends JsonObject = JsonObject>(step: MigrationStep<Input, Output>): MigrationChain<Output>;
     /**
      * Apply all pending steps to `state`.
      *
-     * Handles both versioned state (wrapped in `{ version, data }` envelope) and
-     * unversioned legacy state (treated as version 0).
+     * Handles both flat versioned state (with a `version` field) and unversioned
+     * legacy state (plain object without `version`, treated as version 0).
      *
-     * @param state - The serialized keyring state (from vault or previous serialize).
-     * @returns The migrated state wrapped in a versioned envelope, plus a `migrated`
-     * flag.
-     * @throws If `state`'s version is newer than this chain's latest version, or if a
-     * step's `inputSchema`/`outputSchema` validation fails.
+     * @param state - The serialized keyring state (from vault or previous
+     * serialize).
+     * @returns The migrated state wrapped in a {@link MigrationResult}.
+     * @throws If `state` is not a plain object, if its version is newer than the
+     * chain's latest version, or if a step's `inputSchema`/`outputSchema`
+     * validation fails.
      */
     apply(state: Json): Promise<MigrationResult<Data>>;
 };
@@ -116,9 +143,10 @@ export type MigrationChain<Data extends Json = Json> = {
  *   .add({ migrate: (data) => ({ count: data.numberOfItems }) })
  *   .add({ migrate: (data) => ({ ...data, createdAt: Date.now() }) }); // data typed as the first step's output, no cast
  *
- * const { data } = await migrations.apply(state);
+ * const { state, migrated } = await migrations.apply(serializedState);
+ * // Persist `state`; re-save if `migrated` is true.
  * ```
- * @returns An empty chain, typed to accept `Json` as its first step's input.
+ * @returns An empty chain typed to `JsonObject`.
  */
-export declare function createMigrations(): MigrationChain<Json>;
+export declare function createMigrations(): MigrationChain<JsonObject>;
 //# sourceMappingURL=migration.d.mts.map

package/dist/migration.d.mts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"migration.d.mts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B;~~AAG3D~~,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C~~;;GAEG~~;AACH,eAAO,MAAM,oBAAoB~~;;;;;;EAG~~/B,CAAC;AAEH~~;;;;;;GAMG~~;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,~~IAAI~~,GAAG,~~IAAI~~,IAAI,IAAI,~~CACzD~~,KAAK,CAAC,OAAO,oBAAoB,CAAC,~~EAClC,MAAM,CACP,GAAG;IACF,IAAI,EAAE,IAAI,~~CAAC;~~CACZ,CAAC~~;~~AAEF;;;;;;;GAOG;~~AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,~~IAAI~~,GAAG,~~IAAI~~,IAAI,cAAc,CAAC,IAAI,CAAC,~~GAAG~~;~~IAC7E~~,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;~~AAEF;;;;;GAKG~~;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,~~IAAI~~,GAAG,~~IAAI~~,~~EACxD~~,KAAK,EAAE,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,GACnC,KAAK,IAAI,cAAc,CAAC,KAAK,CAAC,CAEhC;~~AAgBD~~;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CACvB,KAAK,SAAS,~~IAAI~~,GAAG,~~IAAI~~,~~EACzB~~,MAAM,SAAS,~~IAAI~~,GAAG,~~IAAI~~,~~IACxB~~;IACF;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C~~;;;OAGG~~;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF~~;;;;;GAKG~~;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,~~IAAI~~,GAAG,~~IAAI~~,IAAI;~~IACrD~~;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB~~;;;;;;;;;;;;;OAaG~~;IACH,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,IAAI,EAAE,MAAM,SAAS,~~IAAI~~,GAAG,~~IAAI~~,~~EACvD~~,IAAI,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,GACjC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC1B~~;;;;;;;;;;;OAWG~~;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;CACpD,CAAC;~~AAgEF;;;;;;;;;;;;GAYG~~;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAAC,~~IAAI~~,CAAC,~~CAEvD~~"}
1	+ {"version":3,"file":"migration.d.mts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B;AAW3D,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE9C;;;;;GAKG;AAIH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAK/C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;EAE/B,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,UAAU,GAAG,UAAU,IAAI,IAAI,GACrE,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,UAAU,GAAG,UAAU,IAAI;IAClE,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAYF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU,EACpE,KAAK,EAAE,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,GACnC,KAAK,IAAI,cAAc,CAAC,KAAK,CAAC,CAEhC;AAyBD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CACvB,KAAK,SAAS,UAAU,GAAG,UAAU,EACrC,MAAM,SAAS,UAAU,GAAG,UAAU,IACpC;IACF;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,UAAU,GAAG,UAAU,IAAI;IACjE;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,IAAI,EAAE,MAAM,SAAS,UAAU,GAAG,UAAU,EACnE,IAAI,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,GACjC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;CACpD,CAAC;AAmEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAAC,UAAU,CAAC,CAE7D"}

package/dist/migration.mjs CHANGED Viewed

@@ -1,31 +1,66 @@
-import { assert, integer, is, object } from "@metamask/superstruct";
+import { assert, integer, is, record, refine, string, type } from "@metamask/superstruct";
 import { JsonStruct } from "@metamask/utils";
 /**
- * Superstruct schema for the versioned state envelope.
+ * Superstruct schema for a plain JSON object (`Record<string, Json>`).
+ *
+ * Used as the default fallback schema for step input/output validation when no
+ * explicit schema is provided.
+ */
+// `record(string(), JsonStruct)` alone would accept arrays: `typeof [] === 'object'`
+// satisfies superstruct's `isObject` check, and `Object.entries(['a', 'b'])` yields
+// valid string keys with JSON values. The refinement makes the array rejection explicit.
+export const JsonObjectStruct = refine(record(string(), JsonStruct), 'JsonObject', (value) => typeof value === 'object' && value !== null && !Array.isArray(value));
+/**
+ * Superstruct schema for an exact `{ version: integer }` object with no other
+ * fields.
+ *
+ * Use this struct when you need to validate a pure version token. To check
+ * whether arbitrary flat state carries a version field, use
+ * {@link isVersionedState} instead.
  */
-export const VersionedStateStruct = object({
+export const VersionedStateStruct = type({
     version: integer(),
-    data: JsonStruct,
 });
 /**
- * Type guard to check if a value is a {@link VersionedState} envelope.
+ * Type guard to check if a value is a plain JSON object.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a non-null, non-array object.
+ */
+function isJsonObject(value) {
+    return is(value, JsonObjectStruct);
+}
+/**
+ * Type guard to check if a value is a {@link VersionedState}.
+ *
+ * Returns `true` for any plain object that carries a `version: integer` field,
+ * regardless of what other fields are present.
  *
  * @param state - The value to check.
- * @returns `true` if the value is a versioned state envelope.
+ * @returns `true` if the value has a `version: integer` field.
  */
 export function isVersionedState(state) {
     return is(state, VersionedStateStruct);
 }
 /**
- * Get the version and data from state, treating unversioned state as version 0.
+ * Extract the version and inner data from state.
  *
- * @param state - The state to check.
- * @returns The version and data.
+ * For versioned state (`isVersionedState` returns true), strips the `version`
+ * field and returns the rest as data. For unversioned legacy state (plain
+ * object with no `version` field), returns version 0 and the object as-is.
+ *
+ * @param state - The state to decompose.
+ * @returns The version number and the inner data object.
  */
 function getVersionAndData(state) {
-    return isVersionedState(state)
-        ? { version: state.version, data: state.data }
-        : { version: 0, data: state };
+    if (!isJsonObject(state)) {
+        throw new Error('Unversioned state must be a plain object');
+    }
+    if (isVersionedState(state)) {
+        const { version, ...data } = state;
+        return { version, data };
+    }
+    return { version: 0, data: state };
 }
 /**
  * Apply the pending steps of a chain to `state`.
@@ -34,7 +69,7 @@ function getVersionAndData(state) {
  *
  * @param steps - All steps of the chain.
  * @param state - The serialized keyring state.
- * @returns The migrated state wrapped in a versioned envelope, plus a `migrated` flag.
+ * @returns The migrated state in a {@link MigrationResult}.
  */
 async function applySteps(steps, state) {
     const latestVersion = steps.length;
@@ -48,13 +83,16 @@ async function applySteps(steps, state) {
     const pendingSteps = steps.slice(version);
     let data = initialData;
     for (const step of pendingSteps) {
-        assert(data, step.inputSchema ?? JsonStruct);
+        assert(data, step.inputSchema ?? JsonObjectStruct);
         data = await step.migrate(data);
-        assert(data, step.outputSchema ?? JsonStruct);
+        assert(data, step.outputSchema ?? JsonObjectStruct);
     }
     return {
         version: latestVersion,
-        data,
+        state: {
+            ...data,
+            version: latestVersion,
+        },
         migrated: pendingSteps.length > 0,
     };
 }
@@ -80,9 +118,10 @@ function buildChain(steps) {
  *   .add({ migrate: (data) => ({ count: data.numberOfItems }) })
  *   .add({ migrate: (data) => ({ ...data, createdAt: Date.now() }) }); // data typed as the first step's output, no cast
  *
- * const { data } = await migrations.apply(state);
+ * const { state, migrated } = await migrations.apply(serializedState);
+ * // Persist `state`; re-save if `migrated` is true.
  * ```
- * @returns An empty chain, typed to accept `Json` as its first step's input.
+ * @returns An empty chain typed to `JsonObject`.
  */
 export function createMigrations() {
     return buildChain([]);

package/dist/migration.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"migration.mjs","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,8BAA8B;AACpE,OAAO,EAAE,UAAU,EAAE,wBAAwB;AAG7C;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;IACzC,OAAO,EAAE,OAAO,EAAE;IAClB,IAAI,EAAE,UAAU;CACjB,CAAC,CAAC;AA4BH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAoC;IAEpC,OAAO,EAAE,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CACxB,KAAoC;IAEpC,OAAO,gBAAgB,CAAC,KAAK,CAAC;QAC5B,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;QAC9C,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC;AA8ED;;;;;;;;GAQG;AACH,KAAK,UAAU,UAAU,CACvB,KAA+B,EAC/B,KAAW;IAEX,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC;IACnC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAEhE,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,iBAAiB,OAAO,oCAAoC,CAC7D,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,GAAG,aAAa,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,iBAAiB,OAAO,+CAA+C,aAAa,EAAE,CACvF,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,IAAI,GAAG,WAAW,CAAC;IAEvB,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,IAAI,UAAU,CAAC,CAAC;QAC7C,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,IAAI,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,IAAI;QACJ,QAAQ,EAAE,YAAY,CAAC,MAAM,GAAG,CAAC;KACT,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CACjB,KAA+B;IAE/B,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,MAAM;QACrB,GAAG,EAAE,CACH,IAAkC,EAClC,EAAE,CAAC,UAAU,CAAS,CAAC,GAAG,KAAK,EAAE,IAAgC,CAAC,CAAC;QACrE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,UAAU,CAAO,KAAK,EAAE,KAAK,CAAC;KACvD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,CAAO,EAAE,CAAC,CAAC;AAC9B,CAAC","sourcesContent":["import type { Infer, Struct } from '@metamask/superstruct';\nimport { assert, integer, is, object } from '@metamask/superstruct';\nimport { JsonStruct } from '@metamask/utils';\nimport type { Json } from '@metamask/utils';\n\n/*\n Superstruct schema for the versioned state envelope.\n /\nexport const VersionedStateStruct = object({\n version: integer(),\n data: JsonStruct,\n});\n\n/\n Versioned state envelope wrapping the actual keyring data.\n \n After migrations are applied, state is always wrapped in this format. `serialize()`\n * should produce this envelope so that subsequent `deserialize()` calls can detect the\n * version.\n /\nexport type VersionedState<Data extends Json = Json> = Omit<\n Infer<typeof VersionedStateStruct>,\n 'data'\n> & {\n data: Data;\n};\n\n/\n Return value of {@link MigrationChain.apply}.\n \n Extends {@link VersionedState} with a `migrated` flag that is `true` when at least\n * one step was applied during the call. Callers can use this to detect that the\n * in-memory state has been upgraded and schedule a persist so the new version is\n * written to storage, even when no other state change happens in the session.\n /\nexport type MigrationResult<Data extends Json = Json> = VersionedState<Data> & {\n migrated: boolean;\n};\n\n/\n Type guard to check if a value is a {@link VersionedState} envelope.\n \n @param state - The value to check.\n * @returns `true` if the value is a versioned state envelope.\n /\nexport function isVersionedState<State extends Json = Json>(\n state: State \| VersionedState<State>,\n): state is VersionedState<State> {\n return is(state, VersionedStateStruct);\n}\n\n/\n Get the version and data from state, treating unversioned state as version 0.\n \n @param state - The state to check.\n * @returns The version and data.\n /\nfunction getVersionAndData<State extends Json = Json>(\n state: State \| VersionedState<State>,\n): VersionedState<State> {\n return isVersionedState(state)\n ? { version: state.version, data: state.data }\n : { version: 0, data: state };\n}\n\n/\n A single migration step, added to a {@link MigrationChain} via `.add()`.\n \n `Input` is bound automatically to the chain's current data type when the step is\n * passed to `.add()`, so `migrate` receives a correctly typed argument with no manual\n * cast.\n /\nexport type MigrationStep<\n Input extends Json = Json,\n Output extends Json = Json,\n> = {\n /\n Transform state from the previous step's output to this step's output.\n \n Receives the raw inner data (not the versioned envelope). May be sync or async to\n * support complex operations like re-deriving data from secrets.\n \n @param data - The state data from the previous step.\n * @returns The migrated data.\n /\n migrate(data: Input): Output \| Promise<Output>;\n /\n Optional schema validating this step's input before `migrate` is called. Defaults\n * to a generic JSON-shape check when omitted.\n /\n inputSchema?: Struct<Input>;\n /\n Optional schema validating this step's output at runtime.\n /\n outputSchema?: Struct<Output>;\n};\n\n/\n A chain of migration steps for evolving keyring serialized state across versions.\n \n Steps are versioned by position: the first `.add()` call produces version 1, the\n * second version 2, and so on. Create one with {@link createMigrations}.\n /\nexport type MigrationChain<Data extends Json = Json> = {\n /\n The number of steps added so far. Since steps are versioned by position starting at\n * 1, this also doubles as \"the latest version\" (use it in `serialize()`).\n /\n readonly version: number;\n /\n Append a step to the chain.\n \n Returns a new chain typed to `Output`. It does not mutate the chain it's called on,\n * so branching from a shared base chain is safe.\n \n `Input` defaults to the chain's current `Data` type. Providing `inputSchema` lets\n * TypeScript infer a narrower `Input` (bounded to extend `Data`), so `migrate`\n * receives a schema-typed argument when narrowing raw state into a specific shape,\n * typically on a chain's first step, where `Data` is `Json`.\n \n @param step - The migration step to append.\n * @returns A new chain whose data type is the step's `Output`.\n /\n add<Input extends Data = Data, Output extends Json = Json>(\n step: MigrationStep<Input, Output>,\n ): MigrationChain<Output>;\n /\n Apply all pending steps to `state`.\n \n Handles both versioned state (wrapped in `{ version, data }` envelope) and\n * unversioned legacy state (treated as version 0).\n \n @param state - The serialized keyring state (from vault or previous serialize).\n * @returns The migrated state wrapped in a versioned envelope, plus a `migrated`\n * flag.\n * @throws If `state`'s version is newer than this chain's latest version, or if a\n * step's `inputSchema`/`outputSchema` validation fails.\n /\n apply(state: Json): Promise<MigrationResult<Data>>;\n};\n\n/\n Apply the pending steps of a chain to `state`.\n \n Implements {@link MigrationChain.apply} for the chain built from `steps`.\n \n @param steps - All steps of the chain.\n * @param state - The serialized keyring state.\n * @returns The migrated state wrapped in a versioned envelope, plus a `migrated` flag.\n /\nasync function applySteps<Data extends Json>(\n steps: readonly MigrationStep[],\n state: Json,\n): Promise<MigrationResult<Data>> {\n const latestVersion = steps.length;\n const { version, data: initialData } = getVersionAndData(state);\n\n if (version < 0) {\n throw new Error(\n `State version ${version} is invalid; it cannot be negative`,\n );\n }\n\n if (version > latestVersion) {\n throw new Error(\n `State version ${version} is newer than the latest migration version ${latestVersion}`,\n );\n }\n\n const pendingSteps = steps.slice(version);\n let data = initialData;\n\n for (const step of pendingSteps) {\n assert(data, step.inputSchema ?? JsonStruct);\n data = await step.migrate(data);\n assert(data, step.outputSchema ?? JsonStruct);\n }\n\n return {\n version: latestVersion,\n data,\n migrated: pendingSteps.length > 0,\n } as MigrationResult<Data>;\n}\n\n/\n Build a {@link MigrationChain} wrapping the given internal steps.\n \n @param steps - The steps accumulated so far.\n * @returns A chain exposing `add`, `version`, and `apply`.\n /\nfunction buildChain<Data extends Json>(\n steps: readonly MigrationStep[],\n): MigrationChain<Data> {\n return {\n version: steps.length,\n add: <Input extends Data, Output extends Json>(\n step: MigrationStep<Input, Output>,\n ) => buildChain<Output>([...steps, step as unknown as MigrationStep]),\n apply: async (state) => applySteps<Data>(steps, state),\n };\n}\n\n/\n Start a new, empty migration chain.\n \n @example\n * ```typescript\n * const migrations = createMigrations()\n * .add({ migrate: (data) => ({ count: data.numberOfItems }) })\n * .add({ migrate: (data) => ({ ...data, createdAt: Date.now() }) }); // data typed as the first step's output, no cast\n \n const { data } = await migrations.apply(state);\n * ```\n * @returns An empty chain, typed to accept `Json` as its first step's input.\n */\nexport function createMigrations(): MigrationChain<Json> {\n return buildChain<Json>([]);\n}\n"]}
1	+ {"version":3,"file":"migration.mjs","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Infer, Struct } from '@metamask/superstruct';\nimport {\n assert,\n integer,\n is,\n record,\n refine,\n string,\n type,\n} from '@metamask/superstruct';\nimport { JsonStruct } from '@metamask/utils';\nimport type { Json } from '@metamask/utils';\n\n/*\n Constraint for flat migration state: must be a plain JSON object so that the\n * `version` field can be inlined alongside its other fields.\n /\nexport type JsonObject = Record<string, Json>;\n\n/\n Superstruct schema for a plain JSON object (`Record<string, Json>`).\n \n Used as the default fallback schema for step input/output validation when no\n * explicit schema is provided.\n /\n// `record(string(), JsonStruct)` alone would accept arrays: `typeof [] === 'object'`\n// satisfies superstruct's `isObject` check, and `Object.entries(['a', 'b'])` yields\n// valid string keys with JSON values. The refinement makes the array rejection explicit.\nexport const JsonObjectStruct: Struct<JsonObject> = refine(\n record(string(), JsonStruct),\n 'JsonObject',\n (value) =>\n typeof value === 'object' && value !== null && !Array.isArray(value),\n);\n\n/\n Superstruct schema for an exact `{ version: integer }` object with no other\n * fields.\n \n Use this struct when you need to validate a pure version token. To check\n * whether arbitrary flat state carries a version field, use\n * {@link isVersionedState} instead.\n /\nexport const VersionedStateStruct = type({\n version: integer(),\n});\n\n/\n Flat versioned state: the keyring state with `version` inlined alongside its\n * own fields.\n \n This is the format that `serialize()` should produce and `deserialize()` will\n * consume. The `version` field is managed by the migration framework; every\n * other field belongs to the keyring.\n \n Do not use `version` or `migrated` as field names in keyring state, as the\n * framework writes both at the top level when constructing a\n * {@link MigrationResult}.\n \n @example\n * const state: VersionedState<{ accounts: string[] }> = {\n * version: 3,\n * accounts: [],\n * };\n /\nexport type VersionedState<Data extends JsonObject = JsonObject> = Data &\n Infer<typeof VersionedStateStruct>;\n\n/\n Return value of {@link MigrationChain.apply}.\n \n `state` is the flat {@link VersionedState} to persist. `migrated` is a\n * runtime-only flag that is never written to storage. `version` duplicates\n * `state.version` for convenience.\n /\nexport type MigrationResult<Data extends JsonObject = JsonObject> = {\n /* Convenience alias for `state.version`. /\n version: number;\n /* The migrated flat state to persist. /\n state: VersionedState<Data>;\n /* `true` when at least one migration step was applied during this call. /\n migrated: boolean;\n};\n\n/\n Type guard to check if a value is a plain JSON object.\n \n @param value - The value to check.\n * @returns `true` if the value is a non-null, non-array object.\n /\nfunction isJsonObject(value: Json): value is JsonObject {\n return is(value, JsonObjectStruct);\n}\n\n/\n Type guard to check if a value is a {@link VersionedState}.\n \n Returns `true` for any plain object that carries a `version: integer` field,\n * regardless of what other fields are present.\n \n @param state - The value to check.\n * @returns `true` if the value has a `version: integer` field.\n /\nexport function isVersionedState<State extends JsonObject = JsonObject>(\n state: State \| VersionedState<State>,\n): state is VersionedState<State> {\n return is(state, VersionedStateStruct);\n}\n\n/\n Extract the version and inner data from state.\n \n For versioned state (`isVersionedState` returns true), strips the `version`\n * field and returns the rest as data. For unversioned legacy state (plain\n * object with no `version` field), returns version 0 and the object as-is.\n \n @param state - The state to decompose.\n * @returns The version number and the inner data object.\n /\nfunction getVersionAndData(state: Json): { version: number; data: JsonObject } {\n if (!isJsonObject(state)) {\n throw new Error('Unversioned state must be a plain object');\n }\n\n if (isVersionedState(state)) {\n const { version, ...data } = state;\n return { version, data };\n }\n\n return { version: 0, data: state };\n}\n\n/\n A single migration step, added to a {@link MigrationChain} via `.add()`.\n \n `Input` is bound automatically to the chain's current data type when the\n * step is passed to `.add()`, so `migrate` receives a correctly typed argument\n * with no manual cast.\n /\nexport type MigrationStep<\n Input extends JsonObject = JsonObject,\n Output extends JsonObject = JsonObject,\n> = {\n /\n Transform state from the previous step's output to this step's output.\n \n Receives the raw inner data (not the versioned envelope). May be sync or\n * async to support complex operations like re-deriving data from secrets.\n \n @param data - The state data from the previous step.\n * @returns The migrated data.\n /\n migrate(data: Input): Output \| Promise<Output>;\n /\n Optional schema validating this step's input before `migrate` is called.\n /\n inputSchema?: Struct<Input>;\n /\n Optional schema validating this step's output at runtime.\n /\n outputSchema?: Struct<Output>;\n};\n\n/\n A chain of migration steps for evolving keyring serialized state across\n * versions.\n \n Steps are versioned by position: the first `.add()` call produces version 1,\n * the second version 2, and so on. Create one with {@link createMigrations}.\n /\nexport type MigrationChain<Data extends JsonObject = JsonObject> = {\n /\n The number of steps added so far. Also the latest version number (use it\n * in `serialize()`).\n /\n readonly version: number;\n /\n Append a step to the chain.\n \n Returns a new chain typed to `Output`. Does not mutate the chain it is\n * called on, so branching from a shared base chain is safe.\n \n @param step - The migration step to append.\n * @returns A new chain whose data type is the step's `Output`.\n /\n add<Input extends Data = Data, Output extends JsonObject = JsonObject>(\n step: MigrationStep<Input, Output>,\n ): MigrationChain<Output>;\n /\n Apply all pending steps to `state`.\n \n Handles both flat versioned state (with a `version` field) and unversioned\n * legacy state (plain object without `version`, treated as version 0).\n \n @param state - The serialized keyring state (from vault or previous\n * serialize).\n * @returns The migrated state wrapped in a {@link MigrationResult}.\n * @throws If `state` is not a plain object, if its version is newer than the\n * chain's latest version, or if a step's `inputSchema`/`outputSchema`\n * validation fails.\n /\n apply(state: Json): Promise<MigrationResult<Data>>;\n};\n\n/\n Apply the pending steps of a chain to `state`.\n \n Implements {@link MigrationChain.apply} for the chain built from `steps`.\n \n @param steps - All steps of the chain.\n * @param state - The serialized keyring state.\n * @returns The migrated state in a {@link MigrationResult}.\n /\nasync function applySteps<Data extends JsonObject>(\n steps: readonly MigrationStep[],\n state: Json,\n): Promise<MigrationResult<Data>> {\n const latestVersion = steps.length;\n const { version, data: initialData } = getVersionAndData(state);\n\n if (version < 0) {\n throw new Error(\n `State version ${version} is invalid; it cannot be negative`,\n );\n }\n\n if (version > latestVersion) {\n throw new Error(\n `State version ${version} is newer than the latest migration version ${latestVersion}`,\n );\n }\n\n const pendingSteps = steps.slice(version);\n let data: JsonObject = initialData;\n\n for (const step of pendingSteps) {\n assert(data, step.inputSchema ?? JsonObjectStruct);\n data = await step.migrate(data);\n assert(data, step.outputSchema ?? JsonObjectStruct);\n }\n\n return {\n version: latestVersion,\n state: {\n ...data,\n version: latestVersion,\n },\n migrated: pendingSteps.length > 0,\n } as MigrationResult<Data>;\n}\n\n/\n Build a {@link MigrationChain} wrapping the given internal steps.\n \n @param steps - The steps accumulated so far.\n * @returns A chain exposing `add`, `version`, and `apply`.\n /\nfunction buildChain<Data extends JsonObject>(\n steps: readonly MigrationStep[],\n): MigrationChain<Data> {\n return {\n version: steps.length,\n add: <Input extends Data, Output extends JsonObject>(\n step: MigrationStep<Input, Output>,\n ) => buildChain<Output>([...steps, step as unknown as MigrationStep]),\n apply: async (state) => applySteps<Data>(steps, state),\n };\n}\n\n/\n Start a new, empty migration chain.\n \n @example\n * ```typescript\n * const migrations = createMigrations()\n * .add({ migrate: (data) => ({ count: data.numberOfItems }) })\n * .add({ migrate: (data) => ({ ...data, createdAt: Date.now() }) }); // data typed as the first step's output, no cast\n \n const { state, migrated } = await migrations.apply(serializedState);\n * // Persist `state`; re-save if `migrated` is true.\n * ```\n * @returns An empty chain typed to `JsonObject`.\n */\nexport function createMigrations(): MigrationChain<JsonObject> {\n return buildChain<JsonObject>([]);\n}\n"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@metamask/keyring-sdk",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "MetaMask Keyring SDK",
   "keywords": [
     "keyring",
@@ -67,8 +67,8 @@
   },
   "dependencies": {
     "@ethereumjs/tx": "^5.4.0",
-    "@metamask/eth-sig-util": "^8.2.0",
-    "@metamask/keyring-api": "^24.0.0",
+    "@metamask/eth-sig-util": "^9.0.0",
+    "@metamask/keyring-api": "^24.2.0",
     "@metamask/keyring-utils": "^5.0.0",
     "@metamask/scure-bip39": "^2.1.1",
     "@metamask/superstruct": "^3.4.1",