@analogjs/router 2.6.4 → 2.7.0-beta.2

package/types/analogjs-router.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { Type, EnvironmentProviders, Injector } from '@angular/core';
+import { Type, EnvironmentProviders, Injector, ResourceRef, InjectionToken } from '@angular/core';
 import * as _angular_router from '@angular/router';
 import { Route, ActivatedRoute, Router, CanActivateFn, DeprecatedGuard, CanActivateChildFn, CanDeactivateFn, CanMatchFn, ResolveFn, RouterFeatures, Routes, ActivatedRouteSnapshot } from '@angular/router';
 import { H3EventContext, H3Event } from 'h3';
@@ -8,7 +8,6 @@ import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 import * as _angular_common_http from '@angular/common/http';
 import { HttpRequest, HttpHandlerFn } from '@angular/common/http';
-import { SafeHtml } from '@angular/platform-browser';
 
 type RouteOmitted = 'component' | 'loadComponent' | 'loadChildren' | 'path' | 'pathMatch';
 type RestrictedRoute = Omit<Route, RouteOmitted>;
@@ -234,35 +233,149 @@ declare function withDebugRoutes(): {
     }[];
 };
 
-type ServerProps = Record<string, any>;
-type ServerOutputs = Record<string, any>;
+/** Minimal Standard Schema shape (valibot/zod/arktype conform). */
+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;
+            }>;
+        }>;
+    };
+}
+type ServerFnMethod = 'GET' | 'POST';
+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>;
+}
 /**
- * @description
- * Component that defines the bridge between the client and server-only
- * components. The component passes the component ID and props to the server
- * and retrieves the rendered HTML and outputs from the server-only component.
+ * Interceptor-accumulated context, delivered to the handler as its second
+ * argument. Apps extend this by declaration merging.
+ */
+interface ServerFnContext {
+}
+/** A server function reference: callable type on both sides; real impl only on the server. */
+type ServerFn<In, Out> = ((input: In) => Promise<Out>) & {
+    readonly __serverFn: true;
+    readonly id: string;
+    readonly url: string;
+    readonly method: ServerFnMethod;
+};
+type ServerFnHandler<In, Out> = (input: In, context: ServerFnContext) => Promise<Out> | Out;
+interface ServerFnDef {
+    id: string;
+    method: ServerFnMethod;
+    config: ServerFnConfig<unknown>;
+    handler: ServerFnHandler<unknown, unknown>;
+}
+
+/**
+ * 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).
+ */
+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): _angular_core.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: _angular_core.ɵɵFactoryDeclaration<ServerFnClient, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ServerFnClient>;
+}
+/** No-op provider hook; ServerFnClient is `providedIn: 'root'`. */
+declare function provideServerFnClient(): readonly [];
+/**
+ * Reactive read of a server function as an Angular `resource()`.
  *
- * Status: experimental
+ * `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`.
  */
-declare class ServerOnly {
-    component: _angular_core.InputSignal<string>;
-    props: _angular_core.InputSignal<ServerProps | undefined>;
-    outputs: _angular_core.OutputEmitterRef<ServerOutputs>;
-    private http;
-    private sanitizer;
-    protected content: _angular_core.WritableSignal<SafeHtml>;
-    private route;
-    private baseURL;
-    private transferState;
-    constructor();
-    updateContent(content: {
-        html: string;
-        outputs: ServerOutputs;
-    }): void;
-    getComponentUrl(componentId: string): string;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ServerOnly, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ServerOnly, "server-only,ServerOnly,Server", never, { "component": { "alias": "component"; "required": true; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; }, { "outputs": "outputs"; }, never, never, true, never>;
+declare function injectServerFn<Out>(fn: ServerFn<void, Out>): ResourceRef<Out | undefined>;
+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.
+ */
+declare function injectServerFnMutation<In, Out>(fn: ServerFn<In, Out>): (input: In) => Promise<Out>;
+
+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.
+ */
+declare function createServerFnRef<In, Out>(config: ServerFnRefConfig): ServerFn<In, Out>;
+
+/**
+ * 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.
+ */
+type ServerFnDispatcher = <In, Out>(fn: ServerFn<In, Out>, input: In, injector: Injector) => Promise<Out>;
+declare const SERVER_FN_DISPATCHER: InjectionToken<ServerFnDispatcher>;
 
-export { FormAction, ServerOnly, createRoutes, defineRouteMeta, getLoadResolver, injectActivatedRoute, injectDebugRoutes, injectLoad, injectRouteEndpointURL, injectRouter, provideFileRouter, requestContextInterceptor, routes, withDebugRoutes, withExtraRoutes };
-export type { Files, LoadResult, MetaTag, PageServerLoad, RouteExport, RouteMeta };
+export { FormAction, SERVER_FN_DISPATCHER, ServerFnClient, createRoutes, createServerFnRef, defineRouteMeta, getLoadResolver, injectActivatedRoute, injectDebugRoutes, injectLoad, injectRouteEndpointURL, injectRouter, injectServerFn, injectServerFnMutation, provideFileRouter, provideServerFnClient, requestContextInterceptor, routes, withDebugRoutes, withExtraRoutes };
+export type { Files, LoadResult, MetaTag, PageServerLoad, RouteExport, RouteMeta, ServerFn, ServerFnConfig, ServerFnContext, ServerFnDef, ServerFnDispatcher, ServerFnHandler, ServerFnMethod, ServerFnRefConfig, StandardSchemaV1 };