decoders 2.0.0-beta8 → 2.0.1

package/lib/basics.mjs

@@ -0,0 +1,75 @@
+import { define } from '../Decoder.mjs'
+import { either } from './unions.mjs'
+
+export var null_ = define(function (blob, ok, err) {
+  return blob === null ? ok(blob) : err('Must be null')
+})
+
+export var undefined_ = define(function (blob, ok, err) {
+  return blob === undefined ? ok(blob) : err('Must be undefined')
+})
+var undefined_or_null = define(function (blob, ok, err) {
+  return blob === undefined || blob === null ? ok(blob) : err('Must be undefined or null')
+})
+
+function _maybeish(emptyCase) {
+  function _inner(decoder) {
+    var rv = either(emptyCase, decoder)
+
+    if (arguments.length >= 2) {
+      var _defaultValue = arguments[1]
+
+      var _defaultValue2 = typeof _defaultValue === 'function' ? _defaultValue() : _defaultValue
+
+      return rv.transform(function (value) {
+        return value != null ? value : _defaultValue2
+      })
+    } else {
+      return rv
+    }
+  }
+
+  return _inner
+}
+
+export var nullable = _maybeish(null_)
+
+export var optional = _maybeish(undefined_)
+
+export var maybe = _maybeish(undefined_or_null)
+
+export function constant(value) {
+  return define(function (blob, ok, err) {
+    return blob === value ? ok(value) : err('Must be constant ' + String(value))
+  })
+}
+
+export function always(value) {
+  return define(
+    typeof value === 'function'
+      ? function (
+          blob,
+
+          ok,
+          _
+        ) {
+          return ok(value())
+        }
+      : function (
+          blob,
+
+          ok,
+          _
+        ) {
+          return ok(value)
+        }
+  )
+}
+
+export var hardcoded = always
+
+export var unknown = define(function (blob, ok, _) {
+  return ok(blob)
+})
+
+export var mixed = unknown

package/lib/booleans.d.ts

@@ -0,0 +1,16 @@
+import { Decoder } from '../Decoder';
+
+/**
+ * Accepts and returns booleans.
+ */
+export const boolean: Decoder<boolean>;
+
+/**
+ * Accepts anything and will return its "truth" value. Will never reject.
+ */
+export const truthy: Decoder<boolean>;
+
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
+export const numericBoolean: Decoder<boolean>;

package/lib/booleans.js

@@ -0,0 +1,25 @@
+'use strict'
+
+exports.__esModule = true
+exports.truthy = exports.numericBoolean = exports['boolean'] = void 0
+
+var _Decoder = require('../Decoder')
+
+var _numbers = require('./numbers')
+
+var _boolean = (0, _Decoder.define)(function (blob, ok, err) {
+  return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean')
+})
+
+exports['boolean'] = _boolean
+var truthy = (0, _Decoder.define)(function (blob, ok, _) {
+  return ok(!!blob)
+})
+
+exports.truthy = truthy
+
+var numericBoolean = _numbers.number.transform(function (n) {
+  return !!n
+})
+
+exports.numericBoolean = numericBoolean

package/lib/booleans.js.flow

@@ -0,0 +1,22 @@
+// @flow strict
+
+import { define } from '../Decoder';
+import { number } from './numbers';
+import type { Decoder } from '../Decoder';
+
+/**
+ * Accepts and returns booleans.
+ */
+export const boolean: Decoder<boolean> = define((blob, ok, err) => {
+    return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean');
+});
+
+/**
+ * Accepts anything and will return its "truth" value. Will never reject.
+ */
+export const truthy: Decoder<boolean> = define((blob, ok, _) => ok(!!blob));
+
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
+export const numericBoolean: Decoder<boolean> = number.transform((n) => !!n);

package/lib/booleans.mjs

@@ -0,0 +1,15 @@
+import { define } from '../Decoder.mjs'
+import { number } from './numbers.mjs'
+
+var _boolean = define(function (blob, ok, err) {
+  return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean')
+})
+
+export { _boolean as boolean }
+export var truthy = define(function (blob, ok, _) {
+  return ok(!!blob)
+})
+
+export var numericBoolean = number.transform(function (n) {
+  return !!n
+})

package/lib/dates.d.ts

@@ -0,0 +1,15 @@
+import { Decoder } from '../Decoder';
+
+/**
+ * Accepts and returns `Date` instances.
+ */
+export const date: Decoder<Date>;
+
+/**
+ * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
+ * returns them as `Date` instances.
+ *
+ * This is very useful for working with dates in APIs: serialize them as
+ * `.toISOString()` when sending, decode them with `iso8601` when receiving.
+ */
+export const iso8601: Decoder<Date>;

