alepha 0.9.4 → 0.10.0

package/redis.d.ts

@@ -1,13 +1,13 @@
-import * as _alepha_core1 from "alepha";
-import { Alepha, Static, TNumber, TObject, TOptional, TString } from "alepha";
+import * as _alepha_core3 from "alepha";
+import { Alepha, Static } from "alepha";
 import * as _alepha_logger0 from "alepha/logger";
 import { RedisClientType, SetOptions, createClient } from "@redis/client";
 
 //#region src/providers/RedisProvider.d.ts
-declare const envSchema: TObject<{
-  REDIS_PORT: TNumber;
-  REDIS_HOST: TString;
-  REDIS_PASSWORD: TOptional<TString>;
+declare const envSchema: _alepha_core3.TObject<{
+  REDIS_PORT: _alepha_core3.TInteger;
+  REDIS_HOST: _alepha_core3.TString;
+  REDIS_PASSWORD: _alepha_core3.TOptional<_alepha_core3.TString>;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
@@ -30,8 +30,8 @@ declare class RedisProvider {
   };
   protected readonly client: RedisClient;
   get publisher(): RedisClient;
-  protected readonly start: _alepha_core1.HookDescriptor<"start">;
-  protected readonly stop: _alepha_core1.HookDescriptor<"stop">;
+  protected readonly start: _alepha_core3.HookDescriptor<"start">;
+  protected readonly stop: _alepha_core3.HookDescriptor<"stop">;
   /**
    * Connect to the Redis server.
    */
@@ -59,8 +59,8 @@ declare class RedisSubscriberProvider {
   protected readonly redisProvider: RedisProvider;
   protected readonly client: RedisClient;
   get subscriber(): RedisClient;
-  protected readonly start: _alepha_core1.HookDescriptor<"start">;
-  protected readonly stop: _alepha_core1.HookDescriptor<"stop">;
+  protected readonly start: _alepha_core3.HookDescriptor<"start">;
+  protected readonly stop: _alepha_core3.HookDescriptor<"stop">;
   connect(): Promise<void>;
   close(): Promise<void>;
   /**
@@ -76,7 +76,7 @@ declare class RedisSubscriberProvider {
  * @see {@link RedisProvider}
  * @module alepha.redis
  */
-declare const AlephaRedis: _alepha_core1.Service<_alepha_core1.Module>;
+declare const AlephaRedis: _alepha_core3.Service<_alepha_core3.Module>;
 //#endregion
 export { AlephaRedis, RedisClient, RedisClientOptions, RedisProvider, RedisSetOptions, RedisSubscriberProvider };
 //# sourceMappingURL=index.d.ts.map

package/router.d.ts

@@ -3,6 +3,7 @@ declare abstract class RouterProvider<T extends Route = Route> {
   protected routePathRegex: RegExp;
   protected tree: Tree<T>;
   match(path: string): RouteMatch<T>;
+  protected test(path: string): void;
   protected push(route: T): void;
   protected createRouteMatch(path: string): RouteMatch<T>;
   protected mapParams(match: RouteMatch<T>): RouteMatch<T>;

package/security.d.ts

@@ -1,21 +1,21 @@
 import * as _alepha_core1 from "alepha";
 import { Alepha, Descriptor, KIND, Static } from "alepha";
-import * as _alepha_logger1 from "alepha/logger";
+import * as _alepha_logger0 from "alepha/logger";
 import { DateTimeProvider, Duration, DurationLike } from "alepha/datetime";
 import { CryptoKey, FlattenedJWSInput, JSONWebKeySet, JWSHeaderParameters, JWTHeaderParameters, JWTPayload, JWTVerifyResult, KeyObject } from "jose";
-import * as _sinclair_typebox13 from "@sinclair/typebox";
+import * as typebox0 from "typebox";
 import { JWTVerifyOptions } from "jose/jwt/verify";
 
 //#region src/schemas/userAccountInfoSchema.d.ts
-declare const userAccountInfoSchema: _sinclair_typebox13.TObject<{
-  id: _sinclair_typebox13.TString;
-  name: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  email: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  username: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  picture: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  sessionId: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  organizations: _sinclair_typebox13.TOptional<_sinclair_typebox13.TArray<_sinclair_typebox13.TString>>;
-  roles: _sinclair_typebox13.TOptional<_sinclair_typebox13.TArray<_sinclair_typebox13.TString>>;
+declare const userAccountInfoSchema: typebox0.TObject<{
+  id: typebox0.TString;
+  name: typebox0.TOptional<typebox0.TString>;
+  email: typebox0.TOptional<typebox0.TString>;
+  username: typebox0.TOptional<typebox0.TString>;
+  picture: typebox0.TOptional<typebox0.TString>;
+  sessionId: typebox0.TOptional<typebox0.TString>;
+  organizations: typebox0.TOptional<typebox0.TArray<typebox0.TString>>;
+  roles: typebox0.TOptional<typebox0.TArray<typebox0.TString>>;
 }>;
 type UserAccount = Static<typeof userAccountInfoSchema>;
 //#endregion
@@ -41,24 +41,24 @@ interface UserAccountToken extends UserAccount {
 }
 //#endregion
 //#region src/schemas/permissionSchema.d.ts
-declare const permissionSchema: _sinclair_typebox13.TObject<{
-  name: _sinclair_typebox13.TString;
-  group: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  description: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  method: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  path: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
+declare const permissionSchema: typebox0.TObject<{
+  name: typebox0.TString;
+  group: typebox0.TOptional<typebox0.TString>;
+  description: typebox0.TOptional<typebox0.TString>;
+  method: typebox0.TOptional<typebox0.TString>;
+  path: typebox0.TOptional<typebox0.TString>;
 }>;
 type Permission = Static<typeof permissionSchema>;
 //#endregion
 //#region src/schemas/roleSchema.d.ts
-declare const roleSchema: _sinclair_typebox13.TObject<{
-  name: _sinclair_typebox13.TString;
-  description: _sinclair_typebox13.TOptional<_sinclair_typebox13.TString>;
-  default: _sinclair_typebox13.TOptional<_sinclair_typebox13.TBoolean>;
-  permissions: _sinclair_typebox13.TArray<_sinclair_typebox13.TObject<{
-    name: _sinclair_typebox13.TString;
-    ownership: _sinclair_typebox13.TOptional<_sinclair_typebox13.TBoolean>;
-    exclude: _sinclair_typebox13.TOptional<_sinclair_typebox13.TArray<_sinclair_typebox13.TString>>;
+declare const roleSchema: typebox0.TObject<{
+  name: typebox0.TString;
+  description: typebox0.TOptional<typebox0.TString>;
+  default: typebox0.TOptional<typebox0.TBoolean>;
+  permissions: typebox0.TArray<typebox0.TObject<{
+    name: typebox0.TString;
+    ownership: typebox0.TOptional<typebox0.TBoolean>;
+    exclude: typebox0.TOptional<typebox0.TArray<typebox0.TString>>;
   }>>;
 }>;
 type Role = Static<typeof roleSchema>;
@@ -68,7 +68,7 @@ type Role = Static<typeof roleSchema>;
  * Provides utilities for working with JSON Web Tokens (JWT).
  */
 declare class JwtProvider {
-  protected readonly log: _alepha_logger1.Logger;
+  protected readonly log: _alepha_logger0.Logger;
   protected readonly keystore: KeyLoaderHolder[];
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly encoder: TextEncoder;
@@ -140,7 +140,7 @@ declare class SecurityProvider {
   protected readonly UNKNOWN_USER_NAME = "Anonymous User";
   protected readonly PERMISSION_REGEXP: RegExp;
   protected readonly PERMISSION_REGEXP_WILDCARD: RegExp;
-  protected readonly log: _alepha_logger1.Logger;
+  protected readonly log: _alepha_logger0.Logger;
   protected readonly jwt: JwtProvider;
   protected readonly env: {
     SECURITY_SECRET_KEY: string;
@@ -154,7 +154,7 @@ declare class SecurityProvider {
    * The realms configured for the security provider.
    */
   protected readonly realms: Realm[];
-  protected configure: _alepha_core1.HookDescriptor<"start">;
+  protected start: _alepha_core1.HookDescriptor<"start">;
   /**
    * Adds a role to one or more realms.
    *
@@ -397,7 +397,7 @@ declare class RealmDescriptor extends Descriptor<RealmDescriptorOptions> {
   protected readonly securityProvider: SecurityProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly jwt: JwtProvider;
-  protected readonly log: _alepha_logger1.Logger;
+  protected readonly log: _alepha_logger0.Logger;
   get name(): string;
   get accessTokenExpiration(): Duration;
   get refreshTokenExpiration(): Duration;

package/server/cache.d.ts

@@ -10,6 +10,7 @@ import { RequestConfigSchema, ServerRequest, ServerRoute } from "alepha/server";
 declare module "alepha/server" {
   interface ServerRoute {
     cache?: ServerRouteCache;
+    etag?: string;
   }
   interface ActionDescriptor<TConfig extends RequestConfigSchema> {
     invalidate: () => Promise<void>;

package/server/health.d.ts

@@ -2,7 +2,7 @@ import * as _alepha_core0 from "alepha";
 import { Alepha } from "alepha";
 import * as _alepha_server0 from "alepha/server";
 import { DateTimeProvider } from "alepha/datetime";
-import * as _sinclair_typebox0 from "@sinclair/typebox";
+import * as typebox0 from "typebox";
 
 //#region src/providers/ServerHealthProvider.d.ts
 /**
@@ -14,11 +14,11 @@ declare class ServerHealthProvider {
   protected readonly time: DateTimeProvider;
   protected readonly alepha: Alepha;
   readonly health: _alepha_server0.RouteDescriptor<{
-    response: _sinclair_typebox0.TObject<{
-      message: _sinclair_typebox0.TString;
-      uptime: _sinclair_typebox0.TNumber;
-      date: _sinclair_typebox0.TString;
-      ready: _sinclair_typebox0.TBoolean;
+    response: typebox0.TObject<{
+      message: typebox0.TString;
+      uptime: typebox0.TNumber;
+      date: typebox0.TString;
+      ready: typebox0.TBoolean;
     }>;
   }>;
 }

package/server/links.d.ts

@@ -7,26 +7,26 @@ import * as _alepha_logger0 from "alepha/logger";
 import * as _alepha_retry0 from "alepha/retry";
 import { ProxyDescriptorOptions, ServerProxyProvider } from "alepha/server/proxy";
 import { ServiceAccountDescriptor, UserAccountToken } from "alepha/security";
-import * as _sinclair_typebox19 from "@sinclair/typebox";
+import * as typebox0 from "typebox";
 
 //#region src/schemas/apiLinksResponseSchema.d.ts
-declare const apiLinkSchema: _sinclair_typebox19.TObject<{
-  name: _sinclair_typebox19.TString;
-  group: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-  path: _sinclair_typebox19.TString;
-  method: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-  requestBodyType: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-  service: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
+declare const apiLinkSchema: typebox0.TObject<{
+  name: typebox0.TString;
+  group: typebox0.TOptional<typebox0.TString>;
+  path: typebox0.TString;
+  method: typebox0.TOptional<typebox0.TString>;
+  requestBodyType: typebox0.TOptional<typebox0.TString>;
+  service: typebox0.TOptional<typebox0.TString>;
 }>;
-declare const apiLinksResponseSchema: _sinclair_typebox19.TObject<{
-  prefix: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-  links: _sinclair_typebox19.TArray<_sinclair_typebox19.TObject<{
-    name: _sinclair_typebox19.TString;
-    group: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-    path: _sinclair_typebox19.TString;
-    method: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-    requestBodyType: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-    service: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
+declare const apiLinksResponseSchema: typebox0.TObject<{
+  prefix: typebox0.TOptional<typebox0.TString>;
+  links: typebox0.TArray<typebox0.TObject<{
+    name: typebox0.TString;
+    group: typebox0.TOptional<typebox0.TString>;
+    path: typebox0.TString;
+    method: typebox0.TOptional<typebox0.TString>;
+    requestBodyType: typebox0.TOptional<typebox0.TString>;
+    service: typebox0.TOptional<typebox0.TString>;
   }>>;
 }>;
 type ApiLinksResponse = Static<typeof apiLinksResponseSchema>;
@@ -257,15 +257,15 @@ declare class ServerLinksProvider {
    * This is based on the user's permissions.
    */
   readonly links: _alepha_server0.RouteDescriptor<{
-    response: _sinclair_typebox19.TObject<{
-      prefix: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-      links: _sinclair_typebox19.TArray<_sinclair_typebox19.TObject<{
-        name: _sinclair_typebox19.TString;
-        group: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-        path: _sinclair_typebox19.TString;
-        method: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-        requestBodyType: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
-        service: _sinclair_typebox19.TOptional<_sinclair_typebox19.TString>;
+    response: typebox0.TObject<{
+      prefix: typebox0.TOptional<typebox0.TString>;
+      links: typebox0.TArray<typebox0.TObject<{
+        name: typebox0.TString;
+        group: typebox0.TOptional<typebox0.TString>;
+        path: typebox0.TString;
+        method: typebox0.TOptional<typebox0.TString>;
+        requestBodyType: typebox0.TOptional<typebox0.TString>;
+        service: typebox0.TOptional<typebox0.TString>;
       }>>;
     }>;
   }>;
@@ -276,10 +276,10 @@ declare class ServerLinksProvider {
    * I mean for 150+ links, you got 50ms of serialization time.
    */
   readonly schema: _alepha_server0.RouteDescriptor<{
-    params: _sinclair_typebox19.TObject<{
-      name: _sinclair_typebox19.TString;
+    params: typebox0.TObject<{
+      name: typebox0.TString;
     }>;
-    response: _sinclair_typebox19.TRecord<_sinclair_typebox19.TString, _sinclair_typebox19.TAny>;
+    response: typebox0.TRecord<string, typebox0.TAny>;
   }>;
   getSchemaByName(name: string, options?: GetApiLinksOptions): Promise<RequestConfigSchema>;
   /**
@@ -299,6 +299,17 @@ declare module "alepha" {
     api?: ApiLinksResponse;
   }
 }
+/**
+ * Provides server-side link management and remote capabilities for client-server interactions.
+ *
+ * The server-links module enables declarative link definitions using `$remote` and `$client` descriptors,
+ * facilitating seamless API endpoint management and client-server communication. It integrates with server
+ * security features to ensure safe and controlled access to resources.
+ *
+ * @see {@link $remote}
+ * @see {@link $client}
+ * @module alepha.server.links
+ */
 declare const AlephaServerLinks: _alepha_core2.Service<_alepha_core2.Module>;
 //#endregion
 export { $client, $remote, AlephaServerLinks, ApiLink, ApiLinksResponse, ClientScope, FetchLinksOptions, GetApiLinksOptions, HttpClientLink, HttpVirtualClient, LinkProvider, RemoteDescriptor, RemoteDescriptorOptions, RemoteDescriptorProvider, ServerLinksProvider, ServerRemote, VirtualAction, apiLinkSchema, apiLinksResponseSchema };

package/server/proxy.d.ts

@@ -4,16 +4,208 @@ import { ServerHandler, ServerRequest, ServerRouterProvider } from "alepha/serve
 import * as _alepha_logger0 from "alepha/logger";
 
 //#region src/descriptors/$proxy.d.ts
+
+/**
+ * Creates a proxy descriptor to forward requests to another server.
+ *
+ * This descriptor enables you to create reverse proxy functionality, allowing your Alepha server
+ * to forward requests to other services while maintaining a unified API surface. It's particularly
+ * useful for microservice architectures, API gateways, or when you need to aggregate multiple
+ * services behind a single endpoint.
+ *
+ * **Key Features**
+ *
+ * - **Path-based routing**: Match specific paths or patterns to proxy
+ * - **Dynamic targets**: Support both static and dynamic target resolution
+ * - **Request/Response hooks**: Modify requests before forwarding and responses after receiving
+ * - **URL rewriting**: Transform URLs before forwarding to the target
+ * - **Conditional proxying**: Enable/disable proxies based on environment or conditions
+ *
+ * @example
+ * **Basic proxy setup:**
+ * ```ts
+ * import { $proxy } from "alepha/server-proxy";
+ *
+ * class ApiGateway {
+ *   // Forward all /api/* requests to external service
+ *   api = $proxy({
+ *     path: "/api/*",
+ *     target: "https://api.example.com"
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Dynamic target with environment-based routing:**
+ * ```ts
+ * class ApiGateway {
+ *   // Route to different environments based on configuration
+ *   api = $proxy({
+ *     path: "/api/*",
+ *     target: () => process.env.NODE_ENV === "production"
+ *       ? "https://api.prod.example.com"
+ *       : "https://api.dev.example.com"
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Advanced proxy with request/response modification:**
+ * ```ts
+ * class SecureProxy {
+ *   secure = $proxy({
+ *     path: "/secure/*",
+ *     target: "https://secure-api.example.com",
+ *     beforeRequest: async (request, proxyRequest) => {
+ *       // Add authentication headers
+ *       proxyRequest.headers = {
+ *         ...proxyRequest.headers,
+ *         'Authorization': `Bearer ${await getServiceToken()}`,
+ *         'X-Forwarded-For': request.headers['x-forwarded-for'] || request.ip
+ *       };
+ *     },
+ *     afterResponse: async (request, proxyResponse) => {
+ *       // Log response for monitoring
+ *       console.log(`Proxied ${request.url} -> ${proxyResponse.status}`);
+ *     },
+ *     rewrite: (url) => {
+ *       // Remove /secure prefix when forwarding
+ *       url.pathname = url.pathname.replace('/secure', '');
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Conditional proxy based on feature flags:**
+ * ```ts
+ * class FeatureProxy {
+ *   newApi = $proxy({
+ *     path: "/v2/*",
+ *     target: "https://new-api.example.com",
+ *     disabled: !process.env.ENABLE_V2_API // Disable if feature flag is off
+ *   });
+ * }
+ * ```
+ */
 declare const $proxy: {
   (options: ProxyDescriptorOptions): ProxyDescriptor;
   [KIND]: typeof ProxyDescriptor;
 };
 type ProxyDescriptorOptions = {
+  /**
+   * Path pattern to match for proxying requests.
+   *
+   * Supports wildcards and path parameters:
+   * - `/api/*` - Matches all paths starting with `/api/`
+   * - `/api/v1/*` - Matches all paths starting with `/api/v1/`
+   * - `/users/:id` - Matches `/users/123`, `/users/abc`, etc.
+   *
+   * @example "/api/*"
+   * @example "/secure/admin/*"
+   * @example "/users/:id/posts"
+   */
   path: string;
+  /**
+   * Target URL to which matching requests should be forwarded.
+   *
+   * Can be either:
+   * - **Static string**: A fixed URL like `"https://api.example.com"`
+   * - **Dynamic function**: A function that returns the URL, enabling runtime target resolution
+   *
+   * The target URL will be combined with the remaining path from the original request.
+   *
+   * @example "https://api.example.com"
+   * @example () => process.env.API_URL || "http://localhost:3001"
+   */
   target: string | (() => string);
+  /**
+   * Whether this proxy is disabled.
+   *
+   * When `true`, requests matching the path will not be proxied and will be handled
+   * by other routes or return 404. Useful for feature toggles or conditional proxying.
+   *
+   * @default false
+   * @example !process.env.ENABLE_PROXY
+   */
   disabled?: boolean;
+  /**
+   * Hook called before forwarding the request to the target server.
+   *
+   * Use this to:
+   * - Add authentication headers
+   * - Modify request headers or body
+   * - Add request tracking/logging
+   * - Transform the request before forwarding
+   *
+   * @param request - The original incoming server request
+   * @param proxyRequest - The request that will be sent to the target (modifiable)
+   *
+   * @example
+   * ```ts
+   * beforeRequest: async (request, proxyRequest) => {
+   *   proxyRequest.headers = {
+   *     ...proxyRequest.headers,
+   *     'Authorization': `Bearer ${await getToken()}`,
+   *     'X-Request-ID': generateRequestId()
+   *   };
+   * }
+   * ```
+   */
   beforeRequest?: (request: ServerRequest, proxyRequest: RequestInit) => Async<void>;
+  /**
+   * Hook called after receiving the response from the target server.
+   *
+   * Use this to:
+   * - Log response details for monitoring
+   * - Add custom headers to the response
+   * - Transform response data
+   * - Handle error responses
+   *
+   * @param request - The original incoming server request
+   * @param proxyResponse - The response received from the target server
+   *
+   * @example
+   * ```ts
+   * afterResponse: async (request, proxyResponse) => {
+   *   console.log(`Proxy ${request.method} ${request.url} -> ${proxyResponse.status}`);
+   *
+   *   if (!proxyResponse.ok) {
+   *     await logError(`Proxy error: ${proxyResponse.status}`, { request, response: proxyResponse });
+   *   }
+   * }
+   * ```
+   */
   afterResponse?: (request: ServerRequest, proxyResponse: Response) => Async<void>;
+  /**
+   * Function to rewrite the URL before sending to the target server.
+   *
+   * Use this to:
+   * - Remove or add path prefixes
+   * - Transform path parameters
+   * - Modify query parameters
+   * - Change the URL structure entirely
+   *
+   * The function receives a mutable URL object and should modify it in-place.
+   *
+   * @param url - The URL object to modify (mutable)
+   *
+   * @example
+   * ```ts
+   * // Remove /api prefix when forwarding
+   * rewrite: (url) => {
+   *   url.pathname = url.pathname.replace('/api', '');
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Add version prefix
+   * rewrite: (url) => {
+   *   url.pathname = `/v2${url.pathname}`;
+   * }
+   * ```
+   */
   rewrite?: (url: URL) => void;
 };
 declare class ProxyDescriptor extends Descriptor<ProxyDescriptorOptions> {}