@constructive-io/coerce 0.3.0 → 0.4.0

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

@@ -112,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
@@ -171,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.requireArrayOf = exports.asArrayOf = 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'`. */
@@ -209,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
@@ -342,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

@@ -188,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
@@ -315,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.3.0",
+  "version": "0.4.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": "06bf3edad0d1d1dba9b44f17b8c791de6768576d"
+  "gitHead": "b5b6b9f05276b7e9cbd3d1f4acd31dd315c353ea"
 }