fibrae 0.1.0

package/dist/router/Navigator.js

@@ -0,0 +1,225 @@
+/**
+ * Navigator service - type-safe route-aware navigation.
+ *
+ * Provides route-aware navigation on top of History:
+ * - nav.go("routeName", { path: {...}, searchParams: {...} })
+ * - nav.back, nav.forward
+ * - nav.isActive("routeName", params) for active link detection
+ * - currentRoute Atom reflects matched route info
+ *
+ * Design: Navigator uses History internally but provides route-aware API.
+ * It knows about routes and can build URLs from route names.
+ */
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { Atom, Registry as AtomRegistry } from "@effect-atom/atom";
+import { History } from "./History.js";
+// =============================================================================
+// Service Tag
+// =============================================================================
+/**
+ * Navigator service tag for Effect dependency injection.
+ */
+export class Navigator extends Context.Tag("fibrae/Navigator")() {
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Parse search params from URL search string.
+ */
+function parseSearchParams(search) {
+    const params = {};
+    const searchParams = new URLSearchParams(search);
+    searchParams.forEach((value, key) => {
+        params[key] = value;
+    });
+    return params;
+}
+/**
+ * Build search string from params object.
+ */
+function buildSearchString(params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+            searchParams.set(key, String(value));
+        }
+    }
+    const str = searchParams.toString();
+    return str ? `?${str}` : "";
+}
+/**
+ * Strip basePath prefix from pathname for route matching.
+ */
+function stripBasePath(pathname, basePath) {
+    if (!basePath || basePath === "/") {
+        return pathname;
+    }
+    // Normalize: remove trailing slash from basePath
+    const normalizedBase = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+    if (pathname.startsWith(normalizedBase)) {
+        const stripped = pathname.slice(normalizedBase.length);
+        // Ensure we return "/" not "" for root
+        return stripped || "/";
+    }
+    return pathname;
+}
+/**
+ * Match current location against router and return CurrentRoute.
+ */
+function matchLocation(router, location, basePath = "") {
+    const pathname = stripBasePath(location.pathname, basePath);
+    const match = router.matchRoute(pathname);
+    if (Option.isNone(match)) {
+        return Option.none();
+    }
+    return Option.some({
+        routeName: match.value.route.name,
+        params: match.value.params,
+        searchParams: parseSearchParams(location.search),
+    });
+}
+/**
+ * Find a route by name in the router.
+ */
+function findRouteByName(router, name) {
+    for (const group of router.groups) {
+        for (const route of group.routes) {
+            if (route.name === name) {
+                return Option.some(route);
+            }
+        }
+    }
+    return Option.none();
+}
+/**
+ * Create a Navigator layer for the given router.
+ *
+ * Features:
+ * - Type-safe navigation by route name
+ * - Automatic URL building via route.interpolate
+ * - Tracks current matched route in an Atom
+ * - Delegates to History for actual navigation
+ * - Supports basePath for apps mounted at non-root paths
+ */
+export function NavigatorLive(router, options = {}) {
+    const basePath = options.basePath ?? "";
+    return Layer.effect(Navigator, Effect.gen(function* () {
+        const history = yield* History;
+        const registry = yield* AtomRegistry.AtomRegistry;
+        // Get initial location and match
+        const initialLocation = yield* Atom.get(history.location);
+        const initialRoute = matchLocation(router, initialLocation, basePath);
+        // Create currentRoute Atom
+        const currentRouteAtom = Atom.make(initialRoute);
+        // Create a derived effect that updates currentRoute when location changes
+        // This is a reactive subscription
+        const updateCurrentRoute = (location) => {
+            const matched = matchLocation(router, location, basePath);
+            registry.set(currentRouteAtom, matched);
+        };
+        // Note: The actual subscription to location changes should be handled
+        // by by component rendering - currentRoute will be updated when go/back/forward are called
+        const service = {
+            basePath,
+            currentRoute: currentRouteAtom,
+            go: (routeName, options = {}) => Effect.gen(function* () {
+                const route = findRouteByName(router, routeName);
+                if (Option.isNone(route)) {
+                    yield* Effect.logWarning(`Route not found: ${routeName}`);
+                    return;
+                }
+                // Build URL from route and params
+                const pathParams = options.path ?? {};
+                const routePathname = route.value.interpolate(pathParams);
+                // Prepend basePath to route pathname
+                const pathname = basePath + routePathname;
+                const search = options.searchParams
+                    ? buildSearchString(options.searchParams)
+                    : "";
+                const url = `${pathname}${search}`;
+                // Navigate
+                if (options.replace) {
+                    yield* history.replace(url);
+                }
+                else {
+                    yield* history.push(url);
+                }
+                // Update currentRoute
+                const newLocation = yield* Atom.get(history.location);
+                updateCurrentRoute(newLocation);
+            }),
+            back: Effect.gen(function* () {
+                yield* history.back;
+                // Wait a tick for popstate to fire, then update
+                yield* Effect.sleep("10 millis");
+                const location = yield* Atom.get(history.location);
+                updateCurrentRoute(location);
+            }),
+            forward: Effect.gen(function* () {
+                yield* history.forward;
+                // Wait a tick for popstate to fire, then update
+                yield* Effect.sleep("10 millis");
+                const location = yield* Atom.get(history.location);
+                updateCurrentRoute(location);
+            }),
+            isActive: (routeName, params) => Effect.gen(function* () {
+                const current = yield* Atom.get(currentRouteAtom);
+                if (Option.isNone(current)) {
+                    return false;
+                }
+                if (current.value.routeName !== routeName) {
+                    return false;
+                }
+                // If params provided, check they match
+                if (params) {
+                    for (const [key, value] of Object.entries(params)) {
+                        if (current.value.params[key] !== value) {
+                            return false;
+                        }
+                    }
+                }
+                return true;
+            }),
+        };
+        return service;
+    }));
+}
+// =============================================================================
+// Convenience Accessors
+// =============================================================================
+/**
+ * Navigate to a route by name.
+ */
+export const go = (routeName, options) => Effect.gen(function* () {
+    const nav = yield* Navigator;
+    yield* nav.go(routeName, options);
+});
+/**
+ * Go back in history.
+ */
+/* is-tree-shakable-suppress */
+export const back = Effect.gen(function* () {
+    const nav = yield* Navigator;
+    yield* nav.back;
+});
+/**
+ * Go forward in history.
+ */
+/* is-tree-shakable-suppress */
+export const forward = Effect.gen(function* () {
+    const nav = yield* Navigator;
+    yield* nav.forward;
+});
+/**
+ * Get current route info.
+ */
+/* is-tree-shakable-suppress */
+export const getCurrentRoute = Effect.gen(function* () {
+    const nav = yield* Navigator;
+    return yield* Atom.get(nav.currentRoute);
+});
+//# sourceMappingURL=Navigator.js.map

