alepha 0.9.5 → 0.10.0

package/react.d.ts

@@ -6,7 +6,7 @@ import { ClientScope, HttpVirtualClient, LinkProvider, VirtualAction } from "ale
 import * as _alepha_logger1 from "alepha/logger";
 import * as react0 from "react";
 import React, { AnchorHTMLAttributes, CSSProperties, ErrorInfo, FC, PropsWithChildren, ReactNode } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react_jsx_runtime1 from "react/jsx-runtime";
 import { ServerStaticProvider } from "alepha/server/static";
 import { DateTimeProvider } from "alepha/datetime";
 import { Route, RouterProvider } from "alepha/router";
@@ -165,6 +165,91 @@ interface CreateLayersResult {
 //#region src/descriptors/$page.d.ts
 /**
  * Main descriptor for defining a React route in the application.
+ *
+ * The $page descriptor is the core building block for creating type-safe, SSR-enabled React routes.
+ * It provides a declarative way to define pages with powerful features:
+ *
+ * **Routing & Navigation**
+ * - URL pattern matching with parameters (e.g., `/users/:id`)
+ * - Nested routing with parent-child relationships
+ * - Type-safe URL parameter and query string validation
+ *
+ * **Data Loading**
+ * - Server-side data fetching with the `resolve` function
+ * - Automatic serialization and hydration for SSR
+ * - Access to request context, URL params, and parent data
+ *
+ * **Component Loading**
+ * - Direct component rendering or lazy loading for code splitting
+ * - Client-only rendering when browser APIs are needed
+ * - Automatic fallback handling during hydration
+ *
+ * **Performance Optimization**
+ * - Static generation for pre-rendered pages at build time
+ * - Server-side caching with configurable TTL and providers
+ * - Code splitting through lazy component loading
+ *
+ * **Error Handling**
+ * - Custom error handlers with support for redirects
+ * - Hierarchical error handling (child → parent)
+ * - HTTP status code handling (404, 401, etc.)
+ *
+ * **Page Animations**
+ * - CSS-based enter/exit animations
+ * - Dynamic animations based on page state
+ * - Custom timing and easing functions
+ *
+ * **Lifecycle Management**
+ * - Server response hooks for headers and status codes
+ * - Page leave handlers for cleanup (browser only)
+ * - Permission-based access control
+ *
+ * @example Simple page with data fetching
+ * ```typescript
+ * const userProfile = $page({
+ *   path: "/users/:id",
+ *   schema: {
+ *     params: t.object({ id: t.int() }),
+ *     query: t.object({ tab: t.optional(t.string()) })
+ *   },
+ *   resolve: async ({ params }) => {
+ *     const user = await userApi.getUser(params.id);
+ *     return { user };
+ *   },
+ *   lazy: () => import("./UserProfile.tsx")
+ * });
+ * ```
+ *
+ * @example Nested routing with error handling
+ * ```typescript
+ * const projectSection = $page({
+ *   path: "/projects/:id",
+ *   children: () => [projectBoard, projectSettings],
+ *   resolve: async ({ params }) => {
+ *     const project = await projectApi.get(params.id);
+ *     return { project };
+ *   },
+ *   errorHandler: (error) => {
+ *     if (HttpError.is(error, 404)) {
+ *       return <ProjectNotFound />;
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example Static generation with caching
+ * ```typescript
+ * const blogPost = $page({
+ *   path: "/blog/:slug",
+ *   static: {
+ *     entries: posts.map(p => ({ params: { slug: p.slug } }))
+ *   },
+ *   resolve: async ({ params }) => {
+ *     const post = await loadPost(params.slug);
+ *     return { post };
+ *   }
+ * });
+ * ```
  */
 declare const $page: {
   <TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = any, TPropsParent extends object = TPropsParentDefault>(options: PageDescriptorOptions<TConfig, TProps, TPropsParent>): PageDescriptor<TConfig, TProps, TPropsParent>;
@@ -534,25 +619,25 @@ interface ErrorViewerProps {
 declare const ErrorViewer: ({
   error,
   alepha
-}: ErrorViewerProps) => react_jsx_runtime0.JSX.Element;
+}: ErrorViewerProps) => react_jsx_runtime1.JSX.Element;
 //#endregion
 //#region src/components/Link.d.ts
 interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
   href: string;
 }
-declare const Link: (props: LinkProps) => react_jsx_runtime0.JSX.Element;
+declare const Link: (props: LinkProps) => react_jsx_runtime1.JSX.Element;
 //#endregion
 //#region src/components/NestedView.d.ts
 interface NestedViewProps {
   children?: ReactNode;
   errorBoundary?: false | ((error: Error) => ReactNode);
 }
