cross-router-core 1.0.1

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Bricklou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+import { GenericSchema, InferOutput } from 'valibot';
+
+interface RouterContext<T = unknown> {
+    defaultValue?: T;
+}
+declare function createContext<T>(defaultValue?: T): RouterContext<T>;
+declare class RouterContextProvider {
+    private map;
+    /**
+     * Create a new `RouterContextProvider` instance
+     * @param init An optional initial context map to populate the provider with
+     */
+    constructor(init?: Map<RouterContext, unknown>);
+    /**
+     * Access a value from the context. If no value has been set for the context,
+     * it will return the context's `defaultValue` if provided, or throw an error
+     * if no `defaultValue` was set.
+     * @param context The context to get the value for
+     * @returns The value for the context, or the context's `defaultValue` if no
+     * value was set
+     */
+    get<T>(context: RouterContext<T>): T;
+    /**
+     * Set a value for the context. If the context already has a value set, this
+     * will overwrite it.
+     *
+     * @param context The context to set the value for
+     * @param value The value to set for the context
+     * @returns {void}
+     */
+    set<C extends RouterContext>(context: C, value: C extends RouterContext<infer T> ? T : never): void;
+}
+
+type ExtractParams<TPath extends string> = TPath extends `${infer _Start}:${infer Param}/${infer Rest}` ? Param | ExtractParams<`/${Rest}`> : TPath extends `${infer _Start}:${infer Param}` ? Param : never;
+type ParamsFromPath<TPath extends string> = {
+    [K in ExtractParams<TPath>]: string;
+};
+type SearchSchema = GenericSchema<Record<string, unknown>>;
+type InferSearch<TSchema extends SearchSchema> = InferOutput<TSchema>;
+interface MiddlewareArgs {
+    context: RouterContextProvider;
+    request: NavigationRequest;
+}
+type NextFn = () => Promise<void>;
+interface Middleware {
+    handler: (args: MiddlewareArgs, next: NextFn) => Promise<void>;
+}
+type AnyMiddleware = Middleware;
+declare function defineMiddleware(handler: (args: MiddlewareArgs, next: NextFn) => Promise<void>): Middleware;
+type MaybePromise<T> = Promise<T> | T;
+interface LoaderArgs<TParams extends Record<string, string>, TSearch> {
+    context: RouterContextProvider;
+    params: TParams;
+    search: TSearch;
+    request: NavigationRequest;
+}
+interface ActionArgs<TParams extends Record<string, string>> {
+    context: RouterContextProvider;
+    params: TParams;
+    request: NavigationRequest;
+    formData: FormData;
+}
+type LoaderFn<TParams extends Record<string, string>, TSearch, TData> = (args: LoaderArgs<TParams, TSearch>) => MaybePromise<TData>;
+type ActionFn<TParams extends Record<string, string>> = (args: ActionArgs<TParams>) => MaybePromise<unknown>;
+interface RevalidateArgs<TParams extends Record<string, string>> {
+    currentParams: TParams;
+    nextParams: TParams;
+    currentSearch: Record<string, unknown>;
+    nextSearch: Record<string, unknown>;
+    formData?: FormData | undefined;
+}
+interface RouteDefinition<TPath extends string = string, TMiddlewares extends AnyMiddleware[] = AnyMiddleware[], TSearchSchema extends SearchSchema = SearchSchema, TLoaderData = unknown, TComponent = unknown> {
+    id: string;
+    path?: TPath;
+    index?: true;
+    middleware?: TMiddlewares;
+    search?: TSearchSchema;
+    loader?: LoaderFn<ParamsFromPath<TPath>, TSearchSchema extends SearchSchema ? InferSearch<TSearchSchema> : Record<string, unknown>, TLoaderData>;
+    action?: ActionFn<ParamsFromPath<TPath>>;
+    shouldRevalidate?: (args: RevalidateArgs<ParamsFromPath<TPath>>) => boolean;
+    component?: TComponent;
+    errorComponent?: TComponent;
+    lazy?: () => Promise<Partial<Pick<RouteDefinition<TPath, TMiddlewares, TSearchSchema, TLoaderData, TComponent>, 'loader' | 'action' | 'component' | 'errorComponent'>>>;
+    children?: AnyRouteDefinition[];
+    __renderer?: RouteRenderer;
+}
+type AnyRouteDefinition = RouteDefinition<any, any, any, any, any>;
+interface RouteRenderer {
+    /** Mount component into target element. Returns cleanup fn. */
+    mount: (component: unknown, target: HTMLElement) => () => void;
+}
+interface RouteMatch<TLoaderData = unknown> {
+    route: AnyRouteDefinition;
+    params: Record<string, string>;
+    search: Record<string, unknown>;
+    pathname: string;
+    loaderData: TLoaderData;
+    status: 'idle' | 'loading' | 'success' | 'error';
+    error?: unknown;
+}
+type AnyRouteMatch = RouteMatch<unknown>;
+interface NavigationRequest {
+    url: URL;
+    method: 'GET' | 'POST';
+    formData?: FormData;
+}
+type NavigationStatus = 'idle' | 'loading' | 'submitting' | 'redirecting' | 'error';
+interface NavigationState {
+    location: Location;
+    status: NavigationStatus;
+    matches: AnyRouteMatch[];
+    loaderData: Record<string, unknown>;
+    actionData: unknown;
+    error: unknown;
+    isTransitioning: boolean;
+    viewTransition: boolean;
+}
+interface Location {
+    pathname: string;
+    search: string;
+    hash: string;
+    state: unknown;
+    key: string;
+}
+interface RouterOptions {
+    context?: () => RouterContextProvider;
+    middleware?: AnyMiddleware[];
+    notFoundComponent?: unknown;
+    errorComponent?: unknown;
+}
+declare class Redirect {
+    readonly to: string;
+    readonly status: 301 | 302 | 307 | 308;
+    readonly __type: "redirect";
+    constructor(to: string, status?: 301 | 302 | 307 | 308);
+}
+declare function redirect(to: string, status?: 301 | 302 | 307 | 308): never;
+declare function isRedirect(value: unknown): value is Redirect;
+interface RouterInstance {
+    /** Current state */
+    readonly state: NavigationState;
+    /** Subscribe to state changes — returns unsubscribe fn */
+    subscribe: (listener: (state: NavigationState) => void) => () => void;
+    navigate: (to: string, options?: NavigateOptions) => Promise<void>;
+    replace: (to: string, options?: NavigateOptions) => Promise<void>;
+    back: () => void;
+    forward: () => void;
+    /** Form submission trigger (called by <Form> component in adapters) */
+    submit: (formData: FormData, options: SubmitOptions) => Promise<void>;
+    /** Must be called once by the framework adapter before first render */
+    initialize: () => Promise<void>;
+    /** Add routes under a parent node (by id). Use 'root' for top level */
+    patch: (routes: AnyRouteDefinition[], parentId?: string) => void;
+    /** Remove a route subtree by id */
+    unpatch: (routeId: string) => void;
+    /** Cleanup — removes history listener */
+    destroy: () => void;
+}
+interface NavigateOptions {
+    state?: unknown;
+    replace?: boolean;
+    resetScroll?: boolean;
+    viewTransition?: boolean;
+}
+interface SubmitOptions {
+    action: string;
+    method?: 'POST';
+}
+interface RouteRegistry {
+    patch: (routes: AnyRouteDefinition[], parentId?: string) => void;
+    unpatch: (routeId: string) => void;
+    getTree: () => AnyRouteDefinition[];
+    subscribe: (listener: (tree: AnyRouteDefinition[]) => void) => () => void;
+}
+
+type HistoryListener = (location: Location) => void;
+interface History {
+    readonly location: Location;
+    push: (to: string, state?: unknown) => void;
+    replace: (to: string, state?: unknown) => void;
+    back: () => void;
+    forward: () => void;
+    go: (delta: number) => void;
+    listen: (listener: HistoryListener) => () => void;
+    destroy: () => void;
+}
+declare function createBrowserHistory(): History;
+declare function createMemoryHistory(initialPath?: string): History;
+
+declare class MiddlewareError extends Error {
+    readonly middlewareIndex: number;
+    constructor(message: string, middlewareIndex: number);
+}
+
+declare class RegistryError extends Error {
+    constructor(message: string);
+}
+declare function createRegistry(initialRoutes?: AnyRouteDefinition[]): RouteRegistry;
+
+declare function createRouter(history: History, options: RouterOptions, registry: RouteRegistry): RouterInstance;
+declare function createBrowserRouter(options: RouterOptions, initialRoutes?: AnyRouteDefinition[]): RouterInstance;
+/**
+ * Recursively tag all routes (and their children) with a renderer.
+ * This method is used by renderers
+ */
+declare function tag(renderer: RouteRenderer, defs: AnyRouteDefinition[]): AnyRouteDefinition[];
+
+export { type ActionArgs, type ActionFn, type AnyMiddleware, type AnyRouteDefinition, type AnyRouteMatch, type ExtractParams, type History, type HistoryListener, type InferSearch, type LoaderArgs, type LoaderFn, type Location, type Middleware, type MiddlewareArgs, MiddlewareError, type NavigateOptions, type NavigationState, type NavigationStatus, type NextFn, type ParamsFromPath, Redirect, RegistryError, type RevalidateArgs, type RouteDefinition, type RouteMatch, type RouteRegistry, type RouteRenderer, RouterContextProvider, type RouterInstance, type RouterOptions, type SearchSchema, type SubmitOptions, createBrowserHistory, createBrowserRouter, createContext, createMemoryHistory, createRegistry, createRouter, defineMiddleware, isRedirect, redirect, tag };