@alepha/react 0.8.1 → 0.9.1

package/src/descriptors/$page.ts

@@ -1,9 +1,9 @@
 import {
-	__descriptor,
 	type Async,
+	createDescriptor,
+	Descriptor,
 	KIND,
 	NotImplementedError,
-	OPTIONS,
 	type Static,
 	type TSchema,
 } from "@alepha/core";
@@ -13,8 +13,6 @@ import type { FC, ReactNode } from "react";
 import type { ClientOnlyProps } from "../components/ClientOnly.tsx";
 import type { PageReactContext } from "../providers/PageDescriptorProvider.ts";
 
-const KEY = "PAGE";
-
 /**
  * Main descriptor for defining a React route in the application.
  */
@@ -25,45 +23,14 @@ export const $page = <
 >(
 	options: PageDescriptorOptions<TConfig, TProps, TPropsParent>,
 ): PageDescriptor<TConfig, TProps, TPropsParent> => {
-	__descriptor(KEY);
-
-	// if (options.children) {
-	// 	for (const child of options.children) {
-	// 		child[OPTIONS].parent = {
-	// 			[OPTIONS]: options as PageDescriptorOptions<any, any, any>,
-	// 		};
-	// 	}
-	// }
-
-	// if (options.parent) {
-	// 	options.parent[OPTIONS].children ??= [];
-	// 	options.parent[OPTIONS].children.push({
-	// 		[OPTIONS]: options as PageDescriptorOptions<any, any, any>,
-	// 	});
-	// }
-
-	return {
-		[KIND]: KEY,
-		[OPTIONS]: options,
-		render: () => {
-			throw new NotImplementedError(KEY);
-		},
-	};
+	return createDescriptor(
+		PageDescriptor<TConfig, TProps, TPropsParent>,
+		options,
+	);
 };
 
-$page[KIND] = KEY;
-
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface PageConfigSchema {
-	query?: TSchema;
-	params?: TSchema;
-}
-
-export type TPropsDefault = any;
-
-export type TPropsParentDefault = {};
-
 export interface PageDescriptorOptions<
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TProps extends object = TPropsDefault,
@@ -136,11 +103,9 @@ export interface PageDescriptorOptions<
 	 *
 	 * If you still want to render at this pathname, add a child page with an empty path.
 	 */
-	children?:
-		| Array<{ [OPTIONS]: PageDescriptorOptions }>
-		| (() => Array<{ [OPTIONS]: PageDescriptorOptions }>);
+	children?: Array<PageDescriptor> | (() => Array<PageDescriptor>);
 
-	parent?: { [OPTIONS]: PageDescriptorOptions<PageConfigSchema, TPropsParent> };
+	parent?: PageDescriptor<PageConfigSchema, TPropsParent>;
 
 	can?: () => boolean;
 
@@ -168,23 +133,39 @@ export interface PageDescriptorOptions<
 	cache?: ServerRouteCache;
 }
 
-export interface PageDescriptor<
+export class PageDescriptor<
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TProps extends object = TPropsDefault,
 	TPropsParent extends object = TPropsParentDefault,
