Skip to content

Commit

Permalink
docs: document new types
Browse files Browse the repository at this point in the history
  • Loading branch information
@lihbr
lihbr committed Sep 12, 2024
1 parent 895c86c commit 9a07277
Show file tree
Hide file tree
Showing 10 changed files with 538 additions and 100 deletions.
218 changes: 195 additions & 23 deletions src/Migration.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,22 +48,77 @@ export class Migration<
MigrationDocumentValue<TDocuments> = MigrationDocumentValue<TDocuments>,
> {
/**
* Assets registered in the migration.
*
* @internal
*/
_assets: Map<MigrationAssetConfig["file"], MigrationAssetConfig> = new Map()

/**
* Documents registered in the migration.
*
* @internal
*/
_documents: MigrationDocument<TDocuments>[] = []

/**
* A map indexing documents by their type and UID used for quick lookups by
* the {@link getByUID} and {@link getSingle} methods.
*/
#indexedDocuments: Record<
string,
Record<string, MigrationDocument<TDocuments>>
> = {}

/**
* Registers an asset to be created in the migration from an asset object.
*
* @remarks
* This method does not create the asset in Prismic media library right away.
* Instead it registers it in your migration. The asset will be created when
* the migration is executed through the `writeClient.migrate()` method.
*
* @param asset - An asset object from Prismic Asset API.
*
* @returns A migration asset field instance configured to be serialized as an
* image field by default.
*/
createAsset(asset: Asset): MigrationImage

/**
* Registers an asset to be created in the migration from an image or link to
* media field.
*
* @remarks
* This method does not create the asset in Prismic media library right away.
* Instead it registers it in your migration. The asset will be created when
* the migration is executed through the `writeClient.migrate()` method.
*
* @param imageOrLinkToMediaField - An image or link to media field from
* Prismic Document API.
*
* @returns A migration asset field instance configured to be serialized as an
* image field by default.
*/
createAsset(
asset: Asset | FilledImageFieldImage | FilledLinkToMediaField,
imageOrLinkToMediaField: FilledImageFieldImage | FilledLinkToMediaField,
): MigrationImage

/**
* Registers an asset to be created in the migration from a file.
*
* @remarks
* This method does not create the asset in Prismic media library right away.
* Instead it registers it in your migration. The asset will be created when
* the migration is executed through the `writeClient.migrate()` method.
*
* @param file - The URL or content of the file to be created.
* @param filename - The filename of the asset.
* @param params - Additional asset data.
*
* @returns A migration asset field instance configured to be serialized as an
* image field by default.
*/
createAsset(
file: MigrationAssetConfig["file"],
filename: MigrationAssetConfig["filename"],
Expand All @@ -74,8 +129,21 @@ export class Migration<
tags?: string[]
},
): MigrationImage

