@postxl/generator 0.74.2 → 1.0.3

package/dist/generator.context.d.ts

@@ -0,0 +1,174 @@
+import * as Schema from '@postxl/schema';
+import { Conjugated } from '@postxl/utils';
+import { VariableName } from './helpers/branded.types';
+import { VirtualFileSystem } from './utils/vfs.class';
+/**
+ * Baseline context for all generators.
+ *
+ * It provides the VirtualFileSystem, the schema as well as a map of all models and enums.
+ * `models` and `enums` are generic maps - each generator can add its own context to the models' and enums' context.
+ */
+export type Context = {
+    /**
+     * The virtual files system that generators can write to
+     */
+    vfs: VirtualFileSystem;
+    /**
+     * The parsed project schema
+     */
+    schema: Schema.ProjectSchema;
+    /**
+     * Contains the context for each schema model.
+     * Each generator can extend these contexts with its own content.
+     */
+    models: Map<Schema.ModelName, ModelContext>;
+    /**
+     * Contains the context for each schema enum.
+     * Each generator can extend these contexts with its own content.
+     */
+    enums: Map<Schema.EnumName, EnumContext>;
+    /**
+     * Global options for the handling of the generation process (e.g. log settings, etc.)
+     */
+    options: GeneratorOptions;
+};
+export type ModelContext = Schema.Model & {
+    /**
+     * A user friendly name (in singular)
+     *
+     * User friendly name is very generic and  meant to be used in log messages, comments,
+     * errors - and any other places where the user shall read about it!
+     * It is not meant to be used for variables, class names, etc. In code, you should
+     * use a more specific name for your purposes (e.g. `reactCreateModalComponentName`).
+     */
+    userFriendlyName: string;
+    /**
+     * A user friendly name in plural form
+     *
+     * User friendly name is very generic and  meant to be used in log messages, comments,
+     * errors - and any other places where the user shall read about it!
+     * It is not meant to be used for variables, class names, etc. In code, you should
+     * use a more specific name for your purposes (e.g. `reactCreateModalComponentName`).
+     */
+    userFriendlyNamePlural: string;
+    /**
+     * The name of the model in singular form.
+     *
+     * This name is meant to be used in internal variables only.
+     * For any variables, class names, etc. that are exposed, please use a more specific name.
+     * (e.g. `reactCreateModalComponentName`)
+     */
+    internalSingularName: VariableName;
+    /**
+     * The name of the capitalized model in singular form.
+     *
+     * This name is meant to be used in internal types only.
+     * For any types, class names, etc. that are exposed, please use a more specific name.
+     */
+    internalSingularNameCapitalized: VariableName;
+    /**
+     * The name of the model in plural form.
+     *
+     * This name is meant to be used in internal variables only.
+     * For any variables, class names, etc. that are exposed, please use a more specific name.
+     * (e.g. `reactCreateModalComponentName`)
+     */
+    internalPluralName: VariableName;
+    /**
+     * The name of the capitalized model in plural form.
+     *
+     * This name is meant to be used in internal types only.
+     * For any variables, class names, etc. that are exposed, please use a more specific name.
+     */
+    internalPluralNameCapitalized: VariableName;
+    /**
+     * Internal cache for conjugated names.
+     *
+     * IMPORTANT: Do not use these names in generated code. Instead, they are provided to allow
+     *            easy creation of names in the registration functions!
+     *
+     * @internal
+     */
+    _conjugated: Conjugated;
+    /**
+     * Convenience set of related model names referenced by relation and discriminated union
+     * fields in this model.
+     *
+     * Only names (not entire model contexts) are provided so that the models' enhanced
+     * contexts can be retrieved during generation (ie. after all generators have registered their
+     * model contexts).
+     */
+    relatedModelNames: Set<Schema.ModelName>;
+};
+export type EnumContext = Schema.Enum & {
+    /**
+     * A user friendly name (in singular)
+     *
+     * User friendly name is very generic and  meant to be used in log messages, comments,
+     * errors - and any other places where the user shall read about it!
+     * It is not meant to be used for variables, class names, etc. In code, you should
+     * use a more specific name for your purposes (e.g. `reactCreateModalComponentName`).
+     */
+    userFriendlyName: string;
+    /**
+     * A user friendly name in plural form
+     *
+     * User friendly name is very generic and  meant to be used in log messages, comments,
+     * errors - and any other places where the user shall read about it!
+     * It is not meant to be used for variables, class names, etc. In code, you should
+     * use a more specific name for your purposes (e.g. `reactCreateModalComponentName`).
+     */
+    userFriendlyPluralName: string;
+    /**
+     * Internal cache for conjugated names.
+     *
+     * IMPORTANT: Do not use these names in generated code. Instead, they are provided to allow
+     *            easy creation of names in the registration functions!
+     *
+     * @internal
+     */
+    _conjugated: Conjugated;
+};
+export type GeneratorOptions = {
+    /**
+     * If true, the generator will continue generation even if it encounters errors.
+     *
+     * Default: false
+     */
+    readonly ignoreErrors: boolean;
+    errors: string[];
+    /**
+     * Optional glob pattern to filter files during generation (e.g., '**\/*.ts' or 'backend/libs/**').
+     * When specified, only files matching this pattern will be processed (generated, linted, formatted, and synced).
+     *
+     * Default: undefined (no filtering)
+     */
+    filePattern?: string;
+};
+export type ExtendContext<Context, ContextExtension> = Context & ContextExtension;
+export type ExtendModelContext<Context, ModelContextExtension> = Context extends {
+    models: Map<infer K, infer V>;
+} ? Omit<Context, 'models'> & {
+    models: Map<K, V & ModelContextExtension>;
+} : never;
+export type ExtendEnumContext<Context, EnumContextExtension> = Context extends {
+    enums: Map<infer K, infer V>;
+} ? Omit<Context, 'enums'> & {
+    enums: Map<K, V & EnumContextExtension>;
+} : never;
+export type ExtendContextAndModel<Context, Extension, ModelContextExtension> = ExtendModelContext<ExtendContext<Context, Extension>, ModelContextExtension>;
+export type ExtendContextAndModelAndEnum<Context, Extension, ModelContextExtension, EnumContextExtension> = ExtendEnumContext<ExtendModelContext<ExtendContext<Context, Extension>, ModelContextExtension>, EnumContextExtension>;
+export type InferModelContext<Context> = Context extends {
+    models: Map<any, infer V>;
+} ? V : never;
+export type InferEnumContext<Context> = Context extends {
+    enums: Map<any, infer V>;
+} ? V : never;
+export declare function prepareBaseContext(schema: Schema.ProjectSchema, opts?: Partial<GeneratorOptions>): Context;
+/**
+ * Helper function for tests to create a mock schema.
+ */
+export declare function mockSchema(schema?: Partial<Schema.ProjectSchema>): Schema.ProjectSchema;
+export declare function mockSchemaWithDefaultModels(schema?: Partial<Schema.ProjectSchema>): Schema.ProjectSchema;
+export declare function getBaseModelContext(model: Schema.Model): ModelContext;
+export declare function getBaseEnumContext(enumSchema: Schema.Enum): EnumContext;

