elysia 1.4.28 → 2.0.0-beta.0

package/dist/plugin/aot/core.d.ts

@@ -0,0 +1,291 @@
+import { JITProbeResult } from "../../compile/jit-probe.js";
+import { AotTarget } from "./source.js";
+
+//#region src/plugin/aot/core.d.ts
+interface ElysiaAotOptions {
+  /**
+   * Specifier the generated module imports `Compiled` from
+   * Must resolve to the same `elysia` instance the app runs
+   *
+   * @default 'elysia'
+   */
+  registerFrom?: string;
+  /**
+   * Specifier the generated module imports the `Reconstruct` table from.
+   * Pure so any elysia copy works (registration goes through `Compiled`)
+   *
+   * @default 'elysia/reconstruct'
+   */
+  reconstructFrom?: string;
+  /**
+   * Split the emitted validator manifest into lazily-materialized groups
+   *
+   * Validator entries are registered as grouped thunks: a group's
+   * validators are constructed on the first request to any route in that
+   * group, trading first-request latency in unbuilt groups for lower
+   * startup cost. Handlers are always eager. Only validator construction
+   * is deferred. Pass a number to set the group size explicitly.
+   *
+   * @default decided by Elysia based on route batch scale
+   */
+  lazy?: boolean | number;
+  /**
+   * Deploy target for build-time-baked codegen consts (the response-header
+   * path). Set `target: 'workerd'` to build under Bun yet ship a manifest
+   * valid on Cloudflare Workers / Node.
+   *
+   * When set to an unambiguous runtime (`'bun'` or `'node'`/`'workerd'`),
+   * the plugin also aliases `adapter/constants` so that only the matching
+   * adapter ships in the bundle (the other one DCEs). When `target` is
+   * absent the runtime `isBun` check is preserved unchanged.
+   *
+   * @default the build runtime
+   */
+  target?: AotTarget;
+  /**
+   * Replace `import { t } from 'elysia'` with `import * as t from 'elysia/type'`
+   * at build time so unused TypeBox constructors tree-shake
+   *
+   * @default true
+   */
+  treeShake?: boolean;
+  /**
+   * Replace the internal handler compiler with a throwing stub so the bundler
+   * can drop the handler-JIT graph
+   *
+   * This is only safe when every route is reconstructed from the frozen AOT
+   * handler manifest. The plugin verifies that by replaying a frozen build and
+   * watching whether handler JIT is reached
+   *
+   * - `'auto'` (default): stub only when the frozen replay proves handler JIT
+   *   is unused. Skip if any route still reaches handler JIT
+   * - `true`: require a fully precompiled handler manifest and throw if any
+   *   route still reaches handler JIT
+   * - `false`: never stub
+   *
+   * @default 'auto'
+   */
+  strip?: boolean | 'auto';
+  /**
+   * Treat this as a production build, making `isProduction` a compile-time
+   * constant `true` so bundlers can DCE `!isProduction()` branches.
+   *
+   * - `true` (default): stub `isProduction` as `() => true` so dev-verbose
+   *   error paths tree-shake
+   * - `false`: leave `isProduction` as a runtime env read (preserves dev
+   *   behaviour in the bundle)
+   *
+   * @default true
+   */
+  production?: boolean;
+  /**
+   * Log one detail line per affected route when a sealed validator carries
+   * a coercion/codec schema (its 422 error detail can only name the
+   * offending field coarsely, best-effort).
+   *
+   * - `false` (default): collapse all affected routes into a single
+   *   build-end summary line (none if no route is affected)
+   * - `true`: also print the per-route detail line as each one is found
+   *
+   * @default false
+   */
+  verbose?: boolean;
+}
+declare const resolveEntry: (entry: string) => string;
+/** Runtime handler-JIT module a strip build can replace with a throwing stub. */
+interface StubPlan {
+  /** Stub the internal handler codegen module. */
+  jit: boolean;
+  /** Stub internal WS route builders when the app declares no WS routes. */
+  ws: boolean;
+  /**
+   * Stub frozen-handler reconstruction (validator `va`, cookie `cc`, trace `tr`)
+   * when no replayed handler aliases any of them.
+   */
+  reconstruct: boolean;
+  /**
+   * Stub the request-side cookie machinery (parse / jar / signing in
+   * `cookie/utils` + `cookie/config`) when no replayed handler aliases the
+   * cookie config (`cc`)
+   */
+  cookie: boolean;
+  /**
+   * Stub the trace runtime (`trace.ts` `createTracer` + recorder machinery)
+   * when no replayed handler aliases trace (`tr`), or even under live
+   * handler JIT when the app registers no trace handler at all (`~hasTrace`
+   * + history sweep; a mount forbids it). Every call site (fetch, JIT
+   * codegen, frozen reconstruct) only calls in when trace handlers exist, so
+   * a throwing stub is unreachable once detection proves trace is unused
+   *
+   * NOT moot after the `elysia/trace` capability severance. The reachable
+   * post-severance case is: an app that `.use(trace())` (so the capability
+   * is registered and `dist/trace.mjs` IS in the bundle graph via
+   * `dist/plugin/trace.mjs`) but never attaches `.trace(fn)` (no trace
+   * hooks, so `tr` is unaliased and `mayTrace` is false). Under the frozen
+   * path (`jit`) this flag is still `true`, so the stub replaces the real
+   * trace module with the non-throwing `unionTracePhases(){return new Set()}`
+   * fallback (+ throwing `createTracer`, unreachable with zero hooks).
+   * Measured saving for that shape: ~18KB severing trace also tree-shakes
+   * sucrose's `separateFunction`, which trace is the sole importer of. A
+   * traceless app that never imports the capability (Fixture B) has no
+   * trace module in the graph, so the stub is a no-op there.
+   */
+  trace: boolean;
+  /**
+   * Stub the `memory` module's `clearSucroseCache` edge when handler JIT is
+   * stubbed. Sucrose never runs in a precompiled app, so its caches are always
+   * empty and the flush is a no-op. Dropping the import lets the Sucrose
+   * analyzer tree-shake. `flushMemory`'s other clears are preserved, and the
+   * public `elysia/sucrose` module is left untouched
+   */
+  sucrose: boolean;
+  /**
+   * Stub `type/compat` so `setupTypebox` becomes a no-op, un-wiring the
+   * TypeBox bridge from the bundle. Set in BOTH sealed (mode A) and wired
+   * (mode B) builds. In mode A the bridge is severed entirely. Every captured
+   * validator is bridge-free so nothing reaches it. In mode B the mirror
+   * (`bridge` → `bridge-live` reroute) replaces the latch, so `setupTypebox`
+   * must still be a no-op to guarantee the bridge is wired exactly once
+   */
+  compat: boolean;
+  /**
+   * Re-route `type/bridge` → `type/bridge-live` (the statically-wired mirror)
+   * so the bridge exports resolve to real TypeBox members without the runtime
+   * `setupTypebox` latch. Set only in the wired build (mode B): the app has at
+   * least one validator that is not bridge-free, so the bridge is still needed
+   */
+  bridge: boolean;
+  /**
+   * Replace `adapter/constants` with a target-specific stub that hard-selects
+   * either `BunAdapter` or `WebStandardAdapter`, letting the bundler DCE the
+   * other adapter. Only set when `target` unambiguously implies a runtime
+   * (`'bun'` → Bun; `'node'`/`'workerd'` → WebStandard). When `target` is
+   * absent or ambiguous this is `false` and the runtime `isBun` path is kept.
+   */
+  adapter: 'bun' | 'web-standard' | false;
+  /**
+   * Replace `universal/is-production` with a stub that returns `true` at
+   * compile time so bundlers can DCE `!isProduction()` branches. Set when
+   * `production: true` (the default for plugin builds).
+   */
+  isProduction: boolean;
+}
+/**
+ * Chosen TypeBox-collapse strategy for the build, logged in the dry-run line.
+ *
+ * - `'sealed'` (mode A): every captured validator is bridge-free (HTTP and WS
+ *   alike) and the app is fully stripped (handler JIT unused). `compat` is
+ *   stubbed and the bridge is severed, TypeBox collapses entirely
+ * - `'wired'` (mode B): at least one validator still needs the bridge. `compat`
+ *   is stubbed AND the bridge is re-routed to the statically-wired mirror so it
+ *   works without the DCE-fragile `setupTypebox()` anchor
+ * - `'off'`: no bridge action (strip disabled, or handler JIT still reachable,
+ *   the frozen path is not active so the bridge stays wired the normal way)
+ */
+type BridgeMode = 'sealed' | 'wired' | 'off';
+declare const NO_STUB: StubPlan;
+/**
+ * Resolve whether handler JIT is safe to stub for `entry`, honouring the
+ * `strip` option. `'auto'` stubs only when detection proves handler JIT unused;
+ * `true` throws when handler JIT is still reachable; `false` disables.
+ *
+ * Also decides the TypeBox-collapse `mode`:
+ * - `'sealed'`: the frozen path is active (`jit`) and EVERY captured
+ *   validator, HTTP and WS is bridge-free (`bridgeFree`). `setupTypebox` is
+ *   stubbed and the bridge is severe, nothing reaches it, TypeBox collapses.
+ * - `'wired'`: the frozen path is active but at least one validator
+ *   still needs the bridge. `setupTypebox` is stubbed AND the bridge is
+ *   re-routed to the statically-wired mirror (works without the DCE-fragile
+ *   `setupTypebox()` anchor).
+ * - `'off'`: handler JIT still reachable (or strip disabled). The frozen path
+ *   is not active, so the bridge must stay wired the ordinary way. No compat
+ *   stub, no reroute.
+ */
+declare function planFromReport(strip: boolean | 'auto', report: JITProbeResult, hasWS: boolean, mayTrace: boolean, aliases: Set<string>, allBridgeFree: boolean, zeroCapture: boolean, adapterStub?: 'bun' | 'web-standard' | false, productionStub?: boolean): {
+  plan: StubPlan;
+  mode: BridgeMode;
+};
+declare function adapterConstantsSource(target: 'bun' | 'web-standard'): string;
+/** Filter matching elysia's own `adapter/constants` module (src + dist). */
+declare const ADAPTER_CONSTANTS_FILTER: RegExp;
+declare const ADAPTER_BUN_FILTER: RegExp;
+declare const IS_PRODUCTION_FILTER: RegExp;
+/**
+ * Loose fallback filter
+ *
+ * Matches the `/elysia/(dist|src)/` segment anywhere in a path (node_modules layouts,
+ * monorepos, linked installs). Used by esbuild as a broad pre-filter
+ *
+ * The caller must further check that the path is under the resolved elysia package root
+ * to avoid matching user code in a directory that happens to be named "elysia"
+ *
+ * @internal
+ */
+declare const ELYSIA_MODULE_FILTER: RegExp;
+/**
+ * Build a predicate that returns `true` only for modules that are under the
+ * resolved elysia package root (i.e. actually elysia's own files).
+ *
+ * Anchoring to the real package root prevents user projects rooted in a
+ * directory named `elysia` (like this repo itself) from having their code
+ * rewritten.
+ *
+ * Pass the result to both the esbuild `filter` (convert to RegExp via
+ * `makeElysiaModuleFilterRegex`) and the Vite transform (`isElysiaModule`).
+ */
+declare function resolveElysiaRoot(from?: string): string;
+/**
+ * Returns a predicate that is `true` only when the given module path is under
+ * the resolved elysia package root AND matches the broad module filter.
+ */
+declare function makeIsElysiaModule(elysiaRoot: string): (path: string) => boolean;
+/**
+ * Build an esbuild-compatible RegExp that anchors to the resolved elysia root
+ * so the `onLoad` pre-filter is as tight as possible. esbuild uses this as an
+ * initial path filter before calling the callback, so we still double-check
+ * with `makeIsElysiaModule` inside the callback.
+ */
+declare function makeElysiaModuleFilterRegex(elysiaRoot: string): RegExp;
+declare function rewriteIsProductionCalls(code: string): string;
+declare const bunAdapterStubSource: string;
+declare const STUB_SOURCES: Record<Exclude<keyof StubPlan, 'adapter' | 'isProduction'>, Array<{
+  filter: RegExp;
+  source: string;
+}>>;
+declare const alignStubExtensions: (stubSource: string, targetPath: string) => string;
+declare const OVERRIDE_MAP: Record<string, {
+  leaf: string;
+  export: string;
+}>;
+declare function generateVirtualType(typeSpecifier?: string): Promise<string>;
+interface CompiledArtifacts {
+  source: string;
+  /** Handler-JIT modules detection proved safe to stub for this app. */
+  stub: StubPlan;
+  /** Chosen TypeBox-collapse strategy (`sealed` / `wired` / `off`). */
+  mode: BridgeMode;
+  /**
+   * Virtual `elysia/type` module source (re-export surface, no `setupTypebox`).
+   * Served for `elysia/type` in both sealed and wired modes so unused `t.*`
+   * constructors tree-shake. `undefined` when the bridge is left wired (`off`).
+   */
+  virtualType?: string;
+}
+/** @internal Test diagnostic for deterministic worker cleanup. */
+declare const getAotWorkerDiagnostics: () => {
+  activeWorkers: number;
+  lastExit: Promise<number> | undefined;
+};
+/**
+ * Extension mirroring the running module's own build output, so a sibling
+ * source file can be resolved from `import.meta.url` in `.mjs`/`.js`/`.ts`
+ * builds alike.
+ */
+declare function siblingModuleExt(moduleUrl: string): '.mjs' | '.js' | '.ts';
+/** @internal Re-evaluate an entry in a disposable worker for watch rebuilds. */
+declare function generateCompiledArtifactsIsolated(file: string, options?: ElysiaAotOptions): Promise<CompiledArtifacts>;
+declare function generateCompiledArtifacts(file: string, options?: ElysiaAotOptions): Promise<CompiledArtifacts>;
+declare const SOURCE_REGEX: RegExp;
+declare const realPath: (path: string) => string;
+//#endregion
+export { ADAPTER_BUN_FILTER, ADAPTER_CONSTANTS_FILTER, BridgeMode, CompiledArtifacts, ELYSIA_MODULE_FILTER, ElysiaAotOptions, IS_PRODUCTION_FILTER, NO_STUB, OVERRIDE_MAP, SOURCE_REGEX, STUB_SOURCES, StubPlan, adapterConstantsSource, alignStubExtensions, bunAdapterStubSource, generateCompiledArtifacts, generateCompiledArtifactsIsolated, generateVirtualType, getAotWorkerDiagnostics, makeElysiaModuleFilterRegex, makeIsElysiaModule, planFromReport, realPath, resolveElysiaRoot, resolveEntry, rewriteIsProductionCalls, siblingModuleExt };