lambder 3.5.2 → 3.6.1

package/Readme.md

@@ -428,9 +428,20 @@ Responses are finalized once at the end of the request: automatic gzip (when the
 
 **Die Methods**: `res.die.*` - Builds the response and throws it, immediately halting the request at any call depth (handlers, hooks, nested helper functions). Plain `throw res.html(...)` works the same way.
 
-### Typed API Refusals (LambderApiError)
+### Typed API Refusals (refuse / LambderApiError)
 
-A refusal ("you are not allowed", "quota exceeded") is not a crash. `res.die.*` covers refusals where you hold the resolver, but shared helpers (permission checks, validators) usually don't. Throw `LambderApiError` from anywhere in an API call's stack and the pipeline maps it onto the structured envelope instead of the global error handler, so refusals never pollute crash logging and clients get a parseable response:
+A refusal ("you are not allowed", "quota exceeded") is not a crash. `res.die.*` covers refusals where you hold the resolver, but shared helpers (permission checks, validators) usually don't. The one-liner for the common case is `refuse()`: callable from anywhere in an API call's stack, it throws a typed refusal carrying the standard `LambderRefusalMessage` shape (`{ type, title?, content }`) that the pipeline maps onto the envelope's `errorMessage`, so refusals never pollute crash logging and clients get a parseable response:
+
+```typescript
+import { refuse } from "lambder";
+
+if (!row) refuse("Record not found.");                                  // { type: "warning", content }
+if (!isAdmin) refuse("Admins only.", { notAuthorized: true });          // + envelope flag
+refuse("Too many attempts.", { type: "error", statusCode: 429 });       // custom rendering intent + status
+// TypeScript applies never-return narrowing: after `if (!row) refuse(...)`, row is defined.
+```
+
+For full control of the errorMessage payload (apps with their own message vocabulary), throw `LambderApiError` directly; `refuse()` is sugar over it:
 
 ```typescript
 import { LambderApiError } from "lambder";

package/dist/LambderApiError.d.ts

@@ -52,3 +52,40 @@ export declare class LambderApiError extends Error {
 }
 /** Brand-based type guard (see LambderApiError.isLambderApiError). */
 export declare const isLambderApiError: (err: unknown) => err is LambderApiError;
+/**
+ * The standard shape refusals carry on the envelope's errorMessage field.
+ * The caller's errorMessageHandler receives it as-is; apps with their own
+ * errorMessage vocabulary can keep using LambderApiError directly instead.
+ */
+export type LambderRefusalMessage = {
+    type: "warning" | "error" | "info";
+    title?: string;
+    content: string;
+};
+export type LambderRefuseOptions = {
+    /** Rendering intent for the client's errorMessageHandler. Default: "warning". */
+    type?: LambderRefusalMessage["type"];
+    /** Optional heading shown above the content. */
+    title?: string;
+    /** Sets the envelope's notAuthorized flag (routed to the caller's notAuthorizedHandler). */
+    notAuthorized?: boolean;
+    /** Sets the envelope's sessionExpired flag. */
+    sessionExpired?: boolean;
+    /** HTTP status of the refusal. Default 200; avoid 5xx (caller treats as crash) and 422 (reserved for validation). */
+    statusCode?: HttpStatusCode;
+    /** Underlying cause, preserved on the Error cause property. */
+    cause?: unknown;
+};
+/**
+ * Refuse the current API call: a routine business "no" (not found, invalid
+ * input, not allowed) with a user-facing message. Throws a LambderApiError
+ * carrying the standard LambderRefusalMessage shape, so the pipeline maps it
+ * onto the structured envelope instead of a 500, and crash logging never
+ * sees it. Callable from anywhere in the call stack — handlers, hooks,
+ * guards, shared helpers with no resolver access.
+ *
+ * The const carries the annotation so TypeScript applies never-return
+ * control-flow narrowing at call sites (`if (!row) refuse(...)` implies
+ * `row` is defined afterwards).
+ */
+export declare const refuse: (content: string, options?: LambderRefuseOptions) => never;

package/dist/LambderApiError.js

@@ -36,3 +36,28 @@ export class LambderApiError extends Error {
 }
 /** Brand-based type guard (see LambderApiError.isLambderApiError). */
 export const isLambderApiError = (err) => err instanceof Error && err.isLambderApiError === true;
+/**
+ * Refuse the current API call: a routine business "no" (not found, invalid
+ * input, not allowed) with a user-facing message. Throws a LambderApiError
+ * carrying the standard LambderRefusalMessage shape, so the pipeline maps it
+ * onto the structured envelope instead of a 500, and crash logging never
+ * sees it. Callable from anywhere in the call stack — handlers, hooks,
+ * guards, shared helpers with no resolver access.
+ *
+ * The const carries the annotation so TypeScript applies never-return
+ * control-flow narrowing at call sites (`if (!row) refuse(...)` implies
+ * `row` is defined afterwards).
+ */
+export const refuse = (content, options = {}) => {
+    throw new LambderApiError(content, {
+        errorMessage: {
+            type: options.type ?? "warning",
+            ...(options.title !== undefined ? { title: options.title } : {}),
+            content,
+        },
+        notAuthorized: options.notAuthorized,
+        sessionExpired: options.sessionExpired,
+        statusCode: options.statusCode,
+        cause: options.cause,
+    });
+};

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import Lambder from './Lambder.js';
 export default Lambder;
 export { default as LambderCaller } from "./LambderCaller.js";
 export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions } from "./LambderCaller.js";
-export { LambderApiError, isLambderApiError } from "./LambderApiError.js";
-export type { LambderApiErrorOptions } from "./LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse } from "./LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./LambderApiError.js";
 export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
 export { default as LambderResolver } from "./LambderResolver.js";
 export { default as LambderSessionManager } from "./LambderSessionManager.js";

package/dist/index.js

@@ -2,7 +2,7 @@ import Lambder from './Lambder.js';
 export default Lambder;
 export { default as LambderCaller } from "./LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere)
-export { LambderApiError, isLambderApiError } from "./LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse } from "./LambderApiError.js";
 export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
 export { default as LambderResolver } from "./LambderResolver.js";
 export { default as LambderSessionManager } from "./LambderSessionManager.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "3.5.2",
+  "version": "3.6.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",