@postxl/generator 0.74.2 → 1.0.1

package/LICENSE

@@ -0,0 +1,50 @@
+PostXL Non-Commercial License
+
+Copyright (c) 2025 PostXL GmbH
+
+NON-COMMERCIAL USE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software for non-commercial purposes only,
+subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. The Software may not be used for commercial purposes without obtaining a
+   commercial license from PostXL GmbH.
+
+DEFINITION OF NON-COMMERCIAL USE
+
+"Non-commercial use" means personal, educational, research, or evaluation use
+where the primary purpose is not to generate revenue or commercial advantage.
+
+Non-commercial use includes:
+
+- Personal projects and learning
+- Academic research and education
+- Open source projects that are not commercially monetized
+- Evaluation and testing of the Software
+
+COMMERCIAL USE
+
+For commercial use of this Software, including but not limited to:
+
+- Use in products or services sold or licensed to third parties
+- Use in internal business operations that generate revenue
+- Use by for-profit organizations in production environments
+
+You must obtain a commercial license from PostXL GmbH.
+
+Contact: licensing@postxl.com
+
+DISCLAIMER
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
 # PXL Generator
 
-> A utility package that lets you move quickly and generate basic components of your app easily.
+The core package that orchestrates the code generation of a PXL project
+
+## Overview & context
+
+Each PXL project is initially generated using two components:
+
+- The `ProjectSchema` defines the overall structure of the project, including the models, enums, generators, etc.
+- The `generate` program that uses the `ProjectSchema` to generate the code for the project.
+
+The `ProjectSchema` is defined and explained in the [Schema package](../schema/README.md).
+
+This package provides the tooling for the `generate` program.
+
+## Composable generators
+
+The `generate` program is composed of multiple generators.
+
+Here is a simplified example program:
+
+```ts
+import { Generator } from '@postxl/generator'
+import { generateTypes } from '@postxl/generators/types'
+import { registerApiContext, generateApi}* from '@postxl/generators/nestjs-backend'
+import { generateRepositories } from '@postxl/generators/prisma-repositories'
+
+import { zProjectSchema } from '@postxl/schema'
+
+import { projectSchemaJSON } from './project-schema.json'
+
+async function generateProject() {
+
+  const projectSchema = zProjectSchema.parse(projectSchemaJSON)
+
+  const generator = new Generator(projectSchema)
+  await generator
+    // some global generators (API, E2E, CmdK, ?) register some "collectors" in the context,
+    // so other generator can store data in these collectors.
+    // Upon generation, these global generators use this data to generator the code.
+    // Example: E2E Selector collector: frontend generators provide selectors that will be
+    //           used by the E2E generators to generate the selectors object
+    .register(registerApiContext)
+
+    // these generators will create the relevant files in the virtual file system and provide more context
+    // to subsequent generators
+    .generate(generateTypes)
+    .generate(generateRepositories)
+
+    // this will generate the API code using the registered collector
+    .generate(generateApi)
+
+    // prettify files, add disclaimer, calculate checksums and write files to disk
+    // that have not been ejected
+    .flush()
+}
+```
+
+## Running the generator and updating the result on disk
+
+Running the generator will create the code of the project, given the `ProjectSchema` and the generator configs.
+
+From there, two things will happen over time:
+
+- The models (or generator configs) will change,
+- The (initially generated) code will be manually changed (formerly known as "ejected")
+
+In case the file was not manually changed but the model was changed, the generator will
+automatically update the file on disk. In case the file was manually changed and the model
+was not changed, nothing will happen. Only in case the file was manually changed and the model
+was changed, we will need to decide how to handle the conflict. For this, the generator will
+update the existing file in a way that is compatible with a git merge conflict. This way, the
+developer must decide how to resolve the conflict.
+
+Under the hood, the above logic is implemented leveraging the "postxl-lock.json" file.
+This file contains the hash values for each generated file. With this hash value, we can determine:
+
+- If the file was manually changed: in this case the hash of the current file will be different from
+  the hash in the lock file
+- If the file was changed by the latest generator run: in this case the hash of the newly generated
+  file will be different from the hash in the lock file

package/dist/generator-manager.class.d.ts

