plugin/settings-migration-api

The generic half of a settings HANDOVER contract: one plugin offers another the settings it used to own, and the plugin that owns them now decides what to do with the offer.

The shape below is deliberately the envelope and nothing else. A handover has three parts, and only one of them is generic:

• The envelope — a migrateSettings call, who is proposing, and whether the user applied it. Identical for every pair of plugins, so it lives here. - The payload — which settings are being proposed. Entirely the pair’s own business, so it stays a type parameter and is never named here. - The provider’s identity — its plugin id and display name. Also the pair’s own business, and not something this library has any standing to own.

Why it is declared rather than imported. A provider is typically an Obsidian plugin repo, not an npm package, so a consumer has nothing to depend on and hand-writes its own copy of the contract. Five copies of one contract with no compiler link between them means drift is SILENT — every copy still compiles and the handover fails at runtime instead. Declaring the envelope here gives both ends one declaration to compile against; watchPluginApi still negotiates the version at runtime, because the two ends ship independently and always will.

The provider publishes it:

publishPluginApi<SettingsMigrationApi<MyMigratableSettings>>({
  api: this.settingsMigrationApi,
  apiVersion: '1.0.0',
  contract: getSettingsMigrationApiContract<MyMigratableSettings>(),
  plugin: this
});

The consumer reaches it through SettingsMigrationComponent, which owns the whole offer-and-retire dance, and checks the provider against the same contract by default.

Interfaces

Interface	Description
MigrateSettingsParams	Parameters for SettingsMigrationApi.migrateSettings.
MigrateSettingsResult	The outcome of SettingsMigrationApi.migrateSettings.
SettingsMigrationApi	The API a plugin publishes when it is willing to receive settings another plugin used to own.

Functions

Function	Description
getSettingsMigrationApiContract	The contract of SettingsMigrationApi, which both ends of a handover compile against: the provider publishes it, and SettingsMigrationComponent checks the provider against it unless given another. The proposed settings are checked to be an object and no further, because their shape is the pair’s own business (see the file header).