package/lib/dates.js

@@ -0,0 +1,28 @@
+'use strict'
+
+exports.__esModule = true
+exports.iso8601 = exports.date = void 0
+
+var _utils = require('../_utils')
+
+var _Decoder = require('../Decoder')
+
+var _strings = require('./strings')
+var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/
+
+var date = (0, _Decoder.define)(function (blob, ok, err) {
+  var date = (0, _utils.asDate)(blob)
+  return date !== null ? ok(date) : err('Must be a Date')
+})
+
+exports.date = date
+var iso8601 = (0, _strings.regex)(iso8601_re, 'Must be ISO8601 format').transform(function (value) {
+  var date = new Date(value)
+
+  if (isNaN(date.getTime())) {
+    throw new Error('Must be valid date/time value')
+  }
+
+  return date
+})
+exports.iso8601 = iso8601

package/lib/dates.js.flow

@@ -0,0 +1,40 @@
+// @flow strict
+
+import { asDate } from '../_utils';
+import { define } from '../Decoder';
+import { regex } from './strings';
+import type { Decoder } from '../Decoder';
+
+// Only matches the shape.  This "over-matches" some values that still aren't
+// valid dates (like 9999-99-99), but those will be caught by JS Date's
+// internal validations
+const iso8601_re =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+/**
+ * Accepts and returns `Date` instances.
+ */
+export const date: Decoder<Date> = define((blob, ok, err) => {
+    const date = asDate(blob);
+    return date !== null ? ok(date) : err('Must be a Date');
+});
+
+/**
+ * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
+ * returns them as `Date` instances.
+ *
+ * This is very useful for working with dates in APIs: serialize them as
+ * `.toISOString()` when sending, decode them with `iso8601` when receiving.
+ */
+export const iso8601: Decoder<Date> =
+    // Input itself needs to match the ISO8601 regex...
+    regex(iso8601_re, 'Must be ISO8601 format').transform(
+        // Make sure it is a _valid_ date
+        (value: string) => {
+            const date = new Date(value);
+            if (isNaN(date.getTime())) {
+                throw new Error('Must be valid date/time value');
+            }
+            return date;
+        },
+    );

package/lib/dates.mjs

@@ -0,0 +1,19 @@
+import { asDate } from '../_utils.mjs'
+import { define } from '../Decoder.mjs'
+import { regex } from './strings.mjs'
+var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/
+
+export var date = define(function (blob, ok, err) {
+  var date = asDate(blob)
+  return date !== null ? ok(date) : err('Must be a Date')
+})
+
+export var iso8601 = regex(iso8601_re, 'Must be ISO8601 format').transform(function (value) {
+  var date = new Date(value)
+
+  if (isNaN(date.getTime())) {
+    throw new Error('Must be valid date/time value')
+  }
+
+  return date
+})

package/lib/json.d.ts

@@ -0,0 +1,35 @@
+import { Decoder } from '../Decoder';
+
+export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
+export interface JSONObject {
+    [key: string]: JSONValue | undefined;
+}
+export type JSONArray = JSONValue[];
+
+/**
+ * Accepts any value that's a valid JSON value.
+ *
+ * In other words: any value returned by `JSON.parse()` should decode without
+ * failure.
+ *
+ * ```typescript
+ * type JSONValue =
+ *     | null
+ *     | string
+ *     | number
+ *     | boolean
+ *     | { [string]: JSONValue }
+ *     | JSONValue[]
+ * ```
+ */
+export const json: Decoder<JSONValue>;
+
+/**
+ * Accepts arrays that contain only valid JSON values.
+ */
+export const jsonArray: Decoder<JSONArray>;
+
+/**
+ * Accepts objects that contain only valid JSON values.
+ */
+export const jsonObject: Decoder<JSONObject>;

package/lib/json.js

@@ -0,0 +1,33 @@
+'use strict'
+
+exports.__esModule = true
+exports.jsonObject = exports.jsonArray = exports.json = void 0
+
+var _arrays = require('./arrays')
+
+var _booleans = require('./booleans')
+
+var _objects = require('./objects')
+
+var _unions = require('./unions')
+
+var _utilities = require('./utilities')
+
+var _basics = require('./basics')
+
+var _numbers = require('./numbers')
+
+var _strings = require('./strings')
+
+var jsonObject = (0, _utilities.lazy)(function () {
+  return (0, _objects.dict)(json)
+})
+
+exports.jsonObject = jsonObject
+var jsonArray = (0, _utilities.lazy)(function () {
+  return (0, _arrays.array)(json)
+})
+
+exports.jsonArray = jsonArray
+var json = (0, _unions.either)(_basics.null_, _strings.string, _numbers.number, _booleans['boolean'], jsonObject, jsonArray).describe('Must be valid JSON value')
+exports.json = json

