feat(sanity): add exports for sanity/migrate + sanity/migrate/mutations

dev/aliases.cjs

@@ -21,6 +21,7 @@ const devAliases = {
   '@sanity/mutator': './packages/@sanity/mutator/src',
   '@sanity/portable-text-editor': './packages/@sanity/portable-text-editor/src',
   '@sanity/schema': './packages/@sanity/schema/src/_exports',
+  '@sanity/migrate': './packages/@sanity/migrate/src/_exports',
   '@sanity/types': './packages/@sanity/types/src',
   '@sanity/types/parts': './packages/@sanity/types/parts',
   '@sanity/util/fs': './packages/@sanity/util/src/fsTools.ts',

dev/test-studio/migrations/cleanup-empty/cleanup-empty-values.ts

@@ -1,6 +1,6 @@
 /* eslint-disable consistent-return */
-import {unset} from '@sanity/migrate/mutations'
-import {defineMigration} from '@sanity/migrate'
+import {defineMigration} from 'sanity/migrate'
+import {unset} from 'sanity/migrate/mutations'
 
 export default defineMigration({
   name: 'Cleanup empty values',

dev/test-studio/migrations/convert-string-to-pt/convert-string-to-pte.ts

@@ -1,7 +1,7 @@
 /* eslint-disable consistent-return */
-import {set} from 'sanity'
 import {isEqual} from 'lodash'
-import {defineMigration} from '@sanity/migrate'
+import {defineMigration} from 'sanity/migrate'
+import {set} from 'sanity/migrate/mutations'
 
 export default defineMigration({
   name: 'Convert string to PortableText at `some.path` in documents of type `someType`',

dev/tsconfig.dev.json

@@ -11,6 +11,8 @@
       "@sanity/mutator": ["./packages/@sanity/mutator/src"],
       "@sanity/util/fs": ["./packages/@sanity/util/exports/fs.ts"],
       "sanity/_internal": ["./packages/sanity/exports/_internal.ts"],
+      "sanity/migrate": ["./packages/sanity/exports/migrate.ts"],
+      "sanity/migrate/mutations": ["./packages/sanity/exports/migrate-mutations.ts"],
       "sanity/cli": ["./packages/sanity/exports/cli.ts"]
     }
   }

packages/sanity/.eslintignore

@@ -1,8 +1,10 @@
-# package specific
+# legacy package exports
 _internal.js
 cli.js
 desk.js
 form.js
 presentation.js
 router.js
 structure.js
+migrate.js
+/migrate/*

packages/sanity/.gitignore

@@ -19,6 +19,8 @@
 /presentation.js
 /router.js
 /structure.js
+/migrate.js
+/migrate/mutations.js
 
 # Playwright-ct artifacts
 /playwright-ct/report

packages/sanity/exports/migrate-mutations.ts

@@ -0,0 +1 @@
+export * from '@sanity/migrate/mutations'

packages/sanity/exports/migrate.ts

@@ -0,0 +1 @@
+export * from '@sanity/migrate'

packages/sanity/migrate/.gitkeep

@@ -0,0 +1 @@
+This is here to support legacy bundlers

packages/sanity/package.json

@@ -110,6 +110,28 @@
       "import": "./lib/structure.esm.js",
       "default": "./lib/structure.esm.js"
     },
+    "./migrate": {
+      "types": "./lib/exports/migrate.d.ts",
+      "source": "./exports/migrate.ts",
+      "require": "./lib/migrate.js",
+      "node": {
+        "module": "./lib/migrate.esm.js",
+        "import": "./lib/migrate.cjs.mjs"
+      },
+      "import": "./lib/migrate.esm.js",
+      "default": "./lib/migrate.esm.js"
+    },
+    "./migrate/mutations": {
+      "types": "./lib/exports/migrate-mutations.d.ts",
+      "source": "./exports/migrate-mutations.ts",
+      "require": "./lib/migrate-mutations.js",
+      "node": {
+        "module": "./lib/migrate-mutations.esm.js",
+        "import": "./lib/migrate-mutations.cjs.mjs"
+      },
+      "import": "./lib/migrate-mutations.esm.js",
+      "default": "./lib/migrate-mutations.esm.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./lib/index.js",
@@ -130,6 +152,12 @@
       "presentation": [
         "./lib/exports/presentation.d.ts"
       ],
+      "migrate": [
+        "./lib/exports/migrate.d.ts"
+      ],
+      "migrate/mutations": [
+        "./lib/exports/migrate-mutations.d.ts"
+      ],
       "router": [
         "./lib/exports/router.d.ts"
       ],

packages/sanity/src/_internal/cli/commands/migration/createMigrationCommand.ts

@@ -7,34 +7,38 @@ import {MIGRATIONS_DIRECTORY} from './constants'
 import {renameField} from './templates/renameField'
 import {substituteTemplateVariables} from './utils/substituteVariables'
 import {stringToPTE} from './templates/stringToPTE'
+import {cleanSimple} from './templates/clean-simple'
+import {cleanAdvanced} from './templates/clean-advanced'
 
 const helpText = `
-Options
-  --type <type> Type of migration (incremental/full)
-
 Examples
   sanity migration create
   sanity migration create <name>
-  sanity migration create <name> --type incremental
 `
 
-interface MigrateFlags {
-  type?: 'incremental'
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface CreateMigrationFlags {
+  // todo
 }
 
 const TEMPLATES = [
   {name: 'Rename field', template: renameField},
-  {name: 'Convert string field to Portable Text (TODO)', template: stringToPTE},
+  {name: 'Convert string field to Portable Text', template: stringToPTE},
+  {name: 'Clean simple migration to get you started', template: cleanSimple},
+  {
+    name: 'Advanced template using async iterators providing more fine grained control',
+    template: cleanAdvanced,
+  },
 ]
 
-const createMigrationCommand: CliCommandDefinition<MigrateFlags> = {
+const createMigrationCommand: CliCommandDefinition<CreateMigrationFlags> = {
   name: 'create',
   group: 'migration',
   signature: '[NAME]',
   helpText,
   description: 'Create a new content migration within your project',
   action: async (args, context) => {
-    const {output, prompt, workDir} = context
+    const {output, prompt, workDir, chalk} = context
     const flags = args.extOptions
 
     const name = await prompt.single({
@@ -76,10 +80,25 @@ const createMigrationCommand: CliCommandDefinition<MigrateFlags> = {
       type: docType,
     })
 
-    await fs.writeFile(path.join(destDir, 'index.ts'), finalTemplate)
+    const definitionFile = path.join(destDir, 'index.ts')
 
+    await fs.writeFile(definitionFile, finalTemplate)
+    // To dry run it, run \`sanity migration run ${sluggedName}\``)
+    output.print()
+    output.print(`Migration created!`)
+    output.print('Next steps:')
+    output.print(
+      `- Open ${chalk.bold(definitionFile)} in your code editor and write your migration`,
+    )
+    output.print(
+      `- Dry run the migration with \`${chalk.bold(
+        `sanity migrate ${sluggedName}}`,
+      )}\` --project-id=[PROJECT ID] --dataset <DATASET> `,
+    )
     output.print(
-      `Created migration "${name}" in ${destDir}. To dry run it, run \`sanity migration run ${sluggedName}\``,
+      `- Run the migration against a dataset with \`${chalk.bold(
+        `sanity migrate ${sluggedName}}`,
+      )}\` --project-id=[PROJECT ID] --dataset <DATASET> --dry-run false`,
     )
   },
 }

packages/sanity/src/_internal/cli/commands/migration/templates/clean-advanced.ts

@@ -0,0 +1,13 @@
+export const cleanAdvanced = `
+import {mutations, defineMigration} from 'sanity/migrate'
+
+export default defineMigration({
+  name: '%migrationName%',
+  documentType: '%type%',
+  *migrate(documents) {
+    for await (const document in documents) {
+      yield mutations.createIfNotExists(document)
+    }
+  }
+})
+`

packages/sanity/src/_internal/cli/commands/migration/templates/clean-simple.ts

@@ -0,0 +1,50 @@
+export const cleanSimple = `
+import {defineMigration} from 'sanity/migrate'
+
+export default defineMigration({
+  name: '%migrationName%',
+  documentType: '%type%',
+  migrate: {
+    document(doc) {
+      // this will be called for every document of the matching type
+      // any patch returned will be applied to the document
+      // you can also return mutations that touches other documents
+    },
+    node(node, path, context) {
+      // this will be called for every node in every document of the matching type
+      // any patch returned will be applied to the document
+      // you can also return mutations that touches other documents
+    },
+    object(node, path, context) {
+      // this will be called for every object node in every document of the matching type
+      // any patch returned will be applied to the document
+      // you can also return mutations that touches other documents
+    },
+    array(node, path, context) {
+      // this will be called for every array node in every document of the matching type
+      // any patch returned will be applied to the document
+      // you can also return mutations that touches other documents
+    },
+    string(node, path, context) {
+      // this will be called for every string node in every document of the matching type
+      // any patch returned will be applied to the document
+      // you can also return mutations that touches other documents
+    },
+    number(node, path, context) {
+      // this will be called for every number node in every document of the matching type
+      // any patch returned will be applied to the document
+      // you can also return mutations that touches other documents
+    },
+    boolean(node, path, context) {
+      // this will be called for every boolean node in every document of the matching type
+      // any patch returned will be applied to the document
+      // you can also return mutations that touches other documents
+    },
+    null(node, path, context) {
+      // this will be called for every null node in every document of the matching type
+      // any patch returned will be applied to the document
+      // you can also return mutations that touches other documents
+    },
+  },
+})
+`

packages/sanity/src/_internal/cli/commands/migration/templates/renameField.ts

@@ -1,15 +1,11 @@
 export const renameField = `
-import {defineNodeMigration} from '@sanity/migrate'
-import {patch, at, set, unset} from '@sanity/migrate/mutations'
+import {mutations, defineMigration} from 'sanity/migrate'
+import {patch, at, set, unset} from 'sanity/migrate/mutations'
 
-export default defineNodeMigration({
+export default defineMigration({
   name: '%migrationName%',
-  type: '%type%',
-  document(doc) {
-    return patch(doc._id, [
-      at('address', set(doc.location)),
-      at('location', unset())
-    ])
-  },
+  documentType: '%type%',
+  migrate: {
+  }
 })
 `

packages/sanity/src/_internal/cli/commands/migration/templates/stringToPTE.ts

@@ -1,29 +1,31 @@
 export const stringToPTE = `
-import {defineNodeMigration} from '@sanity/migrate'
-import {patch, at, set, unset} from '@sanity/migrate/mutations'
+import {defineMigration} from 'sanity/migrate'
+import {patch, at, set, unset} from 'sanity/mutations'
 
 const targetPath = parsePath('%targetPath%')
 
-export default defineNodeMigration({
+export default defineMigration({
   name: '%migrationName%',
   type: '%type%',
-  string(node, path, ctx) {
-    if (isEqual(path, targetPath)) {
-      return set([
-        {
-          style: 'normal',
-          _type: 'block',
-          children: [
-            {
-              _type: 'span',
-              marks: [],
-              text: node,
-            },
-          ],
-          markDefs: [],
-        },
-      ])
-    }
+  migrate: {
+    string(node, path, ctx) {
+      if (isEqual(path, targetPath)) {
+        return set([
+          {
+            style: 'normal',
+            _type: 'block',
+            children: [
+              {
+                _type: 'span',
+                marks: [],
+                text: node,
+              },
+            ],
+            markDefs: [],
+          },
+        ])
+      }
+    },
   },
 })
 `