assert-response

A lightweight utility library for asserting HTTP response conditions and throwing a Response with the appropriate HTTP status code, and optional body and options.

Usage

$3

If the resource is missing, throw a 404 Not Found response.

``ts import { found } from "assert-response";

function loader() { const foo = getFoo(); // Foo | undefined

// Throws a 404 response if foo is undefined found(foo);

foo; // Type is now Foo // Do something with foo }`

`$3`

If the user is not authenticated, throw a 401 Unauthorized response.

`ts import { authorized } from "assert-response";

function action() { const user = getCurrentUser(); // User | null

// Throws a 401 response if user is null authorized(user);

user; // Type is now User // ... }`

`$3`

If the operation was unsuccessful, throw a 500 Internal Server Error.

`ts import { noError } from "assert-response";

function action() { const success = processRequest(); // boolean

// Throws a 500 response if success is false noError(success); // Do further actions }`

`$3`

If the operation was successful, throw a 200 OK.

`ts import { internalServerError, notOk } from "assert-response";

function action() { const [error] = processOtherRequest(); // [string | null]

// Throws a 200 response if error is null notOk(error); error; // Type is now string

console.error(error);

// Throws a 500 response if error is not null internalServerError(error); }`

`$3`

This example ensures:

- 👋 The user is authenticated (401 Unauthorized). - 🔓 The user has permission to update the document (403 Forbidden). - ✅ The input is valid (400 Bad Request). - 🔍 The document exists (404 Not Found). - 🤝 The document has not been modified since the last retrieval (409 Conflict). - ⚠️ / 👌 The update is successful (500 Internal Server Error / 204 No Content).

`ts import { authorized, allowed, found, match, noContent, valid, internalServerError, } from "assert-response";

interface Document { id: string; lastModified: number; }

async function saveAndContinueEditing(doc?: Document) { const user = getCurrentUser(); // 👋 Throws a 401 response if current user is null authorized(user, "Authentication required"); user; // Type is now User

// 🔓 Throws a 403 response if not permitted allowed( user.permissions.includes("update-document"), "Permission to update document required" );

// ✅ Throws a 400 response if missing update document valid(doc, "Missing document"); doc; // Type is now Document

const prevDoc: Document | undefined = await database.find(doc.id); // 🔍 Throws a 404 response if the document does not exist found(prevDoc, "Document not found"); prevDoc; // Type is now Document

// 🤝 Throws a 409 response if the document has been modified since last retrieval match(prevDoc.lastModified === doc.lastModified, "Conflict detected");

const [error] = await database.put(doc);

// ⚠️ Throws a 500 response if the update failed internalServerError(error);

// 👌 Throws a 204 response if everything successful noContent(true); }`

---

`API`

Each assertion function checks a condition and throws a Responsewith the corresponding HTTP status code if the condition is truthy. Negated functions work in reverse: they throw a response when the condition is falsy.

You may also pass an optional body and options parameters for Response as the second and third arguments for the assertion function. These can either be values or functions that return the respective values.

To use these functions:

`ts import { found, ok, redirect, valid } from "assert-response";

// Throws a 200 response if user is truthy, with a dynamic message ok( user, () => JSON.stringify({ message: "Welcome back!" }), () => ({ headers: { "Content-Type": "application/json" } }) );

// Throws a 302 response with options if redirectURL is set redirect(redirectURL, undefined, { headers: { Location: redirectURL!, }, });

// Validate user input (Negated function, throws 400 response if condition is falsy) valid(isValid(input), "Invalid input");

// Ensure item is found (Negated function, throws 404 response if condition is falsy) found(item, "Item not found");`

`$3`

Each function is mapped to an HTTP status code.

#### Successful Responses (200–299)

#### Redirection Responses (300–399)

| Status Code | Function _(Aliases)_ | Negated Function _(Aliases)_ | | ------------------------------------------------------------- | ------------------------------------ | ----------------------------------------- | | 300 |multipleChoices | notMultipleChoices| | 301 |movedPermanently | notMovedPermanently| | 302 |temporaryFound_(redirect)_ | notTemporaryFound_(noRedirect)_ | | 303 |seeOther | notSeeOther| | 304 |notModified | modified| | 305 |useProxy_(proxy)_ | notUseProxy| | 307 |temporaryRedirect | notTemporaryRedirect| | 308 |permanentRedirect | notPermanentRedirect |

#### Client Error Responses (400–499)

| Status Code | Function _(Aliases)_ | Negated Function _(Aliases)_ | | ------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------- | | 400 |badRequest_(invalid)_ | goodRequest_(valid, correct)_ | | 401 |unauthorized | authorized_(authenticated)_ | | 402 |paymentRequired | paymentNotRequired_(paymentOptional)_ | | 403 |forbidden | notForbidden_(allowed, permitted)_ | | 404 |notFound | found| | 405 |methodNotAllowed | methodAllowed| | 406 |notAcceptable | acceptable| | 407 |proxyAuthRequired | proxyAuthNotRequired_(proxyAuthOptional)_ | | 408 |requestTimeout | notRequestTimeout_(requestFast)_ | | 409 |conflict | notConflict_(match)_ | | 410 |gone | notGone_(present)_ | | 411 |lengthRequired | lengthNotRequired_(lengthOptional)_ | | 412 |preconditionFailed | preconditionSuccessful_(preconditionMet, preconditionPassed)_ | | 413 |payloadTooLarge | notPayloadTooLarge_(payloadSmall)_ | | 414 |uriTooLong | uriNotTooLong_(uriShort)_ | | 415 |unsupportedMediaType | supportedMediaType| | 416 |rangeNotSatisfiable | rangeSatisfiable| | 417 |expectationFailed | expectationSuccessful_(expectationMet, expectationPassed)_ | | 418 |teapot | notTeapot| | 421 |misdirectedRequest | correctlyDirectedRequest_(directedRequest)_ | | 422 |unprocessableEntity | processableEntity| | 423 |locked | unlocked_(open)_ | | 424 |failedDependency | successfulDependency_(dependencyMet, dependencyPassed)_ | | 425 |tooEarly | notTooEarly_(afterSufficientTime, onTime)_ | | 426 |upgradeRequired | upgradeNotRequired_(upgradeOptional)_ | | 428 |preconditionRequired | preconditionNotRequired_(preconditionOptional)_ | | 429 |tooManyRequests | notTooManyRequests_(fewRequests)_ | | 431 |requestHeaderFieldsTooLarge | requestHeaderFieldsAcceptable_(requestHeaderFieldsSmall)_ | | 451 |unavailableForLegalReasons | availableForLegalReasons |

#### Server Error Responses (500–599)

assert-response

A lightweight utility library for asserting HTTP response conditions and throwing a Response with the appropriate HTTP status code, and optional body and options.

Usage

$3

If the resource is missing, throw a 404 Not Found response.

``ts import { found } from "assert-response";

function loader() { const foo = getFoo(); // Foo | undefined

// Throws a 404 response if foo is undefined found(foo);

foo; // Type is now Foo // Do something with foo }`

`$3`

If the user is not authenticated, throw a 401 Unauthorized response.

`ts import { authorized } from "assert-response";

function action() { const user = getCurrentUser(); // User | null

// Throws a 401 response if user is null authorized(user);

user; // Type is now User // ... }`

`$3`

If the operation was unsuccessful, throw a 500 Internal Server Error.

`ts import { noError } from "assert-response";

function action() { const success = processRequest(); // boolean

// Throws a 500 response if success is false noError(success); // Do further actions }`

`$3`

If the operation was successful, throw a 200 OK.

`ts import { internalServerError, notOk } from "assert-response";

function action() { const [error] = processOtherRequest(); // [string | null]

// Throws a 200 response if error is null notOk(error); error; // Type is now string

console.error(error);

// Throws a 500 response if error is not null internalServerError(error); }`

`$3`

This example ensures:

`ts import { authorized, allowed, found, match, noContent, valid, internalServerError, } from "assert-response";

interface Document { id: string; lastModified: number; }

// 🔓 Throws a 403 response if not permitted allowed( user.permissions.includes("update-document"), "Permission to update document required" );

// ✅ Throws a 400 response if missing update document valid(doc, "Missing document"); doc; // Type is now Document

// 🤝 Throws a 409 response if the document has been modified since last retrieval match(prevDoc.lastModified === doc.lastModified, "Conflict detected");

const [error] = await database.put(doc);

// ⚠️ Throws a 500 response if the update failed internalServerError(error);

// 👌 Throws a 204 response if everything successful noContent(true); }`

---

`API`

To use these functions:

`ts import { found, ok, redirect, valid } from "assert-response";

// Throws a 200 response if user is truthy, with a dynamic message ok( user, () => JSON.stringify({ message: "Welcome back!" }), () => ({ headers: { "Content-Type": "application/json" } }) );

// Throws a 302 response with options if redirectURL is set redirect(redirectURL, undefined, { headers: { Location: redirectURL!, }, });

// Validate user input (Negated function, throws 400 response if condition is falsy) valid(isValid(input), "Invalid input");

// Ensure item is found (Negated function, throws 404 response if condition is falsy) found(item, "Item not found");`

`$3`

Each function is mapped to an HTTP status code.

#### Successful Responses (200–299)

#### Redirection Responses (300–399)

| Status Code | Function _(Aliases)_ | Negated Function _(Aliases)_ | | ------------------------------------------------------------- | ------------------------------------ | ----------------------------------------- | | 300 |multipleChoices | notMultipleChoices| | 301 |movedPermanently | notMovedPermanently| | 302 |temporaryFound_(redirect)_ | notTemporaryFound_(noRedirect)_ | | 303 |seeOther | notSeeOther| | 304 |notModified | modified| | 305 |useProxy_(proxy)_ | notUseProxy| | 307 |temporaryRedirect | notTemporaryRedirect| | 308 |permanentRedirect | notPermanentRedirect |

#### Client Error Responses (400–499)

| Status Code | Function _(Aliases)_ | Negated Function _(Aliases)_ | | ------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------- | | 400 |badRequest_(invalid)_ | goodRequest_(valid, correct)_ | | 401 |unauthorized | authorized_(authenticated)_ | | 402 |paymentRequired | paymentNotRequired_(paymentOptional)_ | | 403 |forbidden | notForbidden_(allowed, permitted)_ | | 404 |notFound | found| | 405 |methodNotAllowed | methodAllowed| | 406 |notAcceptable | acceptable| | 407 |proxyAuthRequired | proxyAuthNotRequired_(proxyAuthOptional)_ | | 408 |requestTimeout | notRequestTimeout_(requestFast)_ | | 409 |conflict | notConflict_(match)_ | | 410 |gone | notGone_(present)_ | | 411 |lengthRequired | lengthNotRequired_(lengthOptional)_ | | 412 |preconditionFailed | preconditionSuccessful_(preconditionMet, preconditionPassed)_ | | 413 |payloadTooLarge | notPayloadTooLarge_(payloadSmall)_ | | 414 |uriTooLong | uriNotTooLong_(uriShort)_ | | 415 |unsupportedMediaType | supportedMediaType| | 416 |rangeNotSatisfiable | rangeSatisfiable| | 417 |expectationFailed | expectationSuccessful_(expectationMet, expectationPassed)_ | | 418 |teapot | notTeapot| | 421 |misdirectedRequest | correctlyDirectedRequest_(directedRequest)_ | | 422 |unprocessableEntity | processableEntity| | 423 |locked | unlocked_(open)_ | | 424 |failedDependency | successfulDependency_(dependencyMet, dependencyPassed)_ | | 425 |tooEarly | notTooEarly_(afterSufficientTime, onTime)_ | | 426 |upgradeRequired | upgradeNotRequired_(upgradeOptional)_ | | 428 |preconditionRequired | preconditionNotRequired_(preconditionOptional)_ | | 429 |tooManyRequests | notTooManyRequests_(fewRequests)_ | | 431 |requestHeaderFieldsTooLarge | requestHeaderFieldsAcceptable_(requestHeaderFieldsSmall)_ | | 451 |unavailableForLegalReasons | availableForLegalReasons |

#### Server Error Responses (500–599)