typescript-monorepo-large-file-split

Answer

Layout — the original file stays at its exact path as a 1-line bridge; a new sibling directory holds 10 cohesive submodules + a barrel:

src/services/
  GenerationExecutor.ts              # ← ORIGINAL PATH, now a 1-line bridge
  GenerationExecutor/
    index.ts                         # barrel: re-exports ONLY the public API
    types.ts                         # public + internal types
    config.ts                        # constants / defaults (DEFAULT_BATCH_SIZE, MAX_RETRIES…)
    state.ts                         # internal state factory (pure, takes context)
    validation.ts                    # validateOptions + input guards
    queue.ts                         # batching / job-queue primitives
    execution.ts                     # the GenerationExecutor class itself (core run loop)
    retry.ts                         # computeBackoff, scheduleRetry
    cache.ts                         # cache layer
    metrics.ts                       # counters / telemetry
    events.ts                        # event-emitter helpers

1. Bridge (original file, 1 line — keep it, do not delete it):

// src/services/GenerationExecutor.ts
export * from "./GenerationExecutor/index.js";

Why a bridge and not a directory-only replacement: moduleResolution: "bundler" substitutes .js → .ts for the same basename (GenerationExecutor.js → GenerationExecutor.ts) but never falls back to <name>/index.ts for a .js-suffixed specifier. I verified this — with only GenerationExecutor/index.ts present, import "./GenerationExecutor.js" fails with TS2307: Cannot find module. Keeping the file at the original path means every external importer stays byte-identical.

2. Barrel (public API only — never export * here):

// src/services/GenerationExecutor/index.ts
export { GenerationExecutor } from "./execution.js";
export type { GenerationExecutorOptions, GenerationResult } from "./types.js";

Explicit named re-exports are mandatory. export * would leak internal helpers/types into the public surface and produce TS2308 collisions if two submodules export the same name. The bridge's export * is safe precisely because the barrel is a curated allowlist.

3. Submodules — the class definition moves wholesale into execution.ts (all this.* methods, private fields, overloads stay in one class body); every private helper/const/type moves to its cohesive home and is imported by siblings with .js specifiers:

// src/services/GenerationExecutor/execution.ts
import type { GenerationExecutorOptions, GenerationResult, InternalState } from "./types.js";
import { DEFAULT_BATCH_SIZE, MAX_RETRIES } from "./config.js";
import { buildState } from "./state.js";
import { validateOptions } from "./validation.js";
import { createQueue } from "./queue.js";
import { computeBackoff } from "./retry.js";
import { cacheGet, cacheSet } from "./cache.js";
import { emitMetrics } from "./metrics.js";

export class GenerationExecutor {
  // …unchanged 30-method body moved here verbatim…
}

Import graph is acyclic: types → config → state/validation/queue/retry/cache/metrics/events → execution. The class holds all mutable this state; helpers are pure or take a context/state object, so no circular imports are introduced. Top-level side effects (e.g., metric registration) live in exactly one designated submodule (metrics.ts) imported first by the barrel, preserving initialization order.