@@ -0,0 +1,59 @@
+import { GeneratorInterfaceId } from './helpers/branded.types';
+import { GeneratorInterface } from './generator.class';
+import { Context } from './generator.context';
+/**
+ * The GeneratorManager coordinates the generation process across multiple Generators.
+ *
+ * Initially in the design/implementation of PostXL generators, this was not required as we could simply chain the generators's `register` and `generate` functions.
+ * However, after about 12 generators, we hit TypeScript's recursion limit and thus had to implement this manager.
+ *
+ * The idea is that individual generators still are fully type-safe and come with proper auto-completion, ie each generator is self-standing and only imports
+ * the generators in requires. However, in the projects' main `generate` function. instead of calling the individual generators' `register` and `generate` functions,
+ * we now instantiate a `GeneratorManager` and register all generators. The `GeneratorManager` ensures (at generation time) that all dependencies are met and
+ * and runs the generators in the correct order.
+ *
+ * Each Generator is responsible for generating a specific part of the project, such as the frontend, backend, or data.
+ *
+ * High-level, the generation process is as follows:
+ * - The GeneratorManager is instantiated
+ * - Generators are registered with the GeneratorManager. In the registration, each Generator provides:
+ *   - Its own requirements for the context (e.g. `Repositories` generator needs a `Database` generator)
+ *   - How it extends the context (e.g. `Repositories` generator adds a `Repository` object with detailed definitions to each model in the context)
+ * - When a Generator is registered, the GeneratorManager verifies that dependencies are met
+ * - The GeneratorManager runs each Generator's `generate` method
+ * - The GeneratorManager syncs the generated files to the project
+ */
+export declare class GeneratorManager {
+    private readonly generators;
+    private readonly implementedBy;
+    constructor(generator?: GeneratorInterface | GeneratorInterface[]);
+    registerTestGenerator(generator: GeneratorInterface, dependencies: Record<GeneratorInterfaceId, GeneratorInterface>): this;
+    private registerMockDependencies;
+    /**
+     * Helper method that registers all provided generators as mock generators,
+     * i.e. it will execute the `register` function of the generator, but not
+     * the `generate` function.
+     */
+    registerMockGenerator(generator: GeneratorInterface | GeneratorInterface[]): this;
+    /**
+     * Helper method that creates a mock of the original generator interface.
+     *
+     * If only an id is provided, i mocks a blank generator interface with the given id. If a full
+     * generator interface is provided, it will mock the same generator interface, i.e.
+     *  - Same `id`, `implementsInterface` properties
+     *  - Same `register` function
+     *  - Blank `generate` function
+     *  - Blank `requires` property
+     *
+     * This way, one can provide the interface of a generator without
+     * requiring all dependencies or slowing down the generation process.
+     */
+    static mockGenerator(generator: GeneratorInterface | string): GeneratorInterface;
+    registerGenerator(generators: GeneratorInterface | GeneratorInterface[]): this;
+    generate(context: Context): Promise<Context>;
+    private validateImplementedInterfaces;
+    private checkCircularDependencies;
+    private getDependencies;
+    private topologicalSort;
+    private topologicalSortVisit;
+}

