decoders 2.0.0-beta1 → 2.0.0-beta13

package/lib/basics.js.flow

@@ -0,0 +1,124 @@
+// @flow strict
+
+import { define } from '../Decoder';
+import { either } from './unions';
+import type { _Any } from '../_utils';
+import type { Decoder, Scalar } from '../Decoder';
+
+/**
+ * Accepts and returns only the literal `null` value.
+ */
+export const null_: Decoder<null> = define((blob, ok, err) =>
+    blob === null ? ok(blob) : err('Must be null'),
+);
+
+/**
+ * Accepts and returns only the literal `undefined` value.
+ */
+export const undefined_: Decoder<void> = define((blob, ok, err) =>
+    blob === undefined ? ok(blob) : err('Must be undefined'),
+);
+
+const undefined_or_null: Decoder<null | void> = define((blob, ok, err) =>
+    blob === undefined || blob === null
+        ? ok(blob)
+        : // Combine error message into a single line for readability
+          err('Must be undefined or null'),
+);
+
+interface Maybeish<E> {
+    <T>(decoder: Decoder<T>): Decoder<E | T>;
+    <T, V>(
+        decoder: Decoder<T>,
+        defaultValue: (() => V) | V,
+    ): Decoder<$NonMaybeType<T> | V>;
+}
+
+function _maybeish<E>(emptyCase: Decoder<E>): Maybeish<E> {
+    function _inner(decoder /* defaultValue */) {
+        const rv = either(emptyCase, decoder);
+        if (
+            // If a default value is provided...
+            arguments.length >= 2
+        ) {
+            // ...then return the default value
+            const _defaultValue = arguments[1];
+            const defaultValue =
+                typeof _defaultValue === 'function' ? _defaultValue() : _defaultValue;
+            return rv.transform((value) => value ?? defaultValue);
+        } else {
+            // Otherwise the "normal" empty case
+            return rv;
+        }
+    }
+
+    return (_inner: _Any);
+}
+
+/**
+ * Accepts whatever the given decoder accepts, or `null`.
+ *
+ * If a default value is explicitly provided, return that instead in the `null`
+ * case.
+ */
+export const nullable: Maybeish<null> = _maybeish(null_);
+
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `undefined` case.
+ */
+export const optional: Maybeish<void> = _maybeish(undefined_);
+
+/**
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `null`/`undefined` case.
+ */
+export const maybe: Maybeish<null | void> = _maybeish(undefined_or_null);
+
+/**
+ * Accepts only the given constant value.
+ */
+export function constant<T: Scalar>(value: T): Decoder<T> {
+    return define((blob, ok, err) =>
+        blob === value ? ok(value) : err(`Must be constant ${String(value)}`),
+    );
+}
+
+/**
+ * Accepts anything, completely ignores it, and always returns the provided
+ * value instead.
+ *
+ * This is useful to manually add extra fields to object decoders.
+ */
+export function always<T>(value: (() => T) | T): Decoder<T> {
+    return define(
+        typeof value === 'function'
+            ? (blob /* ignored */, ok, _) =>
+                  // $FlowFixMe[incompatible-use]
+                  ok(value())
+            : (blob /* ignored */, ok, _) => ok(value),
+    );
+}
+
+/**
+ * Alias of always.
+ */
+export const hardcoded: <T>(T) => Decoder<T> = always;
+
+/**
+ * Accepts anything and returns it unchanged.
+ *
+ * Useful for situation in which you don't know or expect a specific type. Of
+ * course, the downside is that you won't know the type of the value statically
+ * and you'll have to further refine it yourself.
+ */
+export const unknown: Decoder<mixed> = define((blob, ok, _) => ok(blob));
+
+/**
+ * Alias of unknown.
+ */
+export const mixed: Decoder<mixed> = unknown;

package/lib/basics.mjs