/**
* Registers an asset to be created in the migration from a file, an asset
* object, or an image or link to media field.
*
* @remarks
* This method does not create the asset in Prismic media library right away.
* Instead it registers it in your migration. The asset will be created when
* the migration is executed through the `writeClient.migrate()` method.
*
* @returns A migration asset field instance configured to be serialized as an
* image field by default.
*/
createAsset(
fileOrAsset:
fileOrAssetOrField:
| MigrationAssetConfig["file"]
| Asset
| FilledImageFieldImage
Expand All @@ -95,26 +163,31 @@ export class Migration<
): MigrationImage {
let asset: MigrationAssetConfig
let maybeInitialField: FilledImageFieldImage | undefined
if (typeof fileOrAsset === "object" && "url" in fileOrAsset) {
if ("dimensions" in fileOrAsset || "link_type" in fileOrAsset) {
const url = fileOrAsset.url.split("?")[0]
if (typeof fileOrAssetOrField === "object" && "url" in fileOrAssetOrField) {
if (
"dimensions" in fileOrAssetOrField ||
"link_type" in fileOrAssetOrField
) {
const url = fileOrAssetOrField.url.split("?")[0]
const filename =
"name" in fileOrAsset
? fileOrAsset.name
"name" in fileOrAssetOrField
? fileOrAssetOrField.name
: url.split("/").pop()!.split("_").pop()!
const credits =
"copyright" in fileOrAsset && fileOrAsset.copyright
? fileOrAsset.copyright
"copyright" in fileOrAssetOrField && fileOrAssetOrField.copyright
? fileOrAssetOrField.copyright
: undefined
const alt =
"alt" in fileOrAsset && fileOrAsset.alt ? fileOrAsset.alt : undefined
"alt" in fileOrAssetOrField && fileOrAssetOrField.alt
? fileOrAssetOrField.alt
: undefined

if ("dimensions" in fileOrAsset) {
maybeInitialField = fileOrAsset
if ("dimensions" in fileOrAssetOrField) {
maybeInitialField = fileOrAssetOrField
}

asset = {
id: fileOrAsset.id,
id: fileOrAssetOrField.id,
file: url,
filename,
notes: undefined,
Expand All @@ -124,19 +197,19 @@ export class Migration<
}
} else {
asset = {
id: fileOrAsset.id,
file: fileOrAsset.url,
filename: fileOrAsset.filename,
notes: fileOrAsset.notes,
credits: fileOrAsset.credits,
alt: fileOrAsset.alt,
tags: fileOrAsset.tags?.map(({ name }) => name),
id: fileOrAssetOrField.id,
file: fileOrAssetOrField.url,
filename: fileOrAssetOrField.filename,
notes: fileOrAssetOrField.notes,
credits: fileOrAssetOrField.credits,
alt: fileOrAssetOrField.alt,
tags: fileOrAssetOrField.tags?.map(({ name }) => name),
}
}
} else {
asset = {
id: fileOrAsset,
file: fileOrAsset,
id: fileOrAssetOrField,
file: fileOrAssetOrField,
filename: filename!,
notes,
credits,
Expand Down Expand Up @@ -167,6 +240,23 @@ export class Migration<
return new MigrationImage(this._assets.get(asset.id)!, maybeInitialField)
}

/**
* Registers a document to be created in the migration.
*
* @remarks
* This method does not create the document in Prismic right away. Instead it
* registers it in your migration. The document will be created when the
* migration is executed through the `writeClient.migrate()` method.
*
* @typeParam TType - Type of Prismic documents to create.
*
* @param document - The document to create.
* @param documentTitle - The title of the document to create which will be
* displayed in the editor.
* @param params - Document master language document ID.
*
* @returns A migration document instance.
*/
createDocument<TType extends TMigrationDocuments["type"]>(
document: ExtractDocumentType<TMigrationDocuments, TType>,
documentTitle: string,
Expand Down Expand Up @@ -198,13 +288,76 @@ export class Migration<
return migrationDocument
}

/**
* Registers an existing document to be updated in the migration.
*
* @remarks
* This method does not update the document in Prismic right away. Instead it
* registers it in your migration. The document will be updated when the
* migration is executed through the `writeClient.migrate()` method.
*
* @typeParam TType - Type of Prismic documents to update.
*
* @param document - The document to update.
* @param documentTitle - The title of the document to update which will be
* displayed in the editor.
*
* @returns A migration document instance.
*/
updateDocument<TType extends TMigrationDocuments["type"]>(
document: Omit<ExtractDocumentType<TMigrationDocuments, TType>, "id"> & {
id: string
},
documentTitle: string,
): MigrationDocument<ExtractDocumentType<TDocuments, TType>> {
const migrationDocument = this.createDocument(
document as ExtractDocumentType<TMigrationDocuments, TType>,
documentTitle,
)

migrationDocument._mode = "update"

return migrationDocument
}

/**
* Creates a content relationship fields that can be used in documents to link
* to other documents.
*
* @param config - A Prismic document, a migration document instance, an
* existing content relationship field's content, or a function that returns
* one of the previous.
* @param text - Link text associated with the content relationship field.
*
* @returns A migration content relationship field instance.
*/
createContentRelationship(
config: UnresolvedMigrationContentRelationshipConfig,
text?: string,
): MigrationContentRelationship {
return new MigrationContentRelationship(config, undefined, text)
return new MigrationContentRelationship(config, text, undefined)
}

/**
* Queries a document from the migration instance with a specific UID and
* custom type.
*
* @example
*
* ```ts
* const contentRelationship = migration.createContentRelationship(() =>
* migration.getByUID("blog_post", "my-first-post"),
* )
* ```
*
* @typeParam TType - Type of the Prismic document returned.
*
* @param documentType - The API ID of the document's custom type.
* @param uid - The UID of the document.
*
* @returns The migration document instance with a UID matching the `uid`
* parameter, if a matching document is found.
*/
getByUID<TType extends TMigrationDocuments["type"]>(
documentType: TType,
uid: string,
Expand All @@ -214,6 +367,25 @@ export class Migration<
| undefined
}

/**
* Queries a singleton document from the migration instance for a specific
* custom type.
*
* @example
*
* ```ts
* const contentRelationship = migration.createContentRelationship(() =>
* migration.getSingle("settings"),
* )
* ```
*
* @typeParam TType - Type of the Prismic document returned.
*
* @param documentType - The API ID of the singleton custom type.
*
* @returns The migration document instance for the custom type, if a matching
* document is found.
*/
getSingle<TType extends TMigrationDocuments["type"]>(
documentType: TType,
): MigrationDocument<ExtractDocumentType<TDocuments, TType>> | undefined {
Expand Down
Loading

0 comments on commit 9a07277

Please sign in to comment.