@lithia-js/core 1.0.0-canary.0

package/dist/server/request.d.ts

@@ -0,0 +1,73 @@
+import type { IncomingHttpHeaders, IncomingMessage } from "node:http";
+import { type FileInfo } from "busboy";
+import { type Cookies } from "cookie";
+import type { Lithia } from "../lithia";
+/** Route parameters extracted from the route matcher. */
+export type Params = Record<string, any>;
+/** Parsed query parameters. Values may be a string or an array for repeated keys. */
+export type Query = Record<string, any>;
+/** Represents an uploaded file. */
+export interface UploadedFile extends FileInfo {
+    /** Field name in the form. */
+    fieldname: string;
+    /** File buffer. */
+    buffer: Buffer;
+}
+/** Request wrapper passed to route handlers.
+ *
+ * Provides convenient accessors for headers, params, query, body and helpers
+ * such as `ip()` and `isSecure()`. The wrapper also exposes a simple
+ * per-request storage via `get()`/`set()` and cookie parsing helpers.
+ */
+export declare class LithiaRequest {
+    private readonly req;
+    private readonly lithia;
+    headers: Readonly<IncomingHttpHeaders>;
+    method: Readonly<string>;
+    params: Params;
+    pathname: Readonly<string>;
+    query: Query;
+    private storage;
+    private _bodyCache;
+    private _filesCache;
+    private _cookies;
+    /**
+     * Wrap a Node `IncomingMessage` into a `LithiaRequest`.
+     *
+     * `lithia` is the runtime instance and is stored in request-local
+     * storage under the `lithia` key for handlers that need access.
+     */
+    constructor(req: IncomingMessage, lithia: Lithia);
+    /**
+     * Read and parse the request body. For JSON content-type this returns the
+     * parsed object; for other content types it returns the raw string. The
+     * result is cached and subsequent calls return the cached value.
+     */
+    body<T>(): Promise<T>;
+    /**
+     * Get uploaded files from a multipart/form-data request.
+     */
+    files(): Promise<UploadedFile[]>;
+    /** Set the request body manually (e.g. after validation/sanitization). */
+    setBody(value: unknown): void;
+    private parseMultipart;
+    /** Retrieve a value from per-request storage. */
+    get<T>(key: string): T | undefined;
+    /** Store a value in per-request storage. */
+    set(key: string, value: unknown): void;
+    /** Parse cookies from the `Cookie` header. */
+    cookies(): Cookies;
+    /** Return a single cookie value by name. */
+    cookie(name: string): string | undefined;
+    /** Client IP address (considers `X-Forwarded-For` and `X-Real-IP`). */
+    ip(): string;
+    /** `User-Agent` header value or empty string. */
+    userAgent(): string;
+    /** Return true when the request was made over TLS. */
+    isSecure(): boolean;
+    /** Host header or `unknown` when missing. */
+    host(): string;
+    /** Full URL constructed from host and pathname. */
+    url(): string;
+}
+export declare function parseQueryToObject(raw: URLSearchParams): Query;