package/dist/generator.context.js

@@ -0,0 +1,125 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareBaseContext = prepareBaseContext;
+exports.mockSchema = mockSchema;
+exports.mockSchemaWithDefaultModels = mockSchemaWithDefaultModels;
+exports.getBaseModelContext = getBaseModelContext;
+exports.getBaseEnumContext = getBaseEnumContext;
+const Schema = __importStar(require("@postxl/schema"));
+const utils_1 = require("@postxl/utils");
+const branded_types_1 = require("./helpers/branded.types");
+const vfs_class_1 = require("./utils/vfs.class");
+const defaultGeneratorOptions = {
+    ignoreErrors: false,
+    errors: [],
+};
+function prepareBaseContext(schema, opts = defaultGeneratorOptions) {
+    const options = { ...defaultGeneratorOptions, ...opts };
+    const models = new Map();
+    const enums = new Map();
+    for (const model of schema.models.values()) {
+        models.set(model.name, getBaseModelContext(model));
+    }
+    for (const enumSchema of schema.enums.values()) {
+        enums.set(enumSchema.name, getBaseEnumContext(enumSchema));
+    }
+    return {
+        schema: schema,
+        vfs: new vfs_class_1.VirtualFileSystem(options.filePattern ? { filePattern: options.filePattern } : undefined),
+        models,
+        enums,
+        options,
+    };
+}
+/**
+ * Helper function for tests to create a mock schema.
+ */
+function mockSchema(schema = {}) {
+    return {
+        name: 'PXL Mock',
+        slug: 'pxl-mock',
+        projectType: { kind: 'standalone' },
+        models: new Map(),
+        enums: new Map(),
+        ...schema,
+    };
+}
+function mockSchemaWithDefaultModels(schema = {}) {
+    return Schema.zProjectSchema.parse({
+        name: 'PXL Mock',
+        slug: 'pxl-mock',
+        projectType: { kind: 'standalone' },
+        ...schema,
+    });
+}
+function getBaseModelContext(model) {
+    const { PascalCase, camelCase, uncapitalizedPlural, capitalized, capitalizedPlural } = (0, utils_1.conjugateNames)(model.name);
+    const relatedModelNames = new Set();
+    extractModelNamesFromFields(model.fields, relatedModelNames);
+    return {
+        ...model,
+        userFriendlyName: PascalCase,
+        userFriendlyNamePlural: capitalizedPlural,
+        internalSingularName: (0, branded_types_1.toVariableName)(camelCase),
+        internalSingularNameCapitalized: (0, branded_types_1.toVariableName)(capitalized),
+        internalPluralName: (0, branded_types_1.toVariableName)(uncapitalizedPlural),
+        internalPluralNameCapitalized: (0, branded_types_1.toVariableName)(capitalizedPlural),
+        _conjugated: (0, utils_1.conjugateNames)(model.name),
+        relatedModelNames,
+    };
+}
+function getBaseEnumContext(enumSchema) {
+    const { PascalCase, capitalizedPlural } = (0, utils_1.conjugateNames)(enumSchema.name);
+    return {
+        ...enumSchema,
+        userFriendlyName: PascalCase,
+        userFriendlyPluralName: capitalizedPlural,
+        _conjugated: (0, utils_1.conjugateNames)(enumSchema.name),
+    };
+}
+function extractModelNamesFromFields(fields, models) {
+    for (const field of fields.values()) {
+        if (field.kind === 'relation' && field.referencedModelName) {
+            models.add(field.referencedModelName);
+        }
+        else if (field.kind === 'discriminatedUnion') {
+            extractModelNamesFromFields(field.commonFields, models);
+            for (const member of field.members.values()) {
+                extractModelNamesFromFields(member.fields, models);
+            }
+        }
+    }
+}

