@analogjs/router 3.0.0-alpha.3 → 3.0.0-alpha.30

package/types/src/lib/route-path.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Typed route path utilities for Analog.
+ *
+ * This module provides:
+ * - The `AnalogRouteTable` base interface (augmented by generated code)
+ * - The `AnalogRoutePath` union type
+ * - The `routePath()` URL builder function
+ *
+ * No Angular dependencies — can be used in any context.
+ */
+/**
+ * Base interface for the typed route table.
+ *
+ * This interface is augmented by generated code in `src/routeTree.gen.ts`.
+ * When no routes are generated, it is empty and `AnalogRoutePath` falls
+ * back to `string`.
+ */
+export interface AnalogRouteTable {
+}
+/**
+ * Union of all valid route paths.
+ *
+ * When routes are generated, this is a string literal union.
+ * When no routes are generated, this falls back to `string`.
+ */
+export type AnalogRoutePath = keyof AnalogRouteTable extends never ? string : Extract<keyof AnalogRouteTable, string>;
+/**
+ * Options for building a route URL.
+ */
+export interface RoutePathOptionsBase {
+    params?: Record<string, string | string[] | undefined>;
+    query?: Record<string, string | string[] | undefined>;
+    hash?: string;
+}
+/**
+ * Extracts the validated output type for route params.
+ *
+ * When a route exports `routeParamsSchema`, this resolves to the schema's
+ * output type (e.g., `{ id: number }` after coercion).
+ * When no schema exists, this is the same as the navigation param type.
+ */
+export type RouteParamsOutput<P extends string> = P extends keyof AnalogRouteTable ? AnalogRouteTable[P] extends {
+    paramsOutput: infer O;
+} ? O : AnalogRouteTable[P] extends {
+    params: infer Params;
+} ? Params : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Extracts the validated output type for route query params.
+ */
+export type RouteQueryOutput<P extends string> = P extends keyof AnalogRouteTable ? AnalogRouteTable[P] extends {
+    queryOutput: infer O;
+} ? O : Record<string, string | string[] | undefined> : Record<string, string | string[] | undefined>;
+type RequiredRouteParamKeys<Params> = Params extends Record<string, never> ? never : {
+    [K in keyof Params]-?: Record<string, never> extends Pick<Params, K> ? never : K;
+}[keyof Params];
+type HasRequiredRouteParams<Params> = [RequiredRouteParamKeys<Params>] extends [
+    never
+] ? false : true;
+/**
+ * Typed options that infer params from the route table when available.
+ */
+export type RoutePathOptions<P extends string = string> = P extends keyof AnalogRouteTable ? AnalogRouteTable[P] extends {
+    params: infer Params;
+} ? Params extends Record<string, never> ? {
+    query?: RouteQueryOutput<P>;
+    hash?: string;
+} : HasRequiredRouteParams<Params> extends true ? {
+    params: Params;
+    query?: RouteQueryOutput<P>;
+    hash?: string;
+} : {
+    params?: Params;
+    query?: RouteQueryOutput<P>;
+    hash?: string;
+} : RoutePathOptionsBase : RoutePathOptionsBase;
+/**
+ * Conditional args: require options when the route has params.
+ */
+export type RoutePathArgs<P extends string = string> = P extends keyof AnalogRouteTable ? AnalogRouteTable[P] extends {
+    params: infer Params;
+} ? Params extends Record<string, never> ? [options?: RoutePathOptions<P>] : HasRequiredRouteParams<Params> extends true ? [options: RoutePathOptions<P>] : [options?: RoutePathOptions<P>] : [options?: RoutePathOptionsBase] : [options?: RoutePathOptionsBase];
+/**
+ * Result of `routePath()` — contains properties that map directly
+ * to Angular's `[routerLink]`, `[queryParams]`, and `[fragment]` inputs.
+ */
+export interface RouteLinkResult {
+    path: string;
+    queryParams: Record<string, string | string[]> | null;
+    fragment: string | undefined;
+}
+/**
+ * Builds a typed route link object from a route path pattern and options.
+ *
+ * The returned object separates path, query params, and fragment for
+ * direct use with Angular's routerLink directive inputs.
+ *
+ * @example
+ * routePath('/about')
+ * // → { path: '/about', queryParams: null, fragment: undefined }
+ *
+ * routePath('/users/[id]', { params: { id: '42' } })
+ * // → { path: '/users/42', queryParams: null, fragment: undefined }
+ *
+ * routePath('/users/[id]', { params: { id: '42' }, query: { tab: 'settings' }, hash: 'bio' })
+ * // → { path: '/users/42', queryParams: { tab: 'settings' }, fragment: 'bio' }
+ *
+ * @example Template usage
+ * ```html
+ * @let link = routePath('/users/[id]', { params: { id: userId } });
+ * <a [routerLink]="link.path" [queryParams]="link.queryParams" [fragment]="link.fragment">
+ * ```
+ */
+export declare function routePath<P extends AnalogRoutePath>(path: P, ...args: RoutePathArgs<P>): RouteLinkResult;
+/**
+ * Internal: builds a `RouteLinkResult` from path and options.
+ * Exported for direct use in tests (avoids generic constraints).
+ */
+export declare function buildRouteLink(path: string, options?: RoutePathOptionsBase): RouteLinkResult;
+/**
+ * Internal URL builder. Separated from `routePath` so it can be
+ * used without generic constraints (e.g., in `injectNavigate`).
+ */
+export declare function buildUrl(path: string, options?: RoutePathOptionsBase): string;
+export {};

package/types/src/lib/route-types.d.ts