-declare const _default: react0.MemoExoticComponent<(props: NestedViewProps) => react_jsx_runtime0.JSX.Element>;
+declare const _default: react0.MemoExoticComponent<(props: NestedViewProps) => react_jsx_runtime1.JSX.Element>;
 //#endregion
 //#region src/components/NotFound.d.ts
 declare function NotFoundPage(props: {
   style?: CSSProperties;
-}): react_jsx_runtime0.JSX.Element;
+}): react_jsx_runtime1.JSX.Element;
 //#endregion
 //#region src/contexts/AlephaContext.d.ts
 declare const AlephaContext: react0.Context<Alepha | undefined>;
@@ -586,7 +671,7 @@ interface UseActiveHook {
  *
  * - alepha.state() for state management
  * - alepha.inject() for dependency injection
- * - alepha.emit() for event handling
+ * - alepha.events.emit() for event handling
  * etc...
  */
 declare const useAlepha: () => Alepha;
@@ -610,7 +695,7 @@ declare const useInject: <T extends object>(service: Service<T>) => T;
 /**
  * Not well tested. Use with caution.
  */
-declare const useQueryParams: <T extends TObject>(schema: T, options?: UseQueryParamsHookOptions) => [Static<T>, (data: Static<T>) => void];
+declare const useQueryParams: <T extends TObject>(schema: T, options?: UseQueryParamsHookOptions) => [Partial<Static<T>>, (data: Static<T>) => void];
 interface UseQueryParamsHookOptions {
   format?: "base64" | "querystring";
   key?: string;
@@ -739,6 +824,7 @@ declare class ReactServerProvider {
     REACT_ROOT_ID: string;
   };
   protected readonly ROOT_DIV_REGEX: RegExp;
+  protected preprocessedTemplate: PreprocessedTemplate | null;
   readonly onConfigure: _alepha_core14.HookDescriptor<"configure">;
   get template(): string;
   protected registerPages(templateLoader: TemplateLoader): Promise<void>;
@@ -751,11 +837,18 @@ declare class ReactServerProvider {
   protected createRenderFunction(name: string, withIndex?: boolean): (options?: PageDescriptorRenderOptions) => Promise<PageDescriptorRenderResult>;
   protected createHandler(route: PageRoute, templateLoader: TemplateLoader): ServerHandler;
   renderToHtml(template: string, state: ReactRouterState, hydration?: boolean): string | Redirection;
+  protected preprocessTemplate(template: string): PreprocessedTemplate;
   protected fillTemplate(response: {
     html: string;
   }, app: string, script: string): void;
 }
 type TemplateLoader = () => Promise<string | undefined>;
+interface PreprocessedTemplate {
+  beforeApp: string;
+  afterApp: string;
+  beforeScript: string;
+  afterScript: string;
+}
 //#endregion
 //#region src/index.d.ts
 declare module "alepha" {

package/redis.d.ts

@@ -1,13 +1,13 @@
 import * as _alepha_core3 from "alepha";
-import { Alepha, Static, TNumber, TObject, TOptional, TString } 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>> {}

package/security.d.ts

@@ -3,19 +3,19 @@ import { Alepha, Descriptor, KIND, Static } from "alepha";
 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>;

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_typebox0 from "@sinclair/typebox";
+import * as typebox0 from "typebox";
 
 //#region src/schemas/apiLinksResponseSchema.d.ts
-declare const apiLinkSchema: _sinclair_typebox0.TObject<{
-  name: _sinclair_typebox0.TString;
-  group: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  path: _sinclair_typebox0.TString;
-  method: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  requestBodyType: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  service: _sinclair_typebox0.TOptional<_sinclair_typebox0.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_typebox0.TObject<{
-  prefix: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  links: _sinclair_typebox0.TArray<_sinclair_typebox0.TObject<{
-    name: _sinclair_typebox0.TString;
-    group: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-    path: _sinclair_typebox0.TString;
-    method: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-    requestBodyType: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-    service: _sinclair_typebox0.TOptional<_sinclair_typebox0.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_typebox0.TObject<{
-      prefix: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-      links: _sinclair_typebox0.TArray<_sinclair_typebox0.TObject<{
-        name: _sinclair_typebox0.TString;
-        group: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-        path: _sinclair_typebox0.TString;
-        method: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-        requestBodyType: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-        service: _sinclair_typebox0.TOptional<_sinclair_typebox0.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_typebox0.TObject<{
-      name: _sinclair_typebox0.TString;
+    params: typebox0.TObject<{
+      name: typebox0.TString;
     }>;
-    response: _sinclair_typebox0.TRecord<_sinclair_typebox0.TString, _sinclair_typebox0.TAny>;
+    response: typebox0.TRecord<string, typebox0.TAny>;
   }>;
   getSchemaByName(name: string, options?: GetApiLinksOptions): Promise<RequestConfigSchema>;
   /**