package/lib/json.js.flow

@@ -0,0 +1,50 @@
+// @flow strict
+
+import { array } from './arrays';
+import { boolean } from './booleans';
+import { dict } from './objects';
+import { either } from './unions';
+import { lazy } from './utilities';
+import { null_ } from './basics';
+import { number } from './numbers';
+import { string } from './strings';
+import type { Decoder } from '../Decoder';
+
+export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
+export type JSONObject = { [string]: JSONValue };
+export type JSONArray = Array<JSONValue>;
+
+/**
+ * Accepts objects that contain only valid JSON values.
+ */
+export const jsonObject: Decoder<JSONObject> = lazy(() => dict(json));
+
+/**
+ * Accepts arrays that contain only valid JSON values.
+ */
+export const jsonArray: Decoder<JSONArray> = lazy(() => array(json));
+
+/**
+ * Accepts any value that's a valid JSON value.
+ *
+ * In other words: any value returned by `JSON.parse()` should decode without
+ * failure.
+ *
+ * ```typescript
+ * type JSONValue =
+ *     | null
+ *     | string
+ *     | number
+ *     | boolean
+ *     | { [string]: JSONValue }
+ *     | JSONValue[]
+ * ```
+ */
+export const json: Decoder<JSONValue> = either(
+    null_,
+    string,
+    number,
+    boolean,
+    jsonObject,
+    jsonArray,
+).describe('Must be valid JSON value');

package/lib/json.mjs

@@ -0,0 +1,18 @@
+import { array } from './arrays.mjs'
+import { boolean as _boolean } from './booleans.mjs'
+import { dict } from './objects.mjs'
+import { either } from './unions.mjs'
+import { lazy } from './utilities.mjs'
+import { null_ } from './basics.mjs'
+import { number } from './numbers.mjs'
+import { string } from './strings.mjs'
+
+export var jsonObject = lazy(function () {
+  return dict(json)
+})
+
+export var jsonArray = lazy(function () {
+  return array(json)
+})
+
+export var json = either(null_, string, number, _boolean, jsonObject, jsonArray).describe('Must be valid JSON value')

package/lib/numbers.d.ts

@@ -0,0 +1,31 @@
+import { Decoder } from '../Decoder';
+
+/**
+ * Accepts any valid ``number`` value.
+ *
+ * This also accepts special values like `NaN` and `Infinity`. Unless you
+ * want to deliberately accept those, you'll likely want to use the
+ * `number` decoder instead.
+ */
+export const anyNumber: Decoder<number>;
+
+/**
+ * Accepts finite numbers (can be integer or float values). Values `NaN`,
+ * or positive and negative `Infinity` will get rejected.
+ */
+export const number: Decoder<number>;
+
+/**
+ * Accepts only finite whole numbers.
+ */
+export const integer: Decoder<number>;
+
+/**
+ * Accepts only positive finite numbers.
+ */
+export const positiveNumber: Decoder<number>;
+
+/**
+ * Accepts only positive finite whole numbers.
+ */
+export const positiveInteger: Decoder<number>;

package/lib/numbers.js

@@ -0,0 +1,31 @@
+'use strict'
+
+exports.__esModule = true
+exports.positiveNumber = exports.positiveInteger = exports.number = exports.integer = exports.anyNumber = void 0
+
+var _Decoder = require('../Decoder')
+
+var anyNumber = (0, _Decoder.define)(function (blob, ok, err) {
+  return typeof blob === 'number' ? ok(blob) : err('Must be number')
+})
+
+exports.anyNumber = anyNumber
+var number = anyNumber.refine(function (n) {
+  return Number.isFinite(n)
+}, 'Number must be finite')
+
+exports.number = number
+var integer = number.refine(function (n) {
+  return Number.isInteger(n)
+}, 'Number must be an integer')
+
+exports.integer = integer
+var positiveNumber = number.refine(function (n) {
+  return n >= 0
+}, 'Number must be positive')
+
+exports.positiveNumber = positiveNumber
+var positiveInteger = integer.refine(function (n) {
+  return n >= 0
+}, 'Number must be positive')
+exports.positiveInteger = positiveInteger

package/lib/numbers.js.flow

