alepha 0.6.9 → 0.7.0

package/react.d.ts

@@ -1,9 +1,9 @@
 import * as _alepha_core from '@alepha/core';
 import { Alepha, Static as Static$1, TSchema as TSchema$1, KIND, OPTIONS, Async, Class, TObject as TObject$1 } from '@alepha/core';
 import * as _alepha_server from '@alepha/server';
-import { HttpClientLink, HttpClient, ServerRouterProvider, ServerHandler, ServerRequest } from '@alepha/server';
-import * as react from 'react';
-import react__default, { ReactNode, FC, AnchorHTMLAttributes } from 'react';
+import { HttpClientLink, HttpClient, ApiLinksResponse, ServerRouterProvider, ServerHandler, ServerRequest } from '@alepha/server';
+import * as React from 'react';
+import React__default, { ReactNode, FC, AnchorHTMLAttributes, PropsWithChildren, ErrorInfo } from 'react';
 import { Root } from 'react-dom/client';
 import { RouterProvider, Route } from '@alepha/router';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -156,7 +156,7 @@ declare class BrowserRouterProvider extends RouterProvider<BrowserRoute> {
     add(entry: PageRouteEntry): void;
     protected readonly configure: _alepha_core.HookDescriptor<"configure">;
     transition(url: URL, options?: TransitionOptions): Promise<RouterRenderResult>;
-    root(state: RouterState, context?: PageReactContext): ReactNode;
+    root(state: RouterState, context: PageReactContext): ReactNode;
 }
 
 declare const envSchema$1: _alepha_core.TObject<{
@@ -193,10 +193,7 @@ declare class ReactBrowserProvider {
     protected render(options?: {
         url?: string;
         previous?: PreviousLayerData[];
-    }): Promise<{
-        url: string;
-        head: Head;
-    }>;
+    }): Promise<RouterRenderResult>;
     /**
      * Get embedded layers from the server.
      *
@@ -218,6 +215,7 @@ declare class ReactBrowserProvider {
 interface RouterGoOptions {
     replace?: boolean;
     match?: TransitionOptions;
+    params?: Record<string, string>;
 }
 interface ReactHydrationState {
     layers?: PreviousLayerData[];
@@ -265,28 +263,16 @@ declare class RouterHookApi {
     createHref(pathname: HrefLike, layer?: {
         path: string;
     }): string;
-    /**
-     *
-     * @param path
-     * @param options
-     */
-    go(path: HrefLike, options?: RouterGoOptions): Promise<void>;
-    /**
-     *
-     * @param path
-     */
-    createAnchorProps(path: string): AnchorProps;
+    go(path: string, options?: RouterGoOptions): Promise<void>;
+    go<T extends object>(path: keyof VirtualRouter<T>, options?: RouterGoOptions): Promise<void>;
+    anchor(path: string): AnchorProps;
     /**
      * Set query params.
      *
      * @param record
      * @param options
      */
