@constructive-io/coerce 0.2.0 → 0.3.1

package/README.md

@@ -66,6 +66,7 @@ Then the text-carried and named shapes — what an env var, a query string or a
 | `asIntegerIn` | `requireIntegerIn` | an integer within `{ min, max }`, inclusive |
 | `asPort` | `requirePort` | a port: an integer in `1..65535`, from a number or a string |
 | `asBigInt` | `requireBigInt` | a `bigint`, an integer, or a digit string |
+| `asBigIntString` | `requireBigIntString` | the same, answered as canonical digits — the wire form of an `int8` |
 | `asUrl` | `requireUrl` | an absolute URL — a scheme is required |
 | `asHostname` | `requireHostname` | a hostname or IP address — no scheme, port or path |
 | `asEmail` | `requireEmail` | an email address |

package/coerce.d.ts

@@ -48,6 +48,14 @@ export declare const asBoolean: (value: unknown) => boolean | null;
  * shrinks.
  */
 export declare const asStringArray: (value: unknown) => string[] | null;
+/**
+ * An array whose every entry coerces through `element`, else `null`. One bad
+ * entry rejects the whole array — a partially-valid list is a partially-wrong
+ * answer.
+ */
+export declare const asArrayOf: <T>(value: unknown, element: (entry: unknown) => T | null) => T[] | null;
+/** {@link asArrayOf}, throwing {@link CoerceError} when absent. */
+export declare const requireArrayOf: <T>(value: unknown, element: (entry: unknown) => T | null, label: string, expected?: string) => T[];
 /**
  * A list of non-empty strings from either an array (see
  * {@link asStringArray}) or a delimited string, else `null`.
@@ -104,6 +112,16 @@ export declare const asPort: (value: unknown) => number | null;
  * its way through JSON, where it cannot survive as a `number`.
  */
 export declare const asBigInt: (value: unknown) => bigint | null;
+/**
+ * A whole number in its canonical text form, else `null` — {@link asBigInt}
+ * spelled the way a 64-bit value travels.
+ *
+ * Text is the wire format for `int8`: node-postgres returns the type as a
+ * string, JSON carries it as one, and a `number` would silently lose identity
+ * past 2^53. Every accepted shape is normalised through `BigInt`, so `'007'`
+ * and `7` both answer `'7'` and two ids compare as themselves.
+ */
+export declare const asBigIntString: (value: unknown) => string | null;
 /**
  * An absolute URL, returned **verbatim**, else `null`. A scheme is required, so
  * `'example.com'` — which is a path, and a classic way to fetch the wrong
@@ -163,6 +181,8 @@ export declare const requireNumericInteger: (value: unknown, label: string) => n
 export declare const requirePort: (value: unknown, label: string) => number;
 /** {@link asBigInt}, throwing {@link CoerceError} when absent. */
 export declare const requireBigInt: (value: unknown, label: string) => bigint;
+/** {@link asBigIntString}, throwing {@link CoerceError} when absent. */
+export declare const requireBigIntString: (value: unknown, label: string) => string;
 /** {@link asUrl}, throwing {@link CoerceError} when absent. */
 export declare const requireUrl: (value: unknown, label: string) => string;
 /** {@link asHostname}, throwing {@link CoerceError} when absent. */

package/coerce.js

@@ -22,7 +22,7 @@
  * which keeps this package usable off the request path.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requireOneOf = exports.asOneOf = exports.requireIntegerIn = exports.requireNumberIn = exports.requireJson = exports.requireDuration = exports.requireUuid = exports.requireEmail = exports.requireHostname = exports.requireUrl = exports.requireBigInt = exports.requirePort = exports.requireNumericInteger = exports.requireNumeric = exports.requireIsoString = exports.requireDate = exports.requireRecord = exports.requireStringList = exports.requireStringArray = exports.requireBoolean = exports.requireInteger = exports.requireNumber = exports.requireString = exports.asJson = exports.asDuration = exports.asUuid = exports.asEmail = exports.asHostname = exports.asUrl = exports.asBigInt = exports.asPort = exports.asIntegerIn = exports.asNumberIn = exports.asNumericInteger = exports.asNumeric = exports.asIsoString = exports.asDate = exports.asRecord = exports.asStringList = exports.asStringArray = exports.asBoolean = exports.asInteger = exports.asNumber = exports.asString = exports.CoerceError = void 0;
+exports.requireOneOf = exports.asOneOf = exports.requireIntegerIn = exports.requireNumberIn = exports.requireJson = exports.requireDuration = exports.requireUuid = exports.requireEmail = exports.requireHostname = exports.requireUrl = exports.requireBigIntString = exports.requireBigInt = exports.requirePort = exports.requireNumericInteger = exports.requireNumeric = exports.requireIsoString = exports.requireDate = exports.requireRecord = exports.requireStringList = exports.requireStringArray = exports.requireBoolean = exports.requireInteger = exports.requireNumber = exports.requireString = exports.asJson = exports.asDuration = exports.asUuid = exports.asEmail = exports.asHostname = exports.asUrl = exports.asBigIntString = exports.asBigInt = exports.asPort = exports.asIntegerIn = exports.asNumberIn = exports.asNumericInteger = exports.asNumeric = exports.asIsoString = exports.asDate = exports.asRecord = exports.asStringList = exports.requireArrayOf = exports.asArrayOf = 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'`. */
@@ -85,6 +85,32 @@ const asStringArray = (value) => {
     return strings;
 };
 exports.asStringArray = asStringArray;
