typanic

type + panic — get the type you expect, or it throws.

Tiny, dependency-free runtime type assertions for untrusted input (request and response bodies, webhook payloads, message/command payloads, parsed config, route/query params). Instead of silently coercing a wrong value into "", 0, or false — which produces noise and hides a real producer bug far from where it happens — typanic either gives you the value as the type you asked for, or throws a TypeError.

// ❌ silent, noisy, swallows malformed data
const name = typeof payload.name === "string" ? payload.name : ""

// ✅ loud and clean
import {forcedString} from "typanic"
const name = forcedString(payload.name, "name") // throws if it isn't a string

For values that are already typed/validated (a generated model accessor, a boundary-typed param) you don't need this at all — just use them directly. typanic is for the boundary where data is genuinely untrusted.

Install

npm install typanic

ESM only. Ships with TypeScript declarations (.d.ts) generated from JSDoc.

API

Every helper takes the value and an optional label used in the error message (Expected <label> to be a <type> but got <actual>).

Required — throw when the value is the wrong type

| Function | Returns | Notes | | --- | --- | --- | | forcedString(value, label?) | string | throws unless typeof value === "string" | | forcedOneOf(value, allowedValues, label?) | T | throws unless value is one of allowedValues (enum / one-of) | | forcedInteger(value, label?) | number | accepts integers and integer-looking strings ("42") | | forcedIntegerFromString(value, label?) | number | accepts safe decimal integer strings only; useful for form/query values | | forcedPositiveInteger(value, label?) | number | accepts safe integers greater than zero and integer-looking strings ("42") | | forcedPositiveIntegerFromString(value, label?) | number | accepts safe positive decimal integer strings only | | forcedStringParam(params, key, label?) | string | reads a required single string from a route/query param map | | forcedNonBlankStringParam(params, key, label?) | string | reads a required trimmed non-blank string from a param map | | forcedPositiveIntegerParam(params, key, label?) | number | reads a required safe positive decimal integer from a string param map | | forcedPositiveIntegerList(value, label?) | number[] | parses a scalar or array list of safe positive integers | | forcedNonBlankString(value, label?) | string | trims and rejects blank strings | | forcedFloat(value, label?) | number | accepts finite numbers and numeric strings; rejects NaN/Infinity | | forcedBoolean(value, label?) | boolean | does not coerce "true"/1 — pass a real boolean | | forcedFunction(value, label?) | Function | throws unless typeof value === "function" | | forcedError(value, label?) | Error | throws unless value instanceof Error |

Error conversion

Use ensureError(value, label?) at catch/throw boundaries where JavaScript can throw strings, numbers, or other non-Error values. Error instances are returned unchanged. Non-Error values are wrapped in a new Error and preserved as error.cause.

Use errorMessage(value, label?) when a UI or status field needs a displayable message for a caught value. String throws are already messages and are returned unchanged; everything else is normalized through ensureError.

import {errorMessage} from "typanic"

try {
  await work()
} catch (error) {
  const message = errorMessage(error, "work error")
  showError(message)
}

Optional — null when absent, throw when present-but-wrong-typed

| Function | Returns | | --- | --- | | optionalString(value, label?) | string \| null | | optionalOneOf(value, allowedValues, label?) | T \| null | | optionalInteger(value, label?) | number \| null | | optionalIntegerFromString(value, label?) | number \| null | | optionalPositiveInteger(value, label?) | number \| null | | optionalPositiveIntegerFromString(value, label?) | number \| null | | optionalStringParam(params, key, label?) | string \| null | | optionalNonBlankStringParam(params, key, label?) | string \| null | | optionalPositiveIntegerParam(params, key, label?) | number \| null | | optionalPositiveIntegerList(value, label?) | number[] \| null | | optionalNonBlankString(value, label?) | string \| null | | optionalFloat(value, label?) | number \| null | | optionalBoolean(value, label?) | boolean \| null | | optionalFunction(value, label?) | Function \| null |

null and undefined both count as "absent" and return null. A value that is present but of the wrong type still throws — absence and corruption are different things.

import {forcedPositiveIntegerFromString, optionalString} from "typanic"

const cols = forcedPositiveIntegerFromString(payload.cols, "cols") // positive decimal string -> number, or throws
const cursor = optionalString(payload.cursor, "cursor")            // string | null
const status = optionalString(payload.status, "status") ?? "ok"    // default only when you truly need one

Param-map helpers are for route/query frameworks that expose values as Record<string, string | string[] | undefined>. They reject repeated single-value params instead of picking the first value silently.

import {forcedPositiveIntegerParam, optionalPositiveIntegerList} from "typanic"

const projectId = forcedPositiveIntegerParam(routeParams, "project_id", "Project ID")
const userIds = optionalPositiveIntegerList(routeParams.user_ids, "User IDs") ?? []

Why "forced"?

The value is forced to be the type you declared. There is no quiet fallback: the data is what you expect, or your code stops at the boundary with a clear error instead of carrying a silent empty string into the rest of the system.

License

MIT