diff --git a/src/Migration.ts b/src/Migration.ts index 4092fdc2..9becfa56 100644 --- a/src/Migration.ts +++ b/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 = MigrationPrismicDocument, > { - #documents: TMigrationDocuments[] = [] - #documentsByUID: Record> = {} + #documents: { + document: TMigrationDocuments + params: MigrationPrismicDocumentParams + }[] = [] + #indexedDocuments: Record> = {} #assets: Map = 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( document: ExtractMigrationDocumentType, + documentName: MigrationPrismicDocumentParams["documentName"], + params: Omit = {}, ): ExtractMigrationDocumentType { - 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, >(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, >(documentType: TType): TMigrationDocument | undefined | undefined { - return this.#documentsByUID[documentType]?.[SINGLE_KEY] as + return this.#indexedDocuments[documentType]?.[SINGLE_KEY] as | TMigrationDocument | undefined } diff --git a/src/types/migration/asset.ts b/src/types/migration/asset.ts index 93a5b535..088ae5cc 100644 --- a/src/types/migration/asset.ts +++ b/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[0]>[0] + + /** + * File to be uploaded as an asset. + */ file: string | URL | File | NonNullable[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[] } diff --git a/src/types/migration/document.ts b/src/types/migration/document.ts index 43af8974..fcf0b2c1 100644 --- a/src/types/migration/document.ts +++ b/src/types/migration/document.ts @@ -106,26 +106,6 @@ export type MigrationPrismicDocument< > = TDocument extends PrismicDocument ? 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) - /** * 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 }> : 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) +} diff --git a/src/types/migration/fields.ts b/src/types/migration/fields.ts index 288a4fae..ca2b13e0 100644 --- a/src/types/migration/fields.ts +++ b/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) + | undefined +/** + * An alternate version of the {@link LinkField} for use with the migration API. + */ export type MigrationLinkField = | MigrationLinkToMediaField | MigrationContentRelationshipField diff --git a/src/types/migration/richText.ts b/src/types/migration/richText.ts index 2f8935e1..18e86f7e 100644 --- a/src/types/migration/richText.ts +++ b/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 & { 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 } diff --git a/test/types/migration-document.types.ts b/test/types/migration-document.types.ts index a745ced2..38d73793 100644 --- a/test/types/migration-document.types.ts +++ b/test/types/migration-document.types.ts @@ -20,7 +20,6 @@ import type * as prismic from "../../src" } expectType({ - title: "", uid: "", type: "", lang: "", @@ -31,7 +30,6 @@ expectType({ * Supports any field when generic. */ expectType({ - title: "", uid: "", type: "", lang: "", @@ -63,7 +61,6 @@ type MigrationDocuments = prismic.MigrationPrismicDocument * Infers data type from document type. */ expectType({ - title: "", uid: "", type: "foo", lang: "", @@ -72,7 +69,6 @@ expectType({ // @ts-expect-error - `FooDocument` has no `bar` field in `data` expectType({ - title: "", uid: "", type: "foo", lang: "", @@ -82,7 +78,6 @@ expectType({ }) expectType({ - title: "", uid: "", type: "bar", lang: "", @@ -93,7 +88,6 @@ expectType({ // @ts-expect-error - `bar` is missing in `data` expectType({ - title: "", uid: "", type: "bar", lang: "", @@ -140,7 +134,6 @@ type MigrationAdvancedDocuments = // Static expectType({ - title: "", uid: "", type: "static", lang: "", @@ -158,7 +151,6 @@ expectType({ // Group expectType({ - title: "", uid: "", type: "group", lang: "", @@ -180,7 +172,6 @@ expectType({ // Slice expectType({ - title: "", uid: "", type: "slice", lang: "", diff --git a/test/types/migration.types.ts b/test/types/migration.types.ts index a6899bd0..8e8a0d8b 100644 --- a/test/types/migration.types.ts +++ b/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 >(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,