alepha 0.8.0 → 0.8.1

package/server/cookies.d.ts

@@ -3,6 +3,16 @@ import { DateTimeProvider, DurationLike } from "alepha/datetime";
 
 //#region src/descriptors/$cookie.d.ts
 declare const KEY = "COOKIE";
+/**
+* Declares a type-safe, configurable HTTP cookie.
+* This descriptor provides methods to get, set, and delete the cookie
+* within the server request/response cycle.
+*/
+declare const $cookie: {
+  <T extends TSchema>(options: CookieDescriptorOptions<T>): CookieDescriptor<T>;
+  [KIND]: string;
+};
+// ---------------------------------------------------------------------------------------------------------------------
 interface CookieDescriptorOptions<T extends TSchema> {
   /** The schema for the cookie's value, used for validation and type safety. */
   schema: T;
@@ -44,16 +54,6 @@ interface CookieDescriptor<T extends TSchema> {
     cookies?: Cookies;
   }) => void;
 }
-/**
-* Declares a type-safe, configurable HTTP cookie.
-* This descriptor provides methods to get, set, and delete the cookie
-* within the server request/response cycle.
-*/
-declare const $cookie: {
-  <T extends TSchema>(options: CookieDescriptorOptions<T>): CookieDescriptor<T>;
-  [KIND]: string;
-};
-// ---------------------------------------------------------------------------------------------------------------------
 interface Cookies {
   req: Record<string, string>;
   res: Record<string, Cookie | null>;
@@ -109,6 +109,183 @@ declare module "alepha/server" {
     cookies: Cookies;
   }
 }
