@constructive-io/coerce 0.2.0 → 0.3.0

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`.

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.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.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`.

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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/coerce",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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": "06bf3edad0d1d1dba9b44f17b8c791de6768576d"
 }