@prismicio/plugin-kit 0.0.1

package/src/fs/lib/fsLimit.ts

@@ -0,0 +1,72 @@
+import * as fs from "node:fs/promises";
+
+import pLimit from "p-limit";
+
+/**
+ * The parsed number value of the SM_FS_LIMIT environment variable.
+ */
+const SM_FS_LIMIT = Number.isNaN(Number(process.env.SM_FS_LIMIT))
+	? undefined
+	: Number(process.env.SM_FS_LIMIT);
+
+/**
+ * The maximum number of concurrent file descriptors allowed to adapters to
+ * minimize issues like `EMFILE: too many open files`.
+ *
+ * - MacOS default limit: 2560 (recent), 256 (old)
+ * - Windows limit (per process): 2048
+ */
+const CONCURRENT_FILE_DESCRIPTORS_LIMIT = SM_FS_LIMIT ?? 1024;
+
+/**
+ * Limit concurrent file descriptors for adapters.
+ */
+const fsLimit = pLimit(CONCURRENT_FILE_DESCRIPTORS_LIMIT);
+
+/**
+ * Wrap a function with `fsLimit()` to limit concurrent calls. All functions
+ * called with `wrapWithFSLimit()` share the same queue.
+ *
+ * @param fn - The function to wrap.
+ *
+ * @returns The wrapped function.
+ */
+const wrapWithFSLimit = <
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	TFn extends (...args: any[]) => any,
+>(
+	fn: TFn,
+): TFn => {
+	return ((...args) => fsLimit(() => fn(...args))) as TFn;
+};
+
+export const access = wrapWithFSLimit(fs.access);
+export const appendFile = wrapWithFSLimit(fs.appendFile);
+export const chmod = wrapWithFSLimit(fs.chmod);
+export const chown = wrapWithFSLimit(fs.chown);
+export const copyFile = wrapWithFSLimit(fs.copyFile);
+export const cp = wrapWithFSLimit(fs.cp);
+export const lchmod = wrapWithFSLimit(fs.lchmod);
+export const lchown = wrapWithFSLimit(fs.lchown);
+export const link = wrapWithFSLimit(fs.link);
+export const lstat = wrapWithFSLimit(fs.lstat);
+export const lutimes = wrapWithFSLimit(fs.lutimes);
+export const mkdir = wrapWithFSLimit(fs.mkdir);
+export const mkdtemp = wrapWithFSLimit(fs.mkdtemp);
+export const open = wrapWithFSLimit(fs.open);
+export const opendir = wrapWithFSLimit(fs.opendir);
+export const readFile = wrapWithFSLimit(fs.readFile);
+export const readdir = wrapWithFSLimit(fs.readdir);
+export const readlink = wrapWithFSLimit(fs.readlink);
+export const realpath = wrapWithFSLimit(fs.realpath);
+export const rename = wrapWithFSLimit(fs.rename);
+export const rm = wrapWithFSLimit(fs.rm);
+export const rmdir = wrapWithFSLimit(fs.rmdir);
+export const stat = wrapWithFSLimit(fs.stat);
+export const statfs = wrapWithFSLimit(fs.statfs);
+export const symlink = wrapWithFSLimit(fs.symlink);
+export const truncate = wrapWithFSLimit(fs.truncate);
+export const unlink = wrapWithFSLimit(fs.unlink);
+export const utimes = wrapWithFSLimit(fs.utimes);
+export const watch = wrapWithFSLimit(fs.watch);
+export const writeFile = wrapWithFSLimit(fs.writeFile);

package/src/fs/lib/isCustomTypeModel.ts

@@ -0,0 +1,7 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+export function isCustomTypeModel(
+	input: unknown,
+): input is TypesInternal.CustomType {
+	return typeof input === "object" && input !== null && "json" in input;
+}

package/src/fs/lib/isSharedSliceModel.ts

