@crombolo/common 0.39.1 → 0.40.0

package/dist/actions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Server actions (story 219): a function on the server that a form posts to,
+ * or an island calls. The config lists action modules, and each export is an
+ * action whose id is the module's key and the export's name, `profile.save`.
+ * docs/rendering.md, "Server actions".
+ */
+import type { FieldError, Result } from './result.ts';
+import type { RouteContext } from './routes.ts';
+/** The path an action is posted to: `/crombolo/actions/{id}`. */
+export declare const ACTIONS_PATH = "/crombolo/actions";
+/** The anti-forgery header and meta tag `/crombolo/bundle.js` uses, which a call from an island sends too. */
+export declare const ACTION_ANTIFORGERY_HEADER = "Crombolo-Antiforgery";
+/** What an action is given besides the form's data: a route's context, less its params. */
+export type ActionContext<Site = unknown, Member = unknown> = Omit<RouteContext<Site, Member>, 'params'>;
+/** An action: the form's data in, a `Response` or a `Result` out. */
+export type ServerAction<Site = unknown, Member = unknown> = (formData: FormData, context: ActionContext<Site, Member>) => Response | Result<unknown> | Promise<Response | Result<unknown>>;
+/** What an action answered, as the page it returned to reads it with `actionState`. */
+export interface ActionState<T = unknown> {
+    ok: boolean;
+    /** A success's value. */
+    value?: T;
+    /** An outcome's status. */
+    status?: number;
+    message?: string;
+    errors?: readonly FieldError[];
+    /** What was submitted, so the form can be shown again; passwords and files left out. */
+    values?: Record<string, string>;
+}
+type Answer<A> = A extends (...args: never[]) => infer R ? Awaited<R> extends Result<infer T, infer S> ? Result<T, S> : Result<unknown> : never;
+/** An action as an island is given it: called with a form's data, or an object of fields. */
+export type ClientAction<A> = (input: FormData | Record<string, string | Blob>) => Promise<Answer<A>>;
+/** An action given to an island, typed as the browser sees it, where inference falls short. */
+export declare function clientAction<A extends (...args: never[]) => unknown>(action: A): ClientAction<A>;
+/** An action in an island's props, as the server writes it. */
+export interface ActionReference {
+    $action: string;
+}
+/**
+ * An island's props with each action rebuilt as a function that posts to it
+ * and resolves to its `Result`; a redirect navigates. What the React mount
+ * does before rendering, and what an `<Island>` module calls itself.
+ */
+export declare function reviveActions<T>(props: T, antiforgery?: () => string | null): T;
+export {};

package/dist/actions.js

@@ -0,0 +1,64 @@
+import { Outcome, ok } from './result.js';
+/** The path an action is posted to: `/crombolo/actions/{id}`. */
+export const ACTIONS_PATH = '/crombolo/actions';
+/** The anti-forgery header and meta tag `/crombolo/bundle.js` uses, which a call from an island sends too. */
+export const ACTION_ANTIFORGERY_HEADER = 'Crombolo-Antiforgery';
+const ANTIFORGERY_META = 'crombolo-antiforgery';
+/** An action given to an island, typed as the browser sees it, where inference falls short. */
+export function clientAction(action) {
+    return action;
+}
+const isReference = (value) => typeof value === 'object' &&
+    value !== null &&
+    Object.keys(value).length === 1 &&
+    typeof value.$action === 'string';
+/**
+ * An island's props with each action rebuilt as a function that posts to it
+ * and resolves to its `Result`; a redirect navigates. What the React mount
+ * does before rendering, and what an `<Island>` module calls itself.
+ */
+export function reviveActions(props, antiforgery) {
+    const token = antiforgery ??
+        (() => globalThis.document
+            ?.querySelector(`meta[name="${ANTIFORGERY_META}"]`)
+            ?.getAttribute('content') ?? null);
+    const revive = (value) => {
+        if (isReference(value))
+            return callAction(value.$action, token);
+        if (Array.isArray(value))
+            return value.map(revive);
+        if (typeof value === 'object' && value !== null)
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, revive(item)]));
+        return value;
+    };
+    return revive(props);
+}
+function callAction(id, token) {
+    return async (input) => {
+        const body = input instanceof FormData ? input : new FormData();
+        if (!(input instanceof FormData))
+            for (const [name, value] of Object.entries(input))
+                body.append(name, value);
+        const headers = { accept: 'application/json' };
+        const antiforgery = token();
+        if (antiforgery)
+            headers[ACTION_ANTIFORGERY_HEADER] = antiforgery;
+        const response = await fetch(`${ACTIONS_PATH}/${encodeURIComponent(id)}`, {
+            method: 'POST',
+            body,
+            headers,
+            credentials: 'same-origin',
+        });
+        const answer = (await response.json());
+        if (answer.redirect) {
+            globalThis.location?.assign(answer.redirect);
+            return Outcome.seeOther(answer.redirect);
+        }
+        if (answer.ok)
+            return ok(answer.value);
+        return Outcome.of((answer.status ?? response.status), {
+            message: answer.message,
+            errors: answer.errors ?? [],
+        });
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './actions.ts';
 export * from './middleware.ts';
 export * from './result.ts';
 export * from './routes.ts';

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './actions.js';
 export * from './middleware.js';
 export * from './result.js';
 export * from './routes.js';

package/dist/result.d.ts

@@ -69,6 +69,11 @@ export declare class Ok<T> implements ResultMethods<T, never> {
     unwrap(): T;
     unwrapOr<U>(_fallback: U): T;
 }
+interface OutcomeInit {
+    message?: string;
+    errors?: readonly FieldError[];
+    location?: string;
+}
 /**
  * An HTTP outcome in place of a value: a redirect, or a refusal the site's
  * status pages render. Built with `Outcome.notFound()` and its siblings; thrown
@@ -97,6 +102,11 @@ export declare class Outcome<S extends OutcomeStatus = OutcomeStatus> implements
     match<R>(handlers: MatchHandlers<never, S, R>): R;
     unwrap(): never;
     unwrapOr<U>(fallback: U): U;
+    /**
+     * One by its status, as JSON carried it (story 219: an action's answer in the
+     * browser). A redirect's location is checked as the redirect helpers check it.
+     */
+    static of<S extends OutcomeStatus>(status: S, init?: OutcomeInit): Outcome<S>;
     /** 307: the visitor is sent on, keeping the request's method. */
     static redirect(url: string): Outcome<307>;
     /** 308: the page has moved for good, keeping the request's method. */

package/dist/result.js

@@ -134,6 +134,18 @@ export class Outcome {
     unwrapOr(fallback) {
         return fallback;
     }
+    /**
+     * One by its status, as JSON carried it (story 219: an action's answer in the
+     * browser). A redirect's location is checked as the redirect helpers check it.
+     */
+    static of(status, init = {}) {
+        if (!(status in OUTCOME_NAMES))
+            throw new Error(`${status} is not an outcome's status.`);
+        return new Outcome(status, {
+            ...init,
+            location: status < 400 ? assertSafeLocation(init.location ?? '') : undefined,
+        });
+    }
     /** 307: the visitor is sent on, keeping the request's method. */
     static redirect(url) {
         return new Outcome(307, { location: assertSafeLocation(url) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/common",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "description": "The contracts code outside crombolo is written against: the Result a site's services return, and the middleware chain's contract. No dependencies.",
   "license": "MIT",
   "author": "Crombolo",