@reckona/mreact-router 0.0.159 → 0.0.161

package/src/typed-routes.ts

@@ -1,23 +1,44 @@
+/**
+ * Represents a value accepted in generated route search params.
+ */
 export type RouteSearchValue = boolean | number | string | null | undefined;
+/**
+ * Represents search params accepted by typed route href helpers.
+ */
 export type RouteSearchParams = Record<
   string,
   RouteSearchValue | readonly RouteSearchValue[]
 >;
 
+/**
+ * Extracts dynamic and catch-all params from an app route path pattern.
+ */
 export type RouteParamsFor<Path extends `/${string}`> = Simplify<ExtractRouteParams<Path>>;
 
+/**
+ * Builds the callable `href()` helper type for a specific app route path.
+ */
 export type AppRouteHref<Path extends `/${string}`> = keyof RouteParamsFor<Path> extends never
   ? (options?: StaticHrefOptions) => string
   : (options: DynamicHrefOptions<Path>) => string;
 
+/**
+ * Builds the Link `href` string type accepted for a specific app route path.
+ */
 export type AppRouteLinkHref<Path extends `/${string}`> =
   `${AppRouteLinkPathname<Path>}${AppRouteLinkHrefSuffix}`;
 
+/**
+ * Configures a static href with optional search params and hash.
+ */
 export interface StaticHrefOptions {
   hash?: string | undefined;
   search?: RouteSearchParams | undefined;
 }
 
+/**
+ * Configures a dynamic href with route params, optional search params, and hash.
+ */
 export interface DynamicHrefOptions<Path extends `/${string}`> extends StaticHrefOptions {
   params: RouteParamsFor<Path>;
 }
@@ -38,18 +59,30 @@ type SegmentRouteParam<Segment extends string> = Segment extends `:...${infer Na
 
 type Simplify<T> = { [Key in keyof T]: T[Key] } & {};
 
+/**
+ * Represents the search and hash suffix portion of a typed route href.
+ */
 export type AppRouteLinkHrefSuffix = "" | `?${string}` | `#${string}` | `?${string}#${string}`;
 
+/**
+ * Builds the pathname string type for a typed route href.
+ */
 export type AppRouteLinkPathname<Path extends `/${string}`> = Path extends "/"
   ? "/"
   : Path extends `/${infer Segments}`
     ? `/${AppRouteLinkSegments<Segments>}`
     : never;
 
+/**
+ * Builds the joined path segment string type for a typed route href.
+ */
 export type AppRouteLinkSegments<Segments extends string> = Segments extends `${infer Segment}/${infer Rest}`
   ? `${AppRouteLinkSegment<Segment>}/${AppRouteLinkSegments<Rest>}`
   : AppRouteLinkSegment<Segments>;
 
+/**
+ * Builds the string type for one static or dynamic route segment.
+ */
 export type AppRouteLinkSegment<Segment extends string> = Segment extends `:${string}`
   ? string
   : Segment;

package/src/types.ts

@@ -1,12 +1,24 @@
 import type { ReactCompatNode } from "@reckona/mreact-compat";
 import type { QueryClient } from "@reckona/mreact-query";
 
+/**
+ * Represents an app-router loader function.
+ */
 export type RouteLoader = (...args: never[]) => unknown;
 
+/**
+ * Infers resolved data returned by a route loader.
+ */
 export type InferLoaderData<TLoader extends RouteLoader> = Awaited<ReturnType<TLoader>>;
 
+/**
+ * Represents dynamic route params passed to loaders, pages, and handlers.
+ */
 export type RouteParams = Record<string, readonly string[] | string>;
 