package/dist/generator-manager.class.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeneratorManager = void 0;
+const utils_1 = require("@postxl/utils");
+const branded_types_1 = require("./helpers/branded.types");
+/**
+ * The GeneratorManager coordinates the generation process across multiple Generators.
+ *
+ * Initially in the design/implementation of PostXL generators, this was not required as we could simply chain the generators's `register` and `generate` functions.
+ * However, after about 12 generators, we hit TypeScript's recursion limit and thus had to implement this manager.
+ *
+ * The idea is that individual generators still are fully type-safe and come with proper auto-completion, ie each generator is self-standing and only imports
+ * the generators in requires. However, in the projects' main `generate` function. instead of calling the individual generators' `register` and `generate` functions,
+ * we now instantiate a `GeneratorManager` and register all generators. The `GeneratorManager` ensures (at generation time) that all dependencies are met and
+ * and runs the generators in the correct order.
+ *
+ * Each Generator is responsible for generating a specific part of the project, such as the frontend, backend, or data.
+ *
+ * High-level, the generation process is as follows:
+ * - The GeneratorManager is instantiated
+ * - Generators are registered with the GeneratorManager. In the registration, each Generator provides:
+ *   - Its own requirements for the context (e.g. `Repositories` generator needs a `Database` generator)
+ *   - How it extends the context (e.g. `Repositories` generator adds a `Repository` object with detailed definitions to each model in the context)
+ * - When a Generator is registered, the GeneratorManager verifies that dependencies are met
+ * - The GeneratorManager runs each Generator's `generate` method
+ * - The GeneratorManager syncs the generated files to the project
+ */
+class GeneratorManager {
+    generators = new Map();
+    implementedBy = new Map();
+    constructor(generator) {
+        if (generator) {
+            if (Array.isArray(generator)) {
+                for (const g of generator) {
+                    this.registerGenerator(g);
+                }
+                return;
+            }
+            else {
+                this.registerGenerator([generator]);
+                return;
+            }
+        }
+    }
+    registerTestGenerator(generator, dependencies) {
+        this.registerGenerator(generator);
+        this.registerMockDependencies(generator.requires, dependencies);
+        return this;
+    }
+    registerMockDependencies(requiredInterfaces, dependencies) {
+        if (!requiredInterfaces) {
+            return;
+        }
+        for (const requiredInterfaceId of requiredInterfaces) {
+            const dependency = dependencies[requiredInterfaceId];
+            if (!dependency) {
+                throw new Error(`No generator definition provided for ${(0, utils_1.yellow)(requiredInterfaceId)}`);
+            }
+            this.registerGenerator(GeneratorManager.mockGenerator(dependency));
+            this.registerMockDependencies(dependency.requires, dependencies);
+        }
+    }
+    /**
+     * Helper method that registers all provided generators as mock generators,
+     * i.e. it will execute the `register` function of the generator, but not
+     * the `generate` function.
+     */
+    registerMockGenerator(generator) {
+        if (!Array.isArray(generator)) {
+            generator = [generator];
+        }
+        const requiredInterfaces = new Set();
+        for (const g of generator) {
+            const mockGenerator = GeneratorManager.mockGenerator(g);
+            this.registerGenerator(mockGenerator);
+            for (const requiredInterfaceId of g.requires ?? []) {
+                requiredInterfaces.add(requiredInterfaceId);
+            }
+        }
+        for (const interfaceId of requiredInterfaces) {
+            this.registerGenerator(GeneratorManager.mockGenerator(interfaceId));
+        }
+        return this;
+    }
+    /**
+     * Helper method that creates a mock of the original generator interface.
+     *
+     * If only an id is provided, i mocks a blank generator interface with the given id. If a full
+     * generator interface is provided, it will mock the same generator interface, i.e.
+     *  - Same `id`, `implementsInterface` properties
+     *  - Same `register` function
+     *  - Blank `generate` function
+     *  - Blank `requires` property
+     *
+     * This way, one can provide the interface of a generator without
+     * requiring all dependencies or slowing down the generation process.
+     */
+    static mockGenerator(generator) {
+        if (typeof generator === 'string') {
+            return {
+                id: (0, branded_types_1.toGeneratorInterfaceId)(generator),
+                requires: [],
+                // eslint-disable-next-line @typescript-eslint/no-empty-function
+                register: () => { },
+                // eslint-disable-next-line @typescript-eslint/no-empty-function
+                generate: () => { },
+            };
+        }
+        return {
+            id: generator.id,
+            requires: generator.requires,
+            implementsInterface: generator.implementsInterface,
+            register: generator.register,
+            // eslint-disable-next-line @typescript-eslint/no-empty-function
+            generate: () => { },
+        };
+    }
+    registerGenerator(generators) {
+        if (!Array.isArray(generators)) {
+            this.registerGenerator([generators]);
+            return this;
+        }
+        for (const generator of generators) {
+            if (this.generators.has(generator.id)) {
+                // The generator was already registered
+                continue;
+            }
+            this.generators.set(generator.id, generator);
+            for (const interfaceId of generator.implementsInterface ?? [generator.id]) {
+                if (this.implementedBy.has(interfaceId)) {
+                    throw new Error(`Interface ${(0, utils_1.yellow)(interfaceId)} implementation is already registered by ${(0, utils_1.yellow)(this.implementedBy.get(interfaceId))}. Double registration (by ${(0, utils_1.yellow)(generator.id)}) is not allowed!`);
+                }
+                this.implementedBy.set(interfaceId, generator.id);
+            }
+        }
+        return this;
+    }
+    async generate(context) {
+        this.validateImplementedInterfaces();
+        this.checkCircularDependencies();
+        const generatorsSorted = this.topologicalSort();
+        for (const generator of generatorsSorted) {
+            // Not all generators extend the context and hence do not need to return it.
+            // Therefore, if the generator does not return the context, we use the original context.
+            context = (await generator.register(context)) ?? context;
+        }
+        for (const generator of generatorsSorted) {
+            if (!generator.afterRegistrations) {
+                continue;
+            }
+            await generator.afterRegistrations(context);
+        }
+        for (const generator of generatorsSorted) {
+            // Not all generators extend the context and hence do not need to return it.
+            // Therefore, if the generator does not return the context, we use the original context.
+            context = (await generator.generate(context)) ?? context;
+        }
+        return context;
+    }
+    validateImplementedInterfaces() {
+        for (const generator of this.generators.values()) {
+            for (const requiredInterfaceId of generator.requires ?? []) {
+                if (!this.implementedBy.has(requiredInterfaceId)) {
+                    throw new Error(`Generator ${(0, utils_1.yellow)(generator.id)} requires generator ${(0, utils_1.yellow)(requiredInterfaceId)} but it is not registered`);
+                }
+            }
+        }
+    }
+    checkCircularDependencies() {
+        const dependenciesCache = new Map();
+        for (const generatorId of this.generators.keys()) {
+            this.getDependencies(generatorId, dependenciesCache);
+        }
+    }
+    getDependencies(generatorId, dependenciesCache, rootGeneratorId) {
+        if (dependenciesCache.has(generatorId)) {
+            return dependenciesCache.get(generatorId);
+        }
+        const dependencies = new Set();
+        dependenciesCache.set(generatorId, dependencies);
+        const generator = this.generators.get(generatorId);
+        for (const requiredInterfaceId of generator.requires ?? []) {
+            const implementedById = this.implementedBy.get(requiredInterfaceId);
+            if (!implementedById) {
+                throw new Error(`Generator ${generatorId} is not registered`);
+            }
+            dependencies.add(implementedById);
+            for (const dependency of this.getDependencies(implementedById, dependenciesCache, rootGeneratorId ?? generatorId)) {
+                if (dependency === rootGeneratorId) {
+                    throw new Error(`Circular dependency detected: ${Array.from(dependencies.values()).join(' -> ')} -> ${dependency}`);
+                }
+                dependencies.add(dependency);
+            }
+        }
+        return dependencies;
+    }
+    topologicalSort() {
+        const visited = new Set();
+        const queue = [];
+        for (const generator of this.generators.values()) {
+            if (!visited.has(generator.id)) {
+                this.topologicalSortVisit(generator, visited, queue);
+            }
+        }
+        return queue;
+    }
+    topologicalSortVisit(generator, visited, queue, level = 0) {
+        visited.add(generator.id);
+        for (const requiredInterfaceId of generator.requires ?? []) {
+            const implementedBy = this.implementedBy.get(requiredInterfaceId);
+            const requiredGenerator = this.generators.get(implementedBy);
+            if (requiredGenerator) {
+                if (!visited.has(requiredGenerator.id)) {
+                    this.topologicalSortVisit(requiredGenerator, visited, queue, level + 1);
+                }
+            }
+        }
+        queue.push(generator);
+    }
+}
+exports.GeneratorManager = GeneratorManager;

