@rivetjs/router 0.1.0-alpha.0 → 0.1.0-alpha.1

package/shared/server-exports.d.ts

@@ -0,0 +1,78 @@
+import type { RequestEvent } from "../server/handler.js";
+import type { RouteId } from "../index.js";
+/**
+ * Tag key of a server export: an own non-enumerable property whose value is the kind. `Symbol.for`
+ * (not a module-local registry): route modules and the server bundle's router may be different
+ * module instances.
+ */
+export declare const SERVER_EXPORT: unique symbol;
+/** What a server export is: the name of the wrapper that made it. */
+export type ServerKind = "load" | "guard" | "actions" | "entries" | "headers" | "onRequest" | "onGet" | "onPost" | "onPut" | "onPatch" | "onDelete" | "onOptions";
+/** A value tagged as a server export of kind `K` (still callable / usable as `V`). */
+export type ServerExport<K extends ServerKind, V> = V & {
+    readonly [SERVER_EXPORT]: K;
+};
+type Params = Record<string, string> | RouteId;
+/** Request handler result: a `Response` ends the request; `undefined` continues; an `HttpError` is thrown or returned. */
+type HandlerResult = Response | undefined | void | Promise<Response | undefined | void>;
+type ActionFn = {
+    bivariance(event: RequestEvent): unknown;
+}["bivariance"];
+/**
+ * Marks a deferred loader (`load(fn, { defer: true })`): an own non-enumerable property of the wrapped function. The
+ * handler starts it with the request and renders without awaiting it (`server/deferred.ts`).
+ */
+export declare const DEFER: unique symbol;
+declare const deferred: unique symbol;
+/**
+ * The data of a deferred loader (`load(fn, { defer: true })`): a handle the page renders through a boundary —
+ * `<Async load={() => data}>` / `resource(() => data)` — while the shell streams without waiting for it. On the server
+ * it follows this request's run of the loader (started with the request); after a client navigation (the data
+ * endpoint awaits deferred loaders) the slot holds the resolved value itself, which boundaries take as it is. Reading
+ * it directly (`data.title`) is a bug: dev throws `DeferredDataError`.
+ */
+export interface Deferred<T> extends PromiseLike<T> {
+    readonly [deferred]: T;
+}
+/** Options of `load(fn, options)`. */
+export interface LoadOptions {
+    /**
+     * Start the loader with the request but do not wait for it before rendering: the page's (layout's) `data` is a
+     * `Deferred<T>`, rendered through `<Async load={() => data}>` / `resource(() => data)`; the response streams the
+     * shell first and the boundary's content when the loader settles. Client navigations (`?_rivet=data`) get the
+     * resolved value. A deferred loader cannot set headers or cookies (TypeError: the response head is already out).
+     */
+    readonly defer?: boolean;
+}
+/** Loader: data for the page / layout (`data` prop; `PageProps<typeof loader>`). Runs on the server only. */
+export declare function load<T, P extends Params = Record<string, string>>(fn: (event: RequestEvent<P>) => T, options?: LoadOptions & {
+    readonly defer?: false;
+}): ServerExport<"load", (event: RequestEvent<P>) => T>;
+/** Deferred loader (`{ defer: true }`): the data is a `Deferred<T>` the page renders through a boundary. */
+export declare function load<T, P extends Params = Record<string, string>>(fn: (event: RequestEvent<P>) => T, options: LoadOptions & {
+    readonly defer: true;
+}): ServerExport<"load", (event: RequestEvent<P>) => Deferred<Awaited<T>>>;
+/** Guard: runs outer → inner before loaders and actions; return a `Response` / throw `redirect()` / `deny()` to stop. */
+export declare function guard<T, P extends Params = Record<string, string>>(fn: (event: RequestEvent<P>) => T): ServerExport<"guard", (event: RequestEvent<P>) => T>;
+/** Form actions (`POST ?/name`): `{ name: (event) => result }`; `fail(status, data)` for validation errors. */
+export declare function actions<A extends Record<string, ActionFn>>(map: A): ServerExport<"actions", A>;
+/** Params to prerender a dynamic route (static builds): one object of param values per page (optional params may be absent). */
+export declare function entries<T extends Iterable<object> | Promise<Iterable<object>>>(fn: () => T): ServerExport<"entries", () => T>;
+/** Response headers of the route (`HeadersInit`), after the guards. */
+export declare function headers<P extends Params = Record<string, string>>(fn: (event: RequestEvent<P>) => HeadersInit | undefined): ServerExport<"headers", (event: RequestEvent<P>) => HeadersInit | undefined>;
+type Handler<P extends Params> = (event: RequestEvent<P>) => HandlerResult;
+/** Any method, before guards (outer → inner); a returned `Response` ends the request. */
+export declare function onRequest<P extends Params = Record<string, string>>(fn: Handler<P>): ServerExport<"onRequest", Handler<P>>;
+/** GET / HEAD request handler (endpoint routes: must return the `Response`; pages: middleware before the guards). */
+export declare function onGet<P extends Params = Record<string, string>>(fn: Handler<P>): ServerExport<"onGet", Handler<P>>;
+/** POST request handler (pages: before actions; endpoints: answers). */
+export declare function onPost<P extends Params = Record<string, string>>(fn: Handler<P>): ServerExport<"onPost", Handler<P>>;
+/** PUT request handler. */
+export declare function onPut<P extends Params = Record<string, string>>(fn: Handler<P>): ServerExport<"onPut", Handler<P>>;
+/** PATCH request handler. */
+export declare function onPatch<P extends Params = Record<string, string>>(fn: Handler<P>): ServerExport<"onPatch", Handler<P>>;
+/** DELETE request handler. */
+export declare function onDelete<P extends Params = Record<string, string>>(fn: Handler<P>): ServerExport<"onDelete", Handler<P>>;
+/** OPTIONS (CORS preflight): no CSRF check; nothing answered → `204` + `Allow`. */
+export declare function onOptions<P extends Params = Record<string, string>>(fn: Handler<P>): ServerExport<"onOptions", Handler<P>>;
+export {};