-> {
-	[KIND]: typeof KEY;
-	[OPTIONS]: PageDescriptorOptions<TConfig, TProps, TPropsParent>;
+> extends Descriptor<PageDescriptorOptions<TConfig, TProps, TPropsParent>> {
+	public get name(): string {
+		return this.options.name ?? this.config.propertyKey;
+	}
 
 	/**
 	 * For testing or build purposes, this will render the page (with or without the HTML layout) and return the HTML and context.
 	 * Only valid for server-side rendering, it will throw an error if called on the client-side.
 	 */
-	render: (
+	public async render(
 		options?: PageDescriptorRenderOptions,
-	) => Promise<PageDescriptorRenderResult>;
+	): Promise<PageDescriptorRenderResult> {
+		throw new NotImplementedError("");
+	}
 }
 
+$page[KIND] = PageDescriptor;
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface PageConfigSchema {
+	query?: TSchema;
+	params?: TSchema;
+}
+
+export type TPropsDefault = any;
+
+export type TPropsParentDefault = {};
+
 export interface PageDescriptorRenderOptions {
 	params?: Record<string, string>;
 	query?: Record<string, string>;

package/src/hooks/useInject.ts

@@ -8,5 +8,5 @@ export const useInject = <T extends object>(clazz: Service<T>): T => {
 		throw new Error("useRouter must be used within a <RouterProvider>");
 	}
 
-	return useMemo(() => ctx.alepha.get(clazz), []);
+	return useMemo(() => ctx.alepha.inject(clazz), []);
 };

package/src/hooks/useRouter.ts

@@ -13,7 +13,7 @@ export const useRouter = (): RouterHookApi => {
 	}
 
 	const pages = useMemo(() => {
-		return ctx.alepha.get(PageDescriptorProvider).getPages();
+		return ctx.alepha.inject(PageDescriptorProvider).getPages();
 	}, []);
 
 	return useMemo(
@@ -24,7 +24,7 @@ export const useRouter = (): RouterHookApi => {
 				ctx.state,
 				layer,
 				ctx.alepha.isBrowser()
-					? ctx.alepha.get(ReactBrowserProvider)
+					? ctx.alepha.inject(ReactBrowserProvider)
 					: undefined,
 			),
 		[layer],

package/src/index.browser.ts

@@ -1,4 +1,4 @@
-import { __bind, type Alepha, type Module } from "@alepha/core";
+import { $module } from "@alepha/core";
 import { AlephaServer } from "@alepha/server";
 import { AlephaServerLinks } from "@alepha/server-links";
 import { $page } from "./descriptors/$page.ts";
@@ -16,16 +16,21 @@ export * from "./providers/ReactBrowserProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class AlephaReact implements Module {
-	public readonly name = "alepha.react";
-	public readonly $services = (alepha: Alepha) =>
+export const AlephaReact = $module({
+	name: "alepha.react",
+	descriptors: [$page],
+	services: [
+		PageDescriptorProvider,
+		ReactBrowserRenderer,
+		BrowserRouterProvider,
+		ReactBrowserProvider,
+	],
+	register: (alepha) =>
 		alepha
 			.with(AlephaServer)
 			.with(AlephaServerLinks)
 			.with(PageDescriptorProvider)
 			.with(ReactBrowserProvider)
 			.with(BrowserRouterProvider)
-			.with(ReactBrowserRenderer);
-}
-
-__bind($page, AlephaReact);
+			.with(ReactBrowserRenderer),
+});

package/src/index.ts

@@ -1,4 +1,4 @@
-import { __bind, type Alepha, type Module } from "@alepha/core";
+import { $module } from "@alepha/core";
 import { AlephaServer, type ServerRequest } from "@alepha/server";
 import { AlephaServerCache } from "@alepha/server-cache";
 import { AlephaServerLinks } from "@alepha/server-links";
@@ -9,7 +9,10 @@ import {
 	type PageRequest,
 	type RouterState,
 } from "./providers/PageDescriptorProvider.ts";
-import type { ReactHydrationState } from "./providers/ReactBrowserProvider.ts";
+import {
+	ReactBrowserProvider,
+	type ReactHydrationState,
+} from "./providers/ReactBrowserProvider.ts";
 import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -72,139 +75,18 @@ declare module "@alepha/core" {
  * It delivers seamless server-side rendering, automatic code splitting, and client-side navigation with full
  * type safety and schema validation for route parameters and data.
  *
- * **Key Features:**
- * - Declarative page definition with `$page` descriptor
- * - Server-side rendering (SSR) with automatic hydration
- * - Type-safe routing with parameter validation
- * - Schema-based data resolution and validation
- * - SEO-friendly meta tag management
- * - Automatic code splitting and lazy loading
- * - Client-side navigation with browser history
- *
- * **Basic Usage:**
- * ```ts
- * import { Alepha, run, t } from "alepha";
- * import { AlephaReact, $page } from "alepha/react";
- *
- * class AppRoutes {
- *   // Home page
- *   home = $page({
- *     path: "/",
- *     component: () => (
- *       <div>
- *         <h1>Welcome to Alepha</h1>
- *         <p>Build amazing React applications!</p>
- *       </div>
- *     ),
- *   });
- *
- *   // About page with meta tags
- *   about = $page({
- *     path: "/about",
- *     head: {
- *       title: "About Us",
- *       description: "Learn more about our mission",
- *     },
- *     component: () => (
- *       <div>
- *         <h1>About Us</h1>
- *         <p>Learn more about our mission.</p>
- *       </div>
- *     ),
- *   });
- * }
- *
- * const alepha = Alepha.create()
- *   .with(AlephaReact)
- *   .with(AppRoutes);
- *
- * run(alepha);
- * ```
- *
- * **Dynamic Routes with Parameters:**
- * ```tsx
- * class UserRoutes {
- *   userProfile = $page({
- *     path: "/users/:id",
- *     schema: {
- *       params: t.object({
- *         id: t.string(),
- *       }),
- *     },
- *     resolve: async ({ params }) => {
- *       // Fetch user data server-side
- *       const user = await getUserById(params.id);
- *       return { user };
- *     },
- *     head: ({ user }) => ({
- *       title: `${user.name} - Profile`,
- *       description: `View ${user.name}'s profile`,
- *     }),
- *     component: ({ user }) => (
- *       <div>
- *         <h1>{user.name}</h1>
- *         <p>Email: {user.email}</p>
- *       </div>
- *     ),
- *   });
- *
- *   userSettings = $page({
- *     path: "/users/:id/settings",
- *     schema: {
- *       params: t.object({
- *         id: t.string(),
- *       }),
- *     },
- *     component: ({ params }) => (
- *       <UserSettings userId={params.id} />
- *     ),
- *   });
- * }
- * ```
- *
- * **Static Generation:**
- * ```tsx
- * class BlogRoutes {
- *   blogPost = $page({
- *     path: "/blog/:slug",
- *     schema: {
- *       params: t.object({
- *         slug: t.string(),
- *       }),
- *     },
- *     static: {
- *       entries: [
- *         { params: { slug: "getting-started" } },
- *         { params: { slug: "advanced-features" } },
- *         { params: { slug: "deployment" } },
- *       ],
- *     },
- *     resolve: ({ params }) => {
- *       const post = getBlogPost(params.slug);
- *       return { post };
- *     },
- *     component: ({ post }) => (
- *       <article>
- *         <h1>{post.title}</h1>
- *         <div>{post.content}</div>
- *       </article>
- *     ),
- *   });
- * }
- * ```
- *
  * @see {@link $page}
  * @module alepha.react
  */
-export class AlephaReact implements Module {
-	public readonly name = "alepha.react";
-	public readonly $services = (alepha: Alepha) =>
+export const AlephaReact = $module({
+	name: "alepha.react",
+	descriptors: [$page],
+	services: [ReactServerProvider, PageDescriptorProvider, ReactBrowserProvider],
+	register: (alepha) =>
 		alepha
 			.with(AlephaServer)
 			.with(AlephaServerCache)
 			.with(AlephaServerLinks)
 			.with(ReactServerProvider)
-			.with(PageDescriptorProvider);
-}
-
-__bind($page, AlephaReact);
+			.with(PageDescriptorProvider),
+});

package/src/providers/PageDescriptorProvider.ts

@@ -1,5 +1,12 @@
-import type { Static } from "@alepha/core";
-import { $hook, $inject, $logger, Alepha, OPTIONS, t } from "@alepha/core";
+import {
+	$env,
+	$hook,
+	$inject,
+	$logger,
+	Alepha,
+	type Static,
+	t,
+} from "@alepha/core";
 import type { ApiLinksResponse } from "@alepha/server";
 import { createElement, type ReactNode, StrictMode } from "react";
 import ClientOnly from "../components/ClientOnly.tsx";
@@ -8,7 +15,11 @@ import NestedView from "../components/NestedView.tsx";
 import NotFoundPage from "../components/NotFound.tsx";
 import { RouterContext } from "../contexts/RouterContext.ts";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import { $page, type PageDescriptorOptions } from "../descriptors/$page.ts";
+import {
+	$page,
+	type PageDescriptor,
+	type PageDescriptorOptions,
+} from "../descriptors/$page.ts";
 import { RedirectionError } from "../errors/RedirectionError.ts";
 
 const envSchema = t.object({
@@ -21,7 +32,7 @@ declare module "@alepha/core" {
 
 export class PageDescriptorProvider {
 	protected readonly log = $logger();
-	protected readonly env = $inject(envSchema);
+	protected readonly env = $env(envSchema);
 	protected readonly alepha = $inject(Alepha);
 	protected readonly pages: PageRoute[] = [];
 
@@ -289,7 +300,7 @@ export class PageDescriptorProvider {
 	}
 
 	public renderError(error: Error): ReactNode {
-		return createElement(ErrorViewer, { error });
+		return createElement(ErrorViewer, { error, alepha: this.alepha });
 	}
 
 	public renderEmptyView(): ReactNode {
@@ -356,14 +367,14 @@ export class PageDescriptorProvider {
 		on: "configure",
 		handler: () => {
 			let hasNotFoundHandler = false;
-			const pages = this.alepha.getDescriptorValues($page);
+			const pages = this.alepha.descriptors($page);
 
-			const hasParent = (it: { [OPTIONS]: PageDescriptorOptions }) => {
+			const hasParent = (it: PageDescriptor) => {
 				for (const page of pages) {
-					const children = page.value[OPTIONS].children
-						? Array.isArray(page.value[OPTIONS].children)
-							? page.value[OPTIONS].children
-							: page.value[OPTIONS].children()
+					const children = page.options.children
+						? Array.isArray(page.options.children)
+							? page.options.children
+							: page.options.children()
 						: [];
 					if (children.includes(it)) {
 						return true;
@@ -371,21 +382,17 @@ export class PageDescriptorProvider {
 				}
 			};
 
-			for (const { value, key } of pages) {
-				value[OPTIONS].name ??= key;
-			}
-
-			for (const { value } of pages) {
-				if (value[OPTIONS].path === "/*") {
+			for (const page of pages) {
+				if (page.options.path === "/*") {
 					hasNotFoundHandler = true;
 				}
 
 				// skip children, we only want root pages
-				if (hasParent(value)) {
+				if (hasParent(page)) {
 					continue;
 				}
 
-				this.add(this.map(pages, value));
+				this.add(this.map(pages, page));
 			}
 
 			if (!hasNotFoundHandler && pages.length > 0) {
@@ -404,17 +411,18 @@ export class PageDescriptorProvider {
 	});
 
 	protected map(
-		pages: Array<{ value: { [OPTIONS]: PageDescriptorOptions } }>,
-		target: { [OPTIONS]: PageDescriptorOptions },
+		pages: Array<PageDescriptor>,
+		target: PageDescriptor,
 	): PageRouteEntry {
-		const children = target[OPTIONS].children
-			? Array.isArray(target[OPTIONS].children)
-				? target[OPTIONS].children
-				: target[OPTIONS].children()
+		const children = target.options.children
+			? Array.isArray(target.options.children)
+				? target.options.children
+				: target.options.children()
 			: [];
 
 		return {
-			...target[OPTIONS],
+			...target.options,
+			name: target.name,
 			parent: undefined,
 			children: children.map((it) => this.map(pages, it)),
 		} as PageRoute;

package/src/providers/ReactBrowserProvider.ts

@@ -174,7 +174,7 @@ export class ReactBrowserProvider {
 			window.addEventListener("popstate", () => {
 				// when you update silently queryparams or hash, skip rendering
 				// if you want to force a rendering, use #go()
-				if (this.state.pathname === location.pathname) {
+				if (this.state.pathname === this.url) {
 					return;
 				}
 

package/src/providers/ReactBrowserRenderer.ts

@@ -1,4 +1,4 @@
-import { $hook, $inject, $logger, type Static, t } from "@alepha/core";
+import { $env, $hook, $inject, $logger, type Static, t } from "@alepha/core";
 import type { ApiLinksResponse } from "@alepha/server";
 import type { Root } from "react-dom/client";
 import { createRoot, hydrateRoot } from "react-dom/client";
@@ -25,7 +25,7 @@ export interface ReactBrowserRendererOptions {
 export class ReactBrowserRenderer {
 	protected readonly browserProvider = $inject(ReactBrowserProvider);
 	protected readonly browserRouterProvider = $inject(BrowserRouterProvider);
-	protected readonly env = $inject(envSchema);
+	protected readonly env = $env(envSchema);
 	protected readonly log = $logger();
 
 	protected root!: Root;

package/src/providers/ReactServerProvider.ts

@@ -1,11 +1,11 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import {
+	$env,
 	$hook,
 	$inject,
 	$logger,
 	Alepha,
-	OPTIONS,
 	type Static,
 	t,
 } from "@alepha/core";
@@ -36,12 +36,16 @@ const envSchema = t.object({
 	REACT_SERVER_PREFIX: t.string({ default: "" }),
 	REACT_SSR_ENABLED: t.optional(t.boolean()),
 	REACT_ROOT_ID: t.string({ default: "root" }),
+	REACT_SERVER_TEMPLATE: t.optional(
+		t.string({
+			size: "rich",
+		}),
+	),
 });
 
 declare module "@alepha/core" {
 	interface Env extends Partial<Static<typeof envSchema>> {}
 	interface State {
-		"react.server.template"?: string;
 		"react.server.ssr"?: boolean;
 	}
 }
@@ -53,7 +57,7 @@ export class ReactServerProvider {
 	protected readonly serverStaticProvider = $inject(ServerStaticProvider);
 	protected readonly serverRouterProvider = $inject(ServerRouterProvider);
 	protected readonly serverTimingProvider = $inject(ServerTimingProvider);
-	protected readonly env = $inject(envSchema);
+	protected readonly env = $env(envSchema);
 	protected readonly ROOT_DIV_REGEX = new RegExp(
 		`<div([^>]*)\\s+id=["']${this.env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`,
 		"is",
@@ -62,17 +66,15 @@ export class ReactServerProvider {
 	public readonly onConfigure = $hook({
 		on: "configure",
 		handler: async () => {
-			const pages = this.alepha.getDescriptorValues($page);
+			const pages = this.alepha.descriptors($page);
 
 			const ssrEnabled =
 				pages.length > 0 && this.env.REACT_SSR_ENABLED !== false;
 
 			this.alepha.state("react.server.ssr", ssrEnabled);
 
-			for (const { key, instance, value } of pages) {
-				const name = value[OPTIONS].name ?? key;
-
-				instance[key].render = this.createRenderFunction(name);
+			for (const page of pages) {
+				page.render = this.createRenderFunction(page.name);
 			}
 
 			// development mode
@@ -105,7 +107,7 @@ export class ReactServerProvider {
 
 			// no SSR enabled, serve index.html for all unmatched routes
 			this.log.info("SSR is disabled, use History API fallback");
-			await this.serverRouterProvider.route({
+			this.serverRouterProvider.createRoute({
 				path: "*",
 				handler: async ({ url, reply }) => {
 					if (url.pathname.includes(".")) {
@@ -127,7 +129,7 @@ export class ReactServerProvider {
 
 	public get template() {
 		return (
-			this.alepha.state("react.server.template") ??
+			this.alepha.env.REACT_SERVER_TEMPLATE ??
 			"<!DOCTYPE html><html lang='en'><head></head><body></body></html>"
 		);
 	}
@@ -140,7 +142,7 @@ export class ReactServerProvider {
 
 			this.log.debug(`+ ${page.match} -> ${page.name}`);
 
-			await this.serverRouterProvider.route({
+			this.serverRouterProvider.createRoute({
 				...page,
 				schema: undefined, // schema is handled by the page descriptor provider for now (shared by browser and server)
 				method: "GET",
@@ -166,7 +168,7 @@ export class ReactServerProvider {
 	}
 
 	protected async configureStaticServer(root: string) {
-		await this.serverStaticProvider.serve({
+		await this.serverStaticProvider.createStaticServer({
 			root,
 			path: this.env.REACT_SERVER_PREFIX,
 		});
@@ -262,7 +264,7 @@ export class ReactServerProvider {
 			};
 
 			if (this.alepha.has(ServerLinksProvider)) {
-				const srv = this.alepha.get(ServerLinksProvider);
+				const srv = this.alepha.inject(ServerLinksProvider);
 				const schema = apiLinksResponseSchema as any;
 
 				context.links = this.alepha.parse(