@@ -8,4 +8,5 @@ export type PageServerLoad = {
     fetch: $Fetch;
     event: H3Event;
 };
-export type LoadResult<A extends (pageServerLoad: PageServerLoad) => Promise<any>> = Awaited<ReturnType<A>>;
+export type LoadResult<A extends (pageServerLoad: PageServerLoad) => Promise<unknown>> = Awaited<ReturnType<A>>;
+export type LoadDataResult<A extends (pageServerLoad: PageServerLoad) => Promise<unknown>> = Exclude<LoadResult<A>, Response>;

package/types/src/lib/routes.d.ts

@@ -1,14 +1,5 @@
 import type { Route } from '@angular/router';
-import type { RouteExport } from './models';
-/**
- * This variable reference is replaced with a glob of all page routes.
- */
-export declare const ANALOG_ROUTE_FILES: {};
-/**
- * This variable reference is replaced with a glob of all content routes.
- */
-export declare const ANALOG_CONTENT_ROUTE_FILES: {};
-export type Files = Record<string, () => Promise<RouteExport | string>>;
+import { type Files } from './route-files';
 /**
  * A function used to parse list of files and create configuration of routes.
  *
@@ -16,4 +7,5 @@ export type Files = Record<string, () => Promise<RouteExport | string>>;
  * @returns Array of routes
  */
 export declare function createRoutes(files: Files, debug?: boolean): Route[];
+export { ANALOG_ROUTE_FILES } from './route-files';
 export declare const routes: Route[];

package/types/src/lib/validation-errors.d.ts

@@ -0,0 +1,7 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export type ValidationFieldErrors = Record<string, string[]>;
+export declare function issuePathToFieldName(path: ReadonlyArray<string | number | symbol | {
+    key: string | number | symbol;
+}>): string;
+export declare function issuesToFieldErrors(issues: ReadonlyArray<StandardSchemaV1.Issue>): ValidationFieldErrors;
+export declare function issuesToFormErrors(issues: ReadonlyArray<StandardSchemaV1.Issue>): string[];

package/types/tanstack-query/server/src/index.d.ts

@@ -0,0 +1 @@
+export { provideServerAnalogQuery } from '../../src/provide-server-analog-query';

package/types/tanstack-query/src/index.d.ts

@@ -0,0 +1,2 @@
+export { ANALOG_QUERY_STATE_KEY, provideAnalogQuery, } from './provide-analog-query.js';
+export { serverQueryOptions, serverMutationOptions, serverInfiniteQueryOptions, } from './server-query.js';

package/types/tanstack-query/src/provide-analog-query.d.ts

@@ -0,0 +1,4 @@
+import type { EnvironmentProviders, StateKey } from '@angular/core';
+import type { DehydratedState } from '@tanstack/angular-query-experimental';
+export declare const ANALOG_QUERY_STATE_KEY: StateKey<DehydratedState>;
+export declare function provideAnalogQuery(): EnvironmentProviders;

package/types/tanstack-query/src/provide-server-analog-query.d.ts

@@ -0,0 +1,2 @@
+import type { EnvironmentProviders } from '@angular/core';
+export declare function provideServerAnalogQuery(): EnvironmentProviders;

package/types/tanstack-query/src/server-query.d.ts

@@ -0,0 +1,16 @@
+import type { HttpClient } from '@angular/common/http';
+import type { CreateQueryOptions, CreateMutationOptions, CreateInfiniteQueryOptions, DefaultError, InfiniteData, QueryKey } from '@tanstack/angular-query-experimental';
+import type { ServerRouteHandler, InferRouteQuery, InferRouteBody, InferRouteResult } from '../../server/actions/src/index.js';
+export declare function serverQueryOptions<TRoute extends ServerRouteHandler<any, any, any>, TError = DefaultError, TData = InferRouteResult<TRoute>, TQueryKey extends QueryKey = QueryKey>(http: HttpClient, url: string, options: {
+    queryKey: TQueryKey;
+    query?: InferRouteQuery<TRoute>;
+} & Omit<CreateQueryOptions<InferRouteResult<TRoute>, TError, TData, TQueryKey>, 'queryKey' | 'queryFn'>): CreateQueryOptions<InferRouteResult<TRoute>, TError, TData, TQueryKey>;
+export declare function serverMutationOptions<TRoute extends ServerRouteHandler<any, any, any>, TError = DefaultError, TOnMutateResult = unknown>(http: HttpClient, url: string, options?: Omit<CreateMutationOptions<InferRouteResult<TRoute>, TError, InferRouteBody<TRoute>, TOnMutateResult>, 'mutationFn'>): CreateMutationOptions<InferRouteResult<TRoute>, TError, InferRouteBody<TRoute>, TOnMutateResult>;
+export declare function serverInfiniteQueryOptions<TRoute extends ServerRouteHandler<any, any, any>, TError = DefaultError, TData = InfiniteData<InferRouteResult<TRoute>>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(http: HttpClient, url: string, options: {
+    queryKey: TQueryKey;
+    query: (context: {
+        pageParam: TPageParam;
+    }) => InferRouteQuery<TRoute>;
+    initialPageParam: TPageParam;
+    getNextPageParam: (lastPage: InferRouteResult<TRoute>, allPages: InferRouteResult<TRoute>[]) => TPageParam | undefined | null;
+} & Omit<CreateInfiniteQueryOptions<InferRouteResult<TRoute>, TError, TData, TQueryKey, TPageParam>, 'queryKey' | 'queryFn' | 'initialPageParam' | 'getNextPageParam'>): CreateInfiniteQueryOptions<InferRouteResult<TRoute>, TError, TData, TQueryKey, TPageParam>;