typanic 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kaspernj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# 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`.
+
+```js
+// ❌ 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
+
+```bash
+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"` |
+| `forcedInteger(value, label?)` | `number` | accepts integers and integer-looking strings (`"42"`) |
+| `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 |
+
+### Optional — `null` when absent, throw when present-but-wrong-typed
+
+| Function | Returns |
+| --- | --- |
+| `optionalString(value, label?)` | `string \| null` |
+| `optionalInteger(value, label?)` | `number \| null` |
+| `optionalFloat(value, label?)` | `number \| null` |
+| `optionalBoolean(value, label?)` | `boolean \| 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.
+
+```js
+import {forcedInteger, optionalString} from "typanic"
+
+const cols = forcedInteger(payload.cols, "cols")                 // 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
+```
+
+## 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

package/build/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Returns the value when it is a string, otherwise throws. Use this for required
+ * values coming from untrusted input (request bodies, webhook payloads, message
+ * payloads, parsed config) instead of silently coercing a wrong type to "".
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {string} the value, typed as a string
+ */
+export function forcedString(value: unknown, label?: string): string;
+/**
+ * Like {@link forcedString}, but allows the value to be absent (null/undefined
+ * become null). A value that is present but of the wrong type still throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {string | null} the string value, or null when absent
+ */
+export function optionalString(value: unknown, label?: string): string | null;
+/**
+ * Returns the value as an integer, otherwise throws. Numeric strings (route and
+ * query params arrive as strings) are parsed; everything else throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {number} the value, typed as an integer
+ */
+export function forcedInteger(value: unknown, label?: string): number;
+/**
+ * Like {@link forcedInteger}, but allows the value to be absent (null/undefined
+ * become null). A value that is present but not an integer still throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {number | null} the integer value, or null when absent
+ */
+export function optionalInteger(value: unknown, label?: string): number | null;
+/**
+ * Returns the value as a finite number, otherwise throws. Numeric strings are
+ * parsed; everything else (including NaN and Infinity) throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {number} the value, typed as a finite number
+ */
+export function forcedFloat(value: unknown, label?: string): number;
+/**
+ * Like {@link forcedFloat}, but allows the value to be absent (null/undefined
+ * become null). A value that is present but not a finite number still throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {number | null} the number value, or null when absent
+ */
+export function optionalFloat(value: unknown, label?: string): number | null;
+/**
+ * Returns the value when it is a boolean, otherwise throws. Strings like "true"
+ * are intentionally NOT coerced — pass an actual boolean.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {boolean} the value, typed as a boolean
+ */
+export function forcedBoolean(value: unknown, label?: string): boolean;
+/**
+ * Like {@link forcedBoolean}, but allows the value to be absent (null/undefined
+ * become null). A value that is present but not a boolean still throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {boolean | null} the boolean value, or null when absent
+ */
+export function optionalBoolean(value: unknown, label?: string): boolean | null;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AACH,oCAJW,OAAO,UACP,MAAM,GACJ,MAAM,CAQlB;AAED;;;;;;;GAOG;AACH,sCAJW,OAAO,UACP,MAAM,GACJ,MAAM,GAAG,IAAI,CAMzB;AAED;;;;;;;GAOG;AACH,qCAJW,OAAO,UACP,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;GAOG;AACH,uCAJW,OAAO,UACP,MAAM,GACJ,MAAM,GAAG,IAAI,CAMzB;AAED;;;;;;;GAOG;AACH,mCAJW,OAAO,UACP,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;GAOG;AACH,qCAJW,OAAO,UACP,MAAM,GACJ,MAAM,GAAG,IAAI,CAMzB;AAED;;;;;;;GAOG;AACH,qCAJW,OAAO,UACP,MAAM,GACJ,OAAO,CAQnB;AAED;;;;;;;GAOG;AACH,uCAJW,OAAO,UACP,MAAM,GACJ,OAAO,GAAG,IAAI,CAM1B"}

package/build/index.js