@@ -0,0 +1,120 @@
+import { define } from '../Decoder.mjs';
+import { either } from './unions.mjs';
+
+/**
+ * Accepts and returns only the literal `null` value.
+ */
+export var null_ = define(function (blob, ok, err) {
+  return blob === null ? ok(blob) : err('Must be null');
+});
+/**
+ * Accepts and returns only the literal `undefined` value.
+ */
+
+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) : // Combine error message into a single line for readability
+  err('Must be undefined or null');
+});
+
+function _maybeish(emptyCase) {
+  function _inner(decoder
+  /* defaultValue */
+  ) {
+    var rv = either(emptyCase, decoder);
+
+    if ( // If a default value is provided...
+    arguments.length >= 2) {
+      // ...then return the default value
+      var _defaultValue = arguments[1];
+
+      var _defaultValue2 = typeof _defaultValue === 'function' ? _defaultValue() : _defaultValue;
+
+      return rv.transform(function (value) {
+        return value != null ? value : _defaultValue2;
+      });
+    } else {
+      // Otherwise the "normal" empty case
+      return rv;
+    }
+  }
+
+  return _inner;
+}
+/**
+ * Accepts whatever the given decoder accepts, or `null`.
+ *
+ * If a default value is explicitly provided, return that instead in the `null`
+ * case.
+ */
+
+
+export var nullable = _maybeish(null_);
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `undefined` case.
+ */
+
+export var optional = _maybeish(undefined_);
+/**
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `null`/`undefined` case.
+ */
+
+export var maybe = _maybeish(undefined_or_null);
+/**
+ * Accepts only the given constant value.
+ */
+
+export function constant(value) {
+  return define(function (blob, ok, err) {
+    return blob === value ? ok(value) : err("Must be constant " + String(value));
+  });
+}
+/**
+ * Accepts anything, completely ignores it, and always returns the provided
+ * value instead.
+ *
+ * This is useful to manually add extra fields to object decoders.
+ */
+
+export function always(value) {
+  return define(typeof value === 'function' ? function (blob
+  /* ignored */
+  , ok, _) {
+    return (// $FlowFixMe[incompatible-use]
+      ok(value())
+    );
+  } : function (blob
+  /* ignored */
+  , ok, _) {
+    return ok(value);
+  });
+}
+/**
+ * Alias of always.
+ */
+
+export var hardcoded = always;
+/**
+ * Accepts anything and returns it unchanged.
+ *
+ * Useful for situation in which you don't know or expect a specific type. Of
+ * course, the downside is that you won't know the type of the value statically
+ * and you'll have to further refine it yourself.
+ */
+
+export var unknown = define(function (blob, ok, _) {
+  return ok(blob);
+});
+/**
+ * Alias of unknown.
+ */
+
+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,35 @@
+"use strict";
+
+exports.__esModule = true;
+exports.truthy = exports.numericBoolean = exports["boolean"] = void 0;
+
+var _Decoder = require("../Decoder");
+
+var _numbers = require("./numbers");
+
+/**
+ * Accepts and returns booleans.
+ */
+var _boolean = (0, _Decoder.define)(function (blob, ok, err) {
+  return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean');
+});
+/**
+ * Accepts anything and will return its "truth" value. Will never reject.
+ */
+
+
+exports["boolean"] = _boolean;
+var truthy = (0, _Decoder.define)(function (blob, ok, _) {
+  return ok(!!blob);
+});
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
+
+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,25 @@
+import { define } from '../Decoder.mjs';
+import { number } from './numbers.mjs';
+
+/**
+ * Accepts and returns booleans.
+ */
+var _boolean = define(function (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 { _boolean as boolean };
+export var truthy = define(function (blob, ok, _) {
+  return ok(!!blob);
+});
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
+
+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,44 @@
+"use strict";
+
+exports.__esModule = true;
+exports.iso8601 = exports.date = void 0;
+
+var _utils = require("../_utils");
+
+var _Decoder = require("../Decoder");
+
+var _strings = require("./strings");
+
+// 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
+var 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.
+ */
+
+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');
+});
+/**
+ * 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.
+ */
+
+exports.date = date;
+var iso8601 = // Input itself needs to match the ISO8601 regex...
+(0, _strings.regex)(iso8601_re, 'Must be ISO8601 format').transform( // Make sure it is a _valid_ date
+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,34 @@
+import { asDate } from '../_utils.mjs';
+import { define } from '../Decoder.mjs';
+import { regex } from './strings.mjs';
+// 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
+var 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 var date = define(function (blob, ok, err) {
+  var 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 var iso8601 = // Input itself needs to match the ISO8601 regex...
+regex(iso8601_re, 'Must be ISO8601 format').transform( // Make sure it is a _valid_ date
+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;
+}
+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>;
+
+/**
+ * Like `json`, but will only decode when the JSON value is an array.
+ */
+export const jsonArray: Decoder<JSONArray>;
+
+/**
+ * Like `json`, but will only decode when the JSON value is an object.
+ */
+export const jsonObject: Decoder<JSONObject>;

package/lib/json.js

@@ -0,0 +1,55 @@
+"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");
+
+/**
+ * Like `json`, but will only decode when the JSON value is an object.
+ */
+var jsonObject = (0, _utilities.lazy)(function () {
+  return (0, _objects.dict)(json);
+});
+/**
+ * Like `json`, but will only decode when the JSON value is an array.
+ */
+
+exports.jsonObject = jsonObject;
+var jsonArray = (0, _utilities.lazy)(function () {
+  return (0, _arrays.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[]
+ * ```
+ */
+
+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>;
+
+/**
+ * Like `json`, but will only decode when the JSON value is an object.
+ */
+export const jsonObject: Decoder<JSONObject> = lazy(() => dict(json));
+
+/**
+ * Like `json`, but will only decode when the JSON value is an array.
+ */
+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,40 @@
+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';
+
+/**
+ * Like `json`, but will only decode when the JSON value is an object.
+ */
+export var jsonObject = lazy(function () {
+  return dict(json);
+});
+/**
+ * Like `json`, but will only decode when the JSON value is an array.
+ */
+
+export var jsonArray = lazy(function () {
+  return 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 var json = either(null_, string, number, _boolean, jsonObject, jsonArray).describe('Must be valid JSON value');