@@ -0,0 +1,14 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+export function isSharedSliceModel(
+	input: unknown,
+): input is TypesInternal.SharedSlice {
+	return (
+		typeof input === "object" &&
+		input !== null &&
+		"type" in input &&
+		input.type === "SharedSlice" &&
+		"id" in input &&
+		typeof input.id === "string"
+	);
+}

package/src/fs/lib/pascalCase.ts

@@ -0,0 +1,17 @@
+import {
+	pascalCase as basePascalCase,
+	pascalCaseTransformMerge,
+} from "pascal-case";
+
+/**
+ * Converts a string to a Pascal cased string.
+ *
+ * @param input - String to convert into a Pascal cased string.
+ *
+ * @returns Pascal cased string version of `input`.
+ */
+export const pascalCase = (...input: (string | undefined)[]): string => {
+	return basePascalCase(input.filter(Boolean).join(" "), {
+		transform: pascalCaseTransformMerge,
+	});
+};

package/src/fs/lib/readJSONFile.ts

@@ -0,0 +1,7 @@
+import * as fs from "./fsLimit";
+
+export async function readJSONFile<T = unknown>(path: string): Promise<T> {
+	const contents = await fs.readFile(path, "utf8");
+
+	return JSON.parse(contents);
+}

package/src/fs/lib/resolveSliceModel.ts

@@ -0,0 +1,28 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import { PluginSystemActions } from "../../createPluginSystemActions";
+
+export type ResolveSliceModelArgs =
+	| {
+			sliceID: string;
+			libraryID: string;
+			actions: PluginSystemActions;
+	  }
+	| {
+			model: TypesInternal.SharedSlice;
+	  };
+
+export async function resolveSliceModel(
+	args: ResolveSliceModelArgs,
+): Promise<TypesInternal.SharedSlice> {
+	if ("model" in args) {
+		return args.model;
+	}
+
+	const { model } = await args.actions.readSliceModel({
+		libraryID: args.libraryID,
+		sliceID: args.sliceID,
+	});
+
+	return model;
+}

package/src/fs/readCustomTypeFile.ts

@@ -0,0 +1,27 @@
+import {
+	buildCustomTypeFilePath,
+	BuildCustomTypeFilePathArgs,
+} from "./buildCustomTypeFilePath";
+import { readProjectFile, ReadProjectFileArgs } from "./readProjectFile";
+import { BufferEncoding } from "./types";
+
+export type ReadCustomTypeFileArgs = BuildCustomTypeFilePathArgs &
+	ReadProjectFileArgs;
+
+export async function readCustomTypeFile(
+	args: ReadCustomTypeFileArgs,
+): Promise<Buffer>;
+export async function readCustomTypeFile(
+	args: ReadCustomTypeFileArgs & { encoding: BufferEncoding },
+): Promise<string>;
+export async function readCustomTypeFile(
+	args: ReadCustomTypeFileArgs & { encoding?: BufferEncoding },
+): Promise<Buffer | string> {
+	const filePath = buildCustomTypeFilePath(args);
+
+	return await readProjectFile({
+		filename: filePath,
+		encoding: args.encoding as BufferEncoding,
+		helpers: args.helpers,
+	});
+}

package/src/fs/readCustomTypeLibrary.ts

