@constructive-io/coerce 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+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,155 @@
+# @constructive-io/coerce
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@constructive-io/coerce"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=packages%2Fcoerce%2Fpackage.json"/></a>
+</p>
+
+Coerce untrusted `unknown` values — JSON request bodies, database rows, Kubernetes specs, env strings — into narrow TypeScript types. Zero dependencies.
+
+## why?
+
+Because every service ends up re-typing the same four functions inline, each subtly different:
+
+```ts
+// don't
+const asString = (v: unknown) => (typeof v === 'string' && v ? v : null);
+const asInteger = (v: unknown) => (typeof v === 'number' && Number.isInteger(v) ? v : null);
+```
+
+## install
+
+```sh
+npm install @constructive-io/coerce
+```
+
+## usage
+
+Two families. `as*` is lenient and returns `null`; `require*` throws a labelled `CoerceError`.
+
+```ts
+import { asInteger, asOneOf, asString, requireString } from '@constructive-io/coerce';
+
+const model = asString(body.model);                            // string | null
+const attempt = asInteger(body.attempt);                       // number | null
+const role = asOneOf(body.author_role, ['user', 'assistant']);  // 'user' | 'assistant' | null
+const messageId = requireString(body.message_id, 'message_id'); // string, or throws
+```
+
+| lenient | strict | accepts |
+| --- | --- | --- |
+| `asString` | `requireString` | a non-empty, non-whitespace string |
+| `asNumber` | `requireNumber` | a finite number |
+| `asInteger` | `requireInteger` | an integer |
+| `asBoolean` | `requireBoolean` | a boolean, or `true/false`, `1/0`, `yes/no`, `on/off`, `t/f`, `y/n` |
+| `asStringArray` | `requireStringArray` | an array whose every entry is a non-empty string |
+| `asStringList` | `requireStringList` | an array, or a delimited string (`'a, b'`) |
+| `asRecord` | `requireRecord` | a plain object (not `null`, not an array) |
+| `asDate` | `requireDate` | a valid `Date`, or a parseable date string |
+| `asIsoString` | `requireIsoString` | a `Date` (serialised) or a string (verbatim) |
+| `asOneOf` | `requireOneOf` | one of the given string literals |
+
+## rules
+
+- **No guessing across types.** `'5'` is not an integer and `1` is not a string. Only `asBoolean` and `asDate` read strings, because env vars and query strings carry nothing else.
+- **A blank string is absent.** `''` and `'   '` coerce to `null`, so an empty value can never read as a supplied identifier.
+- **All-or-nothing lists.** `asStringArray` rejects the whole array rather than dropping bad entries — that is how a list of allowed origins quietly shrinks.
+- **No transport semantics.** `CoerceError` carries the `label` that failed, not an HTTP status. Map it at your boundary:
+
+```ts
+try {
+  return handle(requireString(body.message_id, 'message_id'));
+} catch (err) {
+  if (err instanceof CoerceError) throw new HttpError(400, err.message);
+  throw err;
+}
+```
+
+## related
+
+`12factor-env` builds on this package for its lenient env parsing, and adds envalid-backed environment *schemas* (`cleanEnv`, redaction, cross-field checks). Reach for `12factor-env` when validating `process.env` at boot, and for this package when validating a value at runtime.
+
+## license
+
+MIT
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/coerce.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Coercion of untrusted `unknown` values — JSON request bodies, database rows,
+ * Kubernetes specs, env strings — into narrow TypeScript types.
+ *
+ * Two families, one rule each:
+ *
+ *   - `as*` is lenient: it answers "is this value already a usable T?" and
+ *     returns `null` when it is not. It never guesses across types (`'5'` is
+ *     not an integer, `1` is not a string) and never treats a blank string as
+ *     present, so a caller cannot mistake `''` for a supplied identifier.
+ *   - `require*` is strict: same test, but a miss throws {@link CoerceError}.
+ *
+ * Deliberately transport-agnostic: `CoerceError` carries the offending
+ * `label`, not an HTTP status. A server maps it to 400 at its own boundary,
+ * which keeps this package usable off the request path.
+ */
+/** A value that was required but absent or of the wrong shape. */
+export declare class CoerceError extends Error {
+    /** What the caller was asking for, e.g. `'message_id'`. */
+    readonly label: string;
+    constructor(label: string, expected: string);
+}
+/** A non-empty, non-whitespace string, else `null`. */
+export declare const asString: (value: unknown) => string | null;
+/** A finite number, else `null`. Strings are not parsed. */
+export declare const asNumber: (value: unknown) => number | null;
+/** A safe integer, else `null`. `1.5` and `'1'` are both `null`. */
+export declare const asInteger: (value: unknown) => number | null;
+/**
+ * A boolean. Booleans pass through; the string spellings people actually type
+ * (`true/false`, `1/0`, `yes/no`, `on/off`, `t/f`, `y/n`) are recognised
+ * case-insensitively, because env vars and query strings only carry strings.
+ * Anything else is `null` — notably `''`, so "unset" stays distinguishable
+ * from "false".
+ */
+export declare const asBoolean: (value: unknown) => boolean | null;
+/**
+ * An array whose every entry is a non-empty string, else `null`.
+ *
+ * All-or-nothing on purpose: silently dropping the malformed entries of a
+ * list of role names or allowed origins is how a security list quietly
+ * shrinks.
+ */
+export declare const asStringArray: (value: unknown) => string[] | null;
+/**
+ * A list of non-empty strings from either an array (see
+ * {@link asStringArray}) or a delimited string, else `null`.
+ *
+ * Entries are trimmed and blanks dropped, because the delimited form is what a
+ * `PATH`-style env var, a query parameter or a header carries, and
+ * `'a, b,'` means two entries in all three.
+ */
+export declare const asStringList: (value: unknown, separator?: string) => string[] | null;
+/**
+ * A plain object, else `null`. Arrays and `null` are not records — both are
+ * `typeof 'object'`, and that check is the classic source of a `.length`
+ * lookup on something that was supposed to be a map.
+ */
+export declare const asRecord: (value: unknown) => Record<string, unknown> | null;
+/** A valid `Date`, else `null`. An invalid date parse is not a `Date`. */
+export declare const asDate: (value: unknown) => Date | null;
+/**
+ * A timestamp as an ISO-8601 string, else `null`.
+ *
+ * A `Date` is serialised; a string is passed through **verbatim** rather than
+ * round-tripped through `Date`, so a caller's own cursor value survives
+ * byte-for-byte — the format a database returned is the format it compares
+ * against.
+ */
+export declare const asIsoString: (value: unknown) => string | null;
+/** {@link asString}, throwing {@link CoerceError} when absent. */
+export declare const requireString: (value: unknown, label: string) => string;
+/** {@link asNumber}, throwing {@link CoerceError} when absent. */
+export declare const requireNumber: (value: unknown, label: string) => number;
+/** {@link asInteger}, throwing {@link CoerceError} when absent. */
+export declare const requireInteger: (value: unknown, label: string) => number;
+/** {@link asBoolean}, throwing {@link CoerceError} when absent. */
+export declare const requireBoolean: (value: unknown, label: string) => boolean;
+/** {@link asStringArray}, throwing {@link CoerceError} when absent. */
+export declare const requireStringArray: (value: unknown, label: string) => string[];
+/** {@link asStringList}, throwing {@link CoerceError} when absent. */
+export declare const requireStringList: (value: unknown, label: string) => string[];
+/** {@link asRecord}, throwing {@link CoerceError} when absent. */
+export declare const requireRecord: (value: unknown, label: string) => Record<string, unknown>;
+/** {@link asDate}, throwing {@link CoerceError} when absent. */
+export declare const requireDate: (value: unknown, label: string) => Date;
+/** {@link asIsoString}, throwing {@link CoerceError} when absent. */
+export declare const requireIsoString: (value: unknown, label: string) => string;
+/**
+ * Narrow a value to one of `allowed`, else `null`.
+ *
+ * The literal tuple is preserved, so `asOneOf(body.role, ['user', 'admin'])`
+ * is typed `'user' | 'admin' | null` without a cast at the call site.
+ */
+export declare const asOneOf: <const T extends readonly string[]>(value: unknown, allowed: T) => T[number] | null;
+/** {@link asOneOf}, throwing {@link CoerceError} when the value is not allowed. */
+export declare const requireOneOf: <const T extends readonly string[]>(value: unknown, allowed: T, label: string) => T[number];