package/dist/helpers/branded.types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Utility types and functions that brand strings with a specific prefix.
+ *
+ * The following types are available:
+ *
+ * Generator related types:
+ * - `GeneratorInterfaceId`
+ *
+ * Code related types:
+ * - `TypeName` (and `AnnotatedTypeName` for runtime type checking)
+ * - `FunctionName`
+ * - `ClassName`
+ * - `PackageName` - a package name from npm, JSR or monorepo, e.g. "@postxl/utils"
+ * - `ConstantValue` - a constant value that is used in the generated code, e.g. "POSTXL"
+ * - `DiscriminantValue` - a discriminant value, used to discriminate union types, e.g. "create", "update", "delete"
+ *
+ * Path and file related types:
+ * - `FileName` - file without a file extension, e.g. "aggregation.type" (no path!)
+ * - `FolderName` -  a folder without the trailing and leading slash (e.g. "aggregation").
+ * - `FilePath` - a relative or absolute path to a file or folder.
+ *
+ * The following names are provided by the schema package and not part of this file:
+ * - `ModelName`
+ * - `FieldName`
+ * - `EnumName`
+ *
+ * We use Zod's `.brand()` method to brand strings with a specific prefix.
+ *
+ * Additionally, we provide the following union types:
+ * - `Importable`: TypeName | FunctionName | ClassName
+ * - `ImportPaths`: FilePath | PackageName
+ */
+import z from 'zod';
+declare const zGeneratorInterfaceId: z.ZodBranded<z.ZodString, "PXL.GeneratorInterfaceId">;
+/**
+ * A generator interface id that is used identify what interface a generator implements.
+ */
+export type GeneratorInterfaceId = z.infer<typeof zGeneratorInterfaceId>;
+export declare const toGeneratorInterfaceId: (input: string) => string & z.BRAND<"PXL.GeneratorInterfaceId">;
+declare const zTypeName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.TypeName">, "PXL.Importable">;
+/**
+ * A type name that is used to refer to a type in the generated code.
+ */
+export type TypeName = z.infer<typeof zTypeName>;
+export declare const toTypeName: (input: string) => string & z.BRAND<"PXL.TypeName"> & z.BRAND<"PXL.Importable">;
+/**
+ * A TypeName that is annotated with the kind of the type.
+ * Note: This is used when distinguishing between kinds is required at runtime.
+ */
+export type AnnotatedTypeName = {
+    typeName: TypeName;
+    kind: 'TypeName';
+};
+/**
+ * Converts a branded string to a branded TypeName.
+ */
+export declare const toAnnotatedTypeName: (name: TypeName) => AnnotatedTypeName;
+/**
+ * Type guard to check if a given type is an AnnotatedTypeName.
+ */
+export declare const isAnnotatedTypeName: (t: string | AnnotatedTypeName) => t is AnnotatedTypeName;
+declare const zFunctionName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.FunctionName">, "PXL.Importable">;
+/**
+ * A function name that is used to refer to a function in the generated code.
+ */
+export type FunctionName = z.infer<typeof zFunctionName>;
+export declare const toFunctionName: (input: string) => string & z.BRAND<"PXL.FunctionName"> & z.BRAND<"PXL.Importable">;
+declare const zVariableName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.VariableName">, "PXL.Importable">;
+/**
+ * A variable name that is used to refer to a variable in the generated code.
+ */
+export type VariableName = z.infer<typeof zVariableName>;
+export declare const toVariableName: (input: string) => string & z.BRAND<"PXL.VariableName"> & z.BRAND<"PXL.Importable">;
+declare const zPostXlPackageName: z.ZodBranded<z.ZodEffects<z.ZodString, string, string>, "PXL.PackageName">;
+/**
+ * A package name that is used to refer to a package in the generated code.
+ */
+export declare const toPostXlPackageName: (input: string) => string & z.BRAND<"PXL.PackageName">;
+export declare const toPackageName: (input: string) => string & z.BRAND<"PXL.PackageName">;
+/**
+ * A package name that is used to refer to a package name that is provided via
+ * in package.json or is a NodeJS module.
+ * E.g. "fs", "random", "@nestjs/common".
+ */
+export type PackageName = z.infer<typeof zPostXlPackageName>;
+declare const zClassName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.ClassName">, "PXL.Importable">;
+/**
+ * A class name that is used to refer to a class in the generated code.
+ */
+export type ClassName = z.infer<typeof zClassName>;
+export declare const toClassName: (input: string) => string & z.BRAND<"PXL.ClassName"> & z.BRAND<"PXL.Importable">;
+declare const zConstantName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.ConstantName">, "PXL.Importable">;
+/**
+ * A constant name that is used to refer to a constant in the generated code.
+ */
+export type ConstantName = z.infer<typeof zConstantName>;
+export declare const toConstantName: (input: string) => string & z.BRAND<"PXL.ConstantName"> & z.BRAND<"PXL.Importable">;
+declare const zConstantValue: z.ZodBranded<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, "PXL.ConstantValue">;
+/**
+ * A constant value that is used in the generated code.
+ */
+export type ConstantValue = z.infer<typeof zConstantValue>;
+export declare const toConstantValue: (input: string | number | boolean | null) => (string | number | boolean | null) & z.BRAND<"PXL.ConstantValue">;
+declare const zDiscriminantValue: z.ZodBranded<z.ZodString, "PXL.DiscriminantValue">;
+/**
+ * A discriminant value, used to discriminate union types.
+ */
+export type DiscriminantValue = z.infer<typeof zDiscriminantValue>;
+export declare const toDiscriminantValue: (input: string) => string & z.BRAND<"PXL.DiscriminantValue">;
+declare const zFileName: z.ZodBranded<z.ZodString, "PXL.FileName">;
+/**
+ * A file name that is used to refer to a file in the generated code.
+ */
+export type FileName = z.infer<typeof zFileName>;
+export declare const toFileName: (input: string) => string & z.BRAND<"PXL.FileName">;
+declare const zFolderName: z.ZodBranded<z.ZodString, "PXL.FolderName">;
+/**
+ * A folder name that is used to refer to a folder in the generated code.
+ */
+export type FolderName = z.infer<typeof zFolderName>;
+export declare const toFolderName: (input: string) => string & z.BRAND<"PXL.FolderName">;
+declare const zFilePath: z.ZodBranded<z.ZodString, "PXL.FilePath">;
+/**
+ * A file path that is used to refer to a file in the generated code.
+ */
+export type FilePath = z.infer<typeof zFilePath>;
+export declare const toFilePath: (input: string) => string & z.BRAND<"PXL.FilePath">;
+declare const zBackendModuleName: z.ZodBranded<z.ZodString, "PXL.BackendModuleName">;
+/**
+ * A backend module name that is used to refer to a module in the backend.
+ * E.g. `@actions`.
+ */
+export type BackendModuleName = z.infer<typeof zBackendModuleName>;
+export declare const toBackendModuleName: (input: string) => string & z.BRAND<"PXL.BackendModuleName">;
+declare const zBackendModuleLocation: z.ZodBranded<z.ZodString, "PXL.BackendModuleLocation">;
+/**
+ * A module location is a reference to a file in a locale backend module.
+ * E.g. `@actions/actions.types`.
+ *
+ * Background: In the backend, we do not use index.ts barrel files to control the export
+ * of entries from a module, as this leads to problems that are very hard to debug.
+ * (see (NestJS recommendation)[https://docs.nestjs.com/faq/common-errors#cannot-resolve-dependency-error]).
+ * Therefore, we need to reference the actual file together with the package name.
+ */
+export type BackendModuleLocation = z.infer<typeof zBackendModuleLocation>;
+export declare const toBackendModuleLocation: (input: `@${string}`) => string & z.BRAND<"PXL.BackendModuleLocation">;
+export type ImportableTypes = TypeName | FunctionName | ClassName | ConstantName | AnnotatedTypeName;
+export type ImportPaths = FilePath | PackageName | BackendModuleLocation;
+export {};