@@ -0,0 +1,86 @@
+import * as path from "node:path";
+
+import {
+	buildCustomTypeLibraryDirectoryPath,
+	BuildCustomTypeLibraryDirectoryPathArgs,
+} from "./buildCustomTypeLibraryDirectoryPath";
+import { CUSTOM_TYPE_MODEL_FILENAME } from "./constants";
+import { checkPathExists } from "./lib/checkPathExists";
+import * as fs from "./lib/fsLimit";
+import { isCustomTypeModel } from "./lib/isCustomTypeModel";
+import { readJSONFile } from "./lib/readJSONFile";
+
+export type ReadCustomTypeLibraryArgs = BuildCustomTypeLibraryDirectoryPathArgs;
+
+export type ReadCustomTypeLibraryReturnType = {
+	ids: string[];
+};
+
+export const readCustomTypeLibrary = async (
+	args: ReadCustomTypeLibraryArgs,
+): Promise<ReadCustomTypeLibraryReturnType> => {
+	const libraryDir = buildCustomTypeLibraryDirectoryPath({
+		absolute: true,
+		helpers: args.helpers,
+	});
+
+	if (!(await checkPathExists(libraryDir))) {
+		return {
+			ids: [],
+		};
+	}
+
+	const childDirs = await fs.readdir(libraryDir, { withFileTypes: true });
+
+	/**
+	 * Paths to models that could not be read due to invalid JSON.
+	 */
+	const unreadableModelPaths: string[] = [];
+
+	const ids: string[] = [];
+	await Promise.all(
+		childDirs.map(async (childDir) => {
+			if (childDir.isDirectory()) {
+				const childDirContents = await fs.readdir(
+					path.join(libraryDir, childDir.name),
+					{
+						withFileTypes: true,
+					},
+				);
+				const isCustomTypeDir = childDirContents.some((entry) => {
+					return entry.isFile() && entry.name === CUSTOM_TYPE_MODEL_FILENAME;
+				});
+
+				if (isCustomTypeDir) {
+					const modelPath = path.join(
+						libraryDir,
+						childDir.name,
+						CUSTOM_TYPE_MODEL_FILENAME,
+					);
+
+					try {
+						const modelContents = await readJSONFile(modelPath);
+
+						if (isCustomTypeModel(modelContents)) {
+							ids.push(modelContents.id);
+						}
+					} catch {
+						unreadableModelPaths.push(modelPath);
+					}
+				}
+			}
+		}),
+	);
+
+	if (unreadableModelPaths.length > 0) {
+		const formattedPaths = unreadableModelPaths.join(", ");
+
+		throw new Error(
+			`The following custom type models could not be read: [${formattedPaths}]`,
+		);
+	}
+
+	return {
+		ids: ids.sort(),
+	};
+};

package/src/fs/readCustomTypeModel.ts

@@ -0,0 +1,27 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import { CUSTOM_TYPE_MODEL_FILENAME } from "./constants";
+import {
+	readCustomTypeFile,
+	ReadCustomTypeFileArgs,
+} from "./readCustomTypeFile";
+
+export type ReadCustomTypeModelArgs = Omit<ReadCustomTypeFileArgs, "filename">;
+
+export type ReadCustomTypeModelReturnType = {
+	model: TypesInternal.CustomType;
+};
+
+export const readCustomTypeModel = async (
+	args: ReadCustomTypeModelArgs,
+): Promise<ReadCustomTypeModelReturnType> => {
+	const model = await readCustomTypeFile({
+		...args,
+		filename: CUSTOM_TYPE_MODEL_FILENAME,
+		encoding: "utf8",
+	});
+
+	return {
+		model: JSON.parse(model),
+	};
+};

package/src/fs/readProjectFile.ts

@@ -0,0 +1,24 @@
+import { PluginSystemHelpers } from "../createPluginSystemHelpers";
+
+import * as fs from "./lib/fsLimit";
+
+type BufferEncoding = Extract<Parameters<typeof fs.readFile>[1], string>;
+
+export type ReadProjectFileArgs = {
+	filename: string;
+	helpers: PluginSystemHelpers;
+};
+
+export async function readProjectFile(
+	args: ReadProjectFileArgs,
+): Promise<Buffer>;
+export async function readProjectFile(
+	args: ReadProjectFileArgs & { encoding: BufferEncoding },
+): Promise<string>;
+export async function readProjectFile(
+	args: ReadProjectFileArgs & { encoding?: BufferEncoding },
+): Promise<Buffer | string> {
+	const filePath = args.helpers.joinPathFromRoot(args.filename);
+
+	return await fs.readFile(filePath, args.encoding);
+}

package/src/fs/readSliceFile.ts

