convex-cms 0.0.1

package/src/client/schema/codegen.ts

@@ -0,0 +1,500 @@
+/**
+ * Type Code Generation
+ *
+ * Generates TypeScript types from content types stored in the database.
+ * This allows type safety for content types created via admin UI.
+ *
+ * @example
+ * ```typescript
+ * // In a build script or CLI tool
+ * import { generateTypesFromDatabase } from "@convex-cms/core";
+ *
+ * const output = await generateTypesFromDatabase(ctx, cms);
+ * await fs.writeFile("./src/generated/cms-types.ts", output);
+ * ```
+ *
+ * @example CLI Usage
+ * ```bash
+ * npx convex-cms codegen --output ./src/generated/cms-types.ts
+ * ```
+ */
+
+import type { ConvexContext } from "../wrapper.js";
+import type { CmsClient } from "../wrapper.js";
+import type { ContentType, FieldDefinition } from "../types.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for code generation.
+ */
+export interface CodegenOptions {
+	/**
+	 * Header comment to include at the top of the generated file.
+	 * @default "Auto-generated by @convex-cms/core codegen"
+	 */
+	header?: string;
+
+	/**
+	 * Whether to include JSDoc comments for fields.
+	 * @default true
+	 */
+	includeJsDoc?: boolean;
+
+	/**
+	 * Content type names to include. If not provided, includes all.
+	 */
+	contentTypes?: string[];
+
+	/**
+	 * Content type names to exclude.
+	 */
+	exclude?: string[];
+
+	/**
+	 * Whether to generate a union type of all content type names.
+	 * @default true
+	 */
+	includeNameUnion?: boolean;
+
+	/**
+	 * Whether to generate a discriminated union type.
+	 * @default false
+	 */
+	includeDiscriminatedUnion?: boolean;
+
+	/**
+	 * Custom type name suffix for generated types.
+	 * @default "Data"
+	 */
+	typeSuffix?: string;
+
+	/**
+	 * Whether to mark all fields as optional (for partial updates).
+	 * @default false
+	 */
+	allOptional?: boolean;
+}
+
+/**
+ * Result of code generation.
+ */
+export interface CodegenResult {
+	/**
+	 * The generated TypeScript code.
+	 */
+	code: string;
+
+	/**
+	 * Content types that were included.
+	 */
+	includedTypes: string[];
+
+	/**
+	 * Content types that were excluded.
+	 */
+	excludedTypes: string[];
+
+	/**
+	 * Timestamp of generation.
+	 */
+	generatedAt: number;
+}
+
+// =============================================================================
+// Code Generation
+// =============================================================================
+
+/**
+ * Generate TypeScript types from content types in the database.
+ *
+ * @param ctx - Convex context
+ * @param cmsClient - CMS client to query content types
+ * @param options - Code generation options
+ * @returns Generated TypeScript code
+ *
+ * @example
+ * ```typescript
+ * const result = await generateTypesFromDatabase(ctx, cms);
+ *
+ * // Write to file
+ * await fs.writeFile("./src/generated/cms-types.ts", result.code);
+ *
+ * // Now you can import the types
+ * import type { BlogPostData, AuthorData } from "./generated/cms-types";
+ * ```
+ */
+export async function generateTypesFromDatabase(
+	ctx: ConvexContext,
+	cmsClient: CmsClient,
+	options: CodegenOptions = {},
+): Promise<CodegenResult> {
+	const {
+		header = "Auto-generated by @convex-cms/core codegen",
+		includeJsDoc = true,
+		contentTypes: includeTypes,
+		exclude = [],
+		includeNameUnion = true,
+		includeDiscriminatedUnion = false,
+		typeSuffix = "Data",
+		allOptional = false,
+	} = options;
+
+	// Fetch all content types
+	const allTypes = await cmsClient.contentTypes.getAll(ctx);
+
+	// Filter content types
+	let filteredTypes: ContentType[] = allTypes;
+	if (includeTypes) {
+		filteredTypes = filteredTypes.filter((t: ContentType) => includeTypes.includes(t.name));
+	}
+	filteredTypes = filteredTypes.filter((t: ContentType) => !exclude.includes(t.name));
+
+	const includedTypes = filteredTypes.map((t: ContentType) => t.name);
+	const excludedTypes = allTypes
+		.filter((t: ContentType) => !includedTypes.includes(t.name))
+		.map((t: ContentType) => t.name);
+
+	// Build output
+	const lines: string[] = [];
+
+	// Header
+	lines.push(`/**`);
+	lines.push(` * ${header}`);
+	lines.push(` *`);
+	lines.push(` * DO NOT EDIT - Regenerate with: npx convex-cms codegen`);
+	lines.push(` *`);
+	lines.push(` * Generated: ${new Date().toISOString()}`);
+	lines.push(` * Content types: ${includedTypes.length}`);
+	lines.push(` */`);
+	lines.push("");
+	lines.push("/* eslint-disable */");
+	lines.push("");
+
+	// Generate types for each content type
+	for (const contentType of filteredTypes) {
+		lines.push(
+			...generateTypeForContentType(contentType, {
+				includeJsDoc,
+				typeSuffix,
+				allOptional,
+			}),
+		);
+		lines.push("");
+	}
+
+	// Generate name union
+	if (includeNameUnion && filteredTypes.length > 0) {
+		lines.push("/**");
+		lines.push(" * All content type names.");
+		lines.push(" */");
+		const typeNames = filteredTypes.map((t) => `"${t.name}"`).join(" | ");
+		lines.push(`export type ContentTypeName = ${typeNames};`);
+		lines.push("");
+	}
+
+	// Generate discriminated union
+	if (includeDiscriminatedUnion && filteredTypes.length > 0) {
+		lines.push("/**");
+		lines.push(" * Discriminated union of all content data types.");
+		lines.push(" */");
+		lines.push("export type ContentData =");
+		for (let i = 0; i < filteredTypes.length; i++) {
+			const t = filteredTypes[i];
+			const typeName = toPascalCase(t.name) + typeSuffix;
+			const suffix = i < filteredTypes.length - 1 ? "" : ";";
+			lines.push(`  | { _type: "${t.name}"; data: ${typeName} }${suffix}`);
+		}
+		lines.push("");
+	}
+
+	// Generate type map
+	if (filteredTypes.length > 0) {
+		lines.push("/**");
+		lines.push(" * Map from content type name to data type.");
+		lines.push(" */");
+		lines.push("export interface ContentTypeMap {");
+		for (const t of filteredTypes) {
+			const typeName = toPascalCase(t.name) + typeSuffix;
+			lines.push(`  "${t.name}": ${typeName};`);
+		}
+		lines.push("}");
+		lines.push("");
+	}
+
+	// Helper type
+	lines.push("/**");
+	lines.push(" * Get the data type for a content type name.");
+	lines.push(" */");
+	lines.push(
+		"export type DataForType<T extends ContentTypeName> = ContentTypeMap[T];",
+	);
+
+	return {
+		code: lines.join("\n"),
+		includedTypes,
+		excludedTypes,
+		generatedAt: Date.now(),
+	};
+}
+
+/**
+ * Generate TypeScript interface for a single content type.
+ */
+function generateTypeForContentType(
+	contentType: ContentType,
+	options: {
+		includeJsDoc: boolean;
+		typeSuffix: string;
+		allOptional: boolean;
+	},
+): string[] {
+	const { includeJsDoc, typeSuffix, allOptional } = options;
+	const lines: string[] = [];
+
+	const typeName = toPascalCase(contentType.name) + typeSuffix;
+
+	// JSDoc
+	if (includeJsDoc) {
+		lines.push("/**");
+		lines.push(
+			` * Data type for "${contentType.displayName}" content entries.`,
+		);
+		if (contentType.description) {
+			lines.push(` *`);
+			lines.push(` * ${contentType.description}`);
+		}
+		lines.push(` *`);
+		lines.push(` * @contentType ${contentType.name}`);
+		lines.push(" */");
+	}
+
+	// Interface
+	lines.push(`export interface ${typeName} {`);
+
+	for (const field of contentType.fields) {
+		// Field JSDoc
+		if (includeJsDoc && field.description) {
+			lines.push(`  /** ${field.description} */`);
+		}
+
+		const tsType = fieldTypeToTsType(field);
+		const optional = allOptional || !field.required ? "?" : "";
+		lines.push(`  ${field.name}${optional}: ${tsType};`);
+	}
+
+	lines.push("}");
+
+	return lines;
+}
+
+/**
+ * Convert a field definition to a TypeScript type.
+ *
+ * Note: We cast field.type to string because the database may contain
+ * field types (like "tags", "category") that aren't in the client FieldType union.
+ */
+function fieldTypeToTsType(field: FieldDefinition): string {
+	// Cast to string to handle potential extra field types from the database
+	const fieldType = field.type as string;
+
+	switch (fieldType) {
+		case "text":
+		case "richText":
+			return "string";
+
+		case "number":
+			return "number";
+
+		case "boolean":
+			return "boolean";
+
+		case "date":
+		case "datetime":
+			return "number"; // Unix timestamp
+
+		case "reference": {
+			// Type narrowing: field.type === "reference" means options has reference shape
+			const refOpts = field.options as { multiple?: boolean } | undefined;
+			if (refOpts?.multiple) {
+				return "string[]";
+			}
+			return "string";
+		}
+
+		case "media": {
+			// Type narrowing: field.type === "media" means options has media shape
+			const mediaOpts = field.options as { multiple?: boolean } | undefined;
+			if (mediaOpts?.multiple) {
+				return "string[]";
+			}
+			return "string";
+		}
+
+		case "select": {
+			const selectOpts = field.options as
+				| { options?: Array<{ value: string; label?: string }> }
+				| undefined;
+			return generateSelectUnion(selectOpts?.options);
+		}
+
+		case "multiSelect": {
+			const multiOpts = field.options as
+				| { options?: Array<{ value: string; label?: string }> }
+				| undefined;
+			const unionType = generateSelectUnion(multiOpts?.options);
+			return `(${unionType})[]`;
+		}
+
+		case "json":
+			return "unknown";
+
+		// Handle taxonomy fields (may not be in FieldType union)
+		case "tags":
+		case "category":
+			return "string[]";
+
+		default:
+			return "unknown";
+	}
+}
+
+/**
+ * Generate a union type from select options.
+ */
+function generateSelectUnion(
+	options?: Array<{ value: string; label?: string }>,
+): string {
+	if (!options || options.length === 0) {
+		return "string";
+	}
+	return options.map((o) => `"${escapeString(o.value)}"`).join(" | ");
+}
+
+/**
+ * Convert a string to PascalCase.
+ */
+function toPascalCase(str: string): string {
+	return str
+		.split(/[-_\s]+/)
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+		.join("");
+}
+
+/**
+ * Escape special characters in a string for use in TypeScript.
+ */
+function escapeString(str: string): string {
+	return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+
+// =============================================================================
+// String-based Generation (No Convex Context)
+// =============================================================================
+
+/**
+ * Generate TypeScript types from an array of content type definitions.
+ *
+ * Useful when you already have the content types loaded (e.g., from a JSON file).
+ *
+ * @param contentTypes - Array of content type definitions
+ * @param options - Code generation options
+ * @returns Generated TypeScript code
+ */
+export function generateTypesFromDefinitions(
+	contentTypes: ContentType[],
+	options: CodegenOptions = {},
+): string {
+	const {
+		header = "Auto-generated by @convex-cms/core codegen",
+		includeJsDoc = true,
+		exclude = [],
+		includeNameUnion = true,
+		typeSuffix = "Data",
+		allOptional = false,
+	} = options;
+
+	// Filter content types
+	const filteredTypes = contentTypes.filter((t) => !exclude.includes(t.name));
+
+	const lines: string[] = [];
+
+	// Header
+	lines.push(`/**`);
+	lines.push(` * ${header}`);
+	lines.push(` *`);
+	lines.push(` * DO NOT EDIT`);
+	lines.push(` */`);
+	lines.push("");
+	lines.push("/* eslint-disable */");
+	lines.push("");
+
+	// Generate types
+	for (const contentType of filteredTypes) {
+		lines.push(
+			...generateTypeForContentType(contentType, {
+				includeJsDoc,
+				typeSuffix,
+				allOptional,
+			}),
+		);
+		lines.push("");
+	}
+
+	// Name union
+	if (includeNameUnion && filteredTypes.length > 0) {
+		const typeNames = filteredTypes.map((t) => `"${t.name}"`).join(" | ");
+		lines.push(`export type ContentTypeName = ${typeNames};`);
+		lines.push("");
+	}
+
+	// Type map
+	if (filteredTypes.length > 0) {
+		lines.push("export interface ContentTypeMap {");
+		for (const t of filteredTypes) {
+			const typeName = toPascalCase(t.name) + typeSuffix;
+			lines.push(`  "${t.name}": ${typeName};`);
+		}
+		lines.push("}");
+	}
+
+	return lines.join("\n");
+}
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+/**
+ * Validate that generated types match the expected structure.
+ *
+ * @param code - Generated TypeScript code
+ * @returns Validation result
+ */
+export function validateGeneratedCode(
+	code: string,
+): {
+	valid: boolean;
+	errors: string[];
+} {
+	const errors: string[] = [];
+
+	// Check for basic structure
+	if (!code.includes("export interface") && !code.includes("export type")) {
+		errors.push("No exported types found in generated code");
+	}
+
+	// Check for syntax issues
+	const openBraces = (code.match(/{/g) || []).length;
+	const closeBraces = (code.match(/}/g) || []).length;
+	if (openBraces !== closeBraces) {
+		errors.push(`Mismatched braces: ${openBraces} open, ${closeBraces} close`);
+	}
+
+	return {
+		valid: errors.length === 0,
+		errors,
+	};
+}