prismic-ts-codegen 0.0.2 → 0.0.5

package/src/cli/types.ts

@@ -1,29 +1,159 @@
+/**
+ * Configuration to control the generated types.
+ */
 export type Config = {
+	/**
+	 * The name of the Prismic repository.
+	 */
 	repositoryName?: string;
+
+	/**
+	 * The access token for the Prismic repository. If the repository is private
+	 * and `locales.fetchFromRepository` is `true`, providing a token is required.
+	 */
 	accessToken?: string;
+
+	/**
+	 * The Custom Types API token for the Prismic repository. If
+	 * `models.fetchFromRepository` is `true`, providing a token is required.
+	 */
 	customTypesAPIToken?: string;
 
+	/**
+	 * The file path where the generated types will be saved. This path is
+	 * relative to where the command is called.
+	 */
 	output?: string;
 
+	/**
+	 * Configuration for automatic `@prismicio/client` integration.
+	 */
+	clientIntegration?: {
+		/**
+		 * Determines if a `@prismicio/client` integration with automatic typing
+		 * should be included in the output.
+		 *
+		 * If set to `true`, Prismic clients will automatically be typed with the
+		 * generated Custom Types and Slices.
+		 *
+		 * **Note**: If your project queries content from multiple Prismic
+		 * repositories, set `includeCreateClientInterface` to `false` and manually
+		 * provide the generated `AllDocumentTypes` type to `@prismicio/client`'s
+		 * `createClient()` function instead.
+		 *
+		 * @defaultValue `true`
+		 */
+		includeCreateClientInterface?: boolean;
+	};
+
+	/**
+	 * Configuration for languages for the Prismic repository.
+	 *
+	 * It can be configured by providing an array of locale IDs configured for the
+	 * repository or an object with finer control.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * ["en-us", "fr-fr"];
+	 * ```
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * {
+	 * 	"ids": ["en-us", "fr-fr"],
+	 * 	"fetchFromRepository": true
+	 * }
+	 * ```
+	 */
 	locales?:
 		| string[]
 		| {
+				/**
+				 * A list of locales configured for the Prismic repository. This is used
+				 * to type a document's `lang` property.
+				 *
+				 * @example
+				 *
+				 * ```ts
+				 * ["en-us", "fr-fr"];
+				 * ```
+				 */
 				ids?: string[];
+
+				/**
+				 * Determines if the Prismic repository's locales should be fetched from
+				 * the repository's API.
+				 */
 				fetchFromRepository?: boolean;
 		  };
 
+	/**
+	 * Configuration for Custom Type and Slice models for the Prismic repository.
+	 *
+	 * It can be configured by providing an array of file paths to Custom Type and
+	 * Slice JSON models or an object with finer control.
+	 */
 	models?:
 		| string[]
 		| {
+				/**
+				 * A list of file paths to Custom Type and Slice models. Globs are supported.
+				 */
 				files?: string[];
+
+				/**
+				 * Determines if the Prismic repository's Custom Type and Slice models
+				 * should be fetched from the repository's API.
+				 *
+				 * `customTypesAPIToken` must be provided if set to `true`.
+				 */
 				fetchFromRepository?: boolean;
 		  };
 
+	/**
+	 * Configuration for types generated for fields.
+	 */
 	fields?: {
+		/**
+		 * Configuration for Embed fields.
+		 */
 		embed?: {
+			/**
+			 * An object mapping oEmbed providers to their type. The type should be
+			 * provided as a string and is added directly into the generated types.
+			 *
+			 * @example
+			 *
+			 * ```ts
+			 * {
+			 * 	"YouTube": "import('./types').OEmbedYouTube"
+			 * 	"Twitter": "import('./types').OEmbedTwitter"
+			 * 	"Vimeo": "import('./types').OEmbedVimeo"
+			 * }
+			 * ```
+			 */
 			providerTypes?: Record<string, string>;
 		};
+
+		/**
+		 * Configuration for Integration Fields.
+		 */
 		integrationFields?: {
+			/**
+			 * An object mapping catalog IDs to their type. The type should be
+			 * provided as a string and is added directly into the generated types.
+			 *
+			 * @example
+			 *
+			 * ```ts
+			 * {
+			 * 	"shopify_products": "import('./types').IntegrationFieldShopifyProduct"
+			 * 	"mux_videos": "import('./types').IntegrationFieldMuxVideo"
+			 * }
+			 * ```
+			 */
 			catalogTypes?: Record<string, string>;
 		};
 	};

package/src/generateTypes.ts

@@ -1,4 +1,4 @@
-import { Project } from "ts-morph";
+import { Project, ModuleDeclarationKind } from "ts-morph";
 import type { CustomTypeModel, SharedSliceModel } from "@prismicio/types";
 
 import { BLANK_LINE_IDENTIFIER, NON_EDITABLE_FILE_HEADER } from "./constants";
@@ -6,12 +6,16 @@ import { addTypeAliasForCustomType } from "./lib/addTypeAliasForCustomType";
 import { addTypeAliasForSharedSlice } from "./lib/addTypeAliasForSharedSlice";
 import { getSourceFileText } from "./lib/getSourceFileText";
 import { FieldConfigs } from "./types";
+import { pascalCase } from "./lib/pascalCase";
 
 export type GenerateTypesConfig = {
 	customTypeModels?: CustomTypeModel[];
 	sharedSliceModels?: SharedSliceModel[];
 	localeIDs?: string[];
 	fieldConfigs?: FieldConfigs;
+	clientIntegration?: {
+		includeCreateClientInterface?: boolean;
+	};
 };
 
 export const generateTypes = (config: GenerateTypesConfig = {}) => {
@@ -49,6 +53,18 @@ export const generateTypes = (config: GenerateTypesConfig = {}) => {
 				fieldConfigs: config.fieldConfigs || {},
 			});
 		}