@@ -0,0 +1,27 @@
+import {
+	buildSliceFilePath,
+	BuildSliceFilePathArgs,
+} from "./buildSliceFilePath";
+import { readProjectFile, ReadProjectFileArgs } from "./readProjectFile";
+import { BufferEncoding } from "./types";
+
+export type ReadSliceFileArgs = BuildSliceFilePathArgs & ReadProjectFileArgs;
+
+export async function readSliceFile(args: ReadSliceFileArgs): Promise<Buffer>;
+export async function readSliceFile(
+	args: ReadSliceFileArgs & { encoding: BufferEncoding },
+): Promise<string>;
+export async function readSliceFile(
+	args: ReadSliceFileArgs & { encoding?: BufferEncoding },
+): Promise<Buffer | string> {
+	const filePath = await buildSliceFilePath({
+		...args,
+		absolute: false,
+	});
+
+	return await readProjectFile({
+		filename: filePath,
+		encoding: args.encoding as BufferEncoding,
+		helpers: args.helpers,
+	});
+}

package/src/fs/readSliceLibrary.ts

@@ -0,0 +1,91 @@
+import * as path from "node:path";
+
+import {
+	buildSliceLibraryDirectoryPath,
+	BuildSliceLibraryDirectoryPathArgs,
+} from "./buildSliceLibraryDirectoryPath";
+import { SHARED_SLICE_MODEL_FILENAME } from "./constants";
+import { checkPathExists } from "./lib/checkPathExists";
+import * as fs from "./lib/fsLimit";
+import { isSharedSliceModel } from "./lib/isSharedSliceModel";
+import { readJSONFile } from "./lib/readJSONFile";
+
+export type ReadSliceLibraryArgs = BuildSliceLibraryDirectoryPathArgs;
+
+export type ReadSliceLibraryReturnType = {
+	id: string;
+	sliceIDs: string[];
+};
+
+export const readSliceLibrary = async (
+	args: ReadSliceLibraryArgs,
+): Promise<ReadSliceLibraryReturnType> => {
+	const libraryDir = buildSliceLibraryDirectoryPath({
+		libraryID: args.libraryID,
+		absolute: true,
+		helpers: args.helpers,
+	});
+
+	if (!(await checkPathExists(libraryDir))) {
+		return {
+			id: args.libraryID,
+			sliceIDs: [],
+		};
+	}
+
+	const childDirs = await fs.readdir(libraryDir, { withFileTypes: true });
+
+	/**
+	 * Paths to models that could not be read due to invalid JSON.
+	 */
+	const unreadableModelPaths: string[] = [];
+
+	const sliceIDs: string[] = [];
+	await Promise.all(
+		childDirs.map(async (childDir) => {
+			if (childDir.isDirectory()) {
+				const childDirContents = await fs.readdir(
+					path.join(libraryDir, childDir.name),
+					{
+						withFileTypes: true,
+					},
+				);
+				const isSliceDir = childDirContents.some((entry) => {
+					return entry.isFile() && entry.name === SHARED_SLICE_MODEL_FILENAME;
+				});
+
+				if (isSliceDir) {
+					const modelPath = path.join(
+						libraryDir,
+						childDir.name,
+						SHARED_SLICE_MODEL_FILENAME,
+					);
+
+					try {
+						const modelContents = await readJSONFile(modelPath);
+
+						if (isSharedSliceModel(modelContents)) {
+							sliceIDs.push(modelContents.id);
+						}
+					} catch {
+						// JSON could not be read or parsed
+						unreadableModelPaths.push(modelPath);
+					}
+				}
+			}
+		}),
+	);
+
+	if (unreadableModelPaths.length > 0) {
+		const formattedPaths = unreadableModelPaths.join(", ");
+
+		throw new Error(
+			`The following Slice models could not be read: [${formattedPaths}]`,
+		);
+	}
+
+	return {
+		id: args.libraryID,
+		sliceIDs: sliceIDs.sort(),
+	};
+};

package/src/fs/readSliceModel.ts

