@valkyrjaio/sindri 26.4.1 → 26.5.0

package/src/Sindri/Generate/Abstract/GenerateDataFromAst.ts

@@ -32,6 +32,7 @@ import { AstEventDataFileGenerator } from '../../Generator/Ast/Event/AstEventDat
 import { AstHttpDataFileGenerator } from '../../Generator/Ast/Http/AstHttpDataFileGenerator.ts';
 import { GenerateStatus } from '../../Generator/Enum/GenerateStatus.ts';
 import { SindriInfo } from '../../Constant/SindriInfo.ts';
+import { GenerateFromAst } from './GenerateFromAst.ts';
 
 import type { CliDataFileGeneratorContract } from '../../Generator/Cli/Contract/CliDataFileGeneratorContract.ts';
 import type { ContainerDataFileGeneratorContract } from '../../Generator/Container/Contract/ContainerDataFileGeneratorContract.ts';
@@ -53,7 +54,7 @@ import type { ts } from 'ts-morph';
 import type { HttpRouteData } from '../../Ast/Data/HttpRouteData.ts';
 import type { RouteContract } from '@valkyrjaio/valkyrja/Cli/Routing/Data/Contract/RouteContract.ts';
 
-export abstract class GenerateDataFromAst {
+export abstract class GenerateDataFromAst extends GenerateFromAst {
     public constructor(
         protected readonly outputFactory: OutputFactoryContract,
         protected readonly route: RouteContract,
@@ -70,7 +71,9 @@ export abstract class GenerateDataFromAst {
         protected readonly eventGenerator: EventDataFileGeneratorContract = new AstEventDataFileGenerator(),
         protected readonly cliGenerator: CliDataFileGeneratorContract = new AstCliDataFileGenerator(),
         protected readonly httpGenerator: HttpDataFileGeneratorContract = new AstHttpDataFileGenerator(),
-    ) {}
+    ) {
+        super();
+    }
 
     protected generateData(): OutputContract {
         let output = this.getOutput();
@@ -211,157 +214,6 @@ export abstract class GenerateDataFromAst {
         return '';
     }
 
-    /**
-     * Build the `import { X } from '...'` specifier for a class file, relative
-     * to the generated data file's output directory. Used to import the
-     * provider/handler classes referenced by the generated data caches.
-     */
-    protected relativeSpecifier(fromDir: string, toFile: string): string {
-        const relative = path.relative(fromDir, toFile).split(path.sep).join('/');
-
-        return relative.startsWith('.') ? relative : `./${relative}`;
-    }
-
-    /**
-     * Build the specifier a generated data file should import a class file by.
-     *
-     * Application source is imported by a path relative to the data directory;
-     * a file belonging to an installed package is imported by that package's
-     * own public specifier — so the framework classes the cache references are
-     * written exactly as hand-written application code writes them
-     * (`@valkyrjaio/valkyrja/Cli/Routing/Data/Route.ts`), never as a brittle
-     * reach into `node_modules`.
-     */
-    protected importSpecifier(fromDir: string, toFile: string): string {
-        return this.packageSpecifier(toFile) ?? this.relativeSpecifier(fromDir, toFile);
-    }
-
-    /**
-     * Map an absolute path inside an installed package back to the specifier
-     * that package publicly exposes it as, or undefined when the file is not
-     * part of one.
-     *
-     * The package's `exports` map is inverted: for `"./*.ts": "./src/*.ts"` a
-     * file at `<package>/src/Foo.ts` maps back to `<name>/Foo.ts`. Packages
-     * with no matching pattern fall back to the path as written under the
-     * package root, which is what a package without an `exports` map exposes.
-     */
-    protected packageSpecifier(filePath: string): string | undefined {
-        const normalized = filePath.split(path.sep).join('/');
-        const marker = normalized.lastIndexOf('/node_modules/');
-
-        if (marker === -1) {
-            return undefined;
-        }
-
-        const subject = normalized.substring(marker + '/node_modules/'.length);
-        const segments = subject.split('/');
-        const nameLength = subject.startsWith('@') ? 2 : 1;
-
-        if (segments.length <= nameLength) {
-            return undefined;
-        }
-
-        const packageName = segments.slice(0, nameLength).join('/');
-        const packageDir = normalized.substring(0, marker + '/node_modules/'.length) + packageName;
-        const relative = segments.slice(nameLength).join('/');
-
-        return `${packageName}/${this.exportedSubpath(packageDir, relative) ?? relative}`;
-    }
-
-    /**
-     * Invert a package's `exports` patterns to find the subpath a file inside
-     * it is exposed as, or undefined when no pattern matches it.
-     */
-    protected exportedSubpath(packageDir: string, relative: string): string | undefined {
-        for (const [key, target] of Object.entries(this.readPackageExports(packageDir))) {
-            const star = key.indexOf('*');
-            const targetStar = target.indexOf('*');
-
-            if (star === -1 || targetStar === -1) {
-                continue;
-            }
-
-            const prefix = target.substring(0, targetStar).replace(/^\.\//, '');
-            const suffix = target.substring(targetStar + 1);
-
-            if (!relative.startsWith(prefix) || !relative.endsWith(suffix)) {
-                continue;
-            }
-
-            const value = relative.substring(prefix.length, relative.length - suffix.length);
-
-            return (key.substring(0, star) + value + key.substring(star + 1)).replace(/^\.\//, '');
-        }
-
-        return undefined;
-    }
-
-    /**
-     * Read a package's `exports` map, flattened to subpath → file target.
-     *
-     * Conditional targets are collapsed to their first string value; every
-     * condition a package declares for a subpath points at the same source
-     * file in the layouts sindri generates for.
-     */
-    protected readPackageExports(packageDir: string): Record<string, string> {
-        const manifestPath = path.join(packageDir, 'package.json');
-
-        if (!fs.existsSync(manifestPath)) {
-            return {};
-        }
-
-        let manifest: { exports?: unknown };
-
-        try {
-            manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as { exports?: unknown };
-        } catch {
-            return {};
-        }
-
-        const exports = manifest.exports;
-
-        if (typeof exports !== 'object' || exports === null) {
-            return {};
-        }
-
-        const flattened: Record<string, string> = {};
-
-        for (const [subpath, target] of Object.entries(exports as Record<string, unknown>)) {
-            const resolved = this.firstStringTarget(target);
-
-            if (resolved !== undefined) {
-                flattened[subpath] = resolved;
-            }
-        }
-
-        return flattened;
-    }
-
-    /**
-     * Reduce an `exports` target — a string, or a nested map of conditions — to
-     * the first file path it names.
-     */
-    protected firstStringTarget(target: unknown): string | undefined {
-        if (typeof target === 'string') {
-            return target;
-        }
-
-        if (typeof target !== 'object' || target === null) {
-            return undefined;
-        }
-
-        for (const value of Object.values(target as Record<string, unknown>)) {
-            const resolved = this.firstStringTarget(value);
-
-            if (resolved !== undefined) {
-                return resolved;
-            }
-        }
-
-        return undefined;
-    }
-
     protected generateContainerData(
         serviceProviders: readonly string[],
         config: ConfigResult,

package/src/Sindri/Generate/Abstract/GenerateFromAst.ts

@@ -0,0 +1,173 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Turns an absolute file path into the specifier a generated file must import
+ * it by.
+ *
+ * Every Sindri command that writes TypeScript needs this, because a generated
+ * file sits in a different directory from the files it references. Application
+ * source gets a path relative to the output directory. A file inside an
+ * installed package gets that package's own public specifier.
+ */
+export abstract class GenerateFromAst {
+    /**
+     * Build the `import { X } from '...'` specifier for a class file, relative
+     * to the generated data file's output directory. Used to import the
+     * provider/handler classes referenced by the generated data caches.
+     */
+    protected relativeSpecifier(fromDir: string, toFile: string): string {
+        const relative = path.relative(fromDir, toFile).split(path.sep).join('/');
+
+        return relative.startsWith('.') ? relative : `./${relative}`;
+    }
+
+    /**
+     * Build the specifier a generated data file should import a class file by.
+     *
+     * Application source is imported by a path relative to the data directory;
+     * a file belonging to an installed package is imported by that package's
+     * own public specifier — so the framework classes the cache references are
+     * written exactly as hand-written application code writes them
+     * (`@valkyrjaio/valkyrja/Cli/Routing/Data/Route.ts`), never as a brittle
+     * reach into `node_modules`.
+     */
+    protected importSpecifier(fromDir: string, toFile: string): string {
+        return this.packageSpecifier(toFile) ?? this.relativeSpecifier(fromDir, toFile);
+    }
+
+    /**
+     * Map an absolute path inside an installed package back to the specifier
+     * that package publicly exposes it as, or undefined when the file is not
+     * part of one.
+     *
+     * The package's `exports` map is inverted: for `"./*.ts": "./src/*.ts"` a
+     * file at `<package>/src/Foo.ts` maps back to `<name>/Foo.ts`. Packages
+     * with no matching pattern fall back to the path as written under the
+     * package root, which is what a package without an `exports` map exposes.
+     */
+    protected packageSpecifier(filePath: string): string | undefined {
+        const normalized = filePath.split(path.sep).join('/');
+        const marker = normalized.lastIndexOf('/node_modules/');
+
+        if (marker === -1) {
+            return undefined;
+        }
+
+        const subject = normalized.substring(marker + '/node_modules/'.length);
+        const segments = subject.split('/');
+        const nameLength = subject.startsWith('@') ? 2 : 1;
+
+        if (segments.length <= nameLength) {
+            return undefined;
+        }
+
+        const packageName = segments.slice(0, nameLength).join('/');
+        const packageDir = normalized.substring(0, marker + '/node_modules/'.length) + packageName;
+        const relative = segments.slice(nameLength).join('/');
+
+        return `${packageName}/${this.exportedSubpath(packageDir, relative) ?? relative}`;
+    }
+
+    /**
+     * Invert a package's `exports` patterns to find the subpath a file inside
+     * it is exposed as, or undefined when no pattern matches it.
+     */
+    protected exportedSubpath(packageDir: string, relative: string): string | undefined {
+        for (const [key, target] of Object.entries(this.readPackageExports(packageDir))) {
+            const star = key.indexOf('*');
+            const targetStar = target.indexOf('*');
+
+            if (star === -1 || targetStar === -1) {
+                continue;
+            }
+
+            const prefix = target.substring(0, targetStar).replace(/^\.\//, '');
+            const suffix = target.substring(targetStar + 1);
+
+            if (!relative.startsWith(prefix) || !relative.endsWith(suffix)) {
+                continue;
+            }
+
+            const value = relative.substring(prefix.length, relative.length - suffix.length);
+
+            return (key.substring(0, star) + value + key.substring(star + 1)).replace(/^\.\//, '');
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Read a package's `exports` map, flattened to subpath → file target.
+     *
+     * Conditional targets are collapsed to their first string value; every
+     * condition a package declares for a subpath points at the same source
+     * file in the layouts sindri generates for.
+     */
+    protected readPackageExports(packageDir: string): Record<string, string> {
+        const manifestPath = path.join(packageDir, 'package.json');
+
+        if (!fs.existsSync(manifestPath)) {
+            return {};
+        }
+
+        let manifest: { exports?: unknown };
+
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as { exports?: unknown };
+        } catch {
+            return {};
+        }
+
+        const exports = manifest.exports;
+
+        if (typeof exports !== 'object' || exports === null) {
+            return {};
+        }
+
+        const flattened: Record<string, string> = {};
+
+        for (const [subpath, target] of Object.entries(exports as Record<string, unknown>)) {
+            const resolved = this.firstStringTarget(target);
+
+            if (resolved !== undefined) {
+                flattened[subpath] = resolved;
+            }
+        }
+
+        return flattened;
+    }
+
+    /**
+     * Reduce an `exports` target — a string, or a nested map of conditions — to
+     * the first file path it names.
+     */
+    protected firstStringTarget(target: unknown): string | undefined {
+        if (typeof target === 'string') {
+            return target;
+        }
+
+        if (typeof target !== 'object' || target === null) {
+            return undefined;
+        }
+
+        for (const value of Object.values(target as Record<string, unknown>)) {
+            const resolved = this.firstStringTarget(value);
+
+            if (resolved !== undefined) {
+                return resolved;
+            }
+        }
+
+        return undefined;
+    }
+}

package/src/Sindri/Generator/Ast/Config/AstCachedConfigFileGenerator.ts

@@ -0,0 +1,198 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { AstFileGenerator } from '../../Abstract/AstFileGenerator.ts';
+
+import type { ConfigSourceResult } from '../../../Ast/Data/Result/ConfigSourceResult.ts';
+import type { GenerateStatus } from '../../Enum/GenerateStatus.ts';
+import type { CachedConfigFileGeneratorContract } from '../../Config/Contract/CachedConfigFileGeneratorContract.ts';
+
+/**
+ * Writes a standalone cached config class.
+ *
+ * The generated class implements the config contract directly rather than
+ * extending a framework config. Extending one would import that base, and a
+ * framework config names a component provider in a default parameter value —
+ * which loads the whole component provider tree at module load, whether or not
+ * the default is ever used. That tree is exactly what a cached application does
+ * not need, so the generated config must not reach it by any path.
+ *
+ * Field initializers are copied as source text, so expressions the author wrote
+ * survive unevaluated. Two fields are not copied:
+ *
+ * - `providers` becomes empty. A cached application reads the generated data and
+ *   never walks the provider tree.
+ * - `callbacks` becomes a single callback that publishes the generated container
+ *   data. The application's own callbacks are dropped, because the callback a
+ *   config normally carries is the one that chooses between cached and runtime
+ *   publishing — and it lives on a component provider this file must not import.
+ */
+export class AstCachedConfigFileGenerator extends AstFileGenerator implements CachedConfigFileGeneratorContract {
+    /** The service id constant each contract binds under. */
+    protected static readonly CONTRACT_SERVICE_IDS: Readonly<Record<string, string>> = {
+        ConfigContract: 'ApplicationServiceId.ConfigContract',
+        HttpConfigContract: 'ApplicationServiceId.HttpConfigContract',
+        CliConfigContract: 'ApplicationServiceId.CliConfigContract',
+    };
+
+    protected static readonly APPLICATION_SERVICE_ID =
+        '@valkyrjaio/valkyrja/Application/Constant/ApplicationServiceId.ts';
+
+    protected static readonly CONTAINER_SERVICE_ID = '@valkyrjaio/valkyrja/Container/Constant/ContainerServiceId.ts';
+
+    protected static readonly APPLICATION_CONTRACT =
+        '@valkyrjaio/valkyrja/Application/Kernel/Contract/ApplicationContract.ts';
+
+    protected static readonly COMPONENT_PROVIDER_CONTRACT =
+        '@valkyrjaio/valkyrja/Application/Provider/Contract/ComponentProviderContract.ts';
+
+    /** Fields the generated config replaces rather than copies. */
+    protected static readonly REPLACED_FIELDS: readonly string[] = ['providers', 'callbacks'];
+
+    /** Names the generated header already binds, so a copied import must not repeat them. */
+    protected static readonly RESERVED_IMPORT_NAMES: readonly string[] = [
+        'ApplicationServiceId',
+        'ContainerServiceId',
+        'ApplicationContract',
+        'ComponentProviderContract',
+        'ConfigContract',
+        'HttpConfigContract',
+        'CliConfigContract',
+    ];
+
+    /**
+     * Fields whose copied value would break the generated config.
+     *
+     * Debug mode is pinned off rather than copied. In debug mode the routing
+     * service provider derives the route collection from the provider tree and
+     * writes the result over the routing data. This config has no providers, so
+     * that derivation produces an empty collection, and the empty collection
+     * replaces the generated data. Every route then fails to match. Debug mode
+     * and a cached config are opposite choices, so this file always states the
+     * cached one.
+     */
+    protected static readonly PINNED_FIELDS: Readonly<Record<string, string>> = {
+        debugMode: 'false',
+    };
+
+    generateFile(
+        directory: string,
+        className: string,
+        source: ConfigSourceResult,
+        containerDataClass: string,
+        containerDataSpecifier: string,
+    ): GenerateStatus {
+        const serviceId = AstCachedConfigFileGenerator.CONTRACT_SERVICE_IDS[source.contractName] ?? '';
+        const body = this.buildFields(source, containerDataClass);
+
+        const data = [
+            '// This file was automatically generated by Sindri.',
+            '',
+            `import { ApplicationServiceId } from '${AstCachedConfigFileGenerator.APPLICATION_SERVICE_ID}';`,
+            `import { ContainerServiceId } from '${AstCachedConfigFileGenerator.CONTAINER_SERVICE_ID}';`,
+            `import { ${containerDataClass} } from '${containerDataSpecifier}';`,
+            ...this.buildCopiedImportLines(source),
+            '',
+            `import type { ApplicationContract } from '${AstCachedConfigFileGenerator.APPLICATION_CONTRACT}';`,
+            `import type { ComponentProviderContract } from '${AstCachedConfigFileGenerator.COMPONENT_PROVIDER_CONTRACT}';`,
+            `import type { ${source.contractName} } from '${source.contractSpecifier}';`,
+            ...this.buildCopiedTypeImportLines(source),
+            '',
+            `export class ${className} implements ${source.contractName} {`,
+            `    static readonly id = ${serviceId};`,
+            '',
+            ...body,
+            '}',
+            '',
+        ].join('\n');
+
+        return this.writeFile(directory, className, data);
+    }
+
+    /**
+     * Render every field of the generated class.
+     */
+    protected buildFields(source: ConfigSourceResult, containerDataClass: string): string[] {
+        const lines: string[] = [];
+
+        for (const [name, value] of Object.entries(source.fields)) {
+            if (AstCachedConfigFileGenerator.REPLACED_FIELDS.includes(name)) {
+                continue;
+            }
+
+            const type = source.types[name];
+            const declaration = type !== undefined ? `${name}: ${type}` : name;
+
+            lines.push(`    readonly ${declaration} = ${AstCachedConfigFileGenerator.PINNED_FIELDS[name] ?? value};`);
+        }
+
+        lines.push('    readonly providers: ComponentProviderContract[] = [];');
+        lines.push('    readonly callbacks: ((app: ApplicationContract) => void)[] = [');
+        lines.push('        (app: ApplicationContract): void => {');
+        lines.push(
+            `            app.getContainer().setSingleton(ContainerServiceId.Data, new ${containerDataClass}());`,
+        );
+        lines.push('        },');
+        lines.push('    ];');
+
+        return lines;
+    }
+
+    /**
+     * Re-emit the value imports the copied field text still needs.
+     */
+    protected buildCopiedImportLines(source: ConfigSourceResult): string[] {
+        return this.copiedImports(source, false).map((entry) => `import { ${entry.name} } from '${entry.specifier}';`);
+    }
+
+    /**
+     * Re-emit the type imports the copied field text still needs.
+     */
+    protected buildCopiedTypeImportLines(source: ConfigSourceResult): string[] {
+        return this.copiedImports(source, true).map(
+            (entry) => `import type { ${entry.name} } from '${entry.specifier}';`,
+        );
+    }
+
+    /**
+     * Select the source file's imports that the copied text still references.
+     *
+     * An import used only by `providers` or `callbacks` is dropped with those
+     * fields — that is how the component provider import disappears.
+     */
+    protected copiedImports(source: ConfigSourceResult, isType: boolean): typeof source.imports {
+        const copiedText = Object.entries(source.fields)
+            .filter(([name]) => !AstCachedConfigFileGenerator.REPLACED_FIELDS.includes(name))
+            .filter(([name]) => AstCachedConfigFileGenerator.PINNED_FIELDS[name] === undefined)
+            .flatMap(([name, value]) => [value, source.types[name] ?? ''])
+            .join('\n');
+
+        const seen = new Set<string>();
+
+        return source.imports.filter((entry) => {
+            if (entry.isType !== isType || seen.has(entry.name)) {
+                return false;
+            }
+
+            // The generated header already binds these names. Emitting them a
+            // second time is a duplicate-identifier error.
+            if (AstCachedConfigFileGenerator.RESERVED_IMPORT_NAMES.includes(entry.name)) {
+                return false;
+            }
+
+            if (!new RegExp(`\\b${entry.name}\\b`).test(copiedText)) {
+                return false;
+            }
+
+            seen.add(entry.name);
+
+            return true;
+        });
+    }
+}

package/src/Sindri/Generator/Config/Contract/CachedConfigFileGeneratorContract.ts

@@ -0,0 +1,21 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { ConfigSourceResult } from '../../../Ast/Data/Result/ConfigSourceResult.ts';
+import type { GenerateStatus } from '../../Enum/GenerateStatus.ts';
+
+export interface CachedConfigFileGeneratorContract {
+    generateFile(
+        directory: string,
+        className: string,
+        source: ConfigSourceResult,
+        containerDataClass: string,
+        containerDataSpecifier: string,
+    ): GenerateStatus;
+}