package/coerce.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Coercion of untrusted `unknown` values — JSON request bodies, database rows,
+ * Kubernetes specs, env strings — into narrow TypeScript types.
+ *
+ * Two families, one rule each:
+ *
+ *   - `as*` is lenient: it answers "is this value already a usable T?" and
+ *     returns `null` when it is not. It never guesses across types (`'5'` is
+ *     not an integer, `1` is not a string) and never treats a blank string as
+ *     present, so a caller cannot mistake `''` for a supplied identifier.
+ *   - `require*` is strict: same test, but a miss throws {@link CoerceError}.
+ *
+ * Deliberately transport-agnostic: `CoerceError` carries the offending
+ * `label`, not an HTTP status. A server maps it to 400 at its own boundary,
+ * which keeps this package usable off the request path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireOneOf = exports.asOneOf = exports.requireIsoString = exports.requireDate = exports.requireRecord = exports.requireStringList = exports.requireStringArray = exports.requireBoolean = exports.requireInteger = exports.requireNumber = exports.requireString = exports.asIsoString = exports.asDate = exports.asRecord = exports.asStringList = exports.asStringArray = exports.asBoolean = exports.asInteger = exports.asNumber = exports.asString = exports.CoerceError = void 0;
+/** A value that was required but absent or of the wrong shape. */
+class CoerceError extends Error {
+    /** What the caller was asking for, e.g. `'message_id'`. */
+    label;
+    constructor(label, expected) {
+        super(`${label} is required (expected ${expected})`);
+        this.name = 'CoerceError';
+        this.label = label;
+    }
+}
+exports.CoerceError = CoerceError;
+/** A non-empty, non-whitespace string, else `null`. */
+const asString = (value) => typeof value === 'string' && value.trim() !== '' ? value : null;
+exports.asString = asString;
+/** A finite number, else `null`. Strings are not parsed. */
+const asNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+exports.asNumber = asNumber;
+/** A safe integer, else `null`. `1.5` and `'1'` are both `null`. */
+const asInteger = (value) => typeof value === 'number' && Number.isInteger(value) ? value : null;
+exports.asInteger = asInteger;
+/**
+ * A boolean. Booleans pass through; the string spellings people actually type
+ * (`true/false`, `1/0`, `yes/no`, `on/off`, `t/f`, `y/n`) are recognised
+ * case-insensitively, because env vars and query strings only carry strings.
+ * Anything else is `null` — notably `''`, so "unset" stays distinguishable
+ * from "false".
+ */
+const asBoolean = (value) => {
+    if (typeof value === 'boolean')
+        return value;
+    const str = (0, exports.asString)(value)?.trim().toLowerCase();
+    if (str === undefined)
+        return null;
+    if (TRUTHY.has(str))
+        return true;
+    if (FALSY.has(str))
+        return false;
+    return null;
+};
+exports.asBoolean = asBoolean;
+const TRUTHY = new Set(['1', 'on', 't', 'true', 'y', 'yes']);
+const FALSY = new Set(['0', 'f', 'false', 'n', 'no', 'off']);
+/**
+ * An array whose every entry is a non-empty string, else `null`.
+ *
+ * All-or-nothing on purpose: silently dropping the malformed entries of a
+ * list of role names or allowed origins is how a security list quietly
+ * shrinks.
+ */
+const asStringArray = (value) => {
+    if (!Array.isArray(value))
+        return null;
+    const strings = [];
+    for (const entry of value) {
+        const str = (0, exports.asString)(entry);
+        if (str === null)
+            return null;
+        strings.push(str);
+    }
+    return strings;
+};
+exports.asStringArray = asStringArray;
+/**
+ * A list of non-empty strings from either an array (see
+ * {@link asStringArray}) or a delimited string, else `null`.
+ *
+ * Entries are trimmed and blanks dropped, because the delimited form is what a
+ * `PATH`-style env var, a query parameter or a header carries, and
+ * `'a, b,'` means two entries in all three.
+ */
+const asStringList = (value, separator = ',') => {
+    const str = (0, exports.asString)(value);
+    if (str !== null)
+        return str.split(separator).map(entry => entry.trim()).filter(Boolean);
+    return (0, exports.asStringArray)(value);
+};
+exports.asStringList = asStringList;
+/**
+ * A plain object, else `null`. Arrays and `null` are not records — both are
+ * `typeof 'object'`, and that check is the classic source of a `.length`
+ * lookup on something that was supposed to be a map.
+ */
+const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+exports.asRecord = asRecord;
+/** A valid `Date`, else `null`. An invalid date parse is not a `Date`. */
+const asDate = (value) => {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    const str = (0, exports.asString)(value);
+    if (str === null)
+        return null;
+    const parsed = new Date(str);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+};
+exports.asDate = asDate;
+/**
+ * A timestamp as an ISO-8601 string, else `null`.
+ *
+ * A `Date` is serialised; a string is passed through **verbatim** rather than
+ * round-tripped through `Date`, so a caller's own cursor value survives
+ * byte-for-byte — the format a database returned is the format it compares
+ * against.
+ */
+const asIsoString = (value) => value instanceof Date ? (0, exports.asDate)(value)?.toISOString() ?? null : (0, exports.asString)(value);
+exports.asIsoString = asIsoString;
+const require_ = (as, expected) => (value, label) => {
+    const coerced = as(value);
+    if (coerced === null)
+        throw new CoerceError(label, expected);
+    return coerced;
+};
+/** {@link asString}, throwing {@link CoerceError} when absent. */
+exports.requireString = require_(exports.asString, 'a non-empty string');
+/** {@link asNumber}, throwing {@link CoerceError} when absent. */
+exports.requireNumber = require_(exports.asNumber, 'a finite number');
+/** {@link asInteger}, throwing {@link CoerceError} when absent. */
+exports.requireInteger = require_(exports.asInteger, 'an integer');
+/** {@link asBoolean}, throwing {@link CoerceError} when absent. */
+exports.requireBoolean = require_(exports.asBoolean, 'a boolean');
+/** {@link asStringArray}, throwing {@link CoerceError} when absent. */
+exports.requireStringArray = require_(exports.asStringArray, 'an array of non-empty strings');
+/** {@link asStringList}, throwing {@link CoerceError} when absent. */
+exports.requireStringList = require_(exports.asStringList, 'a list of non-empty strings');
+/** {@link asRecord}, throwing {@link CoerceError} when absent. */
+exports.requireRecord = require_(exports.asRecord, 'an object');
+/** {@link asDate}, throwing {@link CoerceError} when absent. */
+exports.requireDate = require_(exports.asDate, 'a date');
+/** {@link asIsoString}, throwing {@link CoerceError} when absent. */
+exports.requireIsoString = require_(exports.asIsoString, 'a timestamp');
+/**
+ * Narrow a value to one of `allowed`, else `null`.
+ *
+ * The literal tuple is preserved, so `asOneOf(body.role, ['user', 'admin'])`
+ * is typed `'user' | 'admin' | null` without a cast at the call site.
+ */
+const asOneOf = (value, allowed) => {
+    const str = (0, exports.asString)(value);
+    return str !== null && allowed.includes(str) ? str : null;
+};
+exports.asOneOf = asOneOf;
+/** {@link asOneOf}, throwing {@link CoerceError} when the value is not allowed. */
+const requireOneOf = (value, allowed, label) => {
+    const coerced = (0, exports.asOneOf)(value, allowed);
+    if (coerced === null)
+        throw new CoerceError(label, `one of ${allowed.join(', ')}`);
+    return coerced;
+};
+exports.requireOneOf = requireOneOf;

