@lithia-js/core 1.0.0-canary.2 → 1.0.0-canary.21

package/dist/index.mjs

@@ -0,0 +1,856 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { randomUUID } from 'crypto';
+import { parentPort } from 'worker_threads';
+import busboy from 'busboy';
+import { parse, serialize } from 'cookie';
+import { statSync, createReadStream } from 'fs';
+import { join } from 'path';
+import { logger } from '@lithia-js/utils';
+
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+
+// src/errors/base.ts
+var LithiaError = class extends Error {
+  isLithiaError = true;
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var LithiaClientError = class extends LithiaError {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+  timestamp = /* @__PURE__ */ new Date();
+};
+var LithiaEventError = class extends LithiaError {
+  constructor(message, eventName, details) {
+    super(message);
+    this.eventName = eventName;
+    this.details = details;
+  }
+  timestamp = /* @__PURE__ */ new Date();
+};
+
+// src/errors/app/client.ts
+var BadRequestError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 400, d);
+  }
+};
+var UnauthorizedError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 401, d);
+  }
+};
+var ForbiddenError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 403, d);
+  }
+};
+var RouteNotFoundError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 404, d);
+  }
+};
+var NotFoundError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 404, d);
+  }
+};
+var ConflictError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 409, d);
+  }
+};
+
+// src/errors/app/server.ts
+var InternalServerError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 500, d);
+  }
+};
+var ServiceUnavailableError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 503, d);
+  }
+};
+var GatewayTimeoutError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 504, d);
+  }
+};
+
+// src/errors/internal/context.ts
+var NotInLithiaContextError = class extends LithiaError {
+  constructor() {
+    super("Lithia hooks must be used within a managed invocation.");
+  }
+};
+var DependencyNotInitializedError = class extends LithiaError {
+  constructor(dependencyName) {
+    super(`Dependency '${dependencyName}' not initialized. Check _app.ts.`);
+  }
+};
+var NotInEventContextError = class extends NotInLithiaContextError {
+};
+var NotInRequestContextError = class extends NotInLithiaContextError {
+};
+
+// src/context/event-context.ts
+var CONTEXT_GLOBAL_KEY = /* @__PURE__ */ Symbol.for("lithia.event_context.v1");
+function getGlobalStore() {
+  const globalAny = globalThis;
+  if (!globalAny[CONTEXT_GLOBAL_KEY]) {
+    globalAny[CONTEXT_GLOBAL_KEY] = new AsyncLocalStorage();
+  }
+  return globalAny[CONTEXT_GLOBAL_KEY];
+}
+var eventContextStore = getGlobalStore();
+function getEventContext() {
+  const ctx = eventContextStore.getStore();
+  if (!ctx) {
+    throw new NotInEventContextError();
+  }
+  return ctx;
+}
+
+// src/hooks/event-hooks.ts
+function useData() {
+  return getEventContext().data;
+}
+function useSocket() {
+  return getEventContext().socket;
+}
+function useEvent() {
+  return getEventContext().event;
+}
+var LITHIA_CONTEXT_KEY = /* @__PURE__ */ Symbol.for("lithia.base_context.v1");
+function getGlobalLithiaStore() {
+  const globalAny = globalThis;
+  if (!globalAny[LITHIA_CONTEXT_KEY]) {
+    globalAny[LITHIA_CONTEXT_KEY] = new AsyncLocalStorage();
+  }
+  return globalAny[LITHIA_CONTEXT_KEY];
+}
+var lithiaContextStore = getGlobalLithiaStore();
+function getLithiaContext() {
+  const ctx = lithiaContextStore.getStore();
+  if (!ctx) {
+    throw new NotInLithiaContextError();
+  }
+  return ctx;
+}
+
+// src/hooks/lithia-hooks.ts
+function provide(key, value) {
+  const { container } = getLithiaContext();
+  container.set(key, value);
+}
+function useDependency(key) {
+  const { container } = getLithiaContext();
+  if (!container.has(key)) {
+    const name = typeof key === "function" ? key.name : String(key);
+    throw new DependencyNotInitializedError(name);
+  }
+  return container.get(key);
+}
+function useOptionalDependency(key) {
+  const { container } = getLithiaContext();
+  return container.get(key);
+}
+function ensureCloneableTaskArgs(taskId, args) {
+  try {
+    structuredClone(args);
+  } catch (error) {
+    throw new Error(
+      `[task:${taskId}] Task arguments could not be cloned for worker dispatch.`,
+      { cause: error }
+    );
+  }
+}
+function createTaskError(payload) {
+  const error = new Error(payload.message, { cause: payload.cause });
+  error.name = payload.name;
+  if (payload.stack) {
+    error.stack = payload.stack;
+  }
+  return error;
+}
+function postTaskInvocation(taskId, args, options) {
+  ensureCloneableTaskArgs(String(taskId), args);
+  parentPort?.postMessage({
+    type: "invoke",
+    taskId,
+    async: options.async,
+    requestId: options.requestId,
+    executionId: options.executionId,
+    args,
+    source: options.source,
+    attempt: 0
+  });
+  return {
+    taskId: String(taskId),
+    executionId: options.executionId,
+    source: options.source
+  };
+}
+async function executeTask(taskId, ...args) {
+  if (!parentPort) {
+    throw new Error(
+      "Async task invocations can only be used within a Lithia managed instance."
+    );
+  }
+  const requestId = randomUUID();
+  const executionId = randomUUID();
+  return new Promise((resolve, reject) => {
+    const handler = (msg) => {
+      if (msg.requestId === requestId) {
+        cleanup();
+        if (msg.type === "invoke_success") {
+          resolve(msg.result);
+        } else {
+          reject(createTaskError(msg.error));
+        }
+      }
+    };
+    const closeHandler = () => {
+      cleanup();
+      reject(
+        new Error(
+          `[task:${String(taskId)}] Worker thread closed before task execution could complete.`
+        )
+      );
+    };
+    const cleanup = () => {
+      parentPort?.off("message", handler);
+      parentPort?.off("close", closeHandler);
+    };
+    parentPort?.on("message", handler);
+    parentPort?.on("close", closeHandler);
+    postTaskInvocation(taskId, args, {
+      async: false,
+      requestId,
+      executionId,
+      source: "ON_DEMAND"
+    });
+  });
+}
+function dispatchTask(taskId, ...args) {
+  if (!parentPort) {
+    throw new Error(
+      "Async task invocations can only be used within a Lithia managed instance."
+    );
+  }
+  return postTaskInvocation(taskId, args, {
+    async: true,
+    executionId: randomUUID(),
+    source: "ON_DEMAND"
+  });
+}
+async function runTask(taskId, ...args) {
+  return executeTask(taskId, ...args);
+}
+function runTaskAsync(taskId, ...args) {
+  return dispatchTask(taskId, ...args);
+}
+var ROUTE_CONTEXT_KEY = /* @__PURE__ */ Symbol.for("lithia.route_context.v1");
+function getGlobalRouteStore() {
+  const globalAny = globalThis;
+  if (!globalAny[ROUTE_CONTEXT_KEY]) {
+    globalAny[ROUTE_CONTEXT_KEY] = new AsyncLocalStorage();
+  }
+  return globalAny[ROUTE_CONTEXT_KEY];
+}
+var routeContextStore = getGlobalRouteStore();
+function getRouteContext() {
+  const ctx = routeContextStore.getStore();
+  if (!ctx) {
+    throw new NotInRequestContextError();
+  }
+  return ctx;
+}
+
+// src/hooks/route-hooks.ts
+function useRequest() {
+  return getRouteContext().req;
+}
+function useResponse() {
+  return getRouteContext().res;
+}
+function useRoute() {
+  return getRouteContext().route;
+}
+function usePathname() {
+  return getRouteContext().req.pathname;
+}
+function useParams() {
+  return getRouteContext().req.params;
+}
+function useQuery() {
+  return getRouteContext().req.query;
+}
+function useHeaders() {
+  return getRouteContext().req.headers;
+}
+function useSocketServer() {
+  return getRouteContext().socketServer;
+}
+var LithiaRequest = class {
+  /**
+   * Creates a request wrapper for the current HTTP transaction.
+   *
+   * The constructor captures headers, reconstructs a best-effort absolute URL,
+   * normalizes the HTTP method to uppercase, and initializes parsed query and
+   * route-param containers for later middleware and handler use.
+   *
+   * @param {IncomingMessage} req - Raw Node.js request object received by the
+   * HTTP server.
+   * @param {{ maxBodySize?: number }} opts - Per-request parsing options used
+   * when consuming the request body stream.
+   */
+  constructor(req, opts) {
+    this.req = req;
+    this.opts = opts;
+    this.headers = req.headers;
+    const isSecure = this.isSecure();
+    const host = this.headers.host || req.headers.host || "unknown";
+    const fullUrl = `${isSecure ? "https" : "http"}://${host}${req.url || "/"}`;
+    const url = new URL(fullUrl);
+    this.pathname = url.pathname;
+    this.method = (req.method || "GET").toUpperCase();
+    this.query = parseQueryToObject(url.searchParams);
+    this.params = {};
+  }
+  headers;
+  method;
+  pathname;
+  query;
+  params;
+  storage = /* @__PURE__ */ new Map();
+  _bodyCache = null;
+  _filesCache = null;
+  _cookies = null;
+  /**
+   * Returns the best-effort client IP address for the current request.
+   *
+   * The lookup prefers proxy-forwarded headers before falling back to the raw
+   * socket address, which makes the result suitable for deployments behind
+   * reverse proxies that preserve `x-forwarded-for` or `x-real-ip`.
+   *
+   * @returns {string} The resolved client IP address, or `"unknown"` when no
+   * address can be derived.
+   */
+  ip() {
+    return this.headers["x-forwarded-for"]?.split(",")[0]?.trim() || this.headers["x-real-ip"] || this.req.socket?.remoteAddress || "unknown";
+  }
+  /**
+   * Returns the current request user-agent string.
+   *
+   * @returns {string} The raw `user-agent` header value, or an empty string
+   * when the header is missing.
+   */
+  userAgent() {
+    return this.headers["user-agent"] || "";
+  }
+  /**
+   * Returns whether the current request is using HTTPS.
+   *
+   * The check prefers `x-forwarded-proto` for proxy-aware deployments and then
+   * falls back to the encrypted state of the underlying socket.
+   *
+   * @returns {boolean} `true` when the request should be treated as HTTPS.
+   */
+  isSecure() {
+    return this.headers["x-forwarded-proto"] === "https" || this.req.socket?.encrypted === true;
+  }
+  /**
+   * Returns the request host header.
+   *
+   * @returns {string} The current host header value, or `"unknown"` when it is
+   * not available.
+   */
+  host() {
+    return this.headers.host || "unknown";
+  }
+  /**
+   * Returns the absolute request URL reconstructed from the current request.
+   *
+   * This helper rebuilds the URL from the current security state, host header,
+   * and parsed pathname. It does not append the original query string.
+   *
+   * @returns {string} Absolute URL for the current request pathname.
+   */
+  url() {
+    return `${this.isSecure() ? "https" : "http"}://${this.host()}${this.pathname}`;
+  }
+  /**
+   * Parses and returns the request body.
+   *
+   * JSON and plain text bodies are supported automatically. Multipart requests
+   * populate both `body()` and `files()` through a shared parsing pass. The
+   * parsed value is cached after the first read so later consumers do not touch
+   * the underlying stream again.
+   *
+   * Requests whose method is not one of `POST`, `PUT`, `PATCH`, or `DELETE`
+   * resolve to an empty object without reading the stream.
+   *
+   * @returns {Promise<T>} Parsed request body, multipart field map, raw text, or
+   * an empty object for methods that do not consume a body by default.
+   * @throws {BadRequestError} Thrown when the declared or streamed body size
+   * exceeds `maxBodySize`, or when JSON parsing fails.
+   */
+  async body() {
+    const methodsWithBody = ["POST", "PUT", "PATCH", "DELETE"];
+    if (!methodsWithBody.includes(this.method)) {
+      return {};
+    }
+    if (this._bodyCache !== null) return this._bodyCache;
+    const contentType = this.headers["content-type"] || "";
+    if (contentType.includes("multipart/form-data")) {
+      await this.parseMultipart();
+      return this._bodyCache;
+    }
+    const contentLength = parseInt(
+      this.headers["content-length"] || "0",
+      10
+    );
+    const maxBodySize = this.opts.maxBodySize || 1024 * 1024;
+    if (contentLength > maxBodySize) {
+      throw new BadRequestError("Request body too large.");
+    }
+    const body = await new Promise((resolve, reject) => {
+      const chunks = [];
+      let currentSize = 0;
+      this.req.on("data", (chunk) => {
+        currentSize += chunk.length;
+        if (currentSize > maxBodySize) {
+          reject(new BadRequestError("Request body too large."));
+        }
+        chunks.push(chunk);
+      });
+      this.req.on("end", () => {
+        if (chunks.length === 0) return resolve({});
+        const rawBody = Buffer.concat(chunks).toString("utf-8");
+        try {
+          if (contentType.includes("application/json")) {
+            resolve(JSON.parse(rawBody));
+          } else {
+            resolve(rawBody);
+          }
+        } catch {
+          reject(new BadRequestError("Invalid request body format."));
+        }
+      });
+      this.req.on("error", (err) => reject(err));
+    });
+    this._bodyCache = body;
+    this.storage.set("body", body);
+    return body;
+  }
+  /**
+   * Returns uploaded files for multipart/form-data requests.
+   *
+   * `files()` shares the same multipart parsing pass used by `body()`. The
+   * first call buffers every uploaded file into memory and caches both the
+   * parsed field object and file array for later access.
+   *
+   * @returns {Promise<UploadedFile[]>} Buffered multipart files, or an empty
+   * array when the request is not multipart.
+   */
+  async files() {
+    const contentType = this.headers["content-type"] || "";
+    if (!contentType.includes("multipart/form-data")) return [];
+    if (this._filesCache !== null) return this._filesCache;
+    await this.parseMultipart();
+    return this._filesCache || [];
+  }
+  /**
+   * Overrides the cached body value for the current request context.
+   *
+   * This mutates only the wrapper cache and the internal storage map. It does
+   * not modify the underlying Node.js request stream.
+   *
+   * @param {unknown} value - Replacement body value to expose through `body()`
+   * and internal request storage.
+   */
+  setBody(value) {
+    this._bodyCache = value;
+    this.storage.set("body", value);
+  }
+  /**
+   * Returns all parsed cookies from the request.
+   *
+   * Cookies are parsed lazily on first access and cached for the remainder of
+   * the request lifecycle.
+   *
+   * @returns {Cookies} Parsed cookie map for the current request.
+   */
+  cookies() {
+    if (this._cookies === null) {
+      const cookieHeader = this.headers.cookie;
+      this._cookies = cookieHeader ? parse(cookieHeader) : {};
+    }
+    return this._cookies;
+  }
+  /**
+   * Returns a single cookie value by name.
+   *
+   * @param {string} name - Cookie name to read from the parsed cookie map.
+   * @returns {string | undefined} The cookie value when present.
+   */
+  cookie(name) {
+    return this.cookies()[name];
+  }
+  /**
+   * Returns a value stored in the per-request internal storage map.
+   *
+   * This storage is local to the current request wrapper and can be used by
+   * middleware and handlers to exchange derived values without mutating the
+   * typed request surface.
+   *
+   * @param {string} key - Storage key associated with the requested value.
+   * @returns {T | undefined} Stored value for the key, if one exists.
+   */
+  get(key) {
+    return this.storage.get(key);
+  }
+  /**
+   * Stores a value in the per-request internal storage map.
+   *
+   * @param {string} key - Storage key to create or overwrite.
+   * @param {unknown} value - Arbitrary value to retain for the lifetime of the
+   * current request wrapper.
+   */
+  set(key, value) {
+    this.storage.set(key, value);
+  }
+  /**
+   * Parses a multipart/form-data request into cached fields and file buffers.
+   *
+   * The request stream is piped into Busboy exactly once. Field values are
+   * collected into a plain object, file contents are buffered fully in memory,
+   * and both results are stored in the request cache and internal storage map.
+   *
+   * @returns {Promise<void>} Resolves after Busboy finishes consuming the
+   * multipart stream and caches the parsed payload.
+   */
+  async parseMultipart() {
+    if (this._bodyCache !== null && this._filesCache !== null) return;
+    return new Promise((resolve, reject) => {
+      const bb = busboy({ headers: this.headers });
+      const fields = {};
+      const files = [];
+      bb.on("file", (name, file, info) => {
+        const chunks = [];
+        file.on("data", (data) => chunks.push(data));
+        file.on("end", () => {
+          files.push({
+            fieldname: name,
+            buffer: Buffer.concat(chunks),
+            ...info
+          });
+        });
+      });
+      bb.on("field", (name, value) => {
+        fields[name] = value;
+      });
+      bb.on("finish", () => {
+        this._bodyCache = fields;
+        this._filesCache = files;
+        this.storage.set("body", fields);
+        this.storage.set("files", files);
+        resolve();
+      });
+      bb.on("error", reject);
+      this.req.pipe(bb);
+    });
+  }
+};
+function parseQueryToObject(searchParams) {
+  const query = {};
+  for (const [key, value] of searchParams.entries()) {
+    query[key] = value;
+  }
+  return query;
+}
+var LithiaResponse = class {
+  /**
+   * Creates a response wrapper for the current HTTP transaction.
+   *
+   * The wrapper binds a pass-through `on()` helper to the underlying Node.js
+   * response object so route-adjacent code can subscribe to response events
+   * without holding the raw `ServerResponse`.
+   *
+   * @param {ServerResponse} res - Raw Node.js response object associated with
+   * the current request.
+   */
+  constructor(res) {
+    this.res = res;
+    this.on = this.res.on.bind(this.res);
+  }
+  _ended = false;
+  _cookies = [];
+  on;
+  /**
+   * Returns the current HTTP status code.
+   *
+   * @returns {number} Status code currently assigned to the underlying
+   * response.
+   */
+  get statusCode() {
+    return this.res.statusCode;
+  }
+  /**
+   * Sets the HTTP status code for the response.
+   *
+   * This mutates the underlying response only while it is still active.
+   *
+   * @param {number} status - HTTP status code to assign before the response is
+   * sent.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended or when the
+   * supplied status code falls outside the valid HTTP range.
+   */
+  status(status) {
+    this.ensureActive();
+    if (status < 100 || status > 599) {
+      throw new Error(`Invalid HTTP status code: ${status}`);
+    }
+    this.res.statusCode = status;
+    return this;
+  }
+  /**
+   * Returns the currently assigned response headers.
+   *
+   * @returns {Readonly<OutgoingHttpHeaders>} Snapshot of the headers currently
+   * stored on the underlying response.
+   */
+  headers() {
+    return this.res.getHeaders();
+  }
+  /**
+   * Sets multiple response headers at once.
+   *
+   * @param {OutgoingHttpHeaders} headers - Header entries to assign to the
+   * response before it is sent.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  setHeaders(headers) {
+    this.ensureActive();
+    Object.entries(headers).forEach(([key, value]) => {
+      this.res.setHeader(key, value);
+    });
+    return this;
+  }
+  /**
+   * Sets a single response header.
+   *
+   * @param {string} name - Header name to create or overwrite.
+   * @param {string | number | string[]} value - Header value written to the
+   * underlying response.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  setHeader(name, value) {
+    this.ensureActive();
+    this.res.setHeader(name, value);
+    return this;
+  }
+  /**
+   * Removes a response header.
+   *
+   * @param {string} name - Header name to remove.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  removeHeader(name) {
+    this.ensureActive();
+    this.res.removeHeader(name);
+    return this;
+  }
+  /**
+   * Queues a cookie to be written when the response is sent.
+   *
+   * Cookies are accumulated in memory and serialized only when a terminal
+   * response method flushes headers.
+   *
+   * @param {string} name - Cookie name.
+   * @param {string} value - Cookie value.
+   * @param {CookieOptions} [options={}] - Cookie serialization options.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  cookie(name, value, options = {}) {
+    this.ensureActive();
+    this._cookies.push({ name, value, options });
+    return this;
+  }
+  /**
+   * Clears a cookie by expiring it immediately.
+   *
+   * @param {string} name - Cookie name to expire.
+   * @param {CookieOptions} [options={}] - Additional cookie attributes that
+   * must match the original cookie scope.
+   * @returns {this} The current response wrapper for fluent chaining.
+   */
+  clearCookie(name, options = {}) {
+    return this.cookie(name, "", { ...options, expires: /* @__PURE__ */ new Date(0) });
+  }
+  /**
+   * Sends a response body using a best-effort content type.
+   *
+   * The method flushes pending cookies before writing, chooses a default
+   * content type when none is set, and treats plain objects as JSON by
+   * delegating to `json()`. Calling `send()` is a terminal operation for the
+   * response lifecycle.
+   *
+   * @param {unknown} [data] - Response payload to send.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  send(data) {
+    this.applyPendingCookies();
+    this.ensureActive();
+    try {
+      if (data === void 0 || data === null) {
+        this.end();
+        return;
+      }
+      if (Buffer.isBuffer(data)) {
+        if (!this.res.getHeader("Content-Type")) {
+          this.setHeader("Content-Type", "application/octet-stream");
+        }
+        this.res.end(data);
+      } else if (typeof data === "object") {
+        this.json(data);
+        return;
+      } else {
+        if (!this.res.getHeader("Content-Type")) {
+          this.setHeader("Content-Type", "text/plain; charset=utf-8");
+        }
+        this.res.end(String(data));
+      }
+    } finally {
+      this._ended = true;
+    }
+  }
+  /**
+   * Sends a JSON response.
+   *
+   * Pending cookies are flushed before serialization. If JSON serialization
+   * throws, the method logs the failure and falls back to a `500 Internal
+   * Server Error` response body.
+   *
+   * @param {object} obj - Plain object to serialize as JSON.
+   */
+  json(obj) {
+    this.applyPendingCookies();
+    this.ensureActive();
+    try {
+      const body = JSON.stringify(obj);
+      this.res.setHeader("Content-Type", "application/json; charset=utf-8");
+      this.res.end(body);
+    } catch (err) {
+      logger.error("Failed to serialize JSON response:", err);
+      this.res.statusCode = 500;
+      this.res.end("Internal Server Error");
+    } finally {
+      this._ended = true;
+    }
+  }
+  /**
+   * Sends a redirect response.
+   *
+   * This sets the status code, writes the `Location` header, and then ends the
+   * response.
+   *
+   * @param {string} url - Redirect target written to the `Location` header.
+   * @param {number} [status=302] - Redirect status code.
+   */
+  redirect(url, status = 302) {
+    this.status(status).setHeader("Location", url).end();
+  }
+  /**
+   * Ends the response without sending additional data.
+   *
+   * Pending cookies are flushed before the underlying response is closed.
+   *
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  end() {
+    this.applyPendingCookies();
+    this.ensureActive();
+    this.res.end();
+    this._ended = true;
+  }
+  /**
+   * Streams a file to the client.
+   *
+   * The method resolves the final path, verifies that it points to a regular
+   * file, sets `Content-Length`, flushes pending cookies, and pipes the file
+   * stream into the underlying response. Missing files and stream failures fall
+   * back to a `404` JSON error payload.
+   *
+   * @param {string} filePath - File path to stream. When `opts.root` is set, it
+   * is resolved relative to that root.
+   * @param {{ root?: string }} [opts={}] - Optional root directory used to
+   * resolve relative file paths.
+   */
+  sendFile(filePath, opts = {}) {
+    this.ensureActive();
+    try {
+      const fullPath = opts.root ? join(opts.root, filePath) : filePath;
+      const stats = statSync(fullPath);
+      if (!stats.isFile()) throw new Error("Target is not a file");
+      this.setHeader("Content-Length", String(stats.size));
+      const stream = createReadStream(fullPath);
+      this.applyPendingCookies();
+      stream.pipe(this.res);
+      stream.on("error", () => {
+        this.status(404).send({ error: "File not found" });
+      });
+    } catch {
+      this.status(404).send({ error: "File not found" });
+    } finally {
+      this._ended = true;
+    }
+  }
+  /**
+   * Serializes queued cookies into the response headers and clears the queue.
+   *
+   * Existing `Set-Cookie` headers are preserved and extended so multiple
+   * middleware and handler calls can contribute cookies before the response is
+   * finalized.
+   */
+  applyPendingCookies() {
+    if (this._cookies.length === 0) return;
+    const existing = this.res.getHeader("Set-Cookie") || [];
+    const serialized = this._cookies.map(
+      (cookie) => serialize(cookie.name, cookie.value, cookie.options)
+    );
+    this.res.setHeader("Set-Cookie", [...existing, ...serialized]);
+    this._cookies = [];
+  }
+  /**
+   * Ensures the response has not already been finalized.
+   *
+   * @throws {Error} Thrown when a terminal response method has already sent or
+   * ended the response.
+   */
+  ensureActive() {
+    if (this._ended) {
+      throw new Error("Response has already been sent.");
+    }
+  }
+};
+
+export { BadRequestError, ConflictError, ForbiddenError, GatewayTimeoutError, InternalServerError, LithiaClientError, LithiaError, LithiaEventError, LithiaRequest, LithiaResponse, NotFoundError, RouteNotFoundError, ServiceUnavailableError, UnauthorizedError, defineConfig, dispatchTask, executeTask, provide, runTask, runTaskAsync, useData, useDependency, useEvent, useHeaders, useOptionalDependency, useParams, usePathname, useQuery, useRequest, useResponse, useRoute, useSocket, useSocketServer };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map