+
+		if (config.customTypeModels.length > 0) {
+			sourceFile.addTypeAlias({
+				name: "AllDocumentTypes",
+				type: config.customTypeModels
+					.map((customTypeModel) =>
+						pascalCase(`${customTypeModel.id} Document`),
+					)
+					.join(" | "),
+				isExported: true,
+			});
+		}
 	}
 
 	if (config.sharedSliceModels) {
@@ -61,5 +77,42 @@ export const generateTypes = (config: GenerateTypesConfig = {}) => {
 		}
 	}
 
+	if (config.clientIntegration?.includeCreateClientInterface) {
+		sourceFile.addImportDeclaration({
+			moduleSpecifier: "@prismicio/client",
+			namespaceImport: "prismic",
+			isTypeOnly: true,
+		});
+
+		const clientModuleDeclaration = sourceFile.addModule({
+			name: '"@prismicio/client"',
+			hasDeclareKeyword: true,
+			declarationKind: ModuleDeclarationKind.Module,
+		});
+
+		clientModuleDeclaration.addInterface({
+			name: "CreateClient",
+			callSignatures: [
+				{
+					parameters: [
+						{
+							name: "repositoryNameOrEndpoint",
+							type: "string",
+						},
+						{
+							name: "options",
+							type: "prismic.ClientConfig",
+							hasQuestionToken: true,
+						},
+					],
+					returnType:
+						(config.customTypeModels?.length || 0) > 0
+							? "prismic.Client<AllDocumentTypes>"
+							: "prismic.Client",
+				},
+			],
+		});
+	}
+
 	return getSourceFileText(sourceFile);
 };

package/src/lib/addInterfacePropertiesForFields.ts

@@ -23,12 +23,13 @@ type AddInterfacePropertyFromFieldConfig = {
 	sourceFile: SourceFile;
 	path: [
 		PathElement<CustomTypeModel | SharedSliceModel>,
-		...PathElement<CustomTypeModelField | CustomTypeModelSlice>[]
+		...PathElement<CustomTypeModelField | CustomTypeModelSlice>[],
 	];
 	fieldConfigs: FieldConfigs;
+	tabName?: string;
 };
 
