feat: add --experimental-lazy flag for faster CLI startup in monorepos

Skip loading all source files from all tsconfigs when --experimental-lazy
is passed. Instead, only load the config/schema file that was explicitly
requested. This dramatically reduces startup time in large monorepos.

Benchmarks:
- Synthetic (502 files): 277ms -> 3.3ms (83.8x faster)
- Real monorepo (453 files): 24.51s -> 6.16s (3.98x faster)
- Output is byte-for-byte identical

Author: Alp

src/cli/index.ts

@@ -67,6 +67,7 @@ export interface GeneratorOptions {
   enableLegacyMutators?: boolean;
   enableLegacyQueries?: boolean;
   suppressDefaultsWarning?: boolean;
+  experimentalLazy?: boolean;
 }
 
 async function main(opts: GeneratorOptions = {}) {
@@ -85,6 +86,7 @@ async function main(opts: GeneratorOptions = {}) {
     enableLegacyMutators,
     enableLegacyQueries,
     suppressDefaultsWarning,
+    experimentalLazy,
   } = {...opts};
 
   const resolvedTsConfigPath = tsConfigPath ?? defaultTsConfigFile;
@@ -99,18 +101,21 @@ async function main(opts: GeneratorOptions = {}) {
       '😶‍🌫️  drizzle-zero: Using all tables/columns from Drizzle schema',
     );
   }
-  const allTsConfigPaths = await discoverAllTsConfigs(resolvedTsConfigPath);
 
   const tsProject = new Project({
     tsConfigFilePath: resolvedTsConfigPath,
     skipAddingFilesFromTsConfig: true,
   });
