@ubean/routes 0.2.2 → 0.3.0

package/dist/form-action-CZA0dSMO.js

@@ -0,0 +1,511 @@
+import { ACTION_BRAND, ActionError, isActionFailure } from "@ubean/shared";
+//#region src/actions/id.ts
+/**
+* Stable Action ID generation (P9-02).
+*
+* Action IDs are derived from the action's source location (file path +
+* export name) so the client and server agree on the same ID without
+* runtime coordination. The Vite plugin injects the ID at build time,
+* but a runtime fallback is provided for actions defined outside the
+* `'use server'` pipeline (e.g. inline `defineAction` in page modules).
+*
+* Format: `act_<base32(sha1(relPath:exportName)).slice(0, 12)>`
+*   - `act_` prefix avoids collisions with other URL components
+*   - 12 chars of base32 gives ~60 bits of entropy (collision-resistant
+*     for any reasonable project size)
+*   - base32 (RFC 4648, lowercase) is URL-safe and case-insensitive
+*/
+const BASE32_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+/**
+* Compute a stable action ID from a file path and export name.
+*
+* @param filePath Project-relative file path (e.g. `src/actions/auth.ts`)
+* @param exportName The export name (e.g. `login`, `default`)
+* @returns A stable action ID string
+*/
+function createActionId(filePath, exportName) {
+	return `act_${base32HashSync(`${filePath}:${exportName}`).slice(0, 12)}`;
+}
+/**
+* Synchronous base32 hash. Uses a simple FNV-1a hash (32-bit) when
+* `crypto.subtle` is unavailable or async is undesirable. The hash space
+* is smaller than SHA-1 but sufficient for action IDs within a single
+* project (collision probability ~1 in 4 billion for 12 chars).
+*
+* For the Vite plugin path, a stronger SHA-1 hash is injected at build
+* time, so this runtime fallback only affects inline `defineAction` calls
+* without a file context.
+*/
+function base32HashSync(input) {
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	let hash2 = 16777619;
+	for (let i = 0; i < input.length; i++) {
+		hash2 ^= input.charCodeAt(i) * 31;
+		hash2 = Math.imul(hash2, 16777619);
+	}
+	return bigIntToBase32(BigInt(hash >>> 0) * (1n << 28n) + BigInt(hash2 >>> 0), 12);
+}
+function bigIntToBase32(value, length) {
+	let result = "";
+	let v = value;
+	for (let i = 0; i < length; i++) {
+		result = BASE32_ALPHABET[Number(v & 31n)] + result;
+		v >>= 5n;
+	}
+	return result;
+}
+/**
+* Validate that a string is a well-formed action ID.
+*
+* Used by the dispatcher to reject malformed requests early.
+*/
+function isValidActionId(id) {
+	return /^act_[a-z2-7]{12}$/.test(id);
+}
+//#endregion
+//#region src/actions/registry.ts
+const _registry = /* @__PURE__ */ new Map();
+/**
+* Register a server action in the global registry.
+*
+* Called by `defineAction` (implicitly) and by the Vite plugin's virtual
+* module (explicitly) for `'use server'` modules.
+*
+* If an action with the same ID is already registered, the call is a
+* no-op (HMR-safe: re-registering the same action on hot reload doesn't
+* throw).
+*/
+function registerAction(action) {
+	if (!_registry.has(action.id)) _registry.set(action.id, action);
+}
+/**
+* Look up a registered server action by ID.
+*/
+function getAction(id) {
+	return _registry.get(id);
+}
+/**
+* Check whether an action with the given ID is registered.
+*/
+function hasAction(id) {
+	return _registry.has(id);
+}
+/**
+* List all registered actions (for debugging / DevTools).
+*/
+function listActions() {
+	return [..._registry.values()];
+}
+/**
+* Clear the registry (for tests).
+*
+* Not intended for application code — actions are registered once at
+* module load and remain for the lifetime of the process.
+*/
+function clearActions() {
+	_registry.clear();
+}
+/**
+* Register a map of actions at once (bulk registration helper for the
+* Vite plugin's virtual module).
+*/
+function registerActions(actions) {
+	for (const action of actions) registerAction(action);
+}
+//#endregion
+//#region src/actions/define.ts
+/**
+* `defineAction` — Astro-style server action creator (P9-02).
+*
+* Wraps an async function as a server action with a stable ID. The action
+* can be invoked:
+*
+*  - Server-side: call the returned function directly (typed input/output).
+*  - Client-side: the Vite plugin replaces the export with an RPC stub that
+*    POSTs to `/__actions` (transparent to the caller).
+*  - Form (progressive enhancement): use the action's `id` as a form
+*    `action` attribute, e.g. `<form method="POST" action="?/login">`.
+*
+* ## With a schema
+*
+* ```ts
+* import { defineAction } from 'ubean';
+* import { z } from 'zod';
+*
+* export const login = defineAction(
+*   z.object({ email: z.string().email(), password: z.string() }),
+*   async (data, ctx) => {
+*     // data is typed as { email: string; password: string }
+*     return { user: data.email };
+*   }
+* );
+* ```
+*
+* ## Without a schema
+*
+* ```ts
+* export const ping = defineAction(async (input, ctx) => {
+*   // input is the raw parsed body (FormData or JSON object)
+*   return { ok: true, echo: input };
+* });
+* ```
+*
+* ## Errors and validation failures
+*
+* - Throw `ActionError` to signal a user-facing error (with optional `code`).
+* - Return `fail(status, { field: 'message' })` for field-level validation
+*   errors (SvelteKit-style).
+*/
+function defineAction(schemaOrHandler, handlerOrOptions, options) {
+	let schema;
+	let handler;
+	let opts = {};
+	if (typeof schemaOrHandler === "function") {
+		handler = schemaOrHandler;
+		if (handlerOrOptions && typeof handlerOrOptions === "object") opts = handlerOrOptions;
+	} else {
+		schema = schemaOrHandler;
+		handler = handlerOrOptions;
+		if (options) opts = options;
+	}
+	const name = opts.name || handler.name || "anonymous";
+	const filePath = opts.filePath || _guessCallerPath();
+	const action = {
+		id: opts.id || createActionId(filePath, name),
+		handler,
+		schema,
+		name,
+		filePath
+	};
+	Object.defineProperty(action, ACTION_BRAND, {
+		value: true,
+		enumerable: false,
+		configurable: false,
+		writable: false
+	});
+	registerAction(action);
+	return action;
+}
+/**
+* Type-safe server function. Same ID, registry, and `POST /__actions` RPC as
+* `defineAction` — use this alias when the function is a loader/query as well
+* as a mutation. Do not invent a second RPC.
+*/
+const defineServerFn = defineAction;
+/**
+* Best-effort guess of the caller's file path for action ID generation.
+*
+* Uses `Error.stack` parsing (works in Node and most browsers). Falls back
+* to `'inline'` when the stack is unavailable. The Vite plugin overrides
+* this with the actual transformed file path.
+*/
+function _guessCallerPath() {
+	const stack = (/* @__PURE__ */ new Error()).stack;
+	if (!stack) return "inline";
+	const lines = stack.split("\n");
+	for (let i = 3; i < lines.length; i++) {
+		const line = lines[i];
+		if (line && !line.includes("/actions/src/define.ts") && !line.includes("/actions/src/id.ts")) {
+			const match = line.match(/\(([^)]+)\)|at\s+(https?:\/\/\S+)/);
+			if (match) return (match[1] || match[2]).replace(/[?#].*$/, "").replace(/:\d+:\d+$/, "");
+		}
+	}
+	return "inline";
+}
+/**
+* Parse a Request body into a plain object suitable for action handlers.
+*
+* - `application/json` → parsed JSON object
+* - `multipart/form-data` or `application/x-www-form-urlencoded` → Object
+*   from FormData entries (string values, files skipped)
+* - Otherwise → empty object (handler can read `ctx.request` directly)
+*/
+async function parseActionInput(request) {
+	const contentType = request.headers.get("Content-Type") || "";
+	if (contentType.includes("application/json")) try {
+		const text = await request.text();
+		return text ? JSON.parse(text) : {};
+	} catch {
+		return {};
+	}
+	if (contentType.includes("multipart/form-data") || contentType.includes("application/x-www-form-urlencoded")) try {
+		const formData = await request.formData();
+		const obj = {};
+		for (const [key, value] of formData.entries()) if (typeof value === "string") obj[key] = value;
+		return obj;
+	} catch {
+		return {};
+	}
+	return {};
+}
+/**
+* Validate input against an action schema.
+*
+* Returns `{ success: true, data }` on success, or
+* `{ success: false, errors }` on failure (per-field messages).
+*/
+function issuesToErrors(issues) {
+	const errors = {};
+	for (const issue of issues || []) {
+		const key = Array.isArray(issue.path) && issue.path.length > 0 ? String(issue.path[0]) : "_error";
+		errors[key] = issue.message || "Invalid value";
+	}
+	if (Object.keys(errors).length === 0) errors._error = "Invalid value";
+	return errors;
+}
+function validateActionInput(schema, input) {
+	const standard = schema["~standard"];
+	if (standard && typeof standard.validate === "function") {
+		const result = standard.validate(input);
+		if (result && typeof result === "object" && "then" in result) return {
+			success: false,
+			errors: { _error: "Async Standard Schema validation is not supported in actions" }
+		};
+		if (result && typeof result === "object" && "issues" in result && result.issues) return {
+			success: false,
+			errors: issuesToErrors(result.issues)
+		};
+		if (result && typeof result === "object" && "value" in result) return {
+			success: true,
+			data: result.value
+		};
+	}
+	if (schema.safeParse) {
+		const result = schema.safeParse(input);
+		if (result.success) return {
+			success: true,
+			data: result.data
+		};
+		const errors = {};
+		const issues = result.error?.issues || [];
+		for (const issue of issues) {
+			const key = issue.message ? String(issue.message) : "Invalid";
+			errors[key] = issue.message || "Invalid value";
+		}
+		return {
+			success: false,
+			errors
+		};
+	}
+	try {
+		if (schema.parse) return {
+			success: true,
+			data: schema.parse(input)
+		};
+		return {
+			success: true,
+			data: input
+		};
+	} catch (err) {
+		return {
+			success: false,
+			errors: { _error: err instanceof Error ? err.message : String(err) }
+		};
+	}
+}
+/**
+* Normalize a handler return value into an `ActionResult`.
+*
+* - `ActionFailure` → `{ errors, status: failure.status }`
+* - `ActionError` (thrown) → `{ error: { message, code }, status }`
+* - Other thrown error → `{ error: { message }, status: 500 }`
+* - Plain value → `{ data: value, status: 200 }`
+*/
+function normalizeActionResult(result, error, failureStatus = 400) {
+	if (error) {
+		if (error instanceof ActionError) return {
+			error: {
+				message: error.message,
+				code: error.code
+			},
+			status: error.status
+		};
+		return {
+			error: { message: error instanceof Error ? error.message : String(error) },
+			status: 500
+		};
+	}
+	if (isActionFailure(result)) return {
+		errors: result.errors,
+		status: result.status || failureStatus
+	};
+	return {
+		data: result,
+		status: 200
+	};
+}
+/**
+* Build an `ActionContext` from a Hono context.
+*
+* - `request`: the underlying `c.req.raw` Request
+* - `context`: the Hono context (for `c.set`, `c.get`, etc.)
+* - `params`: route params from `c.req.param()`
+*/
+function buildActionContext(c) {
+	return {
+		request: c.req.raw,
+		context: c,
+		params: c.req.param()
+	};
+}
+//#endregion
+//#region src/actions/request-context.ts
+const STORAGE_KEY = "__UBEAN_ACTION_CTX_STORAGE__";
+function bindActionContextStorage(storage) {
+	globalThis[STORAGE_KEY] = storage;
+}
+function getActionContext() {
+	return globalThis[STORAGE_KEY]?.getStore();
+}
+function runWithActionContext(ctx, fn) {
+	const storage = globalThis[STORAGE_KEY];
+	if (storage) return storage.run(ctx, fn);
+	return fn();
+}
+function createDetachedActionContext(request) {
+	const req = request ?? new Request("http://ubean.local/__actions");
+	const params = {};
+	return {
+		request: req,
+		context: {
+			req: {
+				raw: req,
+				param: () => params,
+				path: new URL(req.url).pathname,
+				method: req.method,
+				header: (name) => req.headers.get(name) ?? void 0
+			},
+			get: () => void 0,
+			set: () => void 0
+		},
+		params
+	};
+}
+//#endregion
+//#region src/actions/invoke.ts
+/**
+* Isomorphic invocation for `defineAction` / `defineServerFn`.
+*
+* Same ID and `/__actions` RPC as Server Actions — not a second protocol.
+* Server with ALS: call the real handler. Otherwise (client stub or no
+* request scope): call `handler`, which on the client is the Vite RPC stub.
+*/
+function unwrapActionResult(result) {
+	if (result.error) throw new ActionError(result.error.message, {
+		code: result.error.code,
+		status: result.status
+	});
+	if (result.errors) {
+		const first = Object.values(result.errors)[0] || "Validation failed";
+		throw new ActionError(first, { status: result.status || 400 });
+	}
+	if (result.response) throw result.response;
+	return result.data;
+}
+function isActionResultShape(value) {
+	return typeof value === "object" && value !== null && "status" in value && ("data" in value || "error" in value || "errors" in value || "response" in value);
+}
+async function unwrapServerFnResult(value) {
+	if (isActionFailure(value)) {
+		const first = Object.values(value.errors)[0] || "Validation failed";
+		throw new ActionError(first, { status: value.status });
+	}
+	if (isActionResultShape(value)) return unwrapActionResult(value);
+	return value;
+}
+/**
+* Call a server function from a loader, `useAsyncData`, or the client.
+*
+* Reuses the action ID / `POST /__actions` envelope. Does not invent RPC.
+*/
+async function invokeServerFn(fn, input) {
+	let data = input;
+	if (fn.schema) {
+		const validated = validateActionInput(fn.schema, input);
+		if (!validated.success) {
+			const first = Object.values(validated.errors)[0] || "Validation failed";
+			throw new ActionError(first, { status: 400 });
+		}
+		data = validated.data;
+	}
+	const ctx = getActionContext() ?? createDetachedActionContext();
+	return unwrapServerFnResult(await fn.handler(data, ctx));
+}
+//#endregion
+//#region src/actions/constants.ts
+/**
+* Shared constants for Server Actions RPC.
+*
+* Kept in a leaf module so the browser runtime can import them without
+* pulling the Hono middleware barrel.
+*/
+const ACTIONS_ENDPOINT = "/__actions";
+const ACTION_RESPONSE_HEADER = "x-ubean-action";
+//#endregion
+//#region src/actions/form-action.ts
+/**
+* SvelteKit-style form action URL parsing (P9-02).
+*
+* Form actions are invoked via `POST /page?/<actionName>`:
+*
+*  - `POST /login` → `actions.default`
+*  - `POST /login?/login` → `actions.login`
+*  - `POST /login?/register` → `actions.register`
+*
+* The `?/<name>` syntax is URL-safe and works without JavaScript (the
+* browser submits the form to the full URL). On the server, the page
+* route handler parses the action name from the URL's search query.
+*
+* For progressive enhancement, the client can intercept the form submit
+* and call the action via `useFormAction()` for SPA-style navigation.
+*/
+/**
+* Extract the form action name from a URL's search query.
+*
+* SvelteKit's convention: the query string contains a single key `/<name>`
+* with no value. URLSearchParams treats this as a key with empty value.
+*
+* - `?/login` → `login`
+* - `?/register` → `register`
+* - `?` (no action) → `default`
+* - (no query) → `default`
+*
+* @returns The action name, or `'default'` when no specific action is
+*          specified.
+*/
+function parseFormActionName(url) {
+	const match = (typeof url === "string" ? url : url.search).match(/[?&]\/([^&]+)/);
+	return match ? match[1] : "default";
+}
+/**
+* Build a form action URL for the current page.
+*
+* Used by `useFormAction()` to generate the `action` attribute for
+* `<form>` elements. The URL is relative so it works on any page.
+*
+* - `useFormAction()` → `?/default`
+* - `useFormAction('login')` → `?/login`
+* - `useFormAction('register')` → `?/register`
+*
+* The returned string is intended for `<form :action="formAction">` —
+* the browser submits to the current page URL with the action name
+* appended as a query parameter.
+*/
+function buildFormActionUrl(actionName = "default") {
+	if (!actionName || actionName === "default") return "?/default";
+	return `?/${encodeURIComponent(actionName)}`;
+}
+/**
+* Check whether a URL's query string contains a form action specifier
+* (`?/<name>` pattern).
+*/
+function hasFormAction(url) {
+	const search = typeof url === "string" ? url : url.search;
+	return /[?&]\/[^&]+/.test(search);
+}
+//#endregion
+export { registerAction as C, isValidActionId as E, listActions as S, createActionId as T, parseActionInput as _, ACTION_RESPONSE_HEADER as a, getAction as b, unwrapServerFnResult as c, getActionContext as d, runWithActionContext as f, normalizeActionResult as g, defineServerFn as h, ACTIONS_ENDPOINT as i, bindActionContextStorage as l, defineAction as m, hasFormAction as n, invokeServerFn as o, buildActionContext as p, parseFormActionName as r, unwrapActionResult as s, buildFormActionUrl as t, createDetachedActionContext as u, validateActionInput as v, registerActions as w, hasAction as x, clearActions as y };