package/dist/helpers/branded.types.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Utility types and functions that brand strings with a specific prefix.
+ *
+ * The following types are available:
+ *
+ * Generator related types:
+ * - `GeneratorInterfaceId`
+ *
+ * Code related types:
+ * - `TypeName` (and `AnnotatedTypeName` for runtime type checking)
+ * - `FunctionName`
+ * - `ClassName`
+ * - `PackageName` - a package name from npm, JSR or monorepo, e.g. "@postxl/utils"
+ * - `ConstantValue` - a constant value that is used in the generated code, e.g. "POSTXL"
+ * - `DiscriminantValue` - a discriminant value, used to discriminate union types, e.g. "create", "update", "delete"
+ *
+ * Path and file related types:
+ * - `FileName` - file without a file extension, e.g. "aggregation.type" (no path!)
+ * - `FolderName` -  a folder without the trailing and leading slash (e.g. "aggregation").
+ * - `FilePath` - a relative or absolute path to a file or folder.
+ *
+ * The following names are provided by the schema package and not part of this file:
+ * - `ModelName`
+ * - `FieldName`
+ * - `EnumName`
+ *
+ * We use Zod's `.brand()` method to brand strings with a specific prefix.
+ *
+ * Additionally, we provide the following union types:
+ * - `Importable`: TypeName | FunctionName | ClassName
+ * - `ImportPaths`: FilePath | PackageName
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBackendModuleLocation = exports.toBackendModuleName = exports.toFilePath = exports.toFolderName = exports.toFileName = exports.toDiscriminantValue = exports.toConstantValue = exports.toConstantName = exports.toClassName = exports.toPackageName = exports.toPostXlPackageName = exports.toVariableName = exports.toFunctionName = exports.isAnnotatedTypeName = exports.toAnnotatedTypeName = exports.toTypeName = exports.toGeneratorInterfaceId = void 0;
+const zod_1 = __importDefault(require("zod"));
+const zGeneratorInterfaceId = zod_1.default.string().brand('PXL.GeneratorInterfaceId');
+const toGeneratorInterfaceId = (input) => zGeneratorInterfaceId.parse(input);
+exports.toGeneratorInterfaceId = toGeneratorInterfaceId;
+const zTypeName = zod_1.default.string().brand('PXL.TypeName').brand('PXL.Importable');
+const toTypeName = (input) => zTypeName.parse(input);
+exports.toTypeName = toTypeName;
+/**
+ * Converts a branded string to a branded TypeName.
+ */
+const toAnnotatedTypeName = (name) => ({
+    typeName: name,
+    kind: 'TypeName',
+});
+exports.toAnnotatedTypeName = toAnnotatedTypeName;
+/**
+ * Type guard to check if a given type is an AnnotatedTypeName.
+ */
+const isAnnotatedTypeName = (t) => typeof t === 'object' && t.kind === 'TypeName';
+exports.isAnnotatedTypeName = isAnnotatedTypeName;
+const zFunctionName = zod_1.default.string().brand('PXL.FunctionName').brand('PXL.Importable');
+const toFunctionName = (input) => zFunctionName.parse(input);
+exports.toFunctionName = toFunctionName;
+const zVariableName = zod_1.default.string().brand('PXL.VariableName').brand('PXL.Importable');
+const toVariableName = (input) => zVariableName.parse(input);
+exports.toVariableName = toVariableName;
+const zPostXlPackageName = zod_1.default
+    .string()
+    .refine((name) => name.startsWith('@postxl/'), (name) => ({ message: `Package name must start with "@postxl/", got "${name}"!` }))
+    .brand('PXL.PackageName');
+/**
+ * A package name that is used to refer to a package in the generated code.
+ */
+const toPostXlPackageName = (input) => zPostXlPackageName.parse(input);
+exports.toPostXlPackageName = toPostXlPackageName;
+const zPackageName = zod_1.default
+    .string()
+    //TODO: To be debugged:
+    // .refine(
+    //   // Source: https://github.com/dword-design/package-name-regex/blob/806bbaafb3b9deab270b071b76a0f4e0bcfc1be9/src/index.js#L2
+    //   (name) => /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name),
+    //   (name) => ({ message: `Package name must be a valid package name, get ${name}"!` }),
+    // )
+    .brand('PXL.PackageName');
+const toPackageName = (input) => zPackageName.parse(input);
+exports.toPackageName = toPackageName;
+const zClassName = zod_1.default.string().brand('PXL.ClassName').brand('PXL.Importable');
+const toClassName = (input) => zClassName.parse(input);
+exports.toClassName = toClassName;
+const zConstantName = zod_1.default.string().brand('PXL.ConstantName').brand('PXL.Importable');
+const toConstantName = (input) => zConstantName.parse(input);
+exports.toConstantName = toConstantName;
+const zConstantValue = zod_1.default.union([zod_1.default.string(), zod_1.default.number(), zod_1.default.boolean(), zod_1.default.null()]).brand('PXL.ConstantValue');
+const toConstantValue = (input) => zConstantValue.parse(input);
+exports.toConstantValue = toConstantValue;
+const zDiscriminantValue = zod_1.default.string().brand('PXL.DiscriminantValue');
+const toDiscriminantValue = (input) => zDiscriminantValue.parse(input);
+exports.toDiscriminantValue = toDiscriminantValue;
+const zFileName = zod_1.default.string().brand('PXL.FileName');
+const toFileName = (input) => zFileName.parse(input);
+exports.toFileName = toFileName;
+const zFolderName = zod_1.default.string().brand('PXL.FolderName');
+const toFolderName = (input) => zFolderName.parse(input);
+exports.toFolderName = toFolderName;
+const zFilePath = zod_1.default.string().brand('PXL.FilePath');
+const toFilePath = (input) => zFilePath.parse(input);
+exports.toFilePath = toFilePath;
+const zBackendModuleName = zod_1.default.string().brand('PXL.BackendModuleName');
+const toBackendModuleName = (input) => zBackendModuleName.parse(input);
+exports.toBackendModuleName = toBackendModuleName;
+const zBackendModuleLocation = zod_1.default.string().brand('PXL.BackendModuleLocation');
+const toBackendModuleLocation = (input) => zBackendModuleLocation.parse(input);
+exports.toBackendModuleLocation = toBackendModuleLocation;