package/esm/coerce.js

@@ -0,0 +1,154 @@
+/**
+ * Coercion of untrusted `unknown` values — JSON request bodies, database rows,
+ * Kubernetes specs, env strings — into narrow TypeScript types.
+ *
+ * Two families, one rule each:
+ *
+ *   - `as*` is lenient: it answers "is this value already a usable T?" and
+ *     returns `null` when it is not. It never guesses across types (`'5'` is
+ *     not an integer, `1` is not a string) and never treats a blank string as
+ *     present, so a caller cannot mistake `''` for a supplied identifier.
+ *   - `require*` is strict: same test, but a miss throws {@link CoerceError}.
+ *
+ * Deliberately transport-agnostic: `CoerceError` carries the offending
+ * `label`, not an HTTP status. A server maps it to 400 at its own boundary,
+ * which keeps this package usable off the request path.
+ */
+/** A value that was required but absent or of the wrong shape. */
+export class CoerceError extends Error {
+    /** What the caller was asking for, e.g. `'message_id'`. */
+    label;
+    constructor(label, expected) {
+        super(`${label} is required (expected ${expected})`);
+        this.name = 'CoerceError';
+        this.label = label;
+    }
+}
+/** A non-empty, non-whitespace string, else `null`. */
+export const asString = (value) => typeof value === 'string' && value.trim() !== '' ? value : null;
+/** A finite number, else `null`. Strings are not parsed. */
+export const asNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+/** A safe integer, else `null`. `1.5` and `'1'` are both `null`. */
+export const asInteger = (value) => typeof value === 'number' && Number.isInteger(value) ? value : null;
+/**
+ * A boolean. Booleans pass through; the string spellings people actually type
+ * (`true/false`, `1/0`, `yes/no`, `on/off`, `t/f`, `y/n`) are recognised
+ * case-insensitively, because env vars and query strings only carry strings.
+ * Anything else is `null` — notably `''`, so "unset" stays distinguishable
+ * from "false".
+ */
+export const asBoolean = (value) => {
+    if (typeof value === 'boolean')
+        return value;
+    const str = asString(value)?.trim().toLowerCase();
+    if (str === undefined)
+        return null;
+    if (TRUTHY.has(str))
+        return true;
+    if (FALSY.has(str))
+        return false;
+    return null;
+};
+const TRUTHY = new Set(['1', 'on', 't', 'true', 'y', 'yes']);
+const FALSY = new Set(['0', 'f', 'false', 'n', 'no', 'off']);
+/**
+ * An array whose every entry is a non-empty string, else `null`.
+ *
+ * All-or-nothing on purpose: silently dropping the malformed entries of a
+ * list of role names or allowed origins is how a security list quietly
+ * shrinks.
+ */
+export const asStringArray = (value) => {
+    if (!Array.isArray(value))
+        return null;
+    const strings = [];
+    for (const entry of value) {
+        const str = asString(entry);
+        if (str === null)
+            return null;
+        strings.push(str);
+    }
+    return strings;
+};
+/**
+ * A list of non-empty strings from either an array (see
+ * {@link asStringArray}) or a delimited string, else `null`.
+ *
+ * Entries are trimmed and blanks dropped, because the delimited form is what a
+ * `PATH`-style env var, a query parameter or a header carries, and
+ * `'a, b,'` means two entries in all three.
+ */
+export const asStringList = (value, separator = ',') => {
+    const str = asString(value);
+    if (str !== null)
+        return str.split(separator).map(entry => entry.trim()).filter(Boolean);
+    return asStringArray(value);
+};
+/**
+ * A plain object, else `null`. Arrays and `null` are not records — both are
+ * `typeof 'object'`, and that check is the classic source of a `.length`
+ * lookup on something that was supposed to be a map.
+ */
+export const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+/** A valid `Date`, else `null`. An invalid date parse is not a `Date`. */
+export const asDate = (value) => {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    const str = asString(value);
+    if (str === null)
+        return null;
+    const parsed = new Date(str);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+};
+/**
+ * A timestamp as an ISO-8601 string, else `null`.
+ *
+ * A `Date` is serialised; a string is passed through **verbatim** rather than
+ * round-tripped through `Date`, so a caller's own cursor value survives
+ * byte-for-byte — the format a database returned is the format it compares
+ * against.
+ */
+export const asIsoString = (value) => value instanceof Date ? asDate(value)?.toISOString() ?? null : asString(value);
+const require_ = (as, expected) => (value, label) => {
+    const coerced = as(value);
+    if (coerced === null)
+        throw new CoerceError(label, expected);
+    return coerced;
+};
+/** {@link asString}, throwing {@link CoerceError} when absent. */
+export const requireString = require_(asString, 'a non-empty string');
+/** {@link asNumber}, throwing {@link CoerceError} when absent. */
+export const requireNumber = require_(asNumber, 'a finite number');
+/** {@link asInteger}, throwing {@link CoerceError} when absent. */
+export const requireInteger = require_(asInteger, 'an integer');
+/** {@link asBoolean}, throwing {@link CoerceError} when absent. */
+export const requireBoolean = require_(asBoolean, 'a boolean');
+/** {@link asStringArray}, throwing {@link CoerceError} when absent. */
+export const requireStringArray = require_(asStringArray, 'an array of non-empty strings');
+/** {@link asStringList}, throwing {@link CoerceError} when absent. */
+export const requireStringList = require_(asStringList, 'a list of non-empty strings');
+/** {@link asRecord}, throwing {@link CoerceError} when absent. */
+export const requireRecord = require_(asRecord, 'an object');
+/** {@link asDate}, throwing {@link CoerceError} when absent. */
+export const requireDate = require_(asDate, 'a date');
+/** {@link asIsoString}, throwing {@link CoerceError} when absent. */
+export const requireIsoString = require_(asIsoString, 'a timestamp');
+/**
+ * Narrow a value to one of `allowed`, else `null`.
+ *
+ * The literal tuple is preserved, so `asOneOf(body.role, ['user', 'admin'])`
+ * is typed `'user' | 'admin' | null` without a cast at the call site.
+ */
+export const asOneOf = (value, allowed) => {
+    const str = asString(value);
+    return str !== null && allowed.includes(str) ? str : null;
+};
+/** {@link asOneOf}, throwing {@link CoerceError} when the value is not allowed. */
+export const requireOneOf = (value, allowed, label) => {
+    const coerced = asOneOf(value, allowed);
+    if (coerced === null)
+        throw new CoerceError(label, `one of ${allowed.join(', ')}`);
+    return coerced;
+};

package/esm/index.js

@@ -0,0 +1 @@
+export * from './coerce';

package/index.d.ts

@@ -0,0 +1 @@
+export * from './coerce';

package/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./coerce"), exports);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@constructive-io/coerce",
+  "version": "0.1.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Coerce untrusted unknown values into narrow TypeScript types",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "devDependencies": {
+    "makage": "^0.3.0"
+  },
+  "keywords": [
+    "coerce",
+    "validation",
+    "typescript"
+  ],
+  "gitHead": "50a5ab31f64974a079bfbef6714ffa4b0044ffee"
+}