+/**
+ * An array whose every entry coerces through `element`, else `null`. One bad
+ * entry rejects the whole array — a partially-valid list is a partially-wrong
+ * answer.
+ */
+const asArrayOf = (value, element) => {
+    if (!Array.isArray(value))
+        return null;
+    const entries = [];
+    for (const item of value) {
+        const coerced = element(item);
+        if (coerced === null)
+            return null;
+        entries.push(coerced);
+    }
+    return entries;
+};
+exports.asArrayOf = asArrayOf;
+/** {@link asArrayOf}, throwing {@link CoerceError} when absent. */
+const requireArrayOf = (value, element, label, expected = 'an array of valid entries') => {
+    const entries = (0, exports.asArrayOf)(value, element);
+    if (entries === null)
+        throw new CoerceError(label, expected);
+    return entries;
+};
+exports.requireArrayOf = requireArrayOf;
 /**
  * A list of non-empty strings from either an array (see
  * {@link asStringArray}) or a delimited string, else `null`.
@@ -183,6 +209,17 @@ const asBigInt = (value) => {
 };
 exports.asBigInt = asBigInt;
 const INTEGER_TEXT = /^[+-]?\d+$/;
+/**
+ * A whole number in its canonical text form, else `null` — {@link asBigInt}
+ * spelled the way a 64-bit value travels.
+ *
+ * Text is the wire format for `int8`: node-postgres returns the type as a
+ * string, JSON carries it as one, and a `number` would silently lose identity
+ * past 2^53. Every accepted shape is normalised through `BigInt`, so `'007'`
+ * and `7` both answer `'7'` and two ids compare as themselves.
+ */
+const asBigIntString = (value) => (0, exports.asBigInt)(value)?.toString() ?? null;
+exports.asBigIntString = asBigIntString;
 /**
  * An absolute URL, returned **verbatim**, else `null`. A scheme is required, so
  * `'example.com'` — which is a path, and a classic way to fetch the wrong
@@ -316,6 +353,8 @@ exports.requireNumericInteger = require_(exports.asNumericInteger, 'an integer')
 exports.requirePort = require_(exports.asPort, 'a port in 1..65535');
 /** {@link asBigInt}, throwing {@link CoerceError} when absent. */
 exports.requireBigInt = require_(exports.asBigInt, 'a whole number');
+/** {@link asBigIntString}, throwing {@link CoerceError} when absent. */
+exports.requireBigIntString = require_(exports.asBigIntString, 'a whole number');
 /** {@link asUrl}, throwing {@link CoerceError} when absent. */
 exports.requireUrl = require_(exports.asUrl, 'an absolute URL');
 /** {@link asHostname}, throwing {@link CoerceError} when absent. */

package/esm/coerce.js

@@ -76,6 +76,30 @@ export const asStringArray = (value) => {
     }
     return strings;
 };
+/**
+ * An array whose every entry coerces through `element`, else `null`. One bad
+ * entry rejects the whole array — a partially-valid list is a partially-wrong
+ * answer.
+ */
+export const asArrayOf = (value, element) => {
+    if (!Array.isArray(value))
+        return null;
+    const entries = [];
+    for (const item of value) {
+        const coerced = element(item);
+        if (coerced === null)
+            return null;
+        entries.push(coerced);
+    }
+    return entries;
+};
+/** {@link asArrayOf}, throwing {@link CoerceError} when absent. */
+export const requireArrayOf = (value, element, label, expected = 'an array of valid entries') => {
+    const entries = asArrayOf(value, element);
+    if (entries === null)
+        throw new CoerceError(label, expected);
+    return entries;
+};
 /**
  * A list of non-empty strings from either an array (see
  * {@link asStringArray}) or a delimited string, else `null`.
@@ -164,6 +188,16 @@ export const asBigInt = (value) => {
     return str !== undefined && INTEGER_TEXT.test(str) ? BigInt(str) : null;
 };
 const INTEGER_TEXT = /^[+-]?\d+$/;
+/**
+ * A whole number in its canonical text form, else `null` — {@link asBigInt}
+ * spelled the way a 64-bit value travels.
+ *
+ * Text is the wire format for `int8`: node-postgres returns the type as a
+ * string, JSON carries it as one, and a `number` would silently lose identity
+ * past 2^53. Every accepted shape is normalised through `BigInt`, so `'007'`
+ * and `7` both answer `'7'` and two ids compare as themselves.
+ */
+export const asBigIntString = (value) => asBigInt(value)?.toString() ?? null;
 /**
  * An absolute URL, returned **verbatim**, else `null`. A scheme is required, so
  * `'example.com'` — which is a path, and a classic way to fetch the wrong
@@ -291,6 +325,8 @@ export const requireNumericInteger = require_(asNumericInteger, 'an integer');
 export const requirePort = require_(asPort, 'a port in 1..65535');
 /** {@link asBigInt}, throwing {@link CoerceError} when absent. */
 export const requireBigInt = require_(asBigInt, 'a whole number');
+/** {@link asBigIntString}, throwing {@link CoerceError} when absent. */
+export const requireBigIntString = require_(asBigIntString, 'a whole number');
 /** {@link asUrl}, throwing {@link CoerceError} when absent. */
 export const requireUrl = require_(asUrl, 'an absolute URL');
 /** {@link asHostname}, throwing {@link CoerceError} when absent. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/coerce",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "author": "Constructive <developers@constructive.io>",
   "description": "Coerce untrusted unknown values into narrow TypeScript types",
   "main": "index.js",
@@ -36,5 +36,5 @@
     "validation",
     "typescript"
   ],
-  "gitHead": "10ee73e43c2277405c0e19423e2075baef6c2755"
+  "gitHead": "ce544846eafd96280fac2607f873960392ae2c89"
 }