@@ -0,0 +1,133 @@
+// @ts-check
+/**
+ * Describes the runtime type of a value for error messages, distinguishing the
+ * two falsy "absent" values that `typeof` collapses into other buckets.
+ *
+ * @param {unknown} value the value to describe
+ * @returns {string} a short human-readable type label
+ */
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    return typeof value;
+}
+/**
+ * Returns the value when it is a string, otherwise throws. Use this for required
+ * values coming from untrusted input (request bodies, webhook payloads, message
+ * payloads, parsed config) instead of silently coercing a wrong type to "".
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {string} the value, typed as a string
+ */
+export function forcedString(value, label = "value") {
+    if (typeof value !== "string") {
+        throw new TypeError(`Expected ${label} to be a string but got ${describeType(value)}`);
+    }
+    return value;
+}
+/**
+ * Like {@link forcedString}, but allows the value to be absent (null/undefined
+ * become null). A value that is present but of the wrong type still throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {string | null} the string value, or null when absent
+ */
+export function optionalString(value, label = "value") {
+    if (value === null || value === undefined)
+        return null;
+    return forcedString(value, label);
+}
+/**
+ * Returns the value as an integer, otherwise throws. Numeric strings (route and
+ * query params arrive as strings) are parsed; everything else throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {number} the value, typed as an integer
+ */
+export function forcedInteger(value, label = "value") {
+    if (typeof value === "number" && Number.isInteger(value))
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsedValue = Number(value);
+        if (Number.isInteger(parsedValue))
+            return parsedValue;
+    }
+    throw new TypeError(`Expected ${label} to be an integer but got ${describeType(value)}`);
+}
+/**
+ * Like {@link forcedInteger}, but allows the value to be absent (null/undefined
+ * become null). A value that is present but not an integer still throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {number | null} the integer value, or null when absent
+ */
+export function optionalInteger(value, label = "value") {
+    if (value === null || value === undefined)
+        return null;
+    return forcedInteger(value, label);
+}
+/**
+ * Returns the value as a finite number, otherwise throws. Numeric strings are
+ * parsed; everything else (including NaN and Infinity) throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {number} the value, typed as a finite number
+ */
+export function forcedFloat(value, label = "value") {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsedValue = Number(value);
+        if (Number.isFinite(parsedValue))
+            return parsedValue;
+    }
+    throw new TypeError(`Expected ${label} to be a number but got ${describeType(value)}`);
+}
+/**
+ * Like {@link forcedFloat}, but allows the value to be absent (null/undefined
+ * become null). A value that is present but not a finite number still throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {number | null} the number value, or null when absent
+ */
+export function optionalFloat(value, label = "value") {
+    if (value === null || value === undefined)
+        return null;
+    return forcedFloat(value, label);
+}
+/**
+ * Returns the value when it is a boolean, otherwise throws. Strings like "true"
+ * are intentionally NOT coerced — pass an actual boolean.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {boolean} the value, typed as a boolean
+ */
+export function forcedBoolean(value, label = "value") {
+    if (typeof value !== "boolean") {
+        throw new TypeError(`Expected ${label} to be a boolean but got ${describeType(value)}`);
+    }
+    return value;
+}
+/**
+ * Like {@link forcedBoolean}, but allows the value to be absent (null/undefined
+ * become null). A value that is present but not a boolean still throws.
+ *
+ * @param {unknown} value the value to assert
+ * @param {string} [label] name used in the thrown error message
+ * @returns {boolean | null} the boolean value, or null when absent
+ */
+export function optionalBoolean(value, label = "value") {
+    if (value === null || value === undefined)
+        return null;
+    return forcedBoolean(value, label);
+}
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "typanic",
+  "version": "1.0.1",
+  "description": "Forced runtime type assertions for untrusted input — get the type you expect or throw, instead of silently coercing a wrong value to \"\" / 0 / false.",
+  "keywords": [
+    "type",
+    "types",
+    "assert",
+    "assertion",
+    "validate",
+    "validation",
+    "cast",
+    "coerce",
+    "runtime",
+    "typecheck",
+    "guard",
+    "jsdoc",
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "throw"
+  ],
+  "license": "MIT",
+  "author": "kaspernj <kasper@diestoeckels.de>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaspernj/typanic.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kaspernj/typanic/issues"
+  },
+  "homepage": "https://github.com/kaspernj/typanic#readme",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js"
+    }
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "all-checks": "npm run lint && npm run typecheck && npm test",
+    "build": "tsc --project tsconfig.json",
+    "lint": "eslint .",
+    "prepare": "npm run build",
+    "release:patch": "release-patch",
+    "test": "jasmine",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.6.0",
+    "eslint": "^10.3.0",
+    "eslint-plugin-jsdoc": "^62.9.0",
+    "globals": "^17.6.0",
+    "jasmine": "^6.2.0",
+    "release-patch": "^1.0.0",
+    "typescript": "^5.9.3"
+  }
+}