refactor: MigrationPrismicDocumentParams

src/Migration.ts

@@ -1,6 +1,9 @@
 import type { Asset } from "./types/api/asset/asset"
 import type { MigrationAsset } from "./types/migration/asset"
-import type { MigrationPrismicDocument } from "./types/migration/document"
+import type {
+	MigrationPrismicDocument,
+	MigrationPrismicDocumentParams,
+} from "./types/migration/document"
 import {
 	MigrationFieldType,
 	type MigrationImageField,
@@ -43,8 +46,11 @@ export class Migration<
 	TMigrationDocuments extends
 		MigrationPrismicDocument<TDocuments> = MigrationPrismicDocument<TDocuments>,
 > {
-	#documents: TMigrationDocuments[] = []
-	#documentsByUID: Record<string, Record<string, TMigrationDocuments>> = {}
+	#documents: {
+		document: TMigrationDocuments
+		params: MigrationPrismicDocumentParams
+	}[] = []
+	#indexedDocuments: Record<string, Record<string, TMigrationDocuments>> = {}
 
 	#assets: Map<MigrationAsset["file"], MigrationAsset> = new Map()
 
@@ -54,7 +60,7 @@ export class Migration<
 	createAsset(
 		file: MigrationAsset["file"],
 		filename: MigrationAsset["filename"],
-		options?: {
+		params?: {
 			notes?: string
 			credits?: string
 			alt?: string
@@ -117,13 +123,18 @@ export class Migration<
 
 	createDocument<TType extends TMigrationDocuments["type"]>(
 		document: ExtractMigrationDocumentType<TMigrationDocuments, TType>,
+		documentName: MigrationPrismicDocumentParams["documentName"],
+		params: Omit<MigrationPrismicDocumentParams, "documentName"> = {},
 	): ExtractMigrationDocumentType<TMigrationDocuments, TType> {
-		this.#documents.push(document)
+		this.#documents.push({
+			document,
+			params: { documentName, ...params },
+		})
 
-		if (!(document.type in this.#documentsByUID)) {
-			this.#documentsByUID[document.type] = {}
+		if (!(document.type in this.#indexedDocuments)) {
+			this.#indexedDocuments[document.type] = {}
 		}
-		this.#documentsByUID[document.type][document.uid || SINGLE_KEY] = document
+		this.#indexedDocuments[document.type][document.uid || SINGLE_KEY] = document
 
 		return document
 	}
@@ -135,7 +146,7 @@ export class Migration<
 			{ type: TType }
 		> = Extract<TMigrationDocuments, { type: TType }>,
 	>(documentType: TType, uid: string): TMigrationDocument | undefined {
-		return this.#documentsByUID[documentType]?.[uid] as
+		return this.#indexedDocuments[documentType]?.[uid] as
 			| TMigrationDocument
 			| undefined
 	}
@@ -147,7 +158,7 @@ export class Migration<
 			{ type: TType }
 		> = Extract<TMigrationDocuments, { type: TType }>,
 	>(documentType: TType): TMigrationDocument | undefined | undefined {
-		return this.#documentsByUID[documentType]?.[SINGLE_KEY] as
+		return this.#indexedDocuments[documentType]?.[SINGLE_KEY] as
 			| TMigrationDocument
 			| undefined
 	}

src/types/migration/asset.ts

@@ -1,9 +1,45 @@
+/**
+ * An asset to be uploaded to Prismic media library
+ */
 export type MigrationAsset = {
+	/**
+	 * ID of the asset used to reference it in Prismic documents.
+	 *
+	 * @internal
+	 */
 	id: string | URL | File | NonNullable<ConstructorParameters<File>[0]>[0]
+
+	/**
+	 * File to be uploaded as an asset.
+	 */
 	file: string | URL | File | NonNullable<ConstructorParameters<File>[0]>[0]
+
+	/**
+	 * Filename of the asset.
+	 */
 	filename: string
+
+	/**
+	 * Notes about the asset. Notes are private and only visible in Prismic media
+	 * library.
+	 */
 	notes?: string
+
+	/**
+	 * Credits and copyright for the asset if any.
+	 */
 	credits?: string
+
+	/**
+	 * Alternate text for the asset.
+	 */
 	alt?: string
+
+	/**
+	 * Tags associated with the asset.
+	 *
+	 * @remarks
+	 * Tags should be at least 3 characters long and 20 characters at most.
+	 */
 	tags?: string[]
 }

src/types/migration/document.ts

@@ -106,26 +106,6 @@ export type MigrationPrismicDocument<
 > =
 	TDocument extends PrismicDocument<infer TData, infer TType, infer TLang>
 		? MakeUIDOptional<{
-				/**
-				 * Title of the document displayed in the editor.
-				 */
-				title: string
-
-				/**
-				 * A link to the master language document.
-				 */
-				// We're forced to inline `MigrationContentRelationshipField` here, otherwise
-				// it creates a circular reference to itself which makes TypeScript unhappy.
-				// (but I think it's weird and it doesn't make sense :thinking:)
-				masterLanguageDocument?:
-					| PrismicDocument
-					| MigrationPrismicDocument
-					| (() =>
-							| Promise<PrismicDocument | MigrationPrismicDocument | undefined>
-							| PrismicDocument
-							| MigrationPrismicDocument
-							| undefined)
-
 				/**
 				 * Type of the document.
 				 */
@@ -150,8 +130,8 @@ export type MigrationPrismicDocument<
 
 				/**
 				 * Alternate language documents from Prismic content API. Used as a
-				 * substitute to the `masterLanguageDocument` property when the latter
-				 * is not available.
+				 * substitute to the `masterLanguageDocument` options when the latter is
+				 * not available.
 				 *
 				 * @internal
 				 */
@@ -164,3 +144,30 @@ export type MigrationPrismicDocument<
 				data: FieldsToMigrationFields<TData>
 			}>
 		: never
+
+/**
+ * Parameters used when creating a Prismic document with the migration API.
+ *
+ * @see More details on the migraiton API: {@link https://prismic.io/docs/migration-api-technical-reference}
+ */
+export type MigrationPrismicDocumentParams = {
+	/**
+	 * Name of the document displayed in the editor.
+	 */
+	documentName: string
+
+	/**
+	 * A link to the master language document.
+	 */
+	// We're forced to inline `MigrationContentRelationshipField` here, otherwise
+	// it creates a circular reference to itself which makes TypeScript unhappy.
+	// (but I think it's weird and it doesn't make sense :thinking:)
+	masterLanguageDocument?:
+		| PrismicDocument
+		| MigrationPrismicDocument
+		| (() =>
+				| Promise<PrismicDocument | MigrationPrismicDocument | undefined>
+				| PrismicDocument
+				| MigrationPrismicDocument
+				| undefined)
+}

src/types/migration/fields.ts

@@ -1,4 +1,12 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { ContentRelationshipField } from "../value/contentRelationship"
 import type { PrismicDocument } from "../value/document"
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { ImageField } from "../value/image"
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { LinkField } from "../value/link"
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { LinkToMediaField } from "../value/linkToMedia"
 
 import type { MigrationAsset } from "./asset"
 import type { MigrationPrismicDocument } from "./document"
@@ -8,23 +16,41 @@ export const MigrationFieldType = {
 	LinkToMedia: "linkToMedia",
 } as const
 
-export type MigrationImageField = MigrationAsset & {
-	migrationType: typeof MigrationFieldType.Image
-}
+/**
+ * An alternate version of the {@link ImageField} for use with the migration API.
+ */
+export type MigrationImageField =
+	| (MigrationAsset & {
+			migrationType: typeof MigrationFieldType.Image
+	  })
+	| undefined
 
-export type MigrationLinkToMediaField = MigrationAsset & {
-	migrationType: typeof MigrationFieldType.LinkToMedia
-}
+/**
+ * An alternate version of the {@link LinkToMediaField} for use with the
+ * migration API.
+ */
+export type MigrationLinkToMediaField =
+	| (MigrationAsset & {
+			migrationType: typeof MigrationFieldType.LinkToMedia
+	  })
+	| undefined
 
+/**
+ * An alternate version of the {@link ContentRelationshipField} for use with the
+ * migration API.
+ */
 export type MigrationContentRelationshipField =
 	| PrismicDocument
-	| MigrationPrismicDocument
 	| (() =>
 			| Promise<PrismicDocument | MigrationPrismicDocument | undefined>
 			| PrismicDocument
 			| MigrationPrismicDocument
 			| undefined)
+	| undefined
 
+/**
+ * An alternate version of the {@link LinkField} for use with the migration API.
+ */
 export type MigrationLinkField =
 	| MigrationLinkToMediaField
 	| MigrationContentRelationshipField

src/types/migration/richText.ts

@@ -2,10 +2,18 @@ import type { RTImageNode, RTLinkNode } from "../value/richText"
 
 import type { MigrationImageField, MigrationLinkField } from "./fields"
 
+/**
+ * An alternate version of {@link RTLinkNode} that supports
+ * {@link MigrationLinkField} for use with the migration API.
+ */
 export type MigrationRTLinkNode = Omit<RTLinkNode, "data"> & {
 	data: MigrationLinkField
 }
 
+/**
+ * An alternate version of {@link RTImageNode} that supports
+ * {@link MigrationImageField} for use with the migration API.
+ */
 export type MigrationRTImageNode = MigrationImageField & {
 	linkTo?: RTImageNode["linkTo"] | MigrationLinkField
 }

test/types/migration-document.types.ts

@@ -20,7 +20,6 @@ import type * as prismic from "../../src"
 }
 
 expectType<prismic.MigrationPrismicDocument>({
-	title: "",
 	uid: "",
 	type: "",
 	lang: "",
@@ -31,7 +30,6 @@ expectType<prismic.MigrationPrismicDocument>({
  * Supports any field when generic.
  */
 expectType<prismic.MigrationPrismicDocument>({
-	title: "",
 	uid: "",
 	type: "",
 	lang: "",
@@ -63,7 +61,6 @@ type MigrationDocuments = prismic.MigrationPrismicDocument<Documents>
  * Infers data type from document type.
  */
 expectType<MigrationDocuments>({
-	title: "",
 	uid: "",
 	type: "foo",
 	lang: "",
@@ -72,7 +69,6 @@ expectType<MigrationDocuments>({
 
 // @ts-expect-error - `FooDocument` has no `bar` field in `data`
 expectType<MigrationDocuments>({
-	title: "",
 	uid: "",
 	type: "foo",
 	lang: "",
@@ -82,7 +78,6 @@ expectType<MigrationDocuments>({
 })
 
 expectType<MigrationDocuments>({
-	title: "",
 	uid: "",
 	type: "bar",
 	lang: "",
@@ -93,7 +88,6 @@ expectType<MigrationDocuments>({
 
 // @ts-expect-error - `bar` is missing in `data`
 expectType<MigrationDocuments>({
-	title: "",
 	uid: "",
 	type: "bar",
 	lang: "",
@@ -140,7 +134,6 @@ type MigrationAdvancedDocuments =
 
 // Static
 expectType<MigrationAdvancedDocuments>({
-	title: "",
 	uid: "",
 	type: "static",
 	lang: "",
@@ -158,7 +151,6 @@ expectType<MigrationAdvancedDocuments>({
 
 // Group
 expectType<MigrationAdvancedDocuments>({
-	title: "",
 	uid: "",
 	type: "group",
 	lang: "",
@@ -180,7 +172,6 @@ expectType<MigrationAdvancedDocuments>({
 
 // Slice
 expectType<MigrationAdvancedDocuments>({
-	title: "",
 	uid: "",
 	type: "slice",
 	lang: "",

test/types/migration.types.ts

@@ -78,25 +78,29 @@ expectType<
  */
 
 // Default
-const defaultCreateDocument = defaultMigration.createDocument({
-	title: "",
-	type: "",
-	uid: "",
-	lang: "",
-	data: {},
-})
+const defaultCreateDocument = defaultMigration.createDocument(
+	{
+		type: "",
+		uid: "",
+		lang: "",
+		data: {},
+	},
+	"",
+)
 expectType<
 	TypeEqual<typeof defaultCreateDocument, prismic.MigrationPrismicDocument>
 >(true)
 
 // Documents
-const documentsCreateDocument = documentsMigration.createDocument({
-	title: "",
-	type: "foo",
-	uid: "",
-	lang: "",
-	data: {},
-})
+const documentsCreateDocument = documentsMigration.createDocument(
+	{
+		type: "foo",
+		uid: "",
+		lang: "",
+		data: {},
+	},
+	"",
+)
 expectType<
 	TypeEqual<
 		typeof documentsCreateDocument,