@ecopages/core 0.2.0-alpha.24 → 0.2.0-alpha.26

package/src/config/config-builder.d.ts

@@ -0,0 +1,252 @@
+/**
+ * This module contains the ConfigBuilder class, which is used to build the EcoPagesAppConfig object.
+ * @module
+ */
+import { type BuildOwnership } from '../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoPagesAppConfig, RobotsPreference } from '../types/internal-types.js';
+import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { Processor } from '../plugins/processor.js';
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
+import type { PageMetadataProps } from '../types/public-types.js';
+import type { CacheConfig } from '../services/cache/cache.types.js';
+export declare const CONFIG_BUILDER_ERRORS: {
+    readonly DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique";
+    readonly DUPLICATE_INTEGRATION_EXTENSIONS: "Integrations extensions must be unique";
+    readonly MIXED_JSX_ENGINES: "Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).";
+    readonly duplicateProcessorName: (name: string) => string;
+    readonly duplicateLoaderName: (name: string) => string;
+    readonly duplicateSemanticTemplate: (kind: "html" | "404", matches: string[]) => string;
+    readonly incompatibleRuntimeCapability: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, reason: string) => string;
+    readonly unsupportedRuntimeVersion: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, current: string, min: string) => string;
+    readonly invalidRuntimeVersion: (kind: "integration" | "processor", name: string, version: string) => string;
+};
+type RuntimeKind = 'node' | 'bun';
+/**
+ * A builder class for creating and configuring EcoPages application configuration.
+ * Provides a fluent interface for setting various configuration options and managing
+ * application settings.
+ *
+ * @remarks
+ * The ConfigBuilder follows the builder pattern and allows for:
+ * - Setting directory paths for various components (pages, includes, layouts, etc.)
+ * - Configuring templates and includes
+ * - Managing integrations and plugins
+ * - Setting up processors and loaders
+ * - Configuring API handlers
+ * - Managing metadata and robots.txt preferences
+ *
+ * All setter methods return the instance of the builder for method chaining.
+ * The configuration is finalized by calling the `build()` method, which performs
+ * validation and initialization of the configuration.
+ *
+ * @throws {Error} When building configuration without required fields (e.g., baseUrl)
+ * @throws {Error} When adding duplicate processors or loaders
+ */
+export declare class ConfigBuilder {
+    private buildOwnership;
+    config: EcoPagesAppConfig;
+    /**
+     * Sets the base URL for the application.
+     * This URL is used as the root URL for all pages and assets.
+     *
+     * @param baseUrl - The base URL for the application (e.g., 'https://example.com')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setBaseUrl(baseUrl: string): this;
+    /**
+     * Sets the root directory of the project.
+     * This is the base directory from which all other paths are resolved.
+     *
+     * @param rootDir - The root directory path
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setRootDir(rootDir: string): this;
+    /**
+     * Sets which runtime path owns build execution for the finalized app config.
+     *
+     * @remarks
+     * Bun-native remains the default. Vite-host ownership should be selected only
+     * for host-driven compatibility flows where core must not silently fall back to
+     * Bun build execution.
+     */
+    setBuildOwnership(buildOwnership: BuildOwnership): this;
+    /**
+     * Sets the source directory relative to the root directory.
+     * This directory contains all the source files for the application.
+     *
+     * @param srcDir - The source directory name (default: 'src')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setSrcDir(srcDir: string): this;
+    /**
+     * Sets the pages directory relative to the source directory.
+     * This directory contains all the page files for the application.
+     *
+     * @param pagesDir - The pages directory name (default: 'pages')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setPagesDir(pagesDir: string): this;
+    /**
+     * Sets the includes directory relative to the source directory.
+     * This directory contains template includes and partials.
+     *
+     * @param includesDir - The includes directory name (default: 'includes')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setIncludesDir(includesDir: string): this;
+    /**
+     * Sets the components directory relative to the source directory.
+     * This directory contains reusable components.
+     *
+     * @param componentsDir - The components directory name (default: 'components')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setComponentsDir(componentsDir: string): this;
+    /**
+     * Sets the layouts directory relative to the source directory.
+     * This directory contains layout templates.
+     *
+     * @param layoutsDir - The layouts directory name (default: 'layouts')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setLayoutsDir(layoutsDir: string): this;
+    /**
+     * Sets the public directory relative to the source directory.
+     * This directory contains static assets that should be served as-is.
+     *
+     * @param publicDir - The public directory name (default: 'public')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setPublicDir(publicDir: string): this;
+    /**
+     * Sets the robots.txt configuration.
+     * This determines which paths are allowed/disallowed for search engines.
+     *
+     * @param robotsTxt - The robots.txt configuration object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setRobotsTxt(robotsTxt: {
+        preferences: RobotsPreference;
+    }): this;
+    /**
+     * Sets the integration plugins to use.
+     * These plugins provide additional functionality to the application.
+     *
+     * @param integrations - An array of integration plugins
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setIntegrations(integrations: IntegrationPlugin<unknown>[]): this;
+    /**
+     * Sets the output directory for the built application.
+     *
+     * @param distDir - The distribution directory name (default: 'dist')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setDistDir(distDir: string): this;
+    /**
+     * Sets the internal work directory for runtime-only artifacts.
+     *
+     * @remarks
+     * Use this when deployable output should stay clean while Ecopages still
+     * needs a separate workspace for server transpilation caches, runtime
+     * manifests, and other internal build products.
+     *
+     * @param workDir - The internal work directory name
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setWorkDir(workDir: string): this;
+    /**
+     * Sets the default metadata for pages.
+     * This is used when a page doesn't specify its own metadata.
+     *
+     * @param defaultMetadata - The default metadata object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setDefaultMetadata(defaultMetadata: PageMetadataProps): this;
+    /**
+     * Sets additional paths to watch for changes during development.
+     *
+     * @param additionalWatchPaths - An array of additional paths to watch
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setAdditionalWatchPaths(additionalWatchPaths: string[]): this;
+    /**
+     * Sets the processors to use for the application.
+     * This replaces any existing processors.
+     *
+     * @param processors - An array of processors
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setProcessors(processors: Processor<any>[]): this;
+    /**
+     * Adds a processor to the application.
+     *
+     * @param processor - The processor to add
+     * @returns The ConfigBuilder instance for method chaining
+     * @throws Error if a processor with the same name already exists
+     */
+    addProcessor(processor: Processor): this;
+    /**
+     * Sets the loaders to use for the application.
+     * This replaces any existing loaders.
+     *
+     * @param loaders - An array of build plugins to use as loaders
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setLoaders(loaders: EcoBuildPlugin[]): this;
+    /**
+     * Sets the source transforms to use for transform-first bundlers such as Vite.
+     * This replaces any existing source transforms.
+     */
+    setSourceTransforms(sourceTransforms: EcoSourceTransform[]): this;
+    /**
+     * Adds a loader to the application.
+     *
+     * @param name - The name of the loader
+     * @param loader - The build plugin to use as a loader
+     * @returns The ConfigBuilder instance for method chaining
+     * @throws Error if a loader with the same name already exists
+     */
+    addLoader(name: string, loader: EcoBuildPlugin): this;
+    /**
+     * Adds a source transform to the application.
+     *
+     * @throws Error if a source transform with the same name already exists.
+     */
+    addSourceTransform(name: string, sourceTransform: EcoSourceTransform): this;
+    /**
+     * Sets the cache configuration for ISR and page caching.
+     *
+     * @param cacheConfig - The cache configuration object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setCacheConfig(cacheConfig: CacheConfig): this;
+    setExperimental(experimental: NonNullable<EcoPagesAppConfig['experimental']>): this;
+    private createAbsolutePaths;
+    private resolveSemanticTemplatePath;
+    private createIntegrationTemplatesExt;
+    private initializeProcessors;
+    private validateRuntimeCapabilities;
+    private validateRuntimeCapability;
+    private detectRuntimeEnvironment;
+    private getBunVersion;
+    private describeUnsupportedRuntimeTag;
+    private parseVersion;
+    private compareVersions;
+    /**
+     * Initializes default loaders that are required for EcoPages to function.
+     * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+     */
+    private initializeDefaultLoaders;
+    private reviewBaseUrl;
+    /**
+     * Builds and returns the final configuration object.
+     * This performs validation and initialization of the configuration.
+     *
+     * @returns A promise that resolves to the final EcoPagesAppConfig
+     * @throws Error if required configuration is missing (e.g., baseUrl)
+     */
+    build(): Promise<EcoPagesAppConfig>;
+}
+export {};