package/dist/helpers/config-builder.class.d.ts

@@ -0,0 +1,27 @@
+import { DeepPartial } from '@postxl/utils';
+/**
+ * A utility class that allows to build a configuration object incrementally.
+ *
+ * Example usage:
+ * ```ts
+ * const config = new ConfigBuilder({ a: [1, 2], b: { c: 3 } })
+ *   .with({ a: [3, 4] })
+ *   .with({ b: { d: 4 } })
+ *   .with({ c: 'x' })
+ *   .done()
+ * ```
+ *
+ * The resulting config will be:
+ * ```ts
+ * { a: [1, 2, 3, 4], b: { c: 3, d: 4 }, c: 'x' }
+ * ```
+ */
+export declare class ConfigBuilder<Config extends Record<string, unknown>> {
+    #private;
+    constructor(base: Config);
+    /**
+     * Updates the current configuration with the given partial update.
+     */
+    with(update: DeepPartial<Config>): this;
+    done(): Config;
+}

package/dist/helpers/config-builder.class.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigBuilder = void 0;
+/**
+ * A utility class that allows to build a configuration object incrementally.
+ *
+ * Example usage:
+ * ```ts
+ * const config = new ConfigBuilder({ a: [1, 2], b: { c: 3 } })
+ *   .with({ a: [3, 4] })
+ *   .with({ b: { d: 4 } })
+ *   .with({ c: 'x' })
+ *   .done()
+ * ```
+ *
+ * The resulting config will be:
+ * ```ts
+ * { a: [1, 2, 3, 4], b: { c: 3, d: 4 }, c: 'x' }
+ * ```
+ */
+class ConfigBuilder {
+    #config;
+    constructor(base) {
+        this.#config = base;
+    }
+    /**
+     * Deep merge two objects.
+     */
+    #deepMerge(target, source) {
+        for (const key in source) {
+            if (Array.isArray(source[key])) {
+                target[key] = Array.isArray(target[key]) ? [...target[key], ...source[key]] : source[key];
+            }
+            else if (source[key] !== null && typeof source[key] === 'object') {
+                target[key] = this.#deepMerge(target[key] || {}, source[key]);
+            }
+            else {
+                target[key] = source[key];
+            }
+        }
+        return target;
+    }
+    /**
+     * Updates the current configuration with the given partial update.
+     */
+    with(update) {
+        this.#config = this.#deepMerge(this.#config, update);
+        return this;
+    }
+    done() {
+        return this.#config;
+    }
+}
+exports.ConfigBuilder = ConfigBuilder;