-const addInterfacePropertyFromField = (
+const addInterfacePropertyForField = (
 	config: AddInterfacePropertyFromFieldConfig,
 ) => {
 	switch (config.model.type) {
@@ -45,6 +46,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -59,6 +61,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -73,6 +76,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -105,6 +109,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -119,6 +124,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -138,6 +144,7 @@ const addInterfacePropertyFromField = (
 						id: config.id,
 						model: config.model,
 						path: config.path,
+						tabName: config.tabName,
 					}),
 				});
 			} else {
@@ -148,6 +155,7 @@ const addInterfacePropertyFromField = (
 						id: config.id,
 						model: config.model,
 						path: config.path,
+						tabName: config.tabName,
 					}),
 				});
 			}
@@ -170,6 +178,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -192,6 +201,7 @@ const addInterfacePropertyFromField = (
 							id: config.id,
 							model: config.model,
 							path: config.path,
+							tabName: config.tabName,
 						}),
 					});
 
@@ -206,6 +216,7 @@ const addInterfacePropertyFromField = (
 							id: config.id,
 							model: config.model,
 							path: config.path,
+							tabName: config.tabName,
 						}),
 					});
 
@@ -220,6 +231,7 @@ const addInterfacePropertyFromField = (
 							id: config.id,
 							model: config.model,
 							path: config.path,
+							tabName: config.tabName,
 						}),
 					});
 				}
@@ -236,6 +248,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -257,6 +270,7 @@ const addInterfacePropertyFromField = (
 						id: config.id,
 						model: config.model,
 						path: config.path,
+						tabName: config.tabName,
 					}),
 				});
 			} else {
@@ -267,6 +281,7 @@ const addInterfacePropertyFromField = (
 						id: config.id,
 						model: config.model,
 						path: config.path,
+						tabName: config.tabName,
 					}),
 				});
 			}
@@ -288,6 +303,7 @@ const addInterfacePropertyFromField = (
 						id: config.id,
 						model: config.model,
 						path: config.path,
+						tabName: config.tabName,
 					}),
 				});
 			} else {
@@ -298,6 +314,7 @@ const addInterfacePropertyFromField = (
 						id: config.id,
 						model: config.model,
 						path: config.path,
+						tabName: config.tabName,
 					}),
 				});
 			}
@@ -313,6 +330,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -327,6 +345,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -355,6 +374,7 @@ const addInterfacePropertyFromField = (
 						},
 					},
 				],
+				isExported: true,
 			});
 			addInterfacePropertiesForFields({
 				interface: itemInterface,
@@ -377,6 +397,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -480,6 +501,7 @@ const addInterfacePropertyFromField = (
 									},
 								},
 							],
