payload-live-preview 1.0.0

package/dist/codegen.d.cts

@@ -0,0 +1,162 @@
+import { Project } from 'ts-morph';
+
+/**
+ * Internal schema representation used by the codegen pipeline.
+ *
+ * Decoupled from `PayloadFieldSchema` (the runtime shape that arrives
+ * via postMessage) because:
+ *
+ *   1. Static analysis sees richer information — block definitions,
+ *      relationship targets, hasMany — that the runtime shape may not
+ *      always carry.
+ *   2. The emit phase wants ergonomic structures (TypeScript-like
+ *      type references) that the runtime never needs.
+ *
+ * @module @codegen/parser/types
+ */
+interface ExtractedSchema {
+    readonly globals: readonly ExtractedSlug[];
+    readonly collections: readonly ExtractedSlug[];
+    /** Diagnostics produced during extraction. Soft warnings only. */
+    readonly diagnostics: readonly string[];
+}
+interface ExtractedSlug {
+    /** The Payload slug (`'homepage'`, `'posts'`, …). */
+    readonly slug: string;
+    /** PascalCase type name (`'Homepage'`, `'Post'`, …). */
+    readonly typeName: string;
+    /** Fully-resolved field tree. */
+    readonly fields: readonly ExtractedField[];
+}
+type ExtractedField = ExtractedScalarField | ExtractedArrayField | ExtractedBlocksField | ExtractedGroupField | ExtractedRelationshipField | ExtractedUploadField | ExtractedJsonField | ExtractedSelectField;
+interface ExtractedFieldBase {
+    readonly name: string;
+    readonly required: boolean;
+    readonly localized: boolean;
+}
+interface ExtractedScalarField extends ExtractedFieldBase {
+    readonly kind: 'scalar';
+    readonly typeRef: 'string' | 'number' | 'boolean' | 'Date' | 'unknown';
+}
+interface ExtractedArrayField extends ExtractedFieldBase {
+    readonly kind: 'array';
+    readonly fields: readonly ExtractedField[];
+}
+interface ExtractedBlocksField extends ExtractedFieldBase {
+    readonly kind: 'blocks';
+    readonly blocks: readonly ExtractedBlock[];
+}
+interface ExtractedBlock {
+    readonly slug: string;
+    readonly typeName: string;
+    readonly fields: readonly ExtractedField[];
+}
+interface ExtractedGroupField extends ExtractedFieldBase {
+    readonly kind: 'group';
+    readonly fields: readonly ExtractedField[];
+}
+interface ExtractedRelationshipField extends ExtractedFieldBase {
+    readonly kind: 'relationship';
+    readonly target: string | readonly string[];
+    readonly hasMany: boolean;
+}
+interface ExtractedUploadField extends ExtractedFieldBase {
+    readonly kind: 'upload';
+    readonly target: string;
+}
+interface ExtractedJsonField extends ExtractedFieldBase {
+    readonly kind: 'json';
+}
+interface ExtractedSelectField extends ExtractedFieldBase {
+    readonly kind: 'select';
+    readonly options: readonly string[];
+    readonly hasMany: boolean;
+}
+
+/**
+ * Schema-level extraction: open `payload.config.ts`, find every
+ * collection and global definition, walk into them.
+ *
+ * The extractor is deliberately lenient. Payload configurations are
+ * full TypeScript programs — a strict parser would have to model
+ * conditional types, factory functions, plugin closures. Instead we
+ * recognise the *common* shapes (object literal, identifier
+ * referencing an imported literal, default export from a sibling
+ * file) and emit a diagnostic for anything we can't unwrap.
+ *
+ * @module @codegen/parser/extract-schema
+ */
+
+interface ExtractSchemaOptions {
+    /** Absolute or relative path to `payload.config.ts`. */
+    readonly configPath: string;
+    /** When provided, used instead of constructing a fresh ts-morph project. */
+    readonly project?: Project;
+    /**
+     * Optional path to a `tsconfig.json`. When set, ts-morph loads the
+     * project's module-resolution configuration so cross-file imports
+     * (Homepage from './globals') can be followed.
+     */
+    readonly tsConfigFilePath?: string;
+}
+declare function extractSchema(options: ExtractSchemaOptions): ExtractedSchema;
+
+/**
+ * Render `ExtractedSchema` to a TypeScript source string.
+ *
+ * The output is one self-contained `.ts` file that ships:
+ *
+ *   - one `interface` per global and per collection,
+ *   - nested `interface` declarations for `group`/`array`/`blocks`,
+ *   - discriminated unions for `blocks` fields (one variant per slug),
+ *   - `PayloadCollections` / `PayloadGlobals` maps for slug-keyed
+ *     access (`PayloadCollections['posts']`), and
+ *   - a `PayloadSlug` alias.
+ *
+ * Nothing in the runtime depends on this output — consumers import
+ * what they need by name.
+ *
+ * @module @codegen/emit/emit-types
+ */
+
+interface EmitOptions {
+    /** When true, includes a `@deprecated` JSDoc on localized fields. */
+    readonly markLocalizedAsDeprecated?: boolean;
+    /** Header text injected at the top of the output. Defaults sensibly. */
+    readonly header?: string;
+}
+declare function emitTypes(schema: ExtractedSchema, options?: EmitOptions): string;
+
+/**
+ * Programmatic codegen API.
+ *
+ *   ```ts
+ *   import { generateTypes } from 'payload-live-preview/codegen';
+ *   const { code, diagnostics } = await generateTypes({
+ *     configPath: 'backend/src/payload.config.ts',
+ *     outFile: 'frontend/src/payload-types.ts',
+ *   });
+ *   ```
+ *
+ * @module @codegen
+ */
+
+interface GenerateTypesOptions extends Pick<ExtractSchemaOptions, 'configPath' | 'project' | 'tsConfigFilePath'>, EmitOptions {
+    /**
+     * If set, the generated code is written to this absolute or
+     * cwd-relative path. The function still returns the rendered string
+     * in `code` so callers can verify before writing.
+     */
+    readonly outFile?: string;
+    /** Working directory used to resolve relative paths. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+}
+interface GenerateTypesResult {
+    readonly code: string;
+    readonly diagnostics: readonly string[];
+    readonly schema: ExtractedSchema;
+    readonly outFile?: string;
+}
+declare function generateTypes(options: GenerateTypesOptions): Promise<GenerateTypesResult>;
+
+export { type ExtractedField, type ExtractedSchema, type ExtractedSlug, type GenerateTypesOptions, type GenerateTypesResult, emitTypes, extractSchema, generateTypes };

package/dist/codegen.d.ts

@@ -0,0 +1,162 @@
+import { Project } from 'ts-morph';
+
+/**
+ * Internal schema representation used by the codegen pipeline.
+ *
+ * Decoupled from `PayloadFieldSchema` (the runtime shape that arrives
+ * via postMessage) because:
+ *
+ *   1. Static analysis sees richer information — block definitions,
+ *      relationship targets, hasMany — that the runtime shape may not
+ *      always carry.
+ *   2. The emit phase wants ergonomic structures (TypeScript-like
+ *      type references) that the runtime never needs.
+ *
+ * @module @codegen/parser/types
+ */
+interface ExtractedSchema {
+    readonly globals: readonly ExtractedSlug[];
+    readonly collections: readonly ExtractedSlug[];
+    /** Diagnostics produced during extraction. Soft warnings only. */
+    readonly diagnostics: readonly string[];
+}
+interface ExtractedSlug {
+    /** The Payload slug (`'homepage'`, `'posts'`, …). */
+    readonly slug: string;
+    /** PascalCase type name (`'Homepage'`, `'Post'`, …). */
+    readonly typeName: string;
+    /** Fully-resolved field tree. */
+    readonly fields: readonly ExtractedField[];
+}
+type ExtractedField = ExtractedScalarField | ExtractedArrayField | ExtractedBlocksField | ExtractedGroupField | ExtractedRelationshipField | ExtractedUploadField | ExtractedJsonField | ExtractedSelectField;
+interface ExtractedFieldBase {
+    readonly name: string;
+    readonly required: boolean;
+    readonly localized: boolean;
+}
+interface ExtractedScalarField extends ExtractedFieldBase {
+    readonly kind: 'scalar';
+    readonly typeRef: 'string' | 'number' | 'boolean' | 'Date' | 'unknown';
+}
+interface ExtractedArrayField extends ExtractedFieldBase {
+    readonly kind: 'array';
+    readonly fields: readonly ExtractedField[];
+}
+interface ExtractedBlocksField extends ExtractedFieldBase {
+    readonly kind: 'blocks';
+    readonly blocks: readonly ExtractedBlock[];
+}
+interface ExtractedBlock {
+    readonly slug: string;
+    readonly typeName: string;
+    readonly fields: readonly ExtractedField[];
+}
+interface ExtractedGroupField extends ExtractedFieldBase {
+    readonly kind: 'group';
+    readonly fields: readonly ExtractedField[];
+}
+interface ExtractedRelationshipField extends ExtractedFieldBase {
+    readonly kind: 'relationship';
+    readonly target: string | readonly string[];
+    readonly hasMany: boolean;
+}
+interface ExtractedUploadField extends ExtractedFieldBase {
+    readonly kind: 'upload';
+    readonly target: string;
+}
+interface ExtractedJsonField extends ExtractedFieldBase {
+    readonly kind: 'json';
+}
+interface ExtractedSelectField extends ExtractedFieldBase {
+    readonly kind: 'select';
+    readonly options: readonly string[];
+    readonly hasMany: boolean;
+}
+
+/**
+ * Schema-level extraction: open `payload.config.ts`, find every
+ * collection and global definition, walk into them.
+ *
+ * The extractor is deliberately lenient. Payload configurations are
+ * full TypeScript programs — a strict parser would have to model
+ * conditional types, factory functions, plugin closures. Instead we
+ * recognise the *common* shapes (object literal, identifier
+ * referencing an imported literal, default export from a sibling
+ * file) and emit a diagnostic for anything we can't unwrap.
+ *
+ * @module @codegen/parser/extract-schema
+ */
+
+interface ExtractSchemaOptions {
+    /** Absolute or relative path to `payload.config.ts`. */
+    readonly configPath: string;
+    /** When provided, used instead of constructing a fresh ts-morph project. */
+    readonly project?: Project;
+    /**
+     * Optional path to a `tsconfig.json`. When set, ts-morph loads the
+     * project's module-resolution configuration so cross-file imports
+     * (Homepage from './globals') can be followed.
+     */
+    readonly tsConfigFilePath?: string;
+}
+declare function extractSchema(options: ExtractSchemaOptions): ExtractedSchema;
+
+/**
+ * Render `ExtractedSchema` to a TypeScript source string.
+ *
+ * The output is one self-contained `.ts` file that ships:
+ *
+ *   - one `interface` per global and per collection,
+ *   - nested `interface` declarations for `group`/`array`/`blocks`,
+ *   - discriminated unions for `blocks` fields (one variant per slug),
+ *   - `PayloadCollections` / `PayloadGlobals` maps for slug-keyed
+ *     access (`PayloadCollections['posts']`), and
+ *   - a `PayloadSlug` alias.
+ *
+ * Nothing in the runtime depends on this output — consumers import
+ * what they need by name.
+ *
+ * @module @codegen/emit/emit-types
+ */
+
+interface EmitOptions {
+    /** When true, includes a `@deprecated` JSDoc on localized fields. */
+    readonly markLocalizedAsDeprecated?: boolean;
+    /** Header text injected at the top of the output. Defaults sensibly. */
+    readonly header?: string;
+}
+declare function emitTypes(schema: ExtractedSchema, options?: EmitOptions): string;
+
+/**
+ * Programmatic codegen API.
+ *
+ *   ```ts
+ *   import { generateTypes } from 'payload-live-preview/codegen';
+ *   const { code, diagnostics } = await generateTypes({
+ *     configPath: 'backend/src/payload.config.ts',
+ *     outFile: 'frontend/src/payload-types.ts',
+ *   });
+ *   ```
+ *
+ * @module @codegen
+ */
+
+interface GenerateTypesOptions extends Pick<ExtractSchemaOptions, 'configPath' | 'project' | 'tsConfigFilePath'>, EmitOptions {
+    /**
+     * If set, the generated code is written to this absolute or
+     * cwd-relative path. The function still returns the rendered string
+     * in `code` so callers can verify before writing.
+     */
+    readonly outFile?: string;
+    /** Working directory used to resolve relative paths. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+}
+interface GenerateTypesResult {
+    readonly code: string;
+    readonly diagnostics: readonly string[];
+    readonly schema: ExtractedSchema;
+    readonly outFile?: string;
+}
+declare function generateTypes(options: GenerateTypesOptions): Promise<GenerateTypesResult>;
+
+export { type ExtractedField, type ExtractedSchema, type ExtractedSlug, type GenerateTypesOptions, type GenerateTypesResult, emitTypes, extractSchema, generateTypes };