+/**
+* Provides HTTP cookie management capabilities for server requests and responses with type-safe cookie descriptors.
+*
+* The server-cookies module enables declarative cookie handling using the `$cookie` descriptor on class properties.
+* It offers automatic cookie parsing, secure cookie configuration, and seamless integration with server routes
+* for managing user sessions, preferences, and authentication tokens.
+*
+* **Key Features:**
+* - Declarative cookie definition with `$cookie` descriptor
+* - Automatic cookie parsing from requests
+* - Secure cookie configuration (httpOnly, secure, sameSite)
+* - Type-safe cookie values with schema validation
+* - Automatic cookie serialization and deserialization
+* - Integration with server request/response lifecycle
+*
+* **Basic Usage:**
+* ```ts
+* import { Alepha, run, t } from "alepha";
+* import { AlephaServer, $route } from "alepha/server";
+* import { AlephaServerCookies, $cookie } from "alepha/server/cookies";
+*
+* class AuthRoutes {
+*   // Define authentication cookie
+*   authToken = $cookie({
+*     name: "auth_token",
+*     httpOnly: true,
+*     secure: true,
+*     sameSite: "strict",
+*     maxAge: "7d",
+*   });
+*
+*   // Define user preferences cookie
+*   userPrefs = $cookie({
+*     name: "user_prefs",
+*     schema: t.object({
+*       theme: t.union([t.literal("light"), t.literal("dark")]),
+*       language: t.string(),
+*     }),
+*     maxAge: "30d",
+*   });
+*
+*   login = $route({
+*     path: "/login",
+*     method: "POST",
+*     schema: {
+*       body: t.object({
+*         email: t.string(),
+*         password: t.string(),
+*       }),
+*     },
+*     handler: async ({ body, reply }) => {
+*       const user = await authenticateUser(body.email, body.password);
+*       if (!user) {
+*         return new Response("Invalid credentials", { status: 401 });
+*       }
+*
+*       const token = await generateJWT(user.id);
+*
+*       // Set authentication cookie
+*       this.authToken.set(reply, token);
+*
+*       return Response.json({ success: true, user });
+*     },
+*   });
+*
+*   profile = $route({
+*     path: "/profile",
+*     method: "GET",
+*     handler: async ({ cookies }) => {
+*       // Get authentication token from cookie
+*       const token = this.authToken.get(cookies);
+*       if (!token) {
+*         return new Response("Unauthorized", { status: 401 });
+*       }
+*
+*       const user = await validateJWT(token);
+*       const preferences = this.userPrefs.get(cookies) || {
+*         theme: "light",
+*         language: "en",
+*       };
+*
+*       return Response.json({ user, preferences });
+*     },
+*   });
+*
+*   logout = $route({
+*     path: "/logout",
+*     method: "POST",
+*     handler: async ({ reply }) => {
+*       // Clear authentication cookie
+*       this.authToken.clear(reply);
+*       return Response.json({ success: true });
+*     },
+*   });
+* }
+*
+* const alepha = Alepha.create()
+*   .with(AlephaServer)
+*   .with(AlephaServerCookies)
+*   .with(AuthRoutes);
+*
+* run(alepha);
+* ```
+*
+* **Advanced Cookie Management:**
+* ```ts
+* class SessionRoutes {
+*   // Session cookie with custom configuration
+*   sessionId = $cookie({
+*     name: "session_id",
+*     httpOnly: true,
+*     secure: process.env.NODE_ENV === "production",
+*     sameSite: "lax",
+*     path: "/",
+*     maxAge: "2h",
+*     encrypt: true, // Optional encryption
+*   });
+*
+*   // Shopping cart cookie
+*   cart = $cookie({
+*     name: "shopping_cart",
+*     schema: t.object({
+*       items: t.array(t.object({
+*         id: t.string(),
+*         quantity: t.number(),
+*       })),
+*       total: t.number(),
+*     }),
+*     maxAge: "30d",
+*   });
+*
+*   // Tracking consent cookie
+*   consent = $cookie({
+*     name: "tracking_consent",
+*     schema: t.object({
+*       analytics: t.boolean(),
+*       marketing: t.boolean(),
+*       functional: t.boolean(),
+*     }),
+*     maxAge: "1y",
+*   });
+*
+*   updateCart = $route({
+*     path: "/cart",
+*     method: "POST",
+*     schema: {
+*       body: t.object({
+*         productId: t.string(),
+*         quantity: t.number(),
+*       }),
+*     },
+*     handler: async ({ body, cookies, reply }) => {
+*       const currentCart = this.cart.get(cookies) || { items: [], total: 0 };
+*
+*       // Update cart logic
+*       const existingItem = currentCart.items.find(item => item.id === body.productId);
+*       if (existingItem) {
+*         existingItem.quantity = body.quantity;
+*       } else {
+*         currentCart.items.push({ id: body.productId, quantity: body.quantity });
+*       }
+*
+*       // Recalculate total
+*       currentCart.total = await calculateCartTotal(currentCart.items);
+*
+*       // Update cookie
+*       this.cart.set(reply, currentCart);
+*
+*       return Response.json(currentCart);
+*     },
+*   });
+* }
+* ```
+*
+* @see {@link $cookie}
+* @module alepha.server.cookies
+*/
 declare class AlephaServerCookies implements Module {
   readonly name = "alepha.server.cookies";
   readonly $services: (alepha: Alepha) => void;

package/server/health.d.ts

@@ -25,9 +25,6 @@ declare class ServerHealthProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Server Health Module
-*
-* @description
 * Plugin for Alepha Server that provides health-check endpoints.
 *
 * @see {@link ServerHealthProvider}

package/server/helmet.d.ts

@@ -55,8 +55,6 @@ declare class ServerHelmetProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Server Helmet Module
-*
 * Automatically adds important HTTP security headers to every response
 * to help protect your application from common web vulnerabilities.
 *

package/server/links.d.ts

@@ -46,10 +46,26 @@ type HttpVirtualClient<T> = { [K in keyof T as T[K] extends ActionDescriptor ? K
 } : never };
 //#endregion
 //#region src/descriptors/$client.d.ts
+/**
+* Create a new client.
+*/
 declare const $client: <T extends object>(scope?: ClientScope) => HttpVirtualClient<T>;
 //#endregion
 //#region src/descriptors/$remote.d.ts
 declare const KEY = "REMOTE";
+/**
+* $remote is a descriptor that allows you to define remote service access.
+*
+* Use it only when you have 2 or more services that need to communicate with each other.
+*
+* All remote services can be exposed as actions, ... or not.
+*
+* You can add a service account if you want to use a security layer.
+*/
+declare const $remote: {
+  (options: RemoteDescriptorOptions): RemoteDescriptor;
+  [KIND]: string;
+};
 interface RemoteDescriptorOptions {
   /**
   * The URL of the remote service.
@@ -98,19 +114,6 @@ interface RemoteDescriptor {
   [KIND]: typeof KEY;
   [OPTIONS]: RemoteDescriptorOptions;
 }
-/**
-* $remote is a descriptor that allows you to define a remote service access.
-*
-* Use it only when you have 2 or more services that need to communicate with each other.
-*
-* All remote services can be exposed as actions, ... or not.
-*
-* You can add a service account if you want to use a security layer.
-*/
-declare const $remote: {
-  (options: RemoteDescriptorOptions): RemoteDescriptor;
-  [KIND]: string;
-};
 //#endregion
 //#region src/providers/RemoteDescriptorProvider.d.ts
 declare class RemoteDescriptorProvider {

package/server/metrics.d.ts

@@ -20,8 +20,6 @@ declare class ServerMetricsProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Server Metrics Module
-*
 * This module provides prometheus metrics for the Alepha server.
 * Metrics are exposed at the `/metrics` endpoint.
 *

package/server/multipart.d.ts

@@ -31,8 +31,6 @@ interface HybridFile extends FileLike {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Server Multipart Module
-*
 * This module provides support for handling multipart/form-data requests.
 * It allows to parse body data containing t.file().
 *

package/server/proxy.d.ts

@@ -2,6 +2,10 @@ import { Alepha, Async, HookDescriptor, KIND, Logger, Module, OPTIONS } from "al
 import { ServerHandler, ServerRequest, ServerRouterProvider } from "alepha/server";
 
 //#region src/descriptors/$proxy.d.ts
+declare const $proxy: {
+  (options: ProxyDescriptorOptions): ProxyDescriptor;
+  [KIND]: string;
+};
 type ProxyDescriptorOptions = {
   path: string;
   target: string | (() => string);
@@ -14,10 +18,6 @@ interface ProxyDescriptor {
   [KIND]: "PROXY";
   [OPTIONS]: ProxyDescriptorOptions;
 }
-declare const $proxy: {
-  (options: ProxyDescriptorOptions): ProxyDescriptor;
-  [KIND]: string;
-};
 //#endregion
 //#region src/providers/ProxyDescriptorProvider.d.ts
 declare class ProxyDescriptorProvider {

package/server/static.d.ts

@@ -4,6 +4,13 @@ import { DateTimeProvider, DurationLike } from "alepha/datetime";
 
 //#region src/descriptors/$serve.d.ts
 declare const KEY = "SERVE";
+/**
+* Create a new static file handler.
+*/
+declare const $serve: {
+  (options?: ServeDescriptorOptions): ServeDescriptor;
+  [KIND]: string;
+};
 interface ServeDescriptorOptions {
   /**
   * Prefix for the served path.
@@ -79,10 +86,6 @@ interface ServeDescriptor {
   [OPTIONS]: ServeDescriptorOptions;
   list(): string[];
 }
-declare const $serve: {
-  (options?: ServeDescriptorOptions): ServeDescriptor;
-  [KIND]: string;
-};
 //#endregion
 //#region src/providers/ServerStaticProvider.d.ts
 declare class ServerStaticProvider {
@@ -110,7 +113,7 @@ interface ServeDirectory {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Server Static Module
+* Create static file server with `$static()`.
 *
 * @see {@link ServerStaticProvider}
 * @module alepha.server.static

package/server/swagger.d.ts

@@ -4,6 +4,13 @@ import { ServerStaticProvider } from "alepha/server/static";
 import { OpenAPIV3 } from "openapi-types";
 
 //#region src/descriptors/$swagger.d.ts
+/**
+* Create a new OpenAPI.
+*/
+declare const $swagger: {
+  (options: SwaggerDescriptorOptions): SwaggerDescriptor;
+  [KIND]: string;
+};
 interface SwaggerDescriptorOptions {
   info: OpenAPIV3.InfoObject;
   /**
@@ -77,10 +84,6 @@ interface SwaggerDescriptor {
   [OPTIONS]: SwaggerDescriptorOptions;
   json(): OpenAPIV3.Document;
 }
-declare const $swagger: {
-  (options: SwaggerDescriptorOptions): SwaggerDescriptor;
-  [KIND]: string;
-};
 //#endregion
 //#region src/ServerSwaggerProvider.d.ts
 declare class ServerSwaggerProvider {
@@ -104,8 +107,6 @@ declare class ServerSwaggerProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Server Swagger Module
-*
 * Plugin for Alepha Server that provides Swagger documentation capabilities.
 * It generates OpenAPI v3 documentation for the server's endpoints ($action).
 * It also provides a Swagger UI for interactive API documentation.

package/server.d.ts

@@ -205,6 +205,10 @@ interface HttpAction {
 //#endregion
 //#region src/descriptors/$action.d.ts
 declare const KEY$1 = "ACTION";
+declare const $action: {
+  <TConfig extends RequestConfigSchema>(options: ActionDescriptorOptions<TConfig>): ActionDescriptor<TConfig>;
+  [KIND]: string;
+};
 interface ActionDescriptorOptions<TConfig extends RequestConfigSchema = RequestConfigSchema> extends Omit<ServerRoute, "handler" | "path" | "schema"> {
   /**
    * Name the route.
@@ -286,10 +290,6 @@ interface ActionDescriptor<TConfig extends RequestConfigSchema = RequestConfigSc
    */
   permission: () => string;
 }
-declare const $action: {
-  <TConfig extends RequestConfigSchema>(options: ActionDescriptorOptions<TConfig>): ActionDescriptor<TConfig>;
-  [KIND]: string;
-};
 type ClientRequestEntry<TConfig extends RequestConfigSchema = RequestConfigSchema, T = ClientRequestEntryContainer<TConfig>> = { [K in keyof T as T[K] extends undefined ? never : K]: T[K] };
 type ClientRequestEntryContainer<TConfig extends RequestConfigSchema = RequestConfigSchema> = {
   body: TConfig["body"] extends TSchema ? Static<TConfig["body"]> : undefined;
@@ -354,15 +354,15 @@ interface HttpErrorLike extends Error {
 //#endregion
 //#region src/descriptors/$route.d.ts
 declare const KEY = "ROUTE";
+declare const $route: {
+  <TConfig extends RequestConfigSchema = RequestConfigSchema>(options: RouteDescriptorOptions<TConfig>): RouteDescriptor<TConfig>;
+  [KIND]: string;
+};
 interface RouteDescriptorOptions<TConfig extends RequestConfigSchema = RequestConfigSchema> extends ServerRoute<TConfig> {}
 type RouteDescriptor<TConfig extends RequestConfigSchema = RequestConfigSchema> = {
   [KIND]: typeof KEY;
   [OPTIONS]: RouteDescriptorOptions<TConfig>;
 };
-declare const $route: {
-  <TConfig extends RequestConfigSchema = RequestConfigSchema>(options: RouteDescriptorOptions<TConfig>): RouteDescriptor<TConfig>;
-  [KIND]: string;
-};
 //#endregion
 //#region src/errors/BadRequestError.d.ts
 declare class BadRequestError extends HttpError {
@@ -679,6 +679,159 @@ declare module "alepha" {
     };
   }
 }
+/**
+ * Provides high-performance HTTP server capabilities with declarative routing and action descriptors.
+ *
+ * The server module enables building REST APIs and web applications using `$route` and `$action` descriptors
+ * 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.
+ *
+ * **Key Features:**
+ * - Declarative route definition with `$route` descriptor
+ * - API action handlers with `$action` descriptor
+ * - Schema validation for requests and responses
+ * - Automatic body parsing and response formatting
+ * - Built-in middleware system and error handling
+ * - Type-safe request parameters and response data
+ * - Integration with authentication and security modules
+ *
+ * **Basic Routing:**
+ * ```ts
+ * import { Alepha, run, t } from "alepha";
+ * import { AlephaServer, $route } from "alepha/server";
+ *
+ * class ApiRoutes {
+ *   // Simple GET route
+ *   getUsers = $route({
+ *     path: "/api/users",
+ *     method: "GET",
+ *     handler: async () => {
+ *       const users = await getAllUsers();
+ *       return Response.json(users);
+ *     },
+ *   });
+ *
+ *   // POST route with body validation
+ *   createUser = $route({
+ *     path: "/api/users",
+ *     method: "POST",
+ *     schema: {
+ *       body: t.object({
+ *         name: t.string(),
+ *         email: t.string(),
+ *       }),
+ *     },
+ *     handler: async ({ body }) => {
+ *       const user = await createUser(body);
+ *       return Response.json(user, { status: 201 });
+ *     },
+ *   });
+ *
+ *   // Dynamic route with parameters
+ *   getUserById = $route({
+ *     path: "/api/users/:id",
+ *     method: "GET",
+ *     schema: {
+ *       params: t.object({
+ *         id: t.string(),
+ *       }),
+ *     },
+ *     handler: async ({ params }) => {
+ *       const user = await findUserById(params.id);
+ *       if (!user) {
+ *         return new Response("User not found", { status: 404 });
+ *       }
+ *       return Response.json(user);
+ *     },
+ *   });
+ * }
+ *
+ * const alepha = Alepha.create()
+ *   .with(AlephaServer)
+ *   .with(ApiRoutes);
+ *
+ * run(alepha);
+ * ```
+ *
+ * **Action Descriptors:**
+ * ```ts
+ * import { $action } from "alepha/server";
+ *
+ * class UserController {
+ *   // Reusable business logic action
+ *   getUserProfile = $action({
+ *     schema: {
+ *       params: t.object({
+ *         userId: t.string(),
+ *       }),
+ *       response: t.object({
+ *         id: t.string(),
+ *         name: t.string(),
+ *         email: t.string(),
+ *       }),
+ *     },
+ *     handler: async ({ params }) => {
+ *       const user = await getUserById(params.userId);
+ *       return {
+ *         id: user.id,
+ *         name: user.name,
+ *         email: user.email,
+ *       };
+ *     },
+ *   });
+ *
+ *   // Route that uses the action
+ *   profileRoute = $route({
+ *     path: "/api/profile/:userId",
+ *     method: "GET",
+ *     handler: async ({ params }) => {
+ *       const profile = await this.getUserProfile({ params });
+ *       return Response.json(profile);
+ *     },
+ *   });
+ * }
+ * ```
+ *
+ * **Middleware and Error Handling:**
+ * ```ts
+ * class AppServer {
+ *   // Global middleware
+ *   middleware = $route({
+ *     path: "*",
+ *     method: "*",
+ *     handler: async ({ request, next }) => {
+ *       console.log(`${request.method} ${request.url}`);
+ *       try {
+ *         return await next();
+ *       } catch (error) {
+ *         console.error("Request failed:", error);
+ *         return Response.json({ error: "Internal Server Error" }, { status: 500 });
+ *       }
+ *     },
+ *   });
+ *
+ *   // CORS preflight handling
+ *   corsPrelight = $route({
+ *     path: "*",
+ *     method: "OPTIONS",
+ *     handler: async () => {
+ *       return new Response(null, {
+ *         status: 200,
+ *         headers: {
+ *           "Access-Control-Allow-Origin": "*",
+ *           "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE",
+ *           "Access-Control-Allow-Headers": "Content-Type, Authorization",
+ *         },
+ *       });
+ *     },
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link $route}
+ * @see {@link $action}
+ * @module alepha.server
+ */
 declare class AlephaServer implements Module {
   readonly name = "alepha.server";
   readonly $services: (alepha: Alepha) => void;

package/topic/redis.d.ts

@@ -30,8 +30,6 @@ declare class RedisTopicProvider implements TopicProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Topic Redis Module.
-*
 * Plugin for Alepha Topic that provides Redis pub/sub capabilities.
 *
 * @see {@link RedisTopicProvider}

package/topic.d.ts

@@ -32,6 +32,13 @@ type UnSubscribeFn = () => Promise<void>;
 //#endregion
 //#region src/descriptors/$topic.d.ts
 declare const KEY$1 = "TOPIC";
+/**
+ * Create a new topic.
+ */
+declare const $topic: {
+  <T extends TopicMessageSchema>(options: TopicDescriptorOptions<T>): TopicDescriptor<T>;
+  [KIND]: string;
+};
 interface TopicMessageSchema {
   headers?: TSchema;
   payload: TSchema;
@@ -63,13 +70,19 @@ interface TopicWaitOptions<T extends TopicMessageSchema> {
     payload: Static<T["payload"]>;
   }) => boolean;
 }
-declare const $topic: {
-  <T extends TopicMessageSchema>(options: TopicDescriptorOptions<T>): TopicDescriptor<T>;
-  [KIND]: string;
-};
 //#endregion
 //#region src/descriptors/$subscriber.d.ts
 declare const KEY = "SUBSCRIBER";
+/**
+ * Subscriber descriptor.
+ *
+ * @param options - The subscriber options.
+ * @returns The descriptor value.
+ */
+declare const $subscriber: {
+  <T extends TopicMessageSchema>(options: SubscriberDescriptorOptions<T>): SubscriberDescriptor<T>;
+  [KIND]: string;
+};
 interface SubscriberDescriptorOptions<T extends TopicMessageSchema = TopicMessageSchema> {
   topic: TopicDescriptor<T>;
   handler: (message: {
@@ -81,16 +94,6 @@ interface SubscriberDescriptor<T extends TopicMessageSchema = TopicMessageSchema
   [OPTIONS]: SubscriberDescriptorOptions<T>;
   topic: () => TopicDescriptor<T>;
 }
-/**
- * Subscriber descriptor.
- *
- * @param options - The subscriber options.
- * @returns The descriptor value.
- */
-declare const $subscriber: {
-  <T extends TopicMessageSchema>(options: SubscriberDescriptorOptions<T>): SubscriberDescriptor<T>;
-  [KIND]: string;
-};
 //#endregion
 //#region src/errors/TopicTimeoutError.d.ts
 declare class TopicTimeoutError extends Error {
@@ -196,8 +199,6 @@ declare class TopicDescriptorProvider {
 //#endregion
 //#region src/index.d.ts
 /**
- * Alepha Topic Module
- *
  * Generic interface for pub/sub messaging.
  * Gives you the ability to create topics and subscribers.
  * This module provides only a memory implementation of the topic provider.