@drzl/cli 4.19.0 → 4.23.0

package/dist/config.d.cts

@@ -1,5 +1,56 @@
 import { z } from 'zod';
 
+/**
+ * drizzle-kit interop: read the schema path from `drizzle.config.ts`, so a drizzle-kit user
+ * does not have to state it a second time in `drzl.config.ts`.
+ *
+ * Everything here mirrors drizzle-kit's measured behavior, read from the published dist of
+ * drizzle-kit 0.31.10 rather than from its docs or from memory:
+ *
+ *   - `Config.schema` is `string | string[]` and entries may be glob patterns (`index.d.mts`).
+ *   - The CLI's default config candidates are `drizzle.config.ts`, then `.js`, then `.json`,
+ *     in that order and nothing else (`drizzleConfigFromFile` in `bin.cjs`); a custom path can
+ *     be anything its `--config` flag can name, which `drizzleKit: '<path>'` mirrors.
+ *   - `prepareFilenames` (bin.cjs) expands each entry with glob.sync, expands a directory
+ *     match one level with readdir rather than recursively, unions the results, and hard-errors
+ *     when nothing matched. It also computes the list of code extensions (.ts .js .cjs .mjs
+ *     .mts .cts) into a variable it never reads, and then requires every match; DRZL applies
+ *     that filter for real, which is strictly friendlier than crashing on a README.md sitting
+ *     in the schema directory.
+ *   - `defineConfig` is the identity function (`index.mjs`), so evaluating the config module
+ *     yields the plain object and no drizzle-kit installation is needed to read it.
+ *
+ * Globs are expanded with `node:fs.globSync`, present since Node 22.0 and quiet on the CLI's
+ * `engines` floor (measured: `*`, `**`, `{a,b}` and literal paths all behave; no
+ * ExperimentalWarning on stderr on 22.22). No new dependency, and the config itself is loaded
+ * through the same jiti path as `drzl.config.ts` (`importFreshConfigModule`), so the two
+ * config files cannot drift onto different loaders.
+ */
+
+/**
+ * Where the schema will be read from, decided once and handed to both `generate` and `watch`,
+ * so the two commands cannot resolve differently.
+ */
+interface ResolvedSchemaSource {
+    source: 'drzl' | 'drizzle-kit';
+    /**
+     * What `SchemaAnalyzer` is constructed with: the drzl config's `schema` string verbatim, or
+     * the expanded, sorted, absolute file list from the drizzle-kit config.
+     */
+    schema: string | string[];
+    /**
+     * Absolute directories that must be watched for schema edits. For a glob this is its static
+     * base, so a file created later that matches the pattern still raises an event; a missing
+     * entry here is the infinite-blindness half of the watch-loop rules.
+     */
+    watchDirs: string[];
+    /** Absolute path of the drizzle-kit config consulted, when source is 'drizzle-kit'. */
+    drizzleKitConfigPath?: string;
+    /** The dialect that config declares, verbatim, for the post-analysis cross-check. */
+    drizzleKitDialect?: string;
+    warnings: string[];
+}
+
 declare const NamingSchema: z.ZodObject<{
     routerSuffix: z.ZodOptional<z.ZodDefault<z.ZodString>>;
     procedureCase: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
@@ -51,10 +102,44 @@ declare const ImportExtensionSchema: z.ZodEnum<{
     none: "none";
     ts: "ts";
 }>;
+/**
+ * Every generator DRZL can run, named once.
+ *
+ * Extracted from `GeneratorSchema.kind` rather than restated beside it, because three surfaces
+ * have to agree about this list and two of them used to spell it themselves: the config parser,
+ * the JSON Schema editors validate a `drzl.config.json` against, and the CLI's `--only`. A kind
+ * added here is accepted by all three at once, which is the property `--only` needs to be able to
+ * refuse an unknown value by name instead of matching nothing in silence.
+ */
+declare const GeneratorKindSchema: z.ZodEnum<{
+    orpc: "orpc";
+    trpc: "trpc";
+    hono: "hono";
+    express: "express";
+    fastify: "fastify";
+    nestjs: "nestjs";
+    graphql: "graphql";
+    service: "service";
+    zod: "zod";
+    valibot: "valibot";
+    arktype: "arktype";
+    typebox: "typebox";
+    effect: "effect";
+    "json-schema": "json-schema";
+}>;
+/** One generator kind, as the config spells it. */
+type GeneratorKind = z.infer<typeof GeneratorKindSchema>;
+/** The kinds in declaration order, for a message that has to list them. */
+declare const GENERATOR_KINDS: readonly GeneratorKind[];
 declare const GeneratorSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         orpc: "orpc";
         trpc: "trpc";
+        hono: "hono";
+        express: "express";
+        fastify: "fastify";
+        nestjs: "nestjs";
+        graphql: "graphql";
         service: "service";
         zod: "zod";
         valibot: "valibot";
@@ -63,6 +148,10 @@ declare const GeneratorSchema: z.ZodObject<{
         effect: "effect";
         "json-schema": "json-schema";
     }>;
+    validator: z.ZodOptional<z.ZodEnum<{
+        zod: "zod";
+        standard: "standard";
+    }>>;
     importExtension: z.ZodOptional<z.ZodEnum<{
         js: "js";
         none: "none";
@@ -70,17 +159,32 @@ declare const GeneratorSchema: z.ZodObject<{
     }>>;
     template: z.ZodOptional<z.ZodString>;
     includeRelations: z.ZodOptional<z.ZodBoolean>;
+    sharedEnums: z.ZodOptional<z.ZodBoolean>;
     coerceDates: z.ZodOptional<z.ZodEnum<{
-        none: "none";
         input: "input";
+        none: "none";
         all: "all";
     }>>;
     typedJson: z.ZodOptional<z.ZodBoolean>;
     typedColumns: z.ZodOptional<z.ZodBoolean>;
     applyDefaults: z.ZodOptional<z.ZodBoolean>;
     duplicateFinder: z.ZodOptional<z.ZodBoolean>;
+    constraints: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        errorMap: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+    meta: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+    standardSchema: z.ZodOptional<z.ZodBoolean>;
     nestedSchemas: z.ZodOptional<z.ZodBoolean>;
     nestedDepth: z.ZodOptional<z.ZodNumber>;
+    branded: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        foreignKeys: z.ZodOptional<z.ZodBoolean>;
+        aliases: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
     naming: z.ZodOptional<z.ZodObject<{
         routerSuffix: z.ZodOptional<z.ZodDefault<z.ZodString>>;
         procedureCase: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
@@ -215,16 +319,32 @@ declare const GeneratorSchema: z.ZodObject<{
     }, z.core.$strip>>;
     templateOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, z.core.$strip>;
+/**
+ * One table's column rules. Strict, so `ommit` is refused by the parser rather than dropped.
+ *
+ * The whole option exists to remove a column, and a key zod strips in silence is a config that
+ * looks like it removed one and did not. `GeneratorSchema` is deliberately not strict and has
+ * already cost this repo two options that parsed and then did nothing.
+ */
+declare const ColumnRulesSchema: z.ZodObject<{
+    omit: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pick: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
 declare const AnalyzerSchema: z.ZodObject<{
     includeRelations: z.ZodDefault<z.ZodBoolean>;
     validateConstraints: z.ZodDefault<z.ZodBoolean>;
     includeHeuristicRelations: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 declare const ConfigSchema: z.ZodObject<{
-    schema: z.ZodString;
+    schema: z.ZodOptional<z.ZodString>;
+    drizzleKit: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
     outDir: z.ZodDefault<z.ZodString>;
     include: z.ZodOptional<z.ZodArray<z.ZodString>>;
     exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    columns: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        omit: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        pick: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
     importExtension: z.ZodDefault<z.ZodEnum<{
         js: "js";
         none: "none";
@@ -239,6 +359,11 @@ declare const ConfigSchema: z.ZodObject<{
         kind: z.ZodEnum<{
             orpc: "orpc";
             trpc: "trpc";
+            hono: "hono";
+            express: "express";
+            fastify: "fastify";
+            nestjs: "nestjs";
+            graphql: "graphql";
             service: "service";
             zod: "zod";
             valibot: "valibot";
@@ -247,6 +372,10 @@ declare const ConfigSchema: z.ZodObject<{
             effect: "effect";
             "json-schema": "json-schema";
         }>;
+        validator: z.ZodOptional<z.ZodEnum<{
+            zod: "zod";
+            standard: "standard";
+        }>>;
         importExtension: z.ZodOptional<z.ZodEnum<{
             js: "js";
             none: "none";
@@ -254,17 +383,32 @@ declare const ConfigSchema: z.ZodObject<{
         }>>;
         template: z.ZodOptional<z.ZodString>;
         includeRelations: z.ZodOptional<z.ZodBoolean>;
+        sharedEnums: z.ZodOptional<z.ZodBoolean>;
         coerceDates: z.ZodOptional<z.ZodEnum<{
-            none: "none";
             input: "input";
+            none: "none";
             all: "all";
         }>>;
         typedJson: z.ZodOptional<z.ZodBoolean>;
         typedColumns: z.ZodOptional<z.ZodBoolean>;
         applyDefaults: z.ZodOptional<z.ZodBoolean>;
         duplicateFinder: z.ZodOptional<z.ZodBoolean>;
+        constraints: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            errorMap: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>]>>;
+        meta: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>]>>;
+        standardSchema: z.ZodOptional<z.ZodBoolean>;
         nestedSchemas: z.ZodOptional<z.ZodBoolean>;
         nestedDepth: z.ZodOptional<z.ZodNumber>;
+        branded: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            foreignKeys: z.ZodOptional<z.ZodBoolean>;
+            aliases: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>]>>;
         naming: z.ZodOptional<z.ZodObject<{
             routerSuffix: z.ZodOptional<z.ZodDefault<z.ZodString>>;
             procedureCase: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
@@ -403,6 +547,34 @@ declare const ConfigSchema: z.ZodObject<{
 type DrzlConfigInput = z.input<typeof ConfigSchema>;
 type DrzlConfig = z.output<typeof ConfigSchema>;
 declare function defineConfig<T extends DrzlConfigInput>(cfg: T): T;
+/**
+ * Every filename `drzl` will load a config from, in the order it tries them.
+ *
+ * One list because there were two. `computeWatchTargets` carried its own copy of four of these
+ * names, and the copy was missing `drzl.config.json`: a JSON config loaded fine, and then
+ * `drzl watch` never noticed an edit to it, because nothing was watching the file. The watcher's
+ * test spelled the same four names a third time, so it agreed with the bug.
+ */
+declare const CONFIG_FILE_NAMES: readonly ["drzl.config.ts", "drzl.config.mjs", "drzl.config.js", "drzl.config.cjs", "drzl.config.json"];
+/** Where the published schema answers from, and what `$schema` in a config should point at. */
+declare const CONFIG_SCHEMA_ID = "https://use-drzl.github.io/drzl/drzl.config.schema.json";
+/**
+ * `ConfigSchema` as a JSON Schema, for editors pointed at a `drzl.config.json`.
+ *
+ * Two things about `z.toJSONSchema` decide the arguments here, both measured rather than assumed:
+ *
+ *  - `io` defaults to `'output'`, which marks every key carrying a `.default()` as `required`.
+ *    That is four of the nine top-level keys, so the default would produce a schema that flags
+ *    all 32 configs in the docs and every minimal config a reader writes. `'input'` describes
+ *    what a user writes, which is what a config file is.
+ *  - refinements are dropped silently. The only one here is the affix `.superRefine`; its
+ *    character half is carried by the `pattern` annotations on `affixValueSchema`, and its
+ *    collision half cannot be stated in JSON Schema at all and stays a CLI-only error.
+ *
+ * draft-07 rather than 2020-12 because that is the dialect every editor implements fully, and
+ * this schema uses nothing newer.
+ */
+declare function buildConfigJsonSchema(): Record<string, unknown>;
 /**
  * Where the tRPC generator writes.
  *
@@ -419,6 +591,87 @@ declare function trpcOutDir(g: {
 }, cfg: {
     outDir: string;
 }): string;
+/**
+ * Where the Hono generator writes.
+ *
+ * The same rule as the other two routers, and for the same reason: it writes an `index.ts` of its
+ * own, so a config running two router generators has to give at least one of them a `path`.
+ *
+ * Its own function rather than a call to `trpcOutDir`, because these are three separate decisions
+ * that happen to agree today, and a reader following `computeGeneratorOutputDirs` should not have
+ * to work out whether a function named for tRPC is authoritative for Hono.
+ */
+declare function honoOutDir(g: {
+    path?: string;
+}, cfg: {
+    outDir: string;
+}): string;
+/**
+ * Where the Express generator writes.
+ *
+ * The same rule as the other three routers, and for the same reason: it writes an `index.ts` of
+ * its own, so a config running two router generators has to give at least one of them a `path`.
+ *
+ * Its own function rather than a call to one of the others, for the reason `honoOutDir` records:
+ * these are separate decisions that happen to agree today, and a reader following
+ * `computeGeneratorOutputDirs` should not have to work out which router's function is
+ * authoritative for which kind.
+ */
+declare function expressOutDir(g: {
+    path?: string;
+}, cfg: {
+    outDir: string;
+}): string;
+/**
+ * Where the Fastify generator writes.
+ *
+ * The same rule as the other four routers, and for the same reason: it writes an `index.ts` of
+ * its own, so a config running two router generators has to give at least one of them a `path`.
+ *
+ * Its own function rather than a call to one of the others, for the reason `honoOutDir` records:
+ * these are separate decisions that happen to agree today, and a reader following
+ * `computeGeneratorOutputDirs` should not have to work out which router's function is
+ * authoritative for which kind.
+ */
+declare function fastifyOutDir(g: {
+    path?: string;
+}, cfg: {
+    outDir: string;
+}): string;
+/**
+ * Where the NestJS generator writes.
+ *
+ * The same rule as the five routers, though this one emits DTO modules rather than routes: it
+ * still writes an `index.ts` barrel and a `validation.ts` of its own, so a config that runs it
+ * beside a router generator has to give at least one of them a `path`.
+ *
+ * Its own function rather than a call to one of the others, for the reason `honoOutDir` records:
+ * these are separate decisions that happen to agree today, and a reader following
+ * `computeGeneratorOutputDirs` should not have to work out which kind's function is
+ * authoritative for which.
+ */
+declare function nestjsOutDir(g: {
+    path?: string;
+}, cfg: {
+    outDir: string;
+}): string;
+/**
+ * Where the GraphQL generator writes.
+ *
+ * The same rule as the routers and the NestJS kind, though this one emits SDL modules rather
+ * than routes: it still writes an `index.ts` barrel and a `scalars.ts` of its own, so a config
+ * that runs it beside a router generator has to give at least one of them a `path`.
+ *
+ * Its own function rather than a call to one of the others, for the reason `honoOutDir`
+ * records: these are separate decisions that happen to agree today, and a reader following
+ * `computeGeneratorOutputDirs` should not have to work out which kind's function is
+ * authoritative for which.
+ */
+declare function graphqlOutDir(g: {
+    path?: string;
+}, cfg: {
+    outDir: string;
+}): string;
 /**
  * Fill in cross-generator defaults and refuse configs whose generators would disagree.
  *
@@ -440,7 +693,45 @@ declare function resolveConfig(cfg: DrzlConfig): {
     config: DrzlConfig;
     warnings: string[];
 };
-declare function loadConfig(customPath?: string): Promise<DrzlConfig | null>;
+/**
+ * Load a config module fresh from disk: JSON parsed directly, everything else through jiti
+ * with cache-busting, exactly as `loadConfig` always has.
+ *
+ * Extracted so the drizzle-kit interop reads `drizzle.config.ts` through the same loader that
+ * reads `drzl.config.ts`, rather than through a second dependency or a second set of jiti
+ * options that could drift from this one.
+ */
+declare function importFreshConfigModule(p: string): Promise<unknown>;
+/**
+ * The config, or `null` when there is none.
+ *
+ * `onWarn` exists so the config's warnings reach the output layer rather than the process. They
+ * went to `console.warn` until now, which is stderr with no route through `--quiet` or `--json`:
+ * `drzl generate --json` printed them beside the document it promises is the only thing on
+ * stdout's channel, and `--quiet` could not remove them. Item 79 adds a warning to exactly this
+ * path, so the path is fixed here rather than gaining a second writer that bypasses `Output`.
+ *
+ * The default keeps the old behaviour for any caller that has no output layer to hand.
+ */
+declare function loadConfig(customPath?: string, onWarn?: (warning: string) => void): Promise<DrzlConfig | null>;
+/**
+ * A config nobody wrote to a file, built from what the command line said.
+ *
+ * `drzl generate --schema src/db/schema.ts --only orpc` is the config route with the config
+ * inlined, and it is what replaces the two per-kind commands: those took a schema path and a kind
+ * and could reach none of the config's features, because they had no config at all. This produces
+ * a real one, so everything downstream, the filters, the naming, the write plan, `--check`, is the
+ * same code reading the same shape whether the config came from disk or from two flags.
+ *
+ * Through `ConfigSchema` and `resolveConfig` rather than by hand, and that is the whole point: the
+ * defaults a config file gets are applied here too, `importExtension` is pushed down onto each
+ * generator exactly as it is for a file, and a hand-built object that skipped either would emit
+ * different bytes from the equivalent config for no reason a user could see.
+ *
+ * `schema` may be omitted, in which case the drizzle-kit config answers for it, exactly as it does
+ * for a `drzl.config.ts` with no `schema` key.
+ */
+declare function configFromKinds(kinds: readonly GeneratorKind[], schema?: string, onWarn?: (warning: string) => void): DrzlConfig;
 /** Absolute output dirs for all generators (to ignore in watcher). */
 declare function computeGeneratorOutputDirs(cfg: DrzlConfig, cwd?: string): string[];
 /** Resolve custom template directories (local path or installed package). */
@@ -452,13 +743,30 @@ declare function resolveTemplateDirsSync(cfg: DrzlConfig, cwd?: string): string[
  * Matching is on the database table name, anchored, with `*` as the only metacharacter. Anchored
  * matters: `user` must not also drop `users`, and a substring match would. `exclude` is applied
  * after `include`, so the safer direction wins when both name the same table.
+ *
+ * A table also answers to its schema-qualified name, so `reporting.users` addresses one of two
+ * same-named tables and `reporting.*` addresses a whole schema. See `tableAliases`.
  */
 declare function filterTables<T extends {
     name: string;
+    schema?: string;
 }>(tables: T[], opts: {
     include?: string[];
     exclude?: string[];
 }): T[];
-declare function computeWatchTargets(cfg: DrzlConfig, cwd?: string): string[];
+/**
+ * What to warn about the table filter, before it is applied.
+ *
+ * Separate from `filterTables` so that returns a plain array, as every caller and every test
+ * already expects it to.
+ */
+declare function tableFilterWarnings(tables: readonly {
+    name: string;
+    schema?: string;
+}[], opts: {
+    include?: string[];
+    exclude?: string[];
+}): string[];
+declare function computeWatchTargets(cfg: DrzlConfig, cwd?: string, source?: ResolvedSchemaSource): string[];
 
-export { AffixSchema, AnalyzerSchema, ConfigSchema, type DrzlConfig, type DrzlConfigInput, GeneratorSchema, ImportExtensionSchema, NamingSchema, computeGeneratorOutputDirs, computeWatchTargets, defineConfig, filterTables, loadConfig, resolveConfig, resolveTemplateDirsSync, trpcOutDir };
+export { AffixSchema, AnalyzerSchema, CONFIG_FILE_NAMES, CONFIG_SCHEMA_ID, ColumnRulesSchema, ConfigSchema, type DrzlConfig, type DrzlConfigInput, GENERATOR_KINDS, type GeneratorKind, GeneratorKindSchema, GeneratorSchema, ImportExtensionSchema, NamingSchema, buildConfigJsonSchema, computeGeneratorOutputDirs, computeWatchTargets, configFromKinds, defineConfig, expressOutDir, fastifyOutDir, filterTables, graphqlOutDir, honoOutDir, importFreshConfigModule, loadConfig, nestjsOutDir, resolveConfig, resolveTemplateDirsSync, tableFilterWarnings, trpcOutDir };