+/**
+ * Infers route params from a loader context parameter.
+ */
 export type InferLoaderParams<TLoader extends RouteLoader> = TLoader extends (
   context: infer TContext,
   ...args: never[]
@@ -18,6 +30,9 @@ export type InferLoaderParams<TLoader extends RouteLoader> = TLoader extends (
     : RouteParams
   : RouteParams;
 
+/**
+ * Provides request, params, environment, and query client data to route loaders.
+ */
 export interface LoaderContext<TParams extends RouteParams = RouteParams> {
   env?: unknown;
   params: TParams;
@@ -39,17 +54,26 @@ export interface GenerateMetadataContext<
   request: Request;
 }
 
+/**
+ * Provides request and params to server route handlers.
+ */
 export interface RouteHandlerContext<TParams extends RouteParams = RouteParams> {
   params: TParams;
   request: Request;
 }
 
+/**
+ * Provides loader data, params, and request context to page components.
+ */
 export interface PageProps<TData = unknown, TParams extends RouteParams = RouteParams> {
   data: TData;
   params: TParams;
   request: Request;
 }
 
+/**
+ * Represents a page component whose props are inferred from a route loader.
+ */
 export type PageComponent<TLoader extends RouteLoader> = (
   props: PageProps<InferLoaderData<TLoader>, InferLoaderParams<TLoader>>,
 ) => ReactCompatNode;
@@ -65,16 +89,28 @@ export function definePage<TLoader extends RouteLoader>(
   return component;
 }
 
+/**
+ * Provides children, params, and request context to layout components.
+ */
 export interface LayoutProps<TParams extends RouteParams = RouteParams> {
   children: ReactCompatNode;
   params: TParams;
   request: Request;
 }
 
+/**
+ * Re-exports the node type accepted by mreact-compatible components.
+ */
 export type MReactNode = ReactCompatNode;
 
+/**
+ * Represents scalar metadata values rendered into head tags and headers.
+ */
 export type MetadataScalar = boolean | number | string;
 
+/**
+ * Describes an image value used by route metadata.
+ */
 export interface MetadataImage {
   alt?: MetadataScalar;
   height?: MetadataScalar;
@@ -124,13 +160,22 @@ export interface RouteMetadata {
   viewport?: MetadataScalar | MetadataViewport;
 }
 
+/**
+ * Describes viewport metadata key-value pairs.
+ */
 export type MetadataViewport = Record<string, MetadataScalar | null | undefined>;
 
+/**
+ * Describes a theme-color metadata entry with an optional media query.
+ */
 export interface MetadataThemeColor {
   color?: MetadataScalar;
   media?: MetadataScalar;
 }
 
+/**
+ * Describes an extra head element emitted by route metadata.
+ */
 export interface RouteHeadDescriptor {
   attrs?: Record<string, boolean | number | string | undefined>;
   content?: string;
@@ -138,6 +183,9 @@ export interface RouteHeadDescriptor {
   tag: "base" | "link" | "meta" | "script" | "style";
 }
 
+/**
+ * Configures security-related response headers from route metadata.
+ */
 export interface RouteSecurityHeaders {
   contentTypeOptions?: "nosniff" | null | undefined;
   frameOptions?: "DENY" | "SAMEORIGIN" | null | undefined;
@@ -146,36 +194,54 @@ export interface RouteSecurityHeaders {
   referrerPolicy?: string | null | undefined;
 }
 
+/**
+ * Configures the Strict-Transport-Security header from route metadata.
+ */
 export interface RouteStrictTransportSecurity {
   includeSubDomains?: boolean | undefined;
   maxAge: number;
   preload?: boolean | undefined;
 }
 
+/**
+ * Provides request context to a robots metadata route.
+ */
 export interface RobotsContext {
   baseUrl: string;
   host: string;
   request: Request;
 }
 
+/**
+ * Describes the robots.txt metadata route result.
+ */
 export interface RobotsManifest {
   host?: string | undefined;
   rules?: RobotsRule | readonly RobotsRule[] | undefined;
   sitemap?: string | readonly string[] | undefined;
 }
 
+/**
+ * Describes one robots.txt user-agent rule.
+ */
 export interface RobotsRule {
   allow?: string | readonly string[] | undefined;
   disallow?: string | readonly string[] | undefined;
   userAgent: string | readonly string[];
 }
 
+/**
+ * Provides request context to a sitemap metadata route.
+ */
 export interface SitemapContext {
   baseUrl: string;
   host: string;
   request: Request;
 }
 
+/**
+ * Describes one URL entry returned by a sitemap metadata route.
+ */
 export interface SitemapEntry {
   changeFrequency?: string | undefined;
   lastModified?: Date | string | number | undefined;
@@ -183,10 +249,16 @@ export interface SitemapEntry {
   url: string;
 }
 
+/**
+ * Provides request context to a web app manifest metadata route.
+ */
 export interface ManifestContext {
   baseUrl: string;
   host: string;
   request: Request;
 }
 
+/**
+ * Represents an arbitrary web app manifest descriptor.
+ */
 export type ManifestDescriptor = Record<string, unknown>;

package/src/upgrade.ts

@@ -1,6 +1,9 @@
 import type { IncomingMessage } from "node:http";
 import type { Duplex } from "node:stream";
 
+/**
+ * Handles an HTTP upgrade request on the app-router Node server.
+ */
 export type HttpUpgradeHandler = (
   request: IncomingMessage,
   socket: Duplex,

package/src/vite.ts

@@ -52,6 +52,9 @@ import { hasJsxSyntax } from "./source-jsx.js";
 import { prependTailwindSourceDirectives } from "./tailwind-source.js";
 import { workspacePackageFile } from "./workspace-packages.js";
 
+/**
+ * Configures the app-router Vite middleware used by development servers.
+ */
 export interface AppRouterViteMiddlewareOptions extends AppRouterProjectOptions {
   allowedHosts?: readonly string[] | undefined;
   define?: UserConfig["define"] | undefined;
@@ -68,6 +71,9 @@ type AppRouterViteRuntimeMiddlewareOptions = AppRouterViteMiddlewareOptions & {
   viteDevServer?: ViteDevServer | undefined;
 };
 
+/**
+ * Configures the app-router Vite plugin.
+ */
 export interface AppRouterVitePluginOptions extends AppRouterProjectOptions {
   allowedHosts?: readonly string[] | undefined;
   hostPolicy?: RequestHostPolicy | undefined;
@@ -93,6 +99,9 @@ type MreactRouterPlugin = Plugin & {
   [mreactRouterConfigKey]: MreactRouterPluginConfig;
 };
 
+/**
+ * Creates the app-router Vite plugin for route compilation and development middleware.
+ */
 export function createAppRouterVitePlugin(options: AppRouterVitePluginOptions): Plugin {
   const project = resolveAppRouterProjectOptions(options);
   const normalizedSourceDirs = project.allowedSourceDirs.map((directory) =>
@@ -412,6 +421,9 @@ function isCompatSourcePath(filename: string): boolean {
   return /\.compat(?:\.mreact)?(?:\.[cm]?[jt]sx?)?$/.test(filename);
 }
 
+/**
+ * Alias for `createAppRouterVitePlugin()` used by Vite config files.
+ */
 export const mreactRouter = createAppRouterVitePlugin;
 
 function routeTransformUserVitePlugins(
@@ -448,6 +460,9 @@ function routeTransformUserVitePlugins(
   return plugins;
 }
 
+/**
+ * Reads resolved app-router project config from a Vite plugin list.
+ */
 export function mreactRouterConfigFromPlugins(
   plugins: readonly unknown[],
 ): ResolvedAppRouterProject | undefined {
@@ -466,6 +481,9 @@ export function mreactRouterConfigFromPlugins(
   return undefined;
 }
 
+/**
+ * Creates Connect middleware that renders app-router requests during Vite development.
+ */
 export function createAppRouterViteMiddleware(
   options: AppRouterViteMiddlewareOptions,
 ): Connect.NextHandleFunction {
@@ -572,6 +590,9 @@ async function handleAppRouterViteRequest(
   }
 }
 
+/**
+ * Renders a development client asset generated by the app-router Vite integration.
+ */
 export async function renderAppRouterClientAsset(
   appDir: string,
   pathname: string,