@@ -0,0 +1,48 @@
+// @flow strict
+
+import { define } from '../Decoder';
+import type { Decoder } from '../Decoder';
+
+/**
+ * Accepts any valid ``number`` value.
+ *
+ * This also accepts special values like `NaN` and `Infinity`. Unless you
+ * want to deliberately accept those, you'll likely want to use the
+ * `number` decoder instead.
+ */
+export const anyNumber: Decoder<number> = define((blob, ok, err) =>
+    typeof blob === 'number' ? ok(blob) : err('Must be number'),
+);
+
+/**
+ * Accepts finite numbers (can be integer or float values). Values `NaN`,
+ * or positive and negative `Infinity` will get rejected.
+ */
+export const number: Decoder<number> = anyNumber.refine(
+    (n) => Number.isFinite(n),
+    'Number must be finite',
+);
+
+/**
+ * Accepts only finite whole numbers.
+ */
+export const integer: Decoder<number> = number.refine(
+    (n) => Number.isInteger(n),
+    'Number must be an integer',
+);
+
+/**
+ * Accepts only positive finite numbers.
+ */
+export const positiveNumber: Decoder<number> = number.refine(
+    (n) => n >= 0,
+    'Number must be positive',
+);
+
+/**
+ * Accepts only positive finite whole numbers.
+ */
+export const positiveInteger: Decoder<number> = integer.refine(
+    (n) => n >= 0,
+    'Number must be positive',
+);

package/lib/numbers.mjs

@@ -0,0 +1,21 @@
+import { define } from '../Decoder.mjs'
+
+export var anyNumber = define(function (blob, ok, err) {
+  return typeof blob === 'number' ? ok(blob) : err('Must be number')
+})
+
+export var number = anyNumber.refine(function (n) {
+  return Number.isFinite(n)
+}, 'Number must be finite')
+
+export var integer = number.refine(function (n) {
+  return Number.isInteger(n)
+}, 'Number must be an integer')
+
+export var positiveNumber = number.refine(function (n) {
+  return n >= 0
+}, 'Number must be positive')
+
+export var positiveInteger = integer.refine(function (n) {
+  return n >= 0
+}, 'Number must be positive')

package/lib/objects.d.ts

@@ -0,0 +1,76 @@
+/// <reference lib="es6" />
+
+import { Decoder, DecoderType } from '../Decoder';
+import { AllowImplicit } from './_helpers';
+
+export type ObjectDecoderType<T> = AllowImplicit<{
+    [key in keyof T]: DecoderType<T[key]>;
+}>;
+
+/**
+ * Accepts any "plain old JavaScript object", but doesn't validate its keys or
+ * values further.
+ */
+export const pojo: Decoder<Record<string, unknown>>;
+
+/**
+ * Accepts objects with fields matching the given decoders. Extra fields that
+ * exist on the input object are ignored and will not be returned.
+ */
+export function object(decodersByKey: Record<any, never>): Decoder<Record<string, never>>;
+export function object<O extends Record<string, Decoder<any>>>(
+    decodersByKey: O,
+): Decoder<{ [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] }>;
+//         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+//         This is basically just equivalent to:
+//             ObjectDecoderType<O>
+//
+//         But by "resolving" this with a mapped type, we remove the helper
+//         type names from the inferred type here, making this much easier to
+//         work with while developing.
+
+/**
+ * Like `object()`, but will reject inputs that contain extra fields that are
+ * not specified explicitly.
+ */
+export function exact(decodersByKey: Record<any, never>): Decoder<Record<string, never>>;
+export function exact<O extends Record<string, Decoder<any>>>(
+    decodersByKey: O,
+): Decoder<{ [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] }>;
+//         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+//         Ditto (see above)
+
+/**
+ * Like `object()`, but will pass through any extra fields on the input object
+ * unvalidated that will thus be of `unknown` type statically.
+ */
+export function inexact(
+    decodersByKey: Record<any, never>,
+): Decoder<Record<string, unknown>>;
+export function inexact<O extends Record<string, Decoder<any>>>(
+    decodersByKey: O,
+): Decoder<
+    { [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] } & Record<
+        string,
+        unknown
+    >
+>;
+
+/**
+ * Accepts objects where all values match the given decoder, and returns the
+ * result as a `Record<string, T>`.
+ *
+ * The main difference between `object()` and `dict()` is that you'd typically
+ * use `object()` if this is a record-like object, where all field names are
+ * known and the values are heterogeneous. Whereas with `dict()` the keys are
+ * typically dynamic and the values homogeneous, like in a dictionary,
+ * a lookup table, or a cache.
+ */
+export function dict<T>(decoder: Decoder<T>): Decoder<Record<string, T>>;
+
+/**
+ * Similar to `dict()`, but returns the result as a `Map<string, T>` (an [ES6
+ * Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map))
+ * instead.
+ */
+export function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>>;