package/dist/router/Navigator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Navigator.js","sourceRoot":"","sources":["../../src/router/Navigator.ts"],"names":[],"mappings":"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"}

package/dist/router/Route.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Route declaration module for Fibrae router.
+ *
+ * Mirrors Effect HttpApiEndpoint patterns:
+ * - Route.get("name", "/path") for static routes
+ * - Route.get("name")`/path/${param}` for dynamic routes with template literals
+ * - Route.param for schema-validated path parameters
+ * - .setSearchParams for query string validation
+ */
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+/**
+ * Annotation symbol for storing parameter name in schema metadata.
+ * Mirrors HttpApiSchema.AnnotationParam pattern.
+ */
+export declare const AnnotationParam: unique symbol;
+/**
+ * Represents a single route with path and optional search params validation.
+ * This is immutable data that describes a route.
+ */
+export interface Route<Name extends string = string, PathParams extends Record<string, unknown> = Record<string, unknown>, SearchParams extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: Name;
+    readonly path: string;
+    readonly pathSchema: Option.Option<Schema.Schema<PathParams>>;
+    readonly searchSchema: Option.Option<Schema.Schema<SearchParams>>;
+    /**
+     * Match a pathname against this route.
+     * Returns the decoded path parameters if matched, None otherwise.
+     */
+    readonly match: (pathname: string) => Option.Option<PathParams>;
+    /**
+     * Build a URL from path parameters.
+     * Throws if required params are missing.
+     */
+    readonly interpolate: (params: PathParams) => string;
+    /**
+     * Set search parameter schema for this route.
+     */
+    readonly setSearchParams: <NewSearch extends Record<string, unknown>>(schema: Schema.Schema<NewSearch>) => Route<Name, PathParams, NewSearch>;
+}
+/**
+ * Constructor for building routes with different method types.
+ * Supports both static paths and template literal syntax.
+ */
+export interface RouteConstructor {
+    <const Name extends string>(name: Name, path: string): Route<Name, {}, {}>;
+    <const Name extends string>(name: Name): <const T extends readonly any[]>(segments: TemplateStringsArray, ...params: T) => Route<Name, Record<string, unknown>, {}>;
+}
+/**
+ * Route.get("name", "/path") creates a GET route
+ * Route.get("name")`/path/${param}` creates a GET route with typed path params
+ */
+export declare const get: RouteConstructor;
+/**
+ * Route.post("name", "/path") creates a POST route
+ * Route.post("name")`/path/${param}` creates a POST route with typed path params
+ */
+export declare const post: RouteConstructor;
+/**
+ * Route.param("name", schema) creates a path parameter with validation.
+ * Use in template literals: Route.get("name")`/posts/${Route.param("id", Schema.NumberFromString)}`
+ *
+ * Stores the parameter name in the schema's annotations for extraction during template literal parsing.
+ */
+export declare function param<T>(name: string, schema: Schema.Schema<T>): Schema.Schema<T>;