package/dist/generator.class.d.ts

@@ -0,0 +1,90 @@
+import { GeneratorInterfaceId } from './helpers/branded.types';
+import { Context as BaseContext } from './generator.context';
+/**
+ * Generic function definition for a Generator Function:
+ *
+ * Each Generator Function takes a context (with ModelContext and EnumContext) and returns a new extended context type
+ */
+export type GeneratorFunction<ContextRequirements extends BaseContext, ContextResult extends ContextRequirements = ContextRequirements> = (context: ContextRequirements) => Promise<ContextResult> | ContextResult;
+export type GeneratorInterface = {
+    /**
+     * The id of the generator
+     */
+    readonly id: GeneratorInterfaceId;
+    /**
+     * The id(s) of interfaces that this generator implements.
+     * By default this is the id of the generator itself and does not need to be set. However, some generators
+     * may implement multiple interfaces or implement generic interfaces (e.g. the different database generators).
+     * These interfaces are stored in this property.
+     */
+    readonly implementsInterface?: GeneratorInterfaceId[] | undefined;
+    /**
+     * The id(s) of interfaces that this generator requires.
+     */
+    readonly requires?: GeneratorInterfaceId[] | undefined;
+    /**
+     * The function that registers generator specific properties in the context..
+     * Typically, it extends the context object with one additional property with the same name as the generator.
+     * Additionally, it may also extend context.models and context.enums with additional properties.
+     *
+     * The actual function signature is:
+     * ```ts
+     * register: GeneratorFunction<ContextRequirements, ContextResult>(context: ContextRequirements) => ContextResult
+     * ```
+     * With the generic types being defined as follows:
+     * ```ts
+     * export type GeneratorInterface<
+     *   ContextRequirements extends Generator.Context,
+     *   ContextResult extends ContextRequirements = ContextRequirements,
+     * >
+     * ```
+     *
+     * However, as each implementation of this interface should actually narrows the type of the context (e.g.
+     * `register: <
+     *    ContextRequirements extends WithDatabase<Generator.Context>,
+     *    ContextResult extends WithRepository<ContextRequirements>
+     *   >(context: ContextRequirements): ContextResult
+     * `), this would not comply to the interface definition. Therefore, we use the non-generic `any` escape hatch here.
+     *
+     * @param context The (generic) context that fulfills the requirements of the generator
+     * @returns The context with the generator specific properties added
+     */
+    register: (context: any) => Promise<BaseContext | void> | BaseContext | void;
+    /**
+     * Optional lifecycle function that gets executed after all `register` functions were executed.
+     *
+     * This can be useful, e.g. when the TRPC generator needs to transfer the module registrations from backend to frontend.
+     */
+    afterRegistrations?: (context: any) => Promise<BaseContext | void> | BaseContext | void;
+    /**
+     * The function that generates the actual files/code for this generator.
+     *
+     * The actual function signature is:
+     * ```ts
+     * generate: GeneratorFunction<ContextResult>(context: ContextResult) => ContextResult
+     * ```
+     * See the `register` description for more details, why we use the non-generic `any` escape hatch here.
+     */
+    generate: (context: any) => Promise<BaseContext | void> | BaseContext | void;
+};
+export declare class Generator<Context extends BaseContext> {
+    context: Context;
+    constructor(context: Context);
+    /**
+     * Applies the given generator function to the current context and returns a new generator instance.
+     *
+     * Example usage:
+     * ```ts
+     * const generator = new Generator({ schema, vfs })
+     * generator
+     *  .generate(NestJSGenerator.generate)
+     *  .then((g) => g.generate(NextJSGenerator.generate))
+     *  .then((g) => g.context.vfs.flush())
+     * ```
+     */
+    generate<ExtendedContext extends Context = Context>(generatorFn: GeneratorFunction<Context, ExtendedContext>): Promise<Generator<ExtendedContext>>;
+    /**
+     * Alias for `generate` to allow for a more fluent API.
+     */
+    register<ExtendedContext extends Context = Context>(generatorFn: GeneratorFunction<Context, ExtendedContext>): Promise<Generator<ExtendedContext>>;
+}

package/dist/generator.class.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Generator = void 0;
+class Generator {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    /**
+     * Applies the given generator function to the current context and returns a new generator instance.
+     *
+     * Example usage:
+     * ```ts
+     * const generator = new Generator({ schema, vfs })
+     * generator
+     *  .generate(NestJSGenerator.generate)
+     *  .then((g) => g.generate(NextJSGenerator.generate))
+     *  .then((g) => g.context.vfs.flush())
+     * ```
+     */
+    async generate(generatorFn) {
+        const newContext = await generatorFn(this.context);
+        return new Generator(newContext);
+    }
+    /**
+     * Alias for `generate` to allow for a more fluent API.
+     */
+    async register(generatorFn) {
+        return this.generate(generatorFn);
+    }
+}
+exports.Generator = Generator;