package/shared/server-exports.js

@@ -0,0 +1,77 @@
+/**
+ * Tag key of a server export: an own non-enumerable property whose value is the kind. `Symbol.for`
+ * (not a module-local registry): route modules and the server bundle's router may be different
+ * module instances.
+ */
+export const SERVER_EXPORT = Symbol.for("rivet.server");
+function tag(kind, value) {
+    Object.defineProperty(value, SERVER_EXPORT, { value: kind });
+    return value;
+}
+// A fresh function per wrapper call: `onGet(h)` and `onPost(h)` with one `h` keep their own kinds.
+function wrap(kind, fn) {
+    if (typeof fn !== "function")
+        throw new TypeError(`${kind}() expects a function`);
+    return tag(kind, fn.bind(undefined));
+}
+/**
+ * Marks a deferred loader (`load(fn, { defer: true })`): an own non-enumerable property of the wrapped function. The
+ * handler starts it with the request and renders without awaiting it (`server/deferred.ts`).
+ */
+export const DEFER = Symbol.for("rivet.defer");
+export function load(fn, options) {
+    const loader = wrap("load", fn);
+    if (options?.defer)
+        Object.defineProperty(loader, DEFER, { value: true });
+    return loader;
+}
+/** Guard: runs outer → inner before loaders and actions; return a `Response` / throw `redirect()` / `deny()` to stop. */
+export function guard(fn) {
+    return wrap("guard", fn);
+}
+/** Form actions (`POST ?/name`): `{ name: (event) => result }`; `fail(status, data)` for validation errors. */
+export function actions(map) {
+    if (typeof map !== "object" || map === null)
+        throw new TypeError("actions() expects an object of functions");
+    const copy = { ...map };
+    for (const name of Object.keys(copy))
+        if (typeof copy[name] !== "function")
+            throw new TypeError(`actions(): \`${name}\` is not a function`);
+    return tag("actions", copy);
+}
+/** Params to prerender a dynamic route (static builds): one object of param values per page (optional params may be absent). */
+export function entries(fn) {
+    return wrap("entries", fn);
+}
+/** Response headers of the route (`HeadersInit`), after the guards. */
+export function headers(fn) {
+    return wrap("headers", fn);
+}
+/** Any method, before guards (outer → inner); a returned `Response` ends the request. */
+export function onRequest(fn) {
+    return wrap("onRequest", fn);
+}
+/** GET / HEAD request handler (endpoint routes: must return the `Response`; pages: middleware before the guards). */
+export function onGet(fn) {
+    return wrap("onGet", fn);
+}
+/** POST request handler (pages: before actions; endpoints: answers). */
+export function onPost(fn) {
+    return wrap("onPost", fn);
+}
+/** PUT request handler. */
+export function onPut(fn) {
+    return wrap("onPut", fn);
+}
+/** PATCH request handler. */
+export function onPatch(fn) {
+    return wrap("onPatch", fn);
+}
+/** DELETE request handler. */
+export function onDelete(fn) {
+    return wrap("onDelete", fn);
+}
+/** OPTIONS (CORS preflight): no CSRF check; nothing answered → `204` + `Allow`. */
+export function onOptions(fn) {
+    return wrap("onOptions", fn);
+}