package/dist/router/Route.js

@@ -0,0 +1,143 @@
+/**
+ * Route declaration module for Fibrae router.
+ *
+ * Mirrors Effect HttpApiEndpoint patterns:
+ * - Route.get("name", "/path") for static routes
+ * - Route.get("name")`/path/${param}` for dynamic routes with template literals
+ * - Route.param for schema-validated path parameters
+ * - .setSearchParams for query string validation
+ */
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+/**
+ * Annotation symbol for storing parameter name in schema metadata.
+ * Mirrors HttpApiSchema.AnnotationParam pattern.
+ */
+export const AnnotationParam = Symbol.for("fibrae/Route/AnnotationParam");
+/**
+ * Parse path template to extract param names and build a URL pattern.
+ *
+ * Example: "/posts/:id/comments/:commentId" → { paramNames: ["id", "commentId"], pattern: ... }
+ */
+function parsePathTemplate(segments, schemas) {
+    let path = segments[0];
+    const paramNames = [];
+    const pathSchemaObj = {};
+    for (let i = 0; i < schemas.length; i++) {
+        const schema = schemas[i];
+        // Get param name from schema annotation (if provided) or use index
+        const paramName = getParamName(schema) ?? String(i);
+        paramNames.push(paramName);
+        pathSchemaObj[paramName] = schema;
+        path += `:${paramName}${segments[i + 1]}`;
+    }
+    const pathSchema = paramNames.length > 0
+        ? Option.some(Schema.Struct(pathSchemaObj))
+        : Option.none();
+    return { path, paramNames, pathSchema };
+}
+/**
+ * Get param name from a Schema's annotations.
+ * Mirrors HttpApiSchema.getParam pattern.
+ */
+function getParamName(schema) {
+    const ast = schema.ast;
+    const annotations = ast.annotations;
+    const paramAnnotation = annotations[AnnotationParam];
+    return paramAnnotation?.name;
+}
+/**
+ * Match a pathname against a route pattern.
+ * Pattern: "/posts/:id/comments/:commentId"
+ * Pathname: "/posts/123/comments/456"
+ * Returns: { id: "123", commentId: "456" }
+ */
+function matchPath(pattern, pathname, pathSchema) {
+    // Convert pattern with :params to regex
+    const regexPattern = pattern.replace(/:(\w+)/g, "(?<$1>[^/]+)");
+    const regex = new RegExp(`^${regexPattern}/?$`);
+    const match = pathname.match(regex);
+    if (!match) {
+        return Option.none();
+    }
+    const params = match.groups ?? {};
+    // Decode and validate with schema if present
+    if (Option.isSome(pathSchema)) {
+        try {
+            const decoded = Schema.decodeSync(pathSchema.value)(params);
+            return Option.some(decoded);
+        }
+        catch (_) {
+            return Option.none();
+        }
+    }
+    return Option.some(params);
+}
+/**
+ * Build a URL from a route pattern and parameters.
+ * Pattern: "/posts/:id/comments/:commentId"
+ * Params: { id: 123, commentId: 456 }
+ * Returns: "/posts/123/comments/456"
+ */
+function interpolatePath(pattern, params) {
+    return pattern.replace(/:(\w+)/g, (_, key) => {
+        const value = params[key];
+        if (value === undefined) {
+            throw new Error(`Missing required parameter: ${key}`);
+        }
+        return String(value);
+    });
+}
+/**
+ * Create a route with static path.
+ */
+function makeRoute(_name, path, pathSchema = Option.none(), searchSchema = Option.none()) {
+    return {
+        name: _name,
+        path,
+        pathSchema,
+        searchSchema,
+        match: (pathname) => matchPath(path, pathname, pathSchema),
+        interpolate: (params) => interpolatePath(path, params),
+        setSearchParams: (schema) => makeRoute(_name, path, pathSchema, Option.some(schema)),
+    };
+}
+/**
+ * Create a route getter function supporting both static and template literal syntax.
+ */
+function makeGetter() {
+    return ((name, path) => {
+        // Static path case
+        if (typeof path === "string") {
+            return makeRoute(name, path);
+        }
+        // Return template literal handler
+        return (segments, ...schemas) => {
+            const { path: parsedPath, pathSchema } = parsePathTemplate(segments, Array.from(schemas));
+            return makeRoute(name, parsedPath, pathSchema);
+        };
+    });
+}
+/**
+ * Route.get("name", "/path") creates a GET route
+ * Route.get("name")`/path/${param}` creates a GET route with typed path params
+ */
+export const get = makeGetter();
+/**
+ * Route.post("name", "/path") creates a POST route
+ * Route.post("name")`/path/${param}` creates a POST route with typed path params
+ */
+export const post = makeGetter();
+/**
+ * Route.param("name", schema) creates a path parameter with validation.
+ * Use in template literals: Route.get("name")`/posts/${Route.param("id", Schema.NumberFromString)}`
+ *
+ * Stores the parameter name in the schema's annotations for extraction during template literal parsing.
+ */
+export function param(name, schema) {
+    const annotations = {
+        [AnnotationParam]: { name, schema }
+    };
+    return schema.annotations(annotations);
+}
+//# sourceMappingURL=Route.js.map

