@nikovirtala/projen-constructs 0.1.5 → 0.1.6

package/lib/projen-project-generator.d.ts

@@ -0,0 +1,173 @@
+import type { Property } from "@jsii/spec";
+import type { Project, SourceCodeOptions } from "projen";
+import { Component } from "projen";
+type ProjenModule = "typescript" | "cdk" | "awscdk";
+type ProjenBaseClass<M extends ProjenModule> = `${M}.${string}`;
+/**
+ * Configuration for a component to be integrated into a generated project
+ *
+ * @example
+ * ```typescript
+ * const config: ComponentConfig = {
+ *   component: Vitest,
+ *   optionsProperty: "vitestOptions"
+ * };
+ * ```
+ */
+interface ComponentConfig<T extends Component = Component> {
+    /**
+     * Component class constructor
+     */
+    readonly component: new (project: never, options?: never) => T;
+    /**
+     * Options property configuration for the generated options interface
+     *
+     * When specified, adds an options property to the interface allowing
+     * users to configure the component.
+     */
+    readonly optionsProperty?: {
+        /**
+         * Name of the options property (e.g., "vitestOptions")
+         */
+        readonly name: string;
+        /**
+         * Fully qualified type name (e.g., "@nikovirtala/projen-constructs.VitestOptions")
+         */
+        readonly type: string;
+        /**
+         * Documentation summary
+         */
+        readonly docs?: string;
+    };
+}
+/**
+ * Options for ProjenProjectGenerator component
+ *
+ * Configures the generation of a TypeScript project class that extends a Projen base class
+ * with standard configuration and component integration.
+ *
+ * @example
+ * ```typescript
+ * new ProjenProjectGenerator(project, {
+ *   name: "TypeScriptProject",
+ *   baseClass: "typescript.TypeScriptProject",
+ *   filePath: "src/projects/typescript.generated.ts",
+ *   components: [{ component: Vitest, optionsProperty: "vitestOptions" }]
+ * });
+ * ```
+ */
+export interface ProjenProjectGeneratorOptions<M extends ProjenModule = ProjenModule> extends SourceCodeOptions {
+    /**
+     * Name of the generated class (e.g., "TypeScriptProject")
+     *
+     * The options interface will be named `${name}Options`.
+     */
+    readonly name: string;
+    /**
+     * Fully qualified base class to extend in format "module.ClassName"
+     *
+     * Must be a valid Projen class reference like "typescript.TypeScriptProject",
+     * "cdk.JsiiProject", or "awscdk.AwsCdkTypeScriptApp".
+     *
+     * @example "typescript.TypeScriptProject"
+     * @example "cdk.JsiiProject"
+     */
+    readonly baseClass: ProjenBaseClass<M>;
+    /**
+     * Output file path for the generated class
+     *
+     * Must contain a directory separator. The options interface will be generated
+     * in the same directory with a ".generated.ts" suffix.
+     *
+     * @example "src/projects/typescript.generated.ts"
+     */
+    readonly filePath: string;
+    /**
+     * Components to integrate into the project
+     *
+     * Each component will be instantiated during project construction and can be
+     * configured via an optional options property in the generated interface.
+     *
+     * @default [{ component: Mise }, { component: Vitest, optionsProperty: { name: "vitestOptions", type: "...", docs: "..." } }]
+     */
+    readonly components?: ComponentConfig[];
+    /**
+     * Additional properties to add to the generated options interface
+     *
+     * Use this to extend the base options with custom properties specific to
+     * your project type.
+     */
+    readonly additionalOptions?: Property[];
+    /**
+     * Property names to omit from the base options interface
+     *
+     * Use this to hide base class options that should not be configurable
+     * in the generated project type.
+     */
+    readonly omitOptions?: string[];
+}
+/**
+ * Projen component that generates TypeScript project classes with standard configuration
+ *
+ * This component automates the creation of project classes that extend Projen base classes
+ * with opinionated defaults and component integration. It generates both:
+ * 1. An options interface (via ProjenStruct) that extends the base Projen options
+ * 2. A project class that applies default configuration and instantiates components
+ *
+ * The generated code follows a consistent pattern:
+ * - Imports required modules and components
+ * - Re-exports the generated options interface
+ * - Defines a class extending the Projen base class
+ * - Constructor merges defaults with user options and applies components
+ *
+ * @example
+ * ```typescript
+ * new ProjenProjectGenerator(project, {
+ *   name: "TypeScriptProject",
+ *   baseClass: "typescript.TypeScriptProject",
+ *   filePath: "src/projects/typescript.generated.ts",
+ *   components: [{ component: Vitest, optionsProperty: "vitestOptions" }]
+ * });
+ * ```
+ */
+export declare class ProjenProjectGenerator extends Component {
+    private readonly options;
+    private renderer;
+    /**
+     * @param project - Projen project instance
+     * @param options - Generator configuration
+     */
+    constructor(project: Project, options: ProjenProjectGeneratorOptions<ProjenModule>);
+    /**
+     * Casts project to TypeScript project type
+     *
+     * ProjenStruct requires a TypeScriptProject instance. This generator is only used
+     * within TypeScript projects, so the cast is safe in practice.
+     *
+     * Note: Type assertion is necessary here because Projen's type system doesn't provide
+     * a runtime type guard for TypeScriptProject.
+     *
+     * @param project - Projen project instance
+     * @returns TypeScript project instance
+     */
+    private asTypeScriptProject;
+    /**
+     * Derives the file path for the generated options interface
+     *
+     * Places the options interface file in the same directory as the class file
+     * with a ".generated.ts" suffix.
+     *
+     * @param optionsInterface - Name of the options interface
+     * @returns File path for the options interface
+     * @throws {InvalidFilePathError} When filePath doesn't contain a directory separator
+     */
+    private getOptionsFilePath;
+    /**
+     * Generates the TypeScript class file during Projen synthesis
+     *
+     * Called by Projen during the synthesis phase to generate the project class file.
+     * The file is marked as readonly to prevent manual editing.
+     */
+    preSynthesize(): void;
+}
+export {};