+							isExported: true,
 						});
 						addInterfacePropertiesForFields({
 							interface: itemInterface,
@@ -515,6 +537,7 @@ const addInterfacePropertyFromField = (
 						}, ${
 							itemInterface ? `Simplify<${itemInterface.getName()}>` : "never"
 						}>`,
+						isExported: true,
 					});
 
 					choiceInterfaceNames.push(sliceType.getName());
@@ -555,6 +578,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 
@@ -569,6 +593,7 @@ const addInterfacePropertyFromField = (
 					id: config.id,
 					model: config.model,
 					path: config.path,
+					tabName: config.tabName,
 				}),
 			});
 		}
@@ -580,16 +605,18 @@ type AddInterfacePropertiesForFieldsConfig = Omit<
 	"id" | "model"
 > & {
 	fields: Record<string, AddInterfacePropertyFromFieldConfig["model"]>;
+	tabName?: string;
 };
 
 export const addInterfacePropertiesForFields = (
 	config: AddInterfacePropertiesForFieldsConfig,
 ) => {
 	for (const name in config.fields) {
-		addInterfacePropertyFromField({
+		addInterfacePropertyForField({
 			...config,
-			id: name,
+			id: name.includes("-") ? `"${name}"` : name,
 			model: config.fields[name],
+			tabName: config.tabName,
 		});
 	}
 };

package/src/lib/addTypeAliasForCustomType.ts

@@ -43,18 +43,26 @@ export const addTypeAliasForCustomType = ({
 				},
 			],
 		});
-		addInterfacePropertiesForFields({
-			fields,
-			interface: dataInterface,
-			sourceFile: sourceFile,
-			path: [
-				{
-					id: model.id,
-					model: model,
-				},
-			],
-			fieldConfigs,
-		});
+
+		for (const tabName in model.json) {
+			// This is destructured to ensure the UID field is
+			// ignored.
+			const { uid: _uidField, ...tabFields } = model.json[tabName];
+
+			addInterfacePropertiesForFields({
+				fields: tabFields,
+				interface: dataInterface,
+				sourceFile: sourceFile,
+				path: [
+					{
+						id: model.id,
+						model: model,
+					},
+				],
+				fieldConfigs,
+				tabName,
+			});
+		}
 	} else {
 		dataInterface = sourceFile.addTypeAlias({
 			name: pascalCase(`${model.id} Document Data`),

package/src/lib/addTypeAliasForSharedSlice.ts

@@ -99,6 +99,7 @@ export const addTypeAliasForSharedSlice = (
 						},
 					},
 				],
+				isExported: true,
 			});
 			addInterfacePropertiesForFields({
 				interface: itemInterface,
@@ -144,6 +145,7 @@ export const addTypeAliasForSharedSlice = (
 					},
 				},
 			],
+			isExported: true,
 		});
 
 		variationTypeNames.push(variationType.getName());

package/src/lib/buildFieldDocs.ts

@@ -19,8 +19,9 @@ type BuildFieldDocsConfig = {
 	model: CustomTypeModelField;
 	path: [
 		PathElement<CustomTypeModel | SharedSliceModel>,
-		...PathElement<CustomTypeModelField | CustomTypeModelSlice>[]
+		...PathElement<CustomTypeModelField | CustomTypeModelSlice>[],
 	];
+	tabName?: string;
 };
 
 export const buildFieldDocs = (
@@ -63,6 +64,7 @@ export const buildFieldDocs = (
 					placeholder,
 					defaultValue,
 					apiIDPath,
+					tabName: config.tabName,
 					documentationURL: getFieldDocumentationURL({ model: config.model }),
 				});
 			},

package/src/lib/getAPIIDPath.ts

@@ -14,7 +14,7 @@ import { isSharedSliceModel } from "./isSharedSliceModel";
 type GetAPIIDPathConfig = {
 	path: [
 		PathElement<CustomTypeModel | SharedSliceModel>,
-		...PathElement<CustomTypeModelField | CustomTypeModelSlice>[]
+		...PathElement<CustomTypeModelField | CustomTypeModelSlice>[],
 	];
 };
 

package/src/lib/getHumanReadableFieldPath.ts

@@ -11,7 +11,7 @@ import { getHumanReadableModelName } from "./getHumanReadableModelName";
 type GetHumanReadableFieldPathConfig = {
 	path: [
 		PathElement<CustomTypeModel | SharedSliceModel>,
-		...PathElement<CustomTypeModelField | CustomTypeModelSlice>[]
+		...PathElement<CustomTypeModelField | CustomTypeModelSlice>[],
 	];
 };
 

package/src/lib/writeFieldDocsDescription.ts

@@ -7,6 +7,7 @@ type BuildFieldDocsConfig = {
 	defaultValue?: string | boolean;
 	placeholder?: string;
 	apiIDPath?: string;
+	tabName?: string;
 	documentationURL?: string;
 };
 
@@ -40,6 +41,10 @@ export const writeFieldDocsDescription = (
 		config.writer.writeLine(`- **API ID Path**: ${config.apiIDPath}`);
 	}
 
+	if (config.tabName) {
+		config.writer.writeLine(`- **Tab**: ${config.tabName}`);
+	}
+
 	if (config.documentationURL) {
 		config.writer.writeLine(`- **Documentation**: ${config.documentationURL}`);
 	}