@@ -0,0 +1,90 @@
+import * as path from "node:path";
+
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import { PluginSystemHelpers } from "../createPluginSystemHelpers";
+
+import { buildSliceLibraryDirectoryPath } from "./buildSliceLibraryDirectoryPath";
+import { SHARED_SLICE_MODEL_FILENAME } from "./constants";
+import { checkPathExists } from "./lib/checkPathExists";
+import * as fs from "./lib/fsLimit";
+import { isSharedSliceModel } from "./lib/isSharedSliceModel";
+import { readJSONFile } from "./lib/readJSONFile";
+
+export type ReadSliceModelArgs = {
+	libraryID: string;
+	sliceID: string;
+	helpers: PluginSystemHelpers;
+};
+
+export type ReadSliceModelReturnType = {
+	model: TypesInternal.SharedSlice;
+};
+
+export const readSliceModel = async (
+	args: ReadSliceModelArgs,
+): Promise<ReadSliceModelReturnType> => {
+	const libraryDir = buildSliceLibraryDirectoryPath({
+		libraryID: args.libraryID,
+		absolute: true,
+		helpers: args.helpers,
+	});
+
+	if (await checkPathExists(libraryDir)) {
+		const childDirs = await fs.readdir(libraryDir, { withFileTypes: true });
+
+		/**
+		 * Paths to models that could not be read due to invalid JSON.
+		 */
+		const unreadableModelPaths: string[] = [];
+
+		// Find the first matching model.
+		const models: (TypesInternal.SharedSlice | undefined)[] = await Promise.all(
+			childDirs.map(async (childDir) => {
+				if (childDir.isDirectory()) {
+					const modelPath = path.join(
+						libraryDir,
+						childDir.name,
+						SHARED_SLICE_MODEL_FILENAME,
+					);
+
+					try {
+						const modelContents = await readJSONFile(modelPath);
+
+						if (
+							isSharedSliceModel(modelContents) &&
+							modelContents.id === args.sliceID
+						) {
+							return modelContents;
+						}
+					} catch {
+						unreadableModelPaths.push(modelPath);
+					}
+				}
+			}),
+		);
+		const [model] = models.filter((model): model is TypesInternal.SharedSlice =>
+			isSharedSliceModel(model),
+		);
+
+		if (model) {
+			return {
+				model,
+			};
+		} else {
+			if (unreadableModelPaths.length > 0) {
+				throw new Error(
+					`Did not find a Slice model with ID "${args.sliceID}" in the "${
+						args.libraryID
+					}" Slice Library. The following Slice models could not be read: [${unreadableModelPaths.join(
+						", ",
+					)}]`,
+				);
+			}
+		}
+	}
+
+	throw new Error(
+		`Did not find a Slice model with ID "${args.sliceID}" in the "${args.libraryID}" Slice Library.`,
+	);
+};

package/src/fs/renameCustomType.ts

@@ -0,0 +1,12 @@
+import {
+	writeCustomTypeModel,
+	WriteCustomTypeModelArgs,
+} from "./writeCustomTypeModel";
+
+export type RenameCustomTypeArgs = WriteCustomTypeModelArgs;
+
+export const renameCustomType = async (
+	args: RenameCustomTypeArgs,
+): Promise<void> => {
+	await writeCustomTypeModel(args);
+};

package/src/fs/renameSlice.ts

@@ -0,0 +1,35 @@
+import * as fse from "fs-extra";
+
+import { PluginSystemActions } from "../createPluginSystemActions";
+
+import {
+	buildSliceDirectoryPath,
+	BuildSliceDirectoryPathArgs,
+} from "./buildSliceDirectoryPath";
+import { writeSliceModel, WriteSliceModelArgs } from "./writeSliceModel";
+
+export type RenameSliceArgs = {
+	actions: PluginSystemActions;
+} & Omit<BuildSliceDirectoryPathArgs, "sliceID"> &
+	WriteSliceModelArgs;
+
+export const renameSlice = async (args: RenameSliceArgs): Promise<void> => {
+	const { model: existingModel } = await args.actions.readSliceModel({
+		libraryID: args.libraryID,
+		sliceID: args.model.id,
+	});
+
+	await fse.move(
+		await buildSliceDirectoryPath({
+			...args,
+			model: existingModel,
+			absolute: true,
+		}),
+		await buildSliceDirectoryPath({
+			...args,
+			absolute: true,
+		}),
+	);
+
+	await writeSliceModel(args);
+};