package/dist/server/request.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LithiaRequest = void 0;
+exports.parseQueryToObject = parseQueryToObject;
+const busboy_1 = __importDefault(require("busboy"));
+const cookie_1 = require("cookie");
+/** Request wrapper passed to route handlers.
+ *
+ * Provides convenient accessors for headers, params, query, body and helpers
+ * such as `ip()` and `isSecure()`. The wrapper also exposes a simple
+ * per-request storage via `get()`/`set()` and cookie parsing helpers.
+ */
+class LithiaRequest {
+    req;
+    lithia;
+    headers;
+    method;
+    params;
+    pathname;
+    query;
+    storage = new Map();
+    _bodyCache = null;
+    _filesCache = null;
+    _cookies = null;
+    /**
+     * Wrap a Node `IncomingMessage` into a `LithiaRequest`.
+     *
+     * `lithia` is the runtime instance and is stored in request-local
+     * storage under the `lithia` key for handlers that need access.
+     */
+    constructor(req, lithia) {
+        this.req = req;
+        this.lithia = lithia;
+        const protocol = req.headers["x-forwarded-proto"] === "https" ||
+            req.socket?.encrypted === true
+            ? "https"
+            : "http";
+        const host = req.headers.host || "unknown";
+        const fullUrl = `${protocol}://${host}${req.url || "/"}`;
+        const url = new URL(fullUrl);
+        this.pathname = url.pathname;
+        this.method = (req.method || "GET").toUpperCase();
+        this.headers = req.headers;
+        this.query = parseQueryToObject(url.searchParams);
+        this.params = {};
+        this.storage.set("lithia", this.lithia);
+    }
+    /**
+     * Read and parse the request body. For JSON content-type this returns the
+     * parsed object; for other content types it returns the raw string. The
+     * result is cached and subsequent calls return the cached value.
+     */
+    async body() {
+        if (!["POST", "PUT", "PATCH", "DELETE"].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.lithia.options.http.maxBodySize || 1024 * 1024;
+        if (contentLength > maxBodySize) {
+            throw new Error("Request body too large");
+        }
+        const body = await new Promise((resolve, reject) => {
+            let bodyData = "";
+            this.req.on("data", (chunk) => {
+                bodyData += chunk;
+                if (bodyData.length > maxBodySize) {
+                    reject(new Error("Request body too large"));
+                }
+            });
+            this.req.on("end", () => {
+                if (!bodyData)
+                    return resolve({});
+                try {
+                    if (contentType.includes("application/json")) {
+                        resolve(JSON.parse(bodyData));
+                    }
+                    else {
+                        resolve(bodyData);
+                    }
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+            this.req.on("error", (err) => reject(err));
+        });
+        this._bodyCache = body;
+        this.storage.set("body", body);
+        return body;
+    }
+    /**
+     * Get uploaded files from a multipart/form-data request.
+     */
+    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;
+    }
+    /** Set the request body manually (e.g. after validation/sanitization). */
+    setBody(value) {
+        this._bodyCache = value;
+        this.storage.set("body", value);
+    }
+    async parseMultipart() {
+        if (this._bodyCache !== null && this._filesCache !== null)
+            return;
+        return new Promise((resolve, reject) => {
+            const bb = (0, busboy_1.default)({ 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, val) => {
+                fields[name] = val;
+            });
+            bb.on("close", () => {
+                this._bodyCache = fields;
+                this._filesCache = files;
+                resolve();
+            });
+            bb.on("error", (err) => reject(err));
+            this.req.pipe(bb);
+        });
+    }
+    /** Retrieve a value from per-request storage. */
+    get(key) {
+        return this.storage.get(key);
+    }
+    /** Store a value in per-request storage. */
+    set(key, value) {
+        this.storage.set(key, value);
+    }
+    /** Parse cookies from the `Cookie` header. */
+    cookies() {
+        if (this._cookies === null) {
+            const cookieHeader = this.headers.cookie;
+            const parsedCookies = cookieHeader ? (0, cookie_1.parse)(cookieHeader) : {};
+            this._cookies = parsedCookies;
+        }
+        return this._cookies || {};
+    }
+    /** Return a single cookie value by name. */
+    cookie(name) {
+        return this.cookies()[name];
+    }
+    /** Client IP address (considers `X-Forwarded-For` and `X-Real-IP`). */
+    ip() {
+        return (this.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
+            this.headers["x-real-ip"] ||
+            this.req.socket?.remoteAddress ||
+            "unknown");
+    }
+    /** `User-Agent` header value or empty string. */
+    userAgent() {
+        return this.headers["user-agent"] || "";
+    }
+    /** Return true when the request was made over TLS. */
+    isSecure() {
+        return (this.headers["x-forwarded-proto"] === "https" ||
+            this.req.socket?.encrypted === true);
+    }
+    /** Host header or `unknown` when missing. */
+    host() {
+        return this.headers.host || "unknown";
+    }
+    /** Full URL constructed from host and pathname. */
+    url() {
+        return `${this.isSecure() ? "https" : "http"}://${this.host()}${this.pathname}`;
+    }
+}
+exports.LithiaRequest = LithiaRequest;
+function parseQueryToObject(raw) {
+    const obj = {};
+    for (const [k, v] of raw.entries()) {
+        if (obj[k] === undefined)
+            obj[k] = v;
+        else if (Array.isArray(obj[k]))
+            obj[k].push(v);
+        else
+            obj[k] = [obj[k], v];
+    }
+    return obj;
+}
+//# sourceMappingURL=request.js.map

package/dist/server/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"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"}

package/dist/server/response.d.ts

@@ -0,0 +1,69 @@
+import type { OutgoingHttpHeaders, ServerResponse } from "node:http";
+/** Options used when setting cookies on the response. */
+export interface CookieOptions {
+    domain?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    maxAge?: number;
+    path?: string;
+    sameSite?: boolean | "lax" | "strict" | "none";
+    secure?: boolean;
+}
+/**
+ * High-level response wrapper used by Lithia handlers.
+ *
+ * This class wraps Node's `ServerResponse` and provides convenient helper
+ * methods for common response patterns used by Lithia handlers:
+ * - sending JSON (`json`), text/primitive bodies (`send`) and redirects
+ * - streaming static files (`sendFile`)
+ * - managing headers and queued cookies (`addHeader`, `setHeaders`, `cookie`)
+ *
+ * It also tracks whether the response has already been sent and will throw
+ * if you attempt to mutate the response after it was finalized.
+ *
+ * Instances are created per incoming request and are intended to be passed
+ * through middleware and route handlers.
+ */
+export declare class LithiaResponse {
+    private res;
+    _ended: boolean;
+    private _cookies;
+    /** Create a new `LithiaResponse` wrapping a Node `ServerResponse`. */
+    constructor(res: ServerResponse);
+    /** Current HTTP status code for the response. */
+    get statusCode(): number;
+    /** Convenience passthrough to the underlying `ServerResponse#on`. */
+    on: (event: string, listener: (chunk: unknown) => void) => void;
+    private checkIfEnded;
+    /** Set the numeric HTTP status code. */
+    status(status: number): LithiaResponse;
+    /** Return a copy of currently set headers. */
+    headers(): Readonly<OutgoingHttpHeaders>;
+    /** Replace multiple headers at once. */
+    setHeaders(headers: OutgoingHttpHeaders): LithiaResponse;
+    /** Set a single header. */
+    addHeader(name: string, value: string | number | string[]): LithiaResponse;
+    /** Remove a header if present. */
+    removeHeader(name: string): LithiaResponse;
+    /** End the response without a body. */
+    end(): void;
+    /** Send an object as JSON. Sets `Content-Type: application/json`. */
+    json(obj: object): void;
+    /** Send an HTTP redirect to `url`. */
+    redirect(url: string, status?: number): void;
+    /**
+     * Send a response body.
+     * - `Buffer` bodies are sent as `application/octet-stream`.
+     * - Objects are serialized as JSON.
+     * - Primitives are sent as text/plain.
+     */
+    send(data?: unknown): void;
+    /** Queue a cookie to be set on the response. */
+    cookie(name: string, value: string, options?: CookieOptions): LithiaResponse;
+    /** Clear a cookie by setting it with an expired date. */
+    clearCookie(name: string, options?: CookieOptions): LithiaResponse;
+    /** Send a static file from disk. `opts.root` may be used to resolve relative paths. */
+    sendFile(filePath: string, opts?: {
+        root?: string;
+    }): void;
+}

package/dist/server/response.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LithiaResponse = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const cookie_1 = require("cookie");
+const logger_1 = require("../logger");
+/**
+ * High-level response wrapper used by Lithia handlers.
+ *
+ * This class wraps Node's `ServerResponse` and provides convenient helper
+ * methods for common response patterns used by Lithia handlers:
+ * - sending JSON (`json`), text/primitive bodies (`send`) and redirects
+ * - streaming static files (`sendFile`)
+ * - managing headers and queued cookies (`addHeader`, `setHeaders`, `cookie`)
+ *
+ * It also tracks whether the response has already been sent and will throw
+ * if you attempt to mutate the response after it was finalized.
+ *
+ * Instances are created per incoming request and are intended to be passed
+ * through middleware and route handlers.
+ */
+class LithiaResponse {
+    res;
+    _ended = false;
+    _cookies = [];
+    /** Create a new `LithiaResponse` wrapping a Node `ServerResponse`. */
+    constructor(res) {
+        this.res = res;
+        this.on = this.res.on.bind(this.res);
+    }
+    /** Current HTTP status code for the response. */
+    get statusCode() {
+        return this.res.statusCode;
+    }
+    /** Convenience passthrough to the underlying `ServerResponse#on`. */
+    on;
+    checkIfEnded() {
+        if (this._ended)
+            throw new Error("Cannot modify response after it was sent");
+    }
+    /** Set the numeric HTTP status code. */
+    status(status) {
+        this.checkIfEnded();
+        if (status < 100 || status > 599)
+            throw new Error("Invalid HTTP status code");
+        this.res.statusCode = status;
+        return this;
+    }
+    /** Return a copy of currently set headers. */
+    headers() {
+        return this.res.getHeaders();
+    }
+    /** Replace multiple headers at once. */
+    setHeaders(headers) {
+        this.checkIfEnded();
+        Object.entries(headers).forEach(([k, v]) => {
+            this.res.setHeader(k, v);
+        });
+        return this;
+    }
+    /** Set a single header. */
+    addHeader(name, value) {
+        this.checkIfEnded();
+        this.res.setHeader(name, value);
+        return this;
+    }
+    /** Remove a header if present. */
+    removeHeader(name) {
+        this.checkIfEnded();
+        this.res.removeHeader(name);
+        return this;
+    }
+    /** End the response without a body. */
+    end() {
+        this.checkIfEnded();
+        this.res.end();
+        this._ended = true;
+    }
+    /** Send an object as JSON. Sets `Content-Type: application/json`. */
+    json(obj) {
+        this.checkIfEnded();
+        try {
+            const body = JSON.stringify(obj);
+            this.res.setHeader("Content-Type", "application/json; charset=utf-8");
+            this.res.end(body);
+        }
+        catch (err) {
+            logger_1.logger.error("Failed to serialize JSON response:", err);
+            this.res.statusCode = 500;
+            this.res.end("Internal Server Error");
+        }
+        finally {
+            this._ended = true;
+        }
+    }
+    /** Send an HTTP redirect to `url`. */
+    redirect(url, status = 302) {
+        this.checkIfEnded();
+        this.status(status).addHeader("Location", url).end();
+    }
+    /**
+     * Send a response body.
+     * - `Buffer` bodies are sent as `application/octet-stream`.
+     * - Objects are serialized as JSON.
+     * - Primitives are sent as text/plain.
+     */
+    send(data) {
+        // Set cookies first
+        if (this._cookies.length > 0) {
+            const existing = this.res.getHeader("Set-Cookie") || [];
+            const serialized = this._cookies.map((c) => (0, cookie_1.serialize)(c.name, c.value, c.options));
+            this.res.setHeader("Set-Cookie", [...existing, ...serialized]);
+            this._cookies = [];
+        }
+        this.checkIfEnded();
+        try {
+            if (data === undefined || data === null) {
+                this.end();
+                return;
+            }
+            if (Buffer.isBuffer(data)) {
+                if (!this.res.getHeader("Content-Type"))
+                    this.addHeader("Content-Type", "application/octet-stream");
+                this.res.end(data);
+            }
+            else if (typeof data === "object") {
+                this.json(data);
+            }
+            else {
+                if (!this.res.getHeader("Content-Type"))
+                    this.addHeader("Content-Type", "text/plain; charset=utf-8");
+                this.res.end(String(data));
+            }
+        }
+        finally {
+            this._ended = true;
+        }
+    }
+    /** Queue a cookie to be set on the response. */
+    cookie(name, value, options = {}) {
+        this.checkIfEnded();
+        this._cookies.push({ name, value, options });
+        return this;
+    }
+    /** Clear a cookie by setting it with an expired date. */
+    clearCookie(name, options = {}) {
+        this.checkIfEnded();
+        return this.cookie(name, "", { ...options, expires: new Date(0) });
+    }
+    /** Send a static file from disk. `opts.root` may be used to resolve relative paths. */
+    sendFile(filePath, opts = {}) {
+        this.checkIfEnded();
+        try {
+            const full = opts.root ? (0, node_path_1.join)(opts.root, filePath) : filePath;
+            const stats = (0, node_fs_1.statSync)(full);
+            if (!stats.isFile())
+                throw new Error("Not a file");
+            this.addHeader("Content-Length", String(stats.size));
+            const stream = (0, node_fs_1.createReadStream)(full);
+            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;
+        }
+    }
+}
+exports.LithiaResponse = LithiaResponse;
+//# sourceMappingURL=response.js.map

package/dist/server/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/server/response.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lithia-js/core",
+  "version": "1.0.0-canary.0",
+  "private": false,
+  "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
+  "author": "Lucas Arch <luketsx@icloud.com>",
+  "homepage": "https://lithiajs.com",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lithia-framework/lithia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lithia-framework/lithia/issues"
+  },
+  "devDependencies": {
+    "@types/busboy": "^1.5.4",
+    "@types/source-map-support": "^0.5.10"
+  },
+  "dependencies": {
+    "busboy": "^1.6.0",
+    "c12": "^3.3.3",
+    "cookie": "^1.1.1",
+    "import-fresh": "^3.3.1",
+    "klona": "^2.0.6",
+    "socket.io": "^4.8.1",
+    "source-map-support": "^0.5.21",
+    "zod": "^4.2.1",
+    "@lithia-js/utils": "1.0.0-canary.0",
+    "@lithia-js/native": "1.0.0-canary.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "require": "./dist/lib.js",
+      "import": "./dist/lib.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}