package/dist/router/Route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Route.js","sourceRoot":"","sources":["../../src/router/Route.ts"],"names":[],"mappings":"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"}

package/dist/router/Router.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Router module for organizing and matching routes.
+ *
+ * Mirrors Effect HttpApiGroup/HttpApi patterns:
+ * - Router.group("name") creates a group for organizing routes
+ * - Router.make("name") creates the top-level router
+ * - Routes are added via .add(route)
+ * - Router holds the complete route tree for efficient matching
+ *
+ * SSR Integration:
+ * - Router.serverLayer() - For SSR rendering with loaders
+ * - Router.browserLayer() - For client hydration with initial state
+ */
+import type { Route } from "./Route.js";
+import * as Option from "effect/Option";
+import * as Layer from "effect/Layer";
+import * as Context from "effect/Context";
+import { Registry as AtomRegistry } from "@effect-atom/atom";
+import { History } from "./History.js";
+import { Navigator } from "./Navigator.js";
+import { RouterHandlers } from "./RouterBuilder.js";
+import type { VElement } from "../shared.js";
+/**
+ * A group of routes for organizational purposes.
+ * Groups provide namespacing for handler implementation.
+ */
+export interface RouteGroup<Name extends string = string> {
+    readonly name: Name;
+    readonly routes: readonly Route[];
+    readonly add: (route: Route) => RouteGroup<Name>;
+}
+/**
+ * The complete router holding all route groups and enabling route matching.
+ */
+export interface Router<Name extends string = string> {
+    readonly name: Name;
+    readonly groups: readonly RouteGroup[];
+    readonly add: (group: RouteGroup) => Router<Name>;
+    /**
+     * Match a pathname against all routes in the router.
+     * Returns the matched route, group name, and decoded path parameters.
+     */
+    readonly matchRoute: (pathname: string) => Option.Option<{
+        readonly groupName: string;
+        readonly route: Route;
+        readonly params: Record<string, unknown>;
+    }>;
+}
+/**
+ * Create a route group with the given name.
+ * Routes are added via group.add(route).
+ */
+export declare function group<const Name extends string>(name: Name): RouteGroup<Name>;
+/**
+ * Create a router with the given name.
+ * Groups are added via router.add(group).
+ */
+export declare function make<const Name extends string>(name: Name): Router<Name>;
+/**
+ * Options for server-side rendering layer.
+ */
+export interface ServerLayerOptions {
+    /** The router instance */
+    readonly router: Router;
+    /** Current request pathname */
+    readonly pathname: string;
+    /** Current request search string (with or without leading ?) */
+    readonly search?: string;
+    /** Base path prefix for the app (e.g., "/ssr/router") */
+    readonly basePath?: string;
+}
+/**
+ * Options for browser/client hydration layer.
+ */
+export interface BrowserLayerOptions {
+    /** The router instance */
+    readonly router: Router;
+    /**
+     * @deprecated Use atom hydration instead. RouterStateAtom is automatically
+     * hydrated from __FIBRAE_STATE__ and used by RouterOutlet.
+     */
+    readonly initialState?: DehydratedRouterState;
+    /** Base path prefix for the app (e.g., "/ssr/router") */
+    readonly basePath?: string;
+}
+/**
+ * Dehydrated state from SSR for hydration.
+ * Contains matched route info and loader data.
+ */
+export interface DehydratedRouterState {
+    /** Name of the matched route */
+    readonly routeName: string;
+    /** Decoded path parameters */
+    readonly params: Record<string, unknown>;
+    /** Search parameters */
+    readonly searchParams: Record<string, string>;
+    /** Data returned by the loader */
+    readonly loaderData: unknown;
+}
+/**
+ * Result of SSR rendering a route.
+ */
+export interface SSRRouteResult {
+    /** The rendered VElement */
+    readonly element: VElement;
+    /** Dehydrated state for client hydration */
+    readonly dehydratedState: DehydratedRouterState;
+}
+declare const CurrentRouteElement_base: Context.TagClass<CurrentRouteElement, "fibrae/CurrentRouteElement", {
+    readonly element: VElement;
+    readonly state: DehydratedRouterState;
+}>;
+/**
+ * Service tag for the current route's rendered element.
+ * Used by SSR to provide the matched route's component.
+ */
+export declare class CurrentRouteElement extends CurrentRouteElement_base {
+}
+/**
+ * Create a server-side layer for SSR rendering.
+ *
+ * This layer:
+ * 1. Matches the pathname against the router
+ * 2. Runs the matched route's loader
+ * 3. Renders the component with loader data
+ * 4. Provides the rendered element and dehydrated state
+ *
+ * Usage in SSR:
+ * ```typescript
+ * const serverLayer = Router.serverLayer({
+ *   router: AppRouter,
+ *   pathname: "/posts/42",
+ *   search: "?sort=date",
+ *   basePath: "/ssr/router"
+ * });
+ *
+ * const { element, dehydratedState } = yield* Router.CurrentRouteElement;
+ * ```
+ */
+export declare function serverLayer(options: ServerLayerOptions): Layer.Layer<CurrentRouteElement | History | Navigator, unknown, RouterHandlers | AtomRegistry.AtomRegistry>;
+/**
+ * Create a browser layer for client-side hydration.
+ *
+ * This layer:
+ * 1. Sets up browser history with popstate listener
+ * 2. Checks RouterStateAtom for hydrated SSR state
+ * 3. If hydrated, uses that for initial render (skips loader)
+ * 4. Provides Navigator for subsequent navigation
+ *
+ * SSR hydration works automatically via atom hydration - no need to
+ * pass initialState manually. The RouterStateAtom is hydrated from
+ * __FIBRAE_STATE__ before this layer is created.
+ *
+ * Usage in client:
+ * ```typescript
+ * // Hydrate atoms first (includes RouterStateAtom)
+ * hydrate(container, app, window.__FIBRAE_STATE__);
+ *
+ * // Browser layer reads from hydrated RouterStateAtom
+ * const browserLayer = Router.browserLayer({
+ *   router: AppRouter,
+ *   basePath: "/ssr/router"
+ * });
+ * ```
+ */
+export declare function browserLayer(options: BrowserLayerOptions): Layer.Layer<History | Navigator | CurrentRouteElement, unknown, AtomRegistry.AtomRegistry | RouterHandlers>;
+export {};