@web-ts-toolkit/express-runtime 0.25.0 → 0.27.0

package/cli-api.d.ts

@@ -0,0 +1,237 @@
+import { Response, Express } from 'express';
+import { LocalServerOptions } from './index.js';
+import 'node:http';
+import 'serverless-http';
+
+/**
+ * Version placeholder rewritten at publish time by `@repo-toolkit/publish-package`.
+ */
+declare const CLI_VERSION = "0.0.0-PLACEHOLDER";
+/**
+ * Read the next argv value after a flag, throwing if it is missing or looks
+ * like another flag.
+ */
+declare function readValue(argv: string[], index: number, name: string): string;
+type Subcommand = 'dev' | 'build' | 'start' | 'build-serverless' | 'start-serverless';
+interface DevArgs {
+    appPath: string;
+    options: Omit<LocalServerOptions, 'init' | 'onShutdown'>;
+    /** Modules to preload before loading the app (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the app (repeatable `--env`). */
+    env: string[];
+    /** Directories to watch for changes (repeatable `--watch`). */
+    watch: string[];
+    /** File extensions to watch (default: ts,js,mjs,cjs,json). */
+    watchExt: string[];
+    /** Debounce delay (ms) before restarting on file change (default: 500). */
+    watchDelay: number;
+}
+interface BuildArgs {
+    appPath: string;
+    initPath?: string;
+    outDir: string;
+    outName: string;
+    format: 'cjs' | 'esm';
+    target: string;
+    external: string[];
+    clean: boolean;
+}
+interface BuildEntryContentArgs {
+    entryContent: string;
+    tempEntryFilename: string;
+    outDir: string;
+    outName: string;
+    format: 'cjs' | 'esm';
+    target: string;
+    external: string[];
+    clean: boolean;
+}
+interface StartArgs {
+    appPath: string;
+    options: Omit<LocalServerOptions, 'onShutdown'>;
+    /** Modules to preload before loading the app bundle (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the app bundle (repeatable `--env`). */
+    env: string[];
+}
+interface StartServerlessArgs {
+    handlerPath: string;
+    options: Omit<LocalServerOptions, 'init' | 'onShutdown'>;
+    /** Modules to preload before loading the handler (repeatable `--require`). */
+    require: string[];
+    /** Env files to load before loading the handler (repeatable `--env`). */
+    env: string[];
+}
+type ParsedArgs = {
+    subcommand: 'dev';
+    dev: DevArgs;
+} | {
+    subcommand: 'build';
+    build: BuildArgs;
+} | {
+    subcommand: 'build-serverless';
+    buildServerless: BuildArgs;
+} | {
+    subcommand: 'start';
+    start: StartArgs;
+} | {
+    subcommand: 'start-serverless';
+    startServerless: StartServerlessArgs;
+} | null;
+declare function printHelp(): void;
+declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Type-guard: an Express app is a function with `listen` and `use` methods.
+ */
+declare function isExpressApp(x: unknown): x is Express;
+/**
+ * Extract the primary export from a loaded module: prefer `default`, fall back
+ * to a named `app`.
+ */
+declare function extractExport(mod: Record<string, unknown>): unknown;
+/**
+ * Resolve a raw export into an Express app, awaiting an async factory if
+ * needed. Throws with a friendly message on incompatible exports.
+ */
+declare function resolveExport(exported: unknown, appPath: string): Promise<Express>;
+/**
+ * Dynamically import a module and resolve its primary export to an Express app.
+ */
+declare function loadApp(appPath: string): Promise<Express>;
+/**
+ * Parse env file content as KEY=VALUE lines. Supports `export` prefix,
+ * single/double-quoted values, and `#` comments. Returns parsed entries.
+ *
+ * Exported for direct unit testing.
+ */
+declare function parseEnvFile(content: string): Record<string, string>;
+/**
+ * Load env files into `process.env`. Existing environment variables are
+ * **not** overridden (consistent with dotenv's default behavior). Missing
+ * files throw with a friendly message.
+ *
+ * Exported for direct unit testing.
+ */
+declare function loadEnvFiles(paths: string[]): void;
+/**
+ * Preload modules (e.g. `tsconfig-paths/register`, `dotenv/config`) before
+ * loading the app module. Each module is `require()`-ed, running its
+ * side effects (registering hooks, loading configs, etc.).
+ *
+ * Exported for direct unit testing.
+ */
+declare function preloadModules(modules: string[]): Promise<void>;
+/**
+ * Reconstruct the argv for the child process, stripping --watch/--ext/--delay
+ * flags (the child runs without watch mode).
+ *
+ * Exported for direct unit testing.
+ */
+declare function buildChildArgs(args: DevArgs): string[];
+/**
+ * Run the CLI in watch mode. Forks a child process running the same CLI
+ * without --watch, watches the specified paths for file changes, and
+ * restarts the child (SIGTERM → respawn) on changes matching the given
+ * extensions. Uses Node 20+'s `fs.watch` with `{ recursive: true }`.
+ */
+declare function runWithWatch(args: DevArgs): void;
+type RuntimeModuleInit = () => Promise<void> | void;
+/**
+ * Generate the temporary entry file content that wires the user's app and
+ * optional init hook into a serverless handler.
+ *
+ * Exported for direct unit testing.
+ */
+declare function generateServerlessEntry(appPath: string, initPath?: string): string;
+/**
+ * Generate the temporary entry file content that wires the user's app and
+ * optional init hook into a local runtime bundle.
+ *
+ * Exported for direct unit testing.
+ */
+declare function generateRuntimeEntry(appPath: string, initPath?: string): string;
+declare function buildBundleFromEntryContent(args: BuildEntryContentArgs): Promise<void>;
+/**
+ * Bundle an Express app as a local runtime module. The output default-exports
+ * the app and may additionally export an `init` hook for the `start` command.
+ */
+declare function buildRuntime(args: BuildArgs): Promise<void>;
+/**
+ * Bundle an Express app as a serverless handler. Writes a temporary entry file
+ * to the user's cwd (for node_modules resolution), lazy-loads the bundled
+ * build tool, then cleans up.
+ *
+ * `express` is always external; additional externals can be passed via
+ * `BuildArgs.external`.
+ */
+declare function buildServerless(args: BuildArgs): Promise<void>;
+/**
+ * A platform-agnostic serverless handler function (the output of
+ * `build-serverless`).
+ */
+type GenericHandler = (event: unknown, context: unknown) => Promise<unknown>;
+/**
+ * The result shape returned by `serverless-http` (and the `build` output).
+ */
+interface ServerlessResult {
+    statusCode?: number;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: string;
+    isBase64Encoded?: boolean;
+}
+/**
+ * Build a serverless event from HTTP request components.
+ *
+ * Exported for direct unit testing.
+ */
+declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): Record<string, unknown>;
+/**
+ * Write a serverless handler result to an Express response.
+ *
+ * Exported for direct unit testing.
+ */
+declare function applyServerlessResult(result: unknown, res: Response): void;
+/**
+ * Create an Express app that proxies all requests to a serverless handler.
+ * Each HTTP request is translated into a serverless event, the handler is
+ * invoked, and the result is written back to the response.
+ *
+ * Express body parsers are disabled; the raw request body is read directly
+ * from the stream and passed as a Buffer (so the serverless handler's request
+ * hook — including the #305 workaround — works identically to production).
+ */
+declare function createServerlessAdapterApp(handler: GenericHandler): Express;
+/**
+ * Load a bundled app module from the `build` output.
+ */
+declare function loadBuiltApp(appPath: string): Promise<{
+    app: Express;
+    init?: RuntimeModuleInit;
+}>;
+/**
+ * Load a bundled serverless handler from a JS/CJS module. The module must
+ * export a `handler` function (or use `default` export).
+ */
+declare function loadHandler(handlerPath: string): Promise<GenericHandler>;
+
+type RuntimeCliCommand = Exclude<ParsedArgs, null>;
+interface DevCommandRunner<TLoaded> {
+    load: (appPath: string) => Promise<TLoaded> | TLoaded;
+    start: (loaded: TLoaded, options: DevArgs['options'] & {
+        exitAfterShutdown: true;
+    }) => void;
+    watch?: (args: DevArgs) => void;
+}
+interface BuildEntryCommandOptions {
+    generateEntry: (appPath: string, initPath?: string) => string;
+    tempEntryFilename: string;
+    allowInit?: boolean;
+    initErrorMessage?: string;
+}
+declare function runDevCommand<TLoaded>(args: DevArgs, runner: DevCommandRunner<TLoaded>): Promise<void>;
+declare function runExpressDevCommand(args: DevArgs): Promise<void>;
+declare function runBuildEntryCommand(args: BuildArgs, options: BuildEntryCommandOptions): Promise<void>;
+declare function runCliCommand(parsedArgs: RuntimeCliCommand): Promise<void>;
+
+export { type BuildArgs, type BuildEntryCommandOptions, type BuildEntryContentArgs, CLI_VERSION, type DevArgs, type DevCommandRunner, type GenericHandler, type ParsedArgs, type RuntimeCliCommand, type RuntimeModuleInit, type ServerlessResult, type StartArgs, type StartServerlessArgs, type Subcommand, applyServerlessResult, buildBundleFromEntryContent, buildChildArgs, buildRuntime, buildServerless, createServerlessAdapterApp, extractExport, generateRuntimeEntry, generateServerlessEntry, isExpressApp, loadApp, loadBuiltApp, loadEnvFiles, loadHandler, parseArgs, parseEnvFile, preloadModules, printHelp, readValue, resolveExport, runBuildEntryCommand, runCliCommand, runDevCommand, runExpressDevCommand, runWithWatch, toServerlessEvent };