alepha 0.15.1 → 0.15.3

package/src/server/core/index.ts

@@ -114,14 +114,24 @@ export * from "./services/UserAgentParser.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides high-performance HTTP server capabilities with declarative routing and action primitives.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * The server module enables building REST APIs and web applications using `$route` and `$action` primitives
- * on class properties. It provides automatic request/response handling, schema validation, middleware support,
- * and seamless integration with other Alepha modules for a complete backend solution.
+ * Convention-driven HTTP server with automatic validation and type inference.
+ *
+ * **Features:**
+ * - Type-safe API endpoints with schema validation
+ * - Lower-level HTTP route definitions
+ * - Automatic request/response validation via TypeBox
+ * - Convention-based URL generation (`/api/{ActionName}`)
+ * - Direct invocation (`run()`) or HTTP (`fetch()`)
+ * - Built-in authentication integration
+ * - Multipart file upload handling
+ * - Content-type auto-negotiation (JSON, form-data, text)
+ * - HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
+ * - Error handling: BadRequestError, ValidationError, ForbiddenError, UnauthorizedError, ConflictError, NotFoundError
  *
- * @see {@link $route}
- * @see {@link $action}
  * @module alepha.server
  */
 export const AlephaServer = $module({

package/src/server/core/interfaces/ServerRequest.ts

@@ -83,7 +83,7 @@ export interface ServerRequest<
 
   /**
    * Client IP address.
-   * Will parse `X-Forwarded-For` header if present.
+   * Uses `X-Forwarded-For` header when `TRUST_PROXY=true`.
    */
   ip?: string;
 
@@ -100,6 +100,42 @@ export interface ServerRequest<
    */
   userAgent: UserAgentInfo;
 
+  /**
+   * Geolocation information derived from proxy headers.
+   * Available when behind Cloudflare, Vercel, or similar CDNs.
+   */
+  geo: RequestGeo;
+
+  /**
+   * Whether the request appears to be from a bot/crawler.
+   * Based on user-agent analysis.
+   */
+  isBot: boolean;
+
+  /**
+   * Whether the request is from a mobile device.
+   * Based on user-agent analysis.
+   */
+  isMobile: boolean;
+
+  /**
+   * Request protocol (http or https).
+   * Uses `X-Forwarded-Proto` header when behind a proxy.
+   */
+  protocol: "http" | "https";
+
+  /**
+   * Preferred language from `Accept-Language` header.
+   * Returns the first/most preferred language code (e.g., "en", "fr", "en-US").
+   */
+  language?: string;
+
+  /**
+   * Parsed referer information.
+   * Undefined if no Referer header or invalid URL.
+   */
+  referer?: RequestReferer;
+
   /**
    * Arbitrary metadata attached to the request. Can be used by middlewares to store information.
    */
@@ -208,3 +244,49 @@ export interface WebRequestEvent {
   req: Request;
   res?: Response;
 }
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Geolocation information from proxy headers (Cloudflare, Vercel, etc.)
+ */
+export interface RequestGeo {
+  /**
+   * ISO 3166-1 alpha-2 country code (e.g., "US", "FR", "JP").
+   */
+  country?: string;
+  /**
+   * City name (e.g., "San Francisco", "Paris").
+   */
+  city?: string;
+  /**
+   * Region/state (e.g., "California", "Île-de-France").
+   */
+  region?: string;
+  /**
+   * Latitude (if available).
+   */
+  latitude?: string;
+  /**
+   * Longitude (if available).
+   */
+  longitude?: string;
+}
+
+/**
+ * Parsed referer information.
+ */
+export interface RequestReferer {
+  /**
+   * Full referer URL.
+   */
+  url: string;
+  /**
+   * Hostname of the referer (e.g., "google.com").
+   */
+  hostname: string;
+  /**
+   * Path of the referer URL.
+   */
+  pathname: string;
+}

package/src/server/core/primitives/$action.spec.ts

@@ -1,5 +1,5 @@
 import { Alepha, t } from "alepha";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, test } from "vitest";
 import { $action } from "../index.ts";
 

package/src/server/core/primitives/$action.ts

@@ -20,6 +20,7 @@ import type {
   ServerRequest,
   ServerResponseBody,
   ServerRoute,
+  TRequestBody,
 } from "../interfaces/ServerRequest.ts";
 import { ServerProvider } from "../providers/ServerProvider.ts";
 import { ServerRouterProvider } from "../providers/ServerRouterProvider.ts";
@@ -445,7 +446,9 @@ export type ClientRequestEntry<
 };
 
 export type ClientRequestEntryContainer<TConfig extends RequestConfigSchema> = {
-  body: TConfig["body"] extends TObject ? Static<TConfig["body"]> : undefined;
+  body: TConfig["body"] extends TRequestBody
+    ? Static<TConfig["body"]>
+    : undefined;
 
   params: TConfig["params"] extends TObject
     ? Static<TConfig["params"]>
@@ -453,11 +456,11 @@ export type ClientRequestEntryContainer<TConfig extends RequestConfigSchema> = {
 
   headers?: TConfig["headers"] extends TObject
     ? Static<TConfig["headers"]>
-    : undefined;
+    : Record<string, string>;
 
   query?: TConfig["query"] extends TObject
     ? Partial<Static<TConfig["query"]>>
-    : undefined;
+    : Record<string, string>;
 };
 
 export interface ClientRequestOptions extends FetchOptions {
@@ -465,6 +468,8 @@ export interface ClientRequestOptions extends FetchOptions {
    * Standard request fetch options.
    */
   request?: RequestInit;
+
+  query?: Record<string, string | number | boolean>;
 }
 
 export type ClientRequestResponse<TConfig extends RequestConfigSchema> =

package/src/server/core/providers/NodeHttpServerProvider.spec.ts

@@ -31,7 +31,9 @@ describe("NodeHttpServerProvider", () => {
     });
 
     test("production mode: waits for connections then closes", async () => {
-      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      });
       alepha.with(NodeHttpServerProvider);
 
       await alepha.start();
@@ -52,7 +54,9 @@ describe("NodeHttpServerProvider", () => {
     });
 
     test("production mode: forces close after timeout", async () => {
-      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      });
       alepha.with(NodeHttpServerProvider);
 
       await alepha.start();
@@ -89,7 +93,9 @@ describe("NodeHttpServerProvider", () => {
     });
 
     test("rejects new requests during shutdown", async () => {
-      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      });
       alepha.with(NodeHttpServerProvider);
 
       await alepha.start();

package/src/server/core/providers/NodeHttpServerProvider.ts

@@ -35,15 +35,21 @@ export class NodeHttpServerProvider extends ServerProvider {
   protected readonly env = $env(envSchema);
   protected readonly router = $inject(ServerRouterProvider);
 
-  /** Track active connections for fast shutdown */
+  /**
+   * Track active connections for fast shutdown.
+   */
   protected readonly connections = new Set<Socket>();
 
-  /** Get number of active connections */
+  /**
+   * Get number of active connections.
+   */
   public getConnectionsCount(): number {
     return this.connections.size;
   }
 
-  /** Server options */
+  /**
+   * Server options.
+   */
   public readonly options = {
     /**
      * Graceful shutdown timeout in ms.