From f987324804d59e55a3a5e6770389305d88f39194 Mon Sep 17 00:00:00 2001 From: Chris Villa Date: Mon, 27 Nov 2023 18:12:33 +0000 Subject: [PATCH] feat: add data migration API --- apps/docs/pages/docs/api-reference/data.mdx | 34 ++++++++++-------- .../pages/docs/api-reference/functions.mdx | 1 + .../docs/api-reference/functions/migrate.mdx | 21 +++++++++++ .../pages/docs/integrating-puck/_meta.json | 4 ++- .../docs/integrating-puck/data-migration.mdx | 36 +++++++++++++++++++ packages/core/index.ts | 2 +- 6 files changed, 81 insertions(+), 17 deletions(-) create mode 100644 apps/docs/pages/docs/api-reference/functions/migrate.mdx create mode 100644 apps/docs/pages/docs/integrating-puck/data-migration.mdx diff --git a/apps/docs/pages/docs/api-reference/data.mdx b/apps/docs/pages/docs/api-reference/data.mdx index a13dec7aab..1c384c6381 100644 --- a/apps/docs/pages/docs/api-reference/data.mdx +++ b/apps/docs/pages/docs/api-reference/data.mdx @@ -18,13 +18,17 @@ An object produced by Puck describing the shape of content. } ``` -## `content` +This document describes the latest supported data. To learn more about automatic data migration, visit the [Data Migration docs](/docs/integrating-puck/data-migration). + +## Params + +#### `content` An array containing an object for each component in the main content region. -### `content[*]` +#### `content[*]` -#### Params +##### Params | Param | Example | Type | Status | | ------------------------------ | ---------------------------------- | ------- | -------- | @@ -32,13 +36,13 @@ An array containing an object for each component in the main content region. | [`props`](#contentprops) | `props: { title: "Hello, world" }` | Object | Required | | [`readOnly`](#contentreadonly) | `readOnly: { title: true }` | Object | - | -#### Required params +##### Required params -##### `content[*].type` +###### `content[*].type` The type of the component, which tells Puck to run the [`render()`](/docs/api-reference/configuration/component-config#renderprops) method for the component of the [same key](/docs/api-reference/config#components). -##### `content[*].props` +###### `content[*].props` The props stored based on the [`component config`](/docs/api-reference/configuration/component-config) that Puck will pass to the [`render()`](/docs/api-reference/configuration/component-config#renderprops) method for the component of the [same key](/docs/api-reference/config#components). @@ -58,9 +62,9 @@ The props stored based on the [`component config`](/docs/api-reference/configura } ``` -#### Optional params +##### Optional params -##### `content[*].readOnly` +###### `content[*].readOnly` An object describing which fields are set to [read-only](/docs/api-reference/configuration/component-config#datareadonly-1). @@ -83,20 +87,20 @@ An object describing which fields are set to [read-only](/docs/api-reference/con } ``` -## `root` +### `root` An object describing data for the [`root` config](/docs/api-reference/config#root). -### Params +#### Params | Param | Example | Type | Status | | --------------------------- | ---------------------------------- | ------ | ------ | | [`props`](#rootprops) | `props: { title: "Hello, world" }` | Object | - | | [`readOnly`](#rootreadonly) | `readOnly: { title: true }` | Object | - | -### Optional params +#### Optional params -#### `root.props` +##### `root.props` The props stored based on the [`component config`](/docs/api-reference/configuration/component-config) that Puck will pass to the [`render()`](/docs/api-reference/configuration/component-config#renderprops) method for the [`root` config](/docs/api-reference/config#root). @@ -108,7 +112,7 @@ The props stored based on the [`component config`](/docs/api-reference/configura } ``` -#### `root.readOnly` +##### `root.readOnly` An object describing which fields are set to [read-only](/docs/api-reference/configuration/component-config#datareadonly-1). @@ -124,11 +128,11 @@ An object describing which fields are set to [read-only](/docs/api-reference/con } ``` -## `zones` +### `zones` An object describing nested content regions for each [DropZone](/docs/api-reference/components/drop-zone). -### `zones[zoneKey]` +#### `zones[zoneKey]` An array describing the content for a particular region. Shares a shape with [`content`](#content). diff --git a/apps/docs/pages/docs/api-reference/functions.mdx b/apps/docs/pages/docs/api-reference/functions.mdx index 41a56d4eef..69985880d6 100644 --- a/apps/docs/pages/docs/api-reference/functions.mdx +++ b/apps/docs/pages/docs/api-reference/functions.mdx @@ -1,4 +1,5 @@ # Functions +- [migrate](functions/migrate) - Migrate a legacy [data payload](/docs/api-reference/data) to the latest shape. - [resolveAllData](functions/resolve-all-data) - Utility function to execute all [`resolveData` methods](/docs/api-reference/configuration/component-config#resolvedatadata-params) on a data payload. - [transformProps](functions/transform-props) - Transform component props stored in the [data payload](/docs/api-reference/data). Use this for migrations, like prop renames. diff --git a/apps/docs/pages/docs/api-reference/functions/migrate.mdx b/apps/docs/pages/docs/api-reference/functions/migrate.mdx new file mode 100644 index 0000000000..55799dc6a9 --- /dev/null +++ b/apps/docs/pages/docs/api-reference/functions/migrate.mdx @@ -0,0 +1,21 @@ +--- +title: migrate +--- + +# migrate + +Migrate the [Data payload](/docs/api-reference/data) to the latest shape, automatically transforming deprecated data. + +```tsx copy showLineNumbers {7-10} +import { migrate } from "@measured/puck"; + +migrate(legacyData); +``` + +## Returns + +The updated [Data](/docs/api-reference/data) object. + +## Notes + +- Called internally whenever you pass data to [``](/docs/api-reference/components/puck) or [``](/docs/api-reference/components/render), or calling [`transformProps`](/docs/api-reference/functions/transform-props). diff --git a/apps/docs/pages/docs/integrating-puck/_meta.json b/apps/docs/pages/docs/integrating-puck/_meta.json index 7ba7328fdf..0c71b0b1e1 100644 --- a/apps/docs/pages/docs/integrating-puck/_meta.json +++ b/apps/docs/pages/docs/integrating-puck/_meta.json @@ -5,5 +5,7 @@ "categories": {}, "dynamic-props": {}, "external-data-sources": {}, - "server-components": {} + "server-components": {}, + "prop-migration": {}, + "data-migration": {} } diff --git a/apps/docs/pages/docs/integrating-puck/data-migration.mdx b/apps/docs/pages/docs/integrating-puck/data-migration.mdx new file mode 100644 index 0000000000..cadfe9b178 --- /dev/null +++ b/apps/docs/pages/docs/integrating-puck/data-migration.mdx @@ -0,0 +1,36 @@ +# Data Migration + +Puck automatically migrates legacy data payloads on render, transforming any deprecated properties to their latest counterparts as described by [Data](/docs/api-reference/data). + +This data migration strategy reduces the number of breaking changes required. + +Specifically, Puck will migrate the data when rendering [``](/docs/api-reference/components/puck) or [``](/docs/api-reference/components/render), or calling [`transformProps`](/docs/api-reference/functions/transform-props). + +## Types + +Puck exports two types: + +- `Data`, a backwards compatible type that supports all deprecated data shapes still supported. +- `CurrentData`, the latest data shape used by Puck internally. + +You'll generally want to use `Data` to avoid breaking changes during minor version upgrades, but can use `CurrentData` to stay on the bleeding edge. + +## Manually migrating data + +If you manually want to update your data payload to the latest `CurrentData`, you can run the `migrate` method: + +```tsx +import { migrate } from "@measured/puck"; + +migrate(legacyData); +``` + +## Opting out + +There is currently no way to opt-out of automatic data migrations. + +## Further reading + +- [`Data` API reference](/docs/api-reference/data) +- [`migrate` API reference](/docs/api-reference/functions/migrate) +- [Prop migration](/docs/integrating-puck/prop-migration) diff --git a/packages/core/index.ts b/packages/core/index.ts index 5e15e92ab6..b3a54b72e1 100644 --- a/packages/core/index.ts +++ b/packages/core/index.ts @@ -11,6 +11,6 @@ export * from "./components/Puck"; export * from "./components/Render"; export * from "./lib/resolve-all-data"; -export { transformProps } from "./transforms"; +export { migrate, transformProps } from "./transforms"; export { FieldLabel } from "./components/InputOrGroup";