feat: add createWriteClient and createMigration

[angeloashmore]

Resolves: N/A

Description

A proof-of-concept alternative to #350. Do not merge.

This PR does not handle assets. A strategy similar to the one presented here for documents should be possible for assets.

Checklist

• If my changes require tests, I added them.
• If my changes affect backward compatibility, it has been discussed.
• If my changes require an update to the CONTRIBUTING.md guide, I updated it.

Preview

import {
  createWriteClient,
  createMigration,
  type Content,
} from "@prismicio/client";

const client = createWriteClient<Content.AllDocumentTypes>(
  "example-prismic-repo",
  { writeToken: "..." },
);
const migration = createMigration<Content.AllDocumentTypes>();

// Creating a document with a content relationship.
// This example also demonstrates a circular reference.
migration.createDocument(
  {
    type: "page",
    lang: "en-us",
    uid: "page-1",
    tags: [],
    data: {
      title: [
        {
          type: "heading1",
          text: "Hello from `@prismicio/client`",
          spans: [],
        },
      ],
      related_page: () => migration.getByUID("page", "page-2"),
    },
  },
  "Page 1",
);
migration.createDocument(
  {
    type: "page",
    lang: "en-us",
    uid: "page-2",
    tags: [],
    data: {
      title: [
        {
          type: "heading1",
          text: "This is another page",
          spans: [],
        },
      ],
      related_page: () => migration.getByUID("page", "page-1"),
    },
  },
  "Page 2",
);

// Updating an existing document.
// This example also shows a hyperlink in a rich text field.
const anotherPage = await client.getByUID("page", "another-page");
anotherPage.description = [
  {
    type: "paragraph",
    text: "Not to be confused with another page.",
    spans: [
      {
        type: "hyperlink",
        start: 0,
        end: 10,
        data: () => client.getByUID("page", "home"),
      },
    ],
  },
];
migration.updateDocument(anotherPage);

// Copying a document from Prismic.
// It handles updating old relationship IDs to new ones.
// This isn't a good example since the document is from the original repo,
// but the same logic is applied.
const home = await client.getByUID("page", "home");
home.uid = "copied-home";
migration.createDocumentFromPrismic(home, "Home");

await client.migrate(migration);

How to QA ¹

Footnotes

1. Please use these labels when submitting a review:
   ❓ #ask: Ask a question.
   💡 #idea: Suggest an idea.
   ⚠️ #issue: Strongly suggest a change.
   🎉 #nice: Share a compliment. ↩

[angeloashmore]

These ideas were adopted by #350. Closing.