-  for (const tsConfigPath of allTsConfigPaths) {
-    addSourceFilesFromTsConfigSafe({
-      tsProject,
-      tsConfigPath,
-      debug: Boolean(debug),
-    });
+
+  if (!experimentalLazy) {
+    const allTsConfigPaths = await discoverAllTsConfigs(resolvedTsConfigPath);
+    for (const tsConfigPath of allTsConfigPaths) {
+      addSourceFilesFromTsConfigSafe({
+        tsProject,
+        tsConfigPath,
+        debug: Boolean(debug),
+      });
+    }
   }
 
   if (configFilePath) {
@@ -226,6 +231,11 @@ function cli() {
       'Hide warnings for columns with default values',
       false,
     )
+    .option(
+      '--experimental-lazy',
+      'Use lazy file loading for faster startup (only loads files reachable from config)',
+      false,
+    )
     .option(
       '--force',
       'Overwrite the output file even if it has been manually modified',
@@ -250,6 +260,7 @@ function cli() {
         enableLegacyMutators: command.enableLegacyMutators,
         enableLegacyQueries: command.enableLegacyQueries,
         suppressDefaultsWarning: command.suppressDefaultsWarning,
+        experimentalLazy: command.experimentalLazy,
       });
 
       if (command.output) {

tests/benchmark.test.ts

@@ -0,0 +1,77 @@
+import * as path from 'node:path';
+import {Project} from 'ts-morph';
+import {test, expect} from 'vitest';
+import {discoverAllTsConfigs} from '../src/cli/tsconfig';
+import {
+  addSourceFilesFromTsConfigSafe,
+  ensureSourceFileInProject,
+} from '../src/cli/ts-project';
+
+const fixtureRoot = path.resolve(
+  __dirname,
+  'benchmarks/synthetic-monorepo/tsconfig.json',
+);
+const schemaConfigFile = path.resolve(
+  __dirname,
+  'benchmarks/synthetic-monorepo/schema/drizzle-zero.config.ts',
+);
+
+test(
+  'lazy loading loads fewer files and is faster than eager loading',
+  {timeout: 120_000},
+  async () => {
+    // -- EAGER approach: discover all tsconfigs, add all source files --
+    const eagerStart = performance.now();
+
+    const allTsConfigPaths = await discoverAllTsConfigs(fixtureRoot);
+
+    const eagerProject = new Project({
+      tsConfigFilePath: fixtureRoot,
+      skipAddingFilesFromTsConfig: true,
+    });
+
+    for (const tsConfigPath of allTsConfigPaths) {
+      addSourceFilesFromTsConfigSafe({
+        tsProject: eagerProject,
+        tsConfigPath,
+        debug: false,
+      });
+    }
+
+    ensureSourceFileInProject({
+      tsProject: eagerProject,
+      filePath: schemaConfigFile,
+      debug: false,
+    });
+
+    const eagerFileCount = eagerProject.getSourceFiles().length;
+    const eagerTime = performance.now() - eagerStart;
+
+    // -- LAZY approach: only load the config file and resolve its dependencies --
+    const lazyStart = performance.now();
+
+    const lazyProject = new Project({
+      tsConfigFilePath: fixtureRoot,
+      skipAddingFilesFromTsConfig: true,
+    });
+
+    ensureSourceFileInProject({
+      tsProject: lazyProject,
+      filePath: schemaConfigFile,
+      debug: false,
+    });
+
+    const lazyFileCount = lazyProject.getSourceFiles().length;
+    const lazyTime = performance.now() - lazyStart;
+
+    // -- Report --
+    const ratio = eagerTime / lazyTime;
+    console.log(`Eager: ${eagerFileCount} files in ${eagerTime.toFixed(1)}ms`);
+    console.log(`Lazy:  ${lazyFileCount} files in ${lazyTime.toFixed(1)}ms`);
+    console.log(`Ratio: eager is ${ratio.toFixed(2)}x slower than lazy`);
+
+    // -- Assertions --
+    expect(lazyFileCount).toBeLessThan(eagerFileCount);
+    expect(lazyTime).toBeLessThan(eagerTime);
+  },
+);

tests/benchmarks/synthetic-monorepo/pkg-01/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "composite": true,
+    "declaration": true,
+    "outDir": "out"
+  },
+  "include": ["./**/*.ts"]
+}

tests/benchmarks/synthetic-monorepo/pkg-01/types-01.ts

@@ -0,0 +1,125 @@
+// pkg-01 / types-01  (seed 101) - expensive recursive & mapped types
+
+// ── 1. DeepPartial over a large interface ────────────────────────────────────
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+interface BigRecord101 {
+  a101: { x: number; y: string; z: boolean };
+  b101: { p: string[]; q: Record<string, number> };
+  c101: { nested: { deep: { deeper: { deepest: string } } } };
+  d101: number;
+  e101: string;
+  f101: boolean;
+  g101: null;
+  h101: undefined;
+  i101: bigint;
+  j101: symbol;
+}
+
+type PartialBig101 = DeepPartial<BigRecord101>;
+
+// ── 2. Recursive Flatten ─────────────────────────────────────────────────────
+type Flatten101<T> = T extends Array<infer U> ? Flatten101<U> : T;
+type Nested101 = number[][][][][][][][][][];
+type Flat101 = Flatten101<Nested101>;
+
+// ── 3. Deep readonly + required ──────────────────────────────────────────────
+type DeepReadonly101<T> = {
+  readonly [K in keyof T]: T[K] extends object ? DeepReadonly101<T[K]> : T[K];
+};
+type DeepRequired101<T> = {
+  [K in keyof T]-?: T[K] extends object ? DeepRequired101<T[K]> : T[K];
+};
+type FR101 = DeepReadonly101<DeepRequired101<PartialBig101>>;
+
+// ── 4. Large union type (50 members) ─────────────────────────────────────────
+type BigUnion101 =
+  | "alpha" | "bravo" | "charlie" | "delta" | "echo"
+  | "foxtrot" | "golf" | "hotel" | "india" | "juliet"
+  | "kilo" | "lima" | "mike" | "november" | "oscar"
+  | "papa" | "quebec" | "romeo" | "sierra" | "tango"
+  | "uniform" | "victor" | "whiskey" | "xray" | "yankee"
+  | "zulu" | "one" | "two" | "three" | "four"
+  | "five" | "six" | "seven" | "eight" | "nine"
+  | "ten" | "eleven" | "twelve" | "thirteen" | "fourteen"
+  | "fifteen" | "sixteen" | "seventeen" | "eighteen" | "nineteen"
+  | "twenty" | "twentyone" | "twentytwo" | "twentythree" | "twentyfour"
+  | "twentyfive";
+
+type ExtractAlpha101 = Extract<BigUnion101, "alpha" | "bravo" | "charlie">;
+type ExcludeZulu101 = Exclude<BigUnion101, "zulu">;
+
+// ── 5. Mapped type over intersection of interfaces ───────────────────────────
+interface ShapeA101 { width: number; height: number; depth: number }
+interface ShapeB101 { color: string; opacity: number; blend: string }
+interface ShapeC101 { x: number; y: number; z: number; w: number }
+interface ShapeD101 { label: string; title: string; summary: string }
+
+type Combined101 = ShapeA101 & ShapeB101 & ShapeC101 & ShapeD101;
+type OptionalAll101 = { [K in keyof Combined101]?: Combined101[K] };
+type RequiredAll101 = { [K in keyof Combined101]-?: Combined101[K] };
+type ReadonlyAll101 = { readonly [K in keyof Combined101]: Combined101[K] };
+type NullableAll101 = { [K in keyof Combined101]: Combined101[K] | null };
+
+// ── 6. Conditional type chains ───────────────────────────────────────────────
+type IsString101<T> = T extends string ? true : false;
+type IsNumber101<T> = T extends number ? true : false;
+type TypeName101<T> = T extends string
+  ? "string"
+  : T extends number
+  ? "number"
+  : T extends boolean
+  ? "boolean"
+  : T extends null
+  ? "null"
+  : T extends undefined
+  ? "undefined"
+  : T extends symbol
+  ? "symbol"
+  : T extends bigint
+  ? "bigint"
+  : "object";
+
+type TypeNames101 = {
+  [K in keyof BigRecord101]: TypeName101<BigRecord101[K]>;
+};
+
+// ── 7. Template literal type combinations ────────────────────────────────────
+type Verb101 = "get" | "set" | "delete" | "update" | "create" | "list";
+type Resource101 = "user" | "post" | "comment" | "tag" | "category";
+type Action101 = `${Verb101}_${Resource101}`;
+
+// ── 8. Infer in conditional types ────────────────────────────────────────────
+type UnwrapPromise101<T> = T extends Promise<infer U> ? UnwrapPromise101<U> : T;
+type UnwrapArray101<T> = T extends (infer U)[] ? UnwrapArray101<U> : T;
+type Head101<T extends unknown[]> = T extends [infer H, ...infer _] ? H : never;
+type Tail101<T extends unknown[]> = T extends [infer _, ...infer R] ? R : never;
+
+// ── 9. Permutation of union ───────────────────────────────────────────────────
+type Permutation101<T, K = T> = [T] extends [never]
+  ? []
+  : K extends K
+  ? [K, ...Permutation101<Exclude<T, K>>]
+  : never;
+
+type SmallUnion101 = "a" | "b" | "c" | "d";
+type AllPerms101 = Permutation101<SmallUnion101>;
+
+// ── 10. Re-export to force inclusion ─────────────────────────────────────────
+export type {
+  PartialBig101,
+  Flat101,
+  FR101,
+  BigUnion101,
+  ExtractAlpha101,
+  ExcludeZulu101,
+  OptionalAll101,
+  RequiredAll101,
+  ReadonlyAll101,
+  NullableAll101,
+  TypeNames101,
+  Action101,
+  AllPerms101,
+};