package/src/fs/types.ts

@@ -0,0 +1,5 @@
+import type * as fs from "node:fs/promises";
+
+export type PluginOptions = never;
+
+export type BufferEncoding = Extract<Parameters<typeof fs.readFile>[1], string>;

package/src/fs/upsertGlobalTypeScriptTypes.ts

@@ -0,0 +1,64 @@
+import { detectTypesProvider, generateTypes } from "prismic-ts-codegen";
+
+import { PluginSystemActions } from "../createPluginSystemActions";
+
+import {
+	GLOBAL_TYPESCRIPT_TYPES_FILENAME,
+	NON_EDITABLE_FILE_BANNER,
+} from "./constants";
+import { writeProjectFile, WriteProjectFileArgs } from "./writeProjectFile";
+
+/**
+ * Arguments for `upsertGlobalContentTypes()`.
+ */
+export type UpsertGlobalTypeScriptTypesArgs = {
+	filename?: string;
+	actions: PluginSystemActions;
+} & Omit<WriteProjectFileArgs, "filename" | "contents">;
+
+/**
+ * Creates a globally accessible TypeScript file containing types representing
+ * the Prismic repository's content.
+ *
+ * @returns The file path to the written file.
+ */
+export const upsertGlobalTypeScriptTypes = async (
+	args: UpsertGlobalTypeScriptTypesArgs,
+): Promise<string> => {
+	const project = await args.helpers.getProject();
+
+	const [customTypeModelDescriptors, sharedSliceModelDescriptors] =
+		await Promise.all([
+			args.actions.readAllCustomTypeModels(),
+			args.actions.readAllSliceModels(),
+		]);
+
+	const customTypeModels = customTypeModelDescriptors.map(
+		(customTypeModelDescriptors) => {
+			return customTypeModelDescriptors.model;
+		},
+	);
+	const sharedSliceModels = sharedSliceModelDescriptors.map(
+		(sharedSliceModelDescriptors) => {
+			return sharedSliceModelDescriptors.model;
+		},
+	);
+
+	let contents = generateTypes({
+		customTypeModels,
+		sharedSliceModels,
+		clientIntegration: {
+			includeCreateClientInterface: true,
+			includeContentNamespace: true,
+		},
+		typesProvider: await detectTypesProvider({ cwd: project.root }),
+	});
+
+	contents = `${NON_EDITABLE_FILE_BANNER}\n\n${contents}`;
+
+	return await writeProjectFile({
+		...args,
+		filename: args.filename || GLOBAL_TYPESCRIPT_TYPES_FILENAME,
+		contents,
+	});
+};

package/src/fs/writeCustomTypeFile.ts

@@ -0,0 +1,30 @@
+import {
+	buildCustomTypeFilePath,
+	BuildCustomTypeFilePathArgs,
+} from "./buildCustomTypeFilePath";
+import { writeProjectFile, WriteProjectFileArgs } from "./writeProjectFile";
+
+export type WriteCustomTypeFileArgs = Omit<WriteProjectFileArgs, "filePath"> &
+	BuildCustomTypeFilePathArgs;
+
+/**
+ * Writes a custom type model to the file system.
+ *
+ * @returns The file path to the written file.
+ */
+export const writeCustomTypeFile = async (
+	args: WriteCustomTypeFileArgs,
+): Promise<string> => {
+	const filePath = buildCustomTypeFilePath(args);
+	const relativeFilePath = buildCustomTypeFilePath({
+		...args,
+		absolute: false,
+	});
+
+	await writeProjectFile({
+		...args,
+		filename: relativeFilePath,
+	});
+
+	return filePath;
+};