-    setQueryParams(record: Record<string, any>, options?: {
-        /**
-         * If true, this will merge current query params with the new ones.
-         */
-        merge?: boolean;
+    setQueryParams(record: Record<string, any> | ((queryParams: Record<string, any>) => Record<string, any>), options?: {
         /**
          * If true, this will add a new entry to the history stack.
          */
@@ -299,6 +285,9 @@ type HrefLike = string | {
         name?: string;
     };
 };
+type VirtualRouter<T> = {
+    [K in keyof T as T[K] extends PageDescriptor ? K : never]: T[K];
+};
 
 declare const KEY = "PAGE";
 interface PageConfigSchema {
@@ -324,10 +313,7 @@ interface PageDescriptorOptions<TConfig extends PageConfigSchema = PageConfigSch
     };
     can?: () => boolean;
     head?: Head | ((props: TProps, previous?: Head) => Head);
-    errorHandler?: FC<{
-        error: Error;
-        url: string;
-    }>;
+    errorHandler?: (error: Error) => ReactNode;
 }
 interface PageDescriptor<TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = TPropsDefault, TPropsParent extends object = TPropsParentDefault> {
     [KIND]: typeof KEY;
@@ -361,11 +347,7 @@ interface PageRequestConfig<TConfig extends PageConfigSchema = PageConfigSchema>
     params: TConfig["params"] extends TSchema$1 ? Static$1<TConfig["params"]> : Record<string, string>;
     query: TConfig["query"] extends TSchema$1 ? Static$1<TConfig["query"]> : Record<string, string>;
 }
-type PageResolve<TConfig extends PageConfigSchema = PageConfigSchema, TPropsParent extends object = TPropsParentDefault> = PageRequestConfig<TConfig> & TPropsParent & PageResolveContext;
-interface PageResolveContext {
-    url: URL;
-    head: Head;
-}
+type PageResolve<TConfig extends PageConfigSchema = PageConfigSchema, TPropsParent extends object = TPropsParentDefault> = PageRequestConfig<TConfig> & TPropsParent & PageReactContext;
 
 declare class PageDescriptorProvider {
     protected readonly log: _alepha_core.Logger;
@@ -373,12 +355,9 @@ declare class PageDescriptorProvider {
     protected readonly pages: PageRoute[];
     getPages(): PageRoute[];
     page(name: string): PageRoute;
-    root(state: RouterState, context?: PageReactContext): ReactNode;
+    root(state: RouterState, context: PageReactContext): ReactNode;
     createLayers(route: PageRoute, request: PageRequest): Promise<CreateLayersResult>;
-    protected getErrorHandler(route: PageRoute): react.FC<{
-        error: Error;
-        url: string;
-    }> | undefined;
+    protected getErrorHandler(route: PageRoute): ((error: Error) => ReactNode) | undefined;
     protected createElement(page: PageRoute, props: Record<string, any>): Promise<ReactNode>;
     protected fillHead(page: PageRoute, ctx: PageRequest, props: Record<string, any>): void;
     renderError(e: Error): ReactNode;
@@ -429,14 +408,13 @@ interface Layer {
 }
 type PreviousLayerData = Omit<Layer, "element">;
 interface AnchorProps {
-    href?: string;
-    onClick?: (ev: any) => any;
+    href: string;
+    onClick: (ev: any) => any;
 }
 interface RouterState {
     pathname: string;
     search: string;
     layers: Array<Layer>;
-    head: Head;
 }
 interface TransitionOptions {
     state?: RouterState;
@@ -450,23 +428,27 @@ interface RouterStackItem {
     error?: Error;
 }
 interface RouterRenderResult {
+    state: RouterState;
+    context: PageReactContext;
     redirect?: string;
-    layers: Layer[];
-    head: Head;
-    element: ReactNode;
 }
 interface PageRequest extends PageReactContext {
-    url: URL;
     params: Record<string, any>;
     query: Record<string, string>;
-    head: Head;
     previous?: PreviousLayerData[];
 }
 interface CreateLayersResult extends RouterState {
     redirect?: string;
 }
+/**
+ * It's like RouterState, but publicly available in React context.
+ * This is where we store all plugin data!
+ */
 interface PageReactContext {
-    links?: HttpClientLink[];
+    url: URL;
+    head: Head;
+    onError: (error: Error) => ReactNode;
+    links?: ApiLinksResponse;
 }
 
 interface NestedViewProps {
@@ -478,26 +460,65 @@ interface NestedViewProps {
  * @param props
  * @constructor
  */
-declare const NestedView: (props: NestedViewProps) => string | number | bigint | boolean | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
+declare const NestedView: (props: NestedViewProps) => react_jsx_runtime.JSX.Element;
 
 interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     to: string | PageDescriptor;
-    children?: react__default.ReactNode;
+    children?: React__default.ReactNode;
 }
 declare const Link: (props: LinkProps) => react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Props for the ErrorBoundary component.
+ */
+interface ErrorBoundaryProps {
+    /**
+     * Fallback React node to render when an error is caught.
+     * If not provided, a default error message will be shown.
+     */
+    fallback: (error: Error) => ReactNode;
+    /**
+     * Optional callback that receives the error and error info.
+     * Use this to log errors to a monitoring service.
+     */
+    onError?: (error: Error, info: ErrorInfo) => void;
+}
+/**
+ * State of the ErrorBoundary component.
+ */
+interface ErrorBoundaryState {
+    error?: Error;
+}
+/**
+ * A reusable error boundary for catching rendering errors
+ * in any part of the React component tree.
+ */
+declare class ErrorBoundary extends React__default.Component<PropsWithChildren<ErrorBoundaryProps>, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    /**
+     * Update state so the next render shows the fallback UI.
+     */
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    /**
+     * Lifecycle method called when an error is caught.
+     * You can log the error or perform side effects here.
+     */
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+
 interface RouterContextValue {
     alepha: Alepha;
     state: RouterState;
     context: PageReactContext;
 }
-declare const RouterContext: react.Context<RouterContextValue | undefined>;
+declare const RouterContext: React.Context<RouterContextValue | undefined>;
 
 interface RouterLayerContextValue {
     index: number;
     path: string;
 }
-declare const RouterLayerContext: react.Context<RouterLayerContextValue | undefined>;
+declare const RouterLayerContext: React.Context<RouterLayerContextValue | undefined>;
 
 declare const useInject: <T extends object>(clazz: Class<T>) => T;
 
@@ -574,6 +595,9 @@ declare class ReactServerProvider {
     protected getPublicDirectory(): string;
     protected configureStaticServer(root: string): Promise<void>;
     protected configureVite(): Promise<void>;
+    /**
+     * For testing purposes, creates a render function that can be used.
+     */
     protected createRenderFunction(name: string): (options?: {
         params?: Record<string, string>;
         query?: Record<string, string>;
@@ -587,6 +611,7 @@ declare class ReactServerProvider {
 declare module "@alepha/core" {
     interface Hooks {
         "react:browser:render": {
+            state: RouterState;
             context: PageReactContext;
             hydration?: ReactHydrationState;
         };
@@ -596,6 +621,7 @@ declare module "@alepha/core" {
         };
         "react:transition:begin": {
             state: RouterState;
+            context: PageReactContext;
         };
         "react:transition:success": {
             state: RouterState;
@@ -603,9 +629,11 @@ declare module "@alepha/core" {
         "react:transition:error": {
             error: Error;
             state: RouterState;
+            context: PageReactContext;
         };
         "react:transition:end": {
             state: RouterState;
+            context: PageReactContext;
         };
     }
 }
@@ -614,4 +642,4 @@ declare class ReactModule {
     constructor();
 }
 
-export { $page, type AnchorProps, type CreateLayersResult, type Head, type HrefLike, type Layer, Link, NestedView, type PageConfigSchema, type PageDescriptor, type PageDescriptorOptions, PageDescriptorProvider, type PageReactContext, type PageRequest, type PageRequestConfig, type PageResolve, type PageResolveContext, type PageRoute, type PageRouteEntry, type PreviousLayerData, ReactBrowserProvider, type ReactHydrationState, ReactModule, ReactServerProvider, RedirectionError, RouterContext, type RouterContextValue, type RouterGoOptions, RouterHookApi, RouterLayerContext, type RouterLayerContextValue, type RouterRenderResult, type RouterStackItem, type RouterState, type TPropsDefault, type TPropsParentDefault, type TransitionOptions, type UseActiveHook, type UseQueryParamsHookOptions, envSchema, isPageRoute, useActive, useApi, useClient, useInject, useQueryParams, useRouter, useRouterEvents, useRouterState };
+export { $page, type AnchorProps, type CreateLayersResult, ErrorBoundary, type Head, type HrefLike, type Layer, Link, NestedView, type PageConfigSchema, type PageDescriptor, type PageDescriptorOptions, PageDescriptorProvider, type PageReactContext, type PageRequest, type PageRequestConfig, type PageResolve, type PageRoute, type PageRouteEntry, type PreviousLayerData, ReactBrowserProvider, type ReactHydrationState, ReactModule, ReactServerProvider, RedirectionError, RouterContext, type RouterContextValue, type RouterGoOptions, RouterHookApi, RouterLayerContext, type RouterLayerContextValue, type RouterRenderResult, type RouterStackItem, type RouterState, type TPropsDefault, type TPropsParentDefault, type TransitionOptions, type UseActiveHook, type UseQueryParamsHookOptions, type VirtualRouter, envSchema, isPageRoute, useActive, useApi, useClient, useInject, useQueryParams, useRouter, useRouterEvents, useRouterState };

package/redis.d.ts

@@ -1,7 +1,7 @@
 import * as _alepha_core from '@alepha/core';
 import { Static, Alepha } from '@alepha/core';
 import * as Redis from 'ioredis';
-import Redis__default from 'ioredis';
+import Redis__default, { RedisOptions } from 'ioredis';
 
 /** Symbol key applied to readonly types */
 declare const ReadonlyKind: unique symbol;
@@ -110,6 +110,7 @@ declare class RedisProvider {
      * Close the connection to the Redis server.
      */
     close(): Promise<void>;
+    duplicate(options?: Partial<RedisOptions>): RedisClient;
     /**
      * Redis subscriber client factory method.
      */

package/security.d.ts

@@ -601,24 +601,31 @@ declare const $role: {
  * @param options
  */
 declare const $serviceAccount: (options: ServiceAccountDescriptorOptions) => ServiceAccountDescriptor;
-interface ServiceAccountDescriptorOptions {
-    /**
-     * Get Token URL.
-     */
-    url: string;
-    /**
-     * Client ID.
-     */
-    clientId: string;
-    /**
-     * Client Secret.
-     */
-    clientSecret: string;
-    /**
-     * Scopes to request.
-     */
-    scope?: string;
-}
+type ServiceAccountDescriptorOptions = {
+    oauth2: {
+        /**
+         * Get Token URL.
+         */
+        url: string;
+        /**
+         * Client ID.
+         */
+        clientId: string;
+        /**
+         * Client Secret.
+         */
+        clientSecret: string;
+        /**
+         * Scopes to request.
+         */
+        scope?: string;
+    };
+} | {
+    jwt: {
+        secret: string;
+        roles?: string[];
+    };
+};
 interface ServiceAccountDescriptor {
     options: ServiceAccountDescriptorOptions;
     store: ServiceAccountStore;

package/server/metrics.d.ts

@@ -6,7 +6,7 @@ declare class ServerMetricsProvider {
     private memoryUsage;
     private gcDuration;
     private heapUsage;
-    readonly metrics: _alepha_server.RouteDescriptor<_alepha_server.RequestConfigSchema>;
+    readonly metrics: _alepha_server.ActionDescriptor<_alepha_server.RequestConfigSchema>;
     constructor();
     private collectMetrics;
 }

package/server/proxy.d.ts

@@ -1,34 +1 @@
-import * as _alepha_core from '@alepha/core';
-import { Async, KIND, OPTIONS, Alepha } from '@alepha/core';
-import { ServerRequest, ServerRouterProvider } from '@alepha/server';
-
-type ProxyDescriptorOptions = {
-    path: string;
-    target: string;
-    beforeRequest?: (request: ServerRequest, proxyRequest: RequestInit) => Async<void>;
-    afterResponse?: (request: ServerRequest, proxyResponse: Response) => Async<void>;
-    disabled?: boolean;
-};
-interface ProxyDescriptor {
-    [KIND]: "PROXY";
-    [OPTIONS]: ProxyDescriptorOptions;
-}
-declare const $proxy: {
-    (options: ProxyDescriptorOptions): ProxyDescriptor;
-    [KIND]: string;
-};
-
-declare class ServerProxyProvider {
-    protected readonly routerProvider: ServerRouterProvider;
-    protected readonly alepha: Alepha;
-    readonly configure: _alepha_core.HookDescriptor<"configure">;
-    proxy(options: ProxyDescriptorOptions): Promise<void>;
-    private getRawRequestBody;
-}
-
-declare class ServerProxyModule {
-    protected readonly alepha: Alepha;
-    constructor();
-}
-
-export { $proxy, type ProxyDescriptor, type ProxyDescriptorOptions, ServerProxyModule, ServerProxyProvider };
+export * from '@alepha/server-proxy';

package/server/static.d.ts

@@ -35,6 +35,11 @@ interface ServeDescriptorOptions {
      * @default true
      */
     indexFallback?: boolean;
+    /**
+     * Force all requests "not found" to be served with the index.html file.
+     * This is useful for single-page applications (SPAs) that use client-side only routing.
+     */
+    historyApiFallback?: boolean;
     /**
      * Optional name of the descriptor.
      * This is used for logging and debugging purposes.

package/server/swagger.d.ts

@@ -19,6 +19,7 @@ interface SwaggerDescriptorOptions {
     rewrite?: (doc: OpenAPIV3.Document) => void;
 }
 interface SwaggerUiOptions {
+    root?: string;
     initOAuth?: {
         /**
          * Default clientId.