@analogjs/router 3.0.0-alpha.7 → 3.0.0-alpha.70

package/types/src/lib/form-action.directive.d.ts

@@ -1,17 +1,24 @@
-import { InputSignal, OutputEmitterRef } from '@angular/core';
+import { type InputSignal, type OutputEmitterRef, type WritableSignal } from '@angular/core';
 import * as i0 from "@angular/core";
+export type FormActionState = 'submitting' | 'error' | 'redirect' | 'success' | 'navigate';
 export declare class FormAction {
     action: InputSignal<string>;
     onSuccess: OutputEmitterRef<unknown>;
     onError: OutputEmitterRef<unknown>;
-    state: OutputEmitterRef<'submitting' | 'error' | 'redirect' | 'success' | 'navigate'>;
+    state: OutputEmitterRef<FormActionState>;
     private router;
     private route;
-    private path;
-    submitted($event: any): void;
+    protected currentState: WritableSignal<FormActionState | 'idle'>;
+    /** Cached during construction (injection context) so inject() works. */
+    private _endpointUrl;
+    submitted($event: SubmitEvent): void;
     private _handleGet;
     private _handlePost;
-    private _getPath;
+    private _getExplicitAction;
+    private _getGetPath;
+    private _getPostPath;
+    private _emitState;
+    private _navigateTo;
     private _isJSON;
     static ɵfac: i0.ɵɵFactoryDeclaration<FormAction, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<FormAction, "form[action],form[method]", never, { "action": { "alias": "action"; "required": false; "isSignal": true; }; }, { "onSuccess": "onSuccess"; "onError": "onError"; "state": "state"; }, never, never, true, never>;

package/types/src/lib/inject-load.d.ts

@@ -1,6 +1,9 @@
 import { Injector } from '@angular/core';
 import { Observable } from 'rxjs';
-import { PageServerLoad } from './route-types';
-export declare function injectLoad<T extends (pageServerLoad: PageServerLoad) => Promise<any>>(options?: {
+import { LoadDataResult, PageServerLoad } from './route-types';
+export declare function injectLoad<T extends (pageServerLoad: PageServerLoad) => Promise<unknown>>(options?: {
     injector?: Injector;
 }): Observable<Awaited<ReturnType<T>>>;
+export declare function injectLoadData<T extends (pageServerLoad: PageServerLoad) => Promise<unknown>>(options?: {
+    injector?: Injector;
+}): Observable<LoadDataResult<T>>;

package/types/src/lib/inject-navigate.d.ts

@@ -0,0 +1,23 @@
+import { type NavigationBehaviorOptions } from '@angular/router';
+import type { AnalogRoutePath, RoutePathArgs } from './route-path';
+type NavigateWithExtrasArgs<P extends AnalogRoutePath> = RoutePathArgs<P> extends [options?: infer Options] ? [extras: NavigationBehaviorOptions] | [options: Options | undefined, extras: NavigationBehaviorOptions] : [options: RoutePathArgs<P>[0], extras: NavigationBehaviorOptions];
+type TypedNavigate = {
+    <P extends AnalogRoutePath>(path: P, ...args: RoutePathArgs<P>): Promise<boolean>;
+    <P extends AnalogRoutePath>(path: P, ...args: NavigateWithExtrasArgs<P>): Promise<boolean>;
+};
+/**
+ * Injects a typed navigate function.
+ *
+ * @example
+ * ```ts
+ * const navigate = injectNavigate();
+ *
+ * navigate('/users/[id]', { params: { id: '42' } });   // ✅
+ * navigate('/users/[id]', { params: { id: 42 } });     // ❌ type error
+ *
+ * // With navigation extras
+ * navigate('/users/[id]', { params: { id: '42' } }, { replaceUrl: true });
+ * ```
+ */
+export declare function injectNavigate(): TypedNavigate;
+export {};

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

@@ -0,0 +1,32 @@
+/**
+ * Injects the root route context provided via `withRouteContext()`.
+ *
+ * Inspired by TanStack Router's context inheritance where
+ * `createRootRouteWithContext<T>()` makes a typed context available
+ * to every route's `beforeLoad` and `loader` callbacks.
+ *
+ * In Angular, this uses DI under the hood — `withRouteContext(ctx)`
+ * provides the value, and `injectRouteContext<T>()` retrieves it
+ * with the expected type.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * provideFileRouter(
+ *   withRouteContext({
+ *     auth: inject(AuthService),
+ *     analytics: inject(AnalyticsService),
+ *   }),
+ * )
+ *
+ * // any-page.page.ts
+ * const ctx = injectRouteContext<{
+ *   auth: AuthService;
+ *   analytics: AnalyticsService;
+ * }>();
+ * ctx.analytics.trackPageView();
+ * ```
+ *
+ * @experimental
+ */
+export declare function injectRouteContext<T extends Record<string, unknown> = Record<string, unknown>>(): T;

package/types/src/lib/inject-typed-params.d.ts

@@ -0,0 +1,63 @@
+import { Injector, Signal } from '@angular/core';
+import type { AnalogRoutePath, RouteParamsOutput, RouteQueryOutput } from './route-path';
+/**
+ * Injects typed route params as a signal, constrained by the route table.
+ *
+ * Inspired by TanStack Router's `useParams({ from: '/users/$userId' })`
+ * pattern where the `from` parameter narrows the return type to only
+ * the params defined for that route.
+ *
+ * The `from` parameter is used purely for TypeScript type inference —
+ * at runtime, params are read from the current `ActivatedRoute`. This
+ * means it works correctly when used inside a component rendered by
+ * the specified route.
+ *
+ * When `withTypedRouter({ strictRouteParams: true })` is configured,
+ * a dev-mode assertion checks that the expected params from `from`
+ * exist in the active route and warns on mismatch.
+ *
+ * @example
+ * ```ts
+ * // In a component rendered at /users/[id]
+ * const params = injectParams('/users/[id]');
+ * // params() → { id: string }
+ *
+ * // With schema validation output types
+ * const params = injectParams('/products/[slug]');
+ * // params() → validated output type from routeParamsSchema
+ * ```
+ *
+ * @experimental
+ */
+export declare function injectParams<P extends AnalogRoutePath>(_from: P, options?: {
+    injector?: Injector;
+}): Signal<RouteParamsOutput<P>>;
+/**
+ * Injects typed route query params as a signal, constrained by the
+ * route table.
+ *
+ * Inspired by TanStack Router's `useSearch({ from: '/issues' })` pattern
+ * where search params are validated and typed per-route via
+ * `validateSearch` schemas.
+ *
+ * In Analog, the typing comes from `routeQuerySchema` exports that are
+ * detected at build time and recorded in the generated route table.
+ *
+ * The `from` parameter is used purely for TypeScript type inference.
+ * When `withTypedRouter({ strictRouteParams: true })` is configured,
+ * a dev-mode assertion checks that the expected params from `from`
+ * exist in the active route and warns on mismatch.
+ *
+ * @example
+ * ```ts
+ * // In a component rendered at /issues
+ * // (where routeQuerySchema validates { page: number, status: string })
+ * const query = injectQuery('/issues');
+ * // query() → { page: number; status: string }
+ * ```
+ *
+ * @experimental
+ */
+export declare function injectQuery<P extends AnalogRoutePath>(_from: P, options?: {
+    injector?: Injector;
+}): Signal<RouteQueryOutput<P>>;

package/types/src/lib/json-ld.d.ts

@@ -0,0 +1,32 @@
+import { Router } from '@angular/router';
+import type { Graph, Thing, WithContext } from 'schema-dts';
+export type JsonLdObject = Record<string, unknown>;
+export declare function isJsonLdObject(value: unknown): value is JsonLdObject;
+export declare function normalizeJsonLd(value: unknown): JsonLdObject[];
+export type JsonLd = JsonLdObject | JsonLdObject[];
+/**
+ * Typed JSON-LD document based on `schema-dts`.
+ *
+ * Accepts single Schema.org nodes (`WithContext<Thing>`),
+ * `@graph`-based documents (`Graph`), or arrays of nodes.
+ *
+ * This is the canonical JSON-LD type for route authoring surfaces
+ * (`routeMeta.jsonLd`, `routeJsonLd`, generated manifest).
+ *
+ * @example
+ * ```ts
+ * import type { WebPage, WithContext } from 'schema-dts';
+ *
+ * export const routeMeta = {
+ *   jsonLd: {
+ *     '@context': 'https://schema.org',
+ *     '@type': 'WebPage',
+ *     name: 'Products',
+ *   } satisfies WithContext<WebPage>,
+ * };
+ * ```
+ */
+export type AnalogJsonLdDocument = WithContext<Thing> | Graph | WithContext<Thing>[];
+export declare const ROUTE_JSON_LD_KEY: unique symbol;
+export declare function updateJsonLdOnRouteChange(router?: Router, document?: Document | null): void;
+export declare function serializeJsonLd(entry: JsonLdObject): string | null;

package/types/src/lib/meta-tags.d.ts

@@ -1,3 +1,5 @@
+import { Meta } from '@angular/platform-browser';
+import { Router } from '@angular/router';
 export declare const ROUTE_META_TAGS_KEY: unique symbol;
 declare const CHARSET_KEY = "charset";
 declare const HTTP_EQUIV_KEY = "httpEquiv";
@@ -29,5 +31,5 @@ type MetaTagKey = typeof CHARSET_KEY | typeof HTTP_EQUIV_KEY | typeof NAME_KEY |
 type ExcludeRestMetaTagKeys<Key extends MetaTagKey> = {
     [K in Exclude<MetaTagKey, Key>]?: never;
 };
-export declare function updateMetaTagsOnRouteChange(): void;
+export declare function updateMetaTagsOnRouteChange(router?: Router, metaService?: Meta): void;
 export {};

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

@@ -1,6 +1,7 @@
 import { Type } from '@angular/core';
 import { CanActivateChildFn, CanActivateFn, CanDeactivateFn, CanMatchFn, DeprecatedGuard, ResolveFn, Route } from '@angular/router';
 import { defineRouteMeta } from './define-route';
+import { AnalogJsonLdDocument } from './json-ld';
 import { MetaTag } from './meta-tags';
 type OmittedRouteProps = 'path' | 'matcher' | 'component' | 'loadComponent' | 'children' | 'loadChildren' | 'canLoad' | 'outlet';
 export type RouteConfig = Omit<Route, OmittedRouteProps>;
@@ -14,6 +15,7 @@ export interface DefaultRouteMeta extends Omit<Route, OmittedRouteProps | keyof
     };
     title?: string | ResolveFn<string>;
     meta?: MetaTag[] | ResolveFn<MetaTag[]>;
+    jsonLd?: AnalogJsonLdDocument | ResolveFn<AnalogJsonLdDocument | undefined>;
 }
 export interface RedirectRouteMeta {
     redirectTo: string;
@@ -25,5 +27,6 @@ export type RouteMeta = (DefaultRouteMeta & {
 export type RouteExport = {
     default: Type<unknown>;
     routeMeta?: RouteMeta | ReturnType<typeof defineRouteMeta>;
+    routeJsonLd?: AnalogJsonLdDocument | ResolveFn<AnalogJsonLdDocument | undefined>;
 };
 export {};

package/types/src/lib/provide-file-router-base.d.ts

@@ -0,0 +1,4 @@
+import { EnvironmentProviders } from '@angular/core';
+import { RouterFeatures, Routes } from '@angular/router';
+export declare function provideFileRouterWithRoutes(...features: RouterFeatures[]): EnvironmentProviders;
+export declare function withExtraRoutes(routes: Routes): RouterFeatures;

package/types/src/lib/provide-file-router.d.ts

@@ -1,5 +1,5 @@
 import { EnvironmentProviders } from '@angular/core';
-import { RouterFeatures, Routes } from '@angular/router';
+import { RouterFeatures } from '@angular/router';
 /**
  * Sets up providers for the Angular router, and registers
  * file-based routes. Additional features can be provided
@@ -9,10 +9,4 @@ import { RouterFeatures, Routes } from '@angular/router';
  * @returns Providers and features to configure the router with routes
  */
 export declare function provideFileRouter(...features: RouterFeatures[]): EnvironmentProviders;
-/**
- * Provides extra custom routes in addition to the routes
- * discovered from the filesystem-based routing. These routes are
- * inserted before the filesystem-based routes, and take priority in
- * route matching.
- */
-export declare function withExtraRoutes(routes: Routes): RouterFeatures;
+export { withExtraRoutes } from './provide-file-router-base';

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

@@ -0,0 +1,5 @@
+import type { Route } from '@angular/router';
+import type { RouteExport } from './models';
+export type RouteModuleFactory = () => Promise<RouteExport>;
+export type RouteModuleResolver<TFile> = (filename: string, fileLoader: () => Promise<TFile>) => RouteModuleFactory;
+export declare function createRoutes<TFile>(files: Record<string, () => Promise<TFile>>, resolveModule: RouteModuleResolver<TFile>, debug?: boolean): Route[];

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

@@ -0,0 +1,18 @@
+import { InjectionToken } from '@angular/core';
+import type { RouteExport } from './models';
+export type Files = Record<string, () => Promise<RouteExport>>;
+/**
+ * This variable reference is replaced with a glob of all page routes.
+ */
+export declare const ANALOG_ROUTE_FILES: {};
+export interface ExtraRouteFileSource {
+    files: Record<string, () => Promise<unknown>>;
+    resolveModule: (filename: string, fileLoader: () => Promise<unknown>) => () => Promise<RouteExport>;
+}
+export declare const ANALOG_EXTRA_ROUTE_FILE_SOURCES: InjectionToken<ExtraRouteFileSource[]>;
+/**
+ * Replaced at build time by the Vite router plugin with the number of
+ * discovered content route files. Used in dev mode to warn when content
+ * files exist but `withContentRoutes()` is not configured.
+ */
+export declare const ANALOG_CONTENT_FILE_COUNT = 0;

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/server-fn/dispatcher.d.ts

@@ -0,0 +1,23 @@
+import { InjectionToken, type Injector } from '@angular/core';
+import type { ServerFn } from './types';
+/**
+ * In-process transport for a server function call.
+ *
+ * Provided on the server by `provideServerContext`, so during SSR a server
+ * function runs in the same process — and the same request injector — as the
+ * render instead of making an HTTP request back into the app. Absent in the
+ * browser, where `ServerFnClient` falls back to `HttpClient`.
+ *
+ * `injector` is the **app environment injector** — `ServerFnClient` is
+ * `providedIn: 'root'`, and SSR bootstraps a fresh application per request, so
+ * its injector is both per-request and the right scope for a handler to resolve
+ * from. It is passed rather than captured from the token because
+ * `provideServerContext` is applied as *platform* providers, which sit above
+ * the app's `providedIn: 'root'` services.
+ *
+ * Deliberately not a component's node injector: a handler resolves app-level
+ * services, and making that depend on which component happened to call it would
+ * be surprising and unportable.
+ */
+export type ServerFnDispatcher = <In, Out>(fn: ServerFn<In, Out>, input: In, injector: Injector) => Promise<Out>;
+export declare const SERVER_FN_DISPATCHER: InjectionToken<ServerFnDispatcher>;

package/types/src/lib/server-fn/inject-server-fn.d.ts

@@ -0,0 +1,44 @@
+import { type ResourceRef, type StateKey } from '@angular/core';
+import type { ServerFn } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Client transport for server functions. In the browser it goes through Angular
+ * `HttpClient`, so client `HttpInterceptorFn`s apply. During SSR the dispatcher
+ * token is provided, and the call short-circuits the HTTP round-trip: the
+ * handler runs in-process in the current request injector. Lives in the client
+ * entry (client-safe).
+ */
+export declare class ServerFnClient {
+    private readonly http;
+    private readonly transferState;
+    private readonly injector;
+    private readonly dispatcher;
+    /** True while rendering on the server (the in-process dispatcher is provided). */
+    get isServer(): boolean;
+    call<In, Out>(fn: ServerFn<In, Out>, input: In): Promise<Out>;
+    /** Key a read's value for TransferState hydration (fn id + input). */
+    stateKey<Out>(fn: ServerFn<unknown, Out>, input: unknown): StateKey<Out>;
+    readSeed<Out>(fn: ServerFn<unknown, Out>, input: unknown): Out | undefined;
+    writeSeed<Out>(fn: ServerFn<unknown, Out>, input: unknown, value: Out): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ServerFnClient, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ServerFnClient>;
+}
+/** No-op provider hook; ServerFnClient is `providedIn: 'root'`. */
+export declare function provideServerFnClient(): readonly [];
+/**
+ * Reactive read of a server function as an Angular `resource()`.
+ *
+ * `args` is optional: omit it for an input-less read (the resource loads once);
+ * provide it for an input-bearing read (returning `undefined` from `args` leaves
+ * the resource idle until inputs are ready, the standard resource pattern). For
+ * imperative calls (mutations, event handlers) use `injectServerFnMutation`.
+ */
+export declare function injectServerFn<Out>(fn: ServerFn<void, Out>): ResourceRef<Out | undefined>;
+export declare function injectServerFn<In, Out>(fn: ServerFn<In, Out>, args: () => In | undefined): ResourceRef<Out | undefined>;
+/**
+ * Imperative binding of a server function: returns a callable that dispatches
+ * the call through `HttpClient` (so client interceptors apply) and resolves the
+ * result. Use for mutations and event-driven calls; use `injectServerFn` for
+ * reactive reads.
+ */
+export declare function injectServerFnMutation<In, Out>(fn: ServerFn<In, Out>): (input: In) => Promise<Out>;

package/types/src/lib/server-fn/server-fn-ref.d.ts

@@ -0,0 +1,24 @@
+import type { ServerFn, ServerFnMethod } from './types';
+export interface ServerFnRefConfig {
+    id?: string;
+    method?: ServerFnMethod;
+    /**
+     * Only its presence matters here: when `method` is omitted, a config with an
+     * `input` schema defaults to `POST`, otherwise `GET`. The schema itself is
+     * never used to build the ref — validation happens server-side.
+     */
+    input?: unknown;
+}
+/**
+ * Builds a server-function reference: the client-safe `{ __serverFn, id, url,
+ * method }` metadata that `injectServerFn`/`ServerFnClient` dispatch through.
+ *
+ * Shared by both sides so they produce identical refs: the server `serverFn`
+ * wraps this with registration + the handler, and the client build's scrub
+ * transform emits a call to this factory in place of the server module so the
+ * browser bundle carries only the ref, never the handler or its server imports.
+ *
+ * The returned value is callable-typed but throws if invoked directly — it is
+ * always dispatched via `injectServerFn`/`ServerFnClient`, never called.
+ */
+export declare function createServerFnRef<In, Out>(config: ServerFnRefConfig): ServerFn<In, Out>;

package/types/src/lib/server-fn/types.d.ts

@@ -0,0 +1,55 @@
+/** Minimal Standard Schema shape (valibot/zod/arktype conform). */
+export interface StandardSchemaV1<In = unknown> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        validate: (value: unknown) => {
+            value: In;
+            issues?: undefined;
+        } | {
+            issues: ReadonlyArray<{
+                message: string;
+            }>;
+        } | Promise<{
+            value: In;
+            issues?: undefined;
+        } | {
+            issues: ReadonlyArray<{
+                message: string;
+            }>;
+        }>;
+    };
+}
+export type ServerFnMethod = 'GET' | 'POST';
+export interface ServerFnConfig<In> {
+    /**
+     * Opaque route id `/_analog/fn/<id>`. **Build-injected, not author-supplied:**
+     * the Analog transform derives `hash(fileId + exportName)` and stamps it into
+     * both the server registration and the client proxy, so authors never choose a
+     * route. Absent at runtime means the transform did not run — `serverFn` throws.
+     */
+    id?: string;
+    /** Defaults to 'POST' when `input` is present, otherwise 'GET'. */
+    method?: ServerFnMethod;
+    input?: StandardSchemaV1<In>;
+}
+/**
+ * Interceptor-accumulated context, delivered to the handler as its second
+ * argument. Apps extend this by declaration merging.
+ */
+export interface ServerFnContext {
+}
+/** A server function reference: callable type on both sides; real impl only on the server. */
+export type ServerFn<In, Out> = ((input: In) => Promise<Out>) & {
+    readonly __serverFn: true;
+    readonly id: string;
+    readonly url: string;
+    readonly method: ServerFnMethod;
+};
+export type ServerFnHandler<In, Out> = (input: In, context: ServerFnContext) => Promise<Out> | Out;
+export interface ServerFnDef {
+    id: string;
+    method: ServerFnMethod;
+    config: ServerFnConfig<unknown>;
+    handler: ServerFnHandler<unknown, unknown>;
+}

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[];