decoders 1.25.5 → 2.0.0-beta2

package/annotate.js

@@ -0,0 +1,161 @@
+"use strict";
+
+exports.__esModule = true;
+exports.__private_annotate = annotate;
+exports.annotate = public_annotate;
+exports.annotateObject = public_annotateObject;
+exports.array = array;
+exports.asAnnotation = asAnnotation;
+exports.circularRef = circularRef;
+exports.func = func;
+exports.merge = merge;
+exports.object = object;
+exports.scalar = scalar;
+exports.unknown = unknown;
+exports.updateText = updateText;
+
+function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
+
+var _register = new WeakSet();
+
+function brand(ann) {
+  _register.add(ann);
+
+  return ann;
+}
+
+function object(fields, text) {
+  return brand({
+    type: 'object',
+    fields: fields,
+    text: text
+  });
+}
+
+function array(items, text) {
+  return brand({
+    type: 'array',
+    items: items,
+    text: text
+  });
+}
+
+function func(text) {
+  return brand({
+    type: 'function',
+    text: text
+  });
+}
+
+function unknown(value, text) {
+  return brand({
+    type: 'unknown',
+    value: value,
+    text: text
+  });
+}
+
+function scalar(value, text) {
+  return brand({
+    type: 'scalar',
+    value: value,
+    text: text
+  });
+}
+
+function circularRef(text) {
+  return brand({
+    type: 'circular-ref',
+    text: text
+  });
+}
+/**
+ * Given an existing Annotation, set the annotation's text to a new value.
+ */
+
+
+function updateText(annotation, text) {
+  if (text !== undefined) {
+    return brand(_extends({}, annotation, {
+      text: text
+    }));
+  } else {
+    return annotation;
+  }
+}
+/**
+ * Given an existing ObjectAnnotation, merges new Annotations in there.
+ */
+
+
+function merge(objAnnotation, fields) {
+  var newFields = _extends({}, objAnnotation.fields, fields);
+
+  return object(newFields, objAnnotation.text);
+}
+
+function asAnnotation(thing) {
+  return typeof thing === 'object' && thing !== null && _register.has(thing) ? thing : undefined;
+}
+
+function annotateArray(value, text, seen) {
+  seen.add(value);
+  var items = value.map(function (v) {
+    return annotate(v, undefined, seen);
+  });
+  return array(items, text);
+}
+
+function annotateObject(obj, text, seen) {
+  seen.add(obj);
+  var fields = {};
+  Object.keys(obj).forEach(function (key) {
+    var value = obj[key];
+    fields[key] = annotate(value, undefined, seen);
+  });
+  return object(fields, text);
+}
+
+function annotate(value, text, seen) {
+  if (value === null || value === undefined || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'symbol' || typeof value.getMonth === 'function') {
+    return scalar(value, text);
+  }
+
+  var ann = asAnnotation(value);
+
+  if (ann) {
+    return updateText(ann, text);
+  }
+
+  if (Array.isArray(value)) {
+    // "Circular references" can only exist in objects or arrays
+    if (seen.has(value)) {
+      return circularRef(text);
+    } else {
+      return annotateArray(value, text, seen);
+    }
+  }
+
+  if (typeof value === 'object') {
+    // "Circular references" can only exist in objects or arrays
+    if (seen.has(value)) {
+      return circularRef(text);
+    } else {
+      return annotateObject(value, text, seen);
+    }
+  }
+
+  if (typeof value === 'function') {
+    return func(text);
+  }
+
+  return unknown(value, text);
+}
+
+function public_annotate(value, text) {
+  return annotate(value, text, new WeakSet());
+}
+
+function public_annotateObject(obj, text) {
+  return annotateObject(obj, text, new WeakSet());
+}

package/annotate.js.flow

@@ -0,0 +1,218 @@
+// @flow strict
+
+type cast = $FlowFixMe;
+
+const _register: WeakSet<{ ... }> = new WeakSet();
+
+export type ObjectAnnotation = {|
+    +type: 'object',
+    +fields: { +[key: string]: Annotation },
+    +text?: string,
+|};
+
+export type ArrayAnnotation = {|
+    +type: 'array',
+    +items: $ReadOnlyArray<Annotation>,
+    +text?: string,
+|};
+
+export type ScalarAnnotation = {|
+    +type: 'scalar',
+    +value: mixed,
+    +text?: string,
+|};
+
+export type FunctionAnnotation = {|
+    +type: 'function',
+    +text?: string,
+|};
+
+export type CircularRefAnnotation = {|
+    +type: 'circular-ref',
+    +text?: string,
+|};
+
+export type UnknownAnnotation = {|
+    +type: 'unknown',
+    +value: mixed,
+    +text?: string,
+|};
+
+export type Annotation =
+    | ObjectAnnotation
+    | ArrayAnnotation
+    | ScalarAnnotation
+    | FunctionAnnotation
+    | CircularRefAnnotation
+    | UnknownAnnotation;
+
+function brand<A: Annotation>(ann: A): A {
+    _register.add(ann);
+    return ann;
+}
+
+export function object(
+    fields: { +[key: string]: Annotation },
+    text?: string,
+): ObjectAnnotation {
+    return brand({ type: 'object', fields, text });
+}
+
+export function array(items: $ReadOnlyArray<Annotation>, text?: string): ArrayAnnotation {
+    return brand({
+        type: 'array',
+        items,
+        text,
+    });
+}
+
+export function func(text?: string): FunctionAnnotation {
+    return brand({
+        type: 'function',
+        text,
+    });
+}
+
+export function unknown(value: mixed, text?: string): UnknownAnnotation {
+    return brand({
+        type: 'unknown',
+        value,
+        text,
+    });
+}
+
+export function scalar(value: mixed, text?: string): ScalarAnnotation {
+    return brand({
+        type: 'scalar',
+        value,
+        text,
+    });
+}
+
+export function circularRef(text?: string): CircularRefAnnotation {
+    return brand({
+        type: 'circular-ref',
+        text,
+    });
+}
+
+/**
+ * Given an existing Annotation, set the annotation's text to a new value.
+ */
+export function updateText<A: Annotation>(annotation: A, text?: string): A {
+    if (text !== undefined) {
+        return brand({ ...annotation, text });
+    } else {
+        return annotation;
+    }
+}
+
+/**
+ * Given an existing ObjectAnnotation, merges new Annotations in there.
+ */
+export function merge(
+    objAnnotation: ObjectAnnotation,
+    fields: { +[key: string]: Annotation },
+): ObjectAnnotation {
+    const newFields = { ...objAnnotation.fields, ...fields };
+    return object(newFields, objAnnotation.text);
+}
+
+export function asAnnotation(thing: mixed): Annotation | void {
+    return typeof thing === 'object' && thing !== null && _register.has(thing)
+        ? ((thing: cast): Annotation)
+        : undefined;
+}
+
+type RefSet = WeakSet<{ ... } | $ReadOnlyArray<mixed>>;
+
+function annotateArray(
+    value: $ReadOnlyArray<mixed>,
+    text?: string,
+    seen: RefSet,
+): ArrayAnnotation | CircularRefAnnotation {
+    seen.add(value);
+
+    const items = value.map((v) => annotate(v, undefined, seen));
+    return array(items, text);
+}
+
+function annotateObject(
+    obj: { +[string]: mixed },
+    text?: string,
+    seen: RefSet,
+): ObjectAnnotation {
+    seen.add(obj);
+
+    const fields = {};
+    Object.keys(obj).forEach((key) => {
+        const value = obj[key];
+        fields[key] = annotate(value, undefined, seen);
+    });
+    return object(fields, text);
+}
+
+function annotate(value: mixed, text?: string, seen: RefSet): Annotation {
+    if (
+        value === null ||
+        value === undefined ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        typeof value === 'symbol' ||
+        typeof value.getMonth === 'function'
+    ) {
+        return scalar(value, text);
+    }
+
+    const ann = asAnnotation(value);
+    if (ann) {
+        return updateText(ann, text);
+    }
+
+    if (Array.isArray(value)) {
+        // "Circular references" can only exist in objects or arrays
+        if (seen.has(value)) {
+            return circularRef(text);
+        } else {
+            return annotateArray(value, text, seen);
+        }
+    }
+
+    if (typeof value === 'object') {
+        // "Circular references" can only exist in objects or arrays
+        if (seen.has(value)) {
+            return circularRef(text);
+        } else {
+            return annotateObject(value, text, seen);
+        }
+    }
+
+    if (typeof value === 'function') {
+        return func(text);
+    }
+
+    return unknown(value, text);
+}
+
+function public_annotate(value: mixed, text?: string): Annotation {
+    return annotate(value, text, new WeakSet());
+}
+
+function public_annotateObject(
+    obj: { +[string]: mixed },
+    text?: string,
+): ObjectAnnotation {
+    return annotateObject(obj, text, new WeakSet());
+}
+
+export {
+    // This construct just ensures the "seen" weakmap (used for circular
+    // reference detection) isn't made part of the public API.
+    public_annotate as annotate,
+    public_annotateObject as annotateObject,
+    //
+    // NOTE: Don't acces theses private APIs directly. They are only exported here
+    // to better enable unit testing.
+    annotate as __private_annotate,
+};

package/core/array.js

@@ -0,0 +1,108 @@
+"use strict";
+
+exports.__esModule = true;
+exports.array = array;
+exports.nonEmptyArray = nonEmptyArray;
+exports.poja = void 0;
+
+var Result = _interopRequireWildcard(require("../result"));
+
+var _annotate = require("../annotate");
+
+var _composition = require("./composition");
+
+function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
+
+function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { "default": obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj["default"] = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
+
+/**
+ * Like a "Plain Old JavaScript Object", but for arrays: "Plain Old JavaScript
+ * Array" ^_^
+ */
+var poja = function poja(blob) {
+  if (!Array.isArray(blob)) {
+    return Result.err((0, _annotate.annotate)(blob, 'Must be an array'));
+  }
+
+  return Result.ok( // NOTE: Since Flow 0.98, Array.isArray() returns $ReadOnlyArray<mixed>
+  // instead of Array<mixed>.  For rationale, see
+  // https://github.com/facebook/flow/issues/7684.  In this case, we
+  // don't want to output read-only types because it's up to the user of
+  // decoders to determine what they want to do with the decoded output.
+  // If they want to write items into the array, that's fine!
+  // The fastest way to turn a read-only array into a normal array in
+  // Javascript is to use .slice() on it, see this benchmark:
+  // http://jsben.ch/lO6C5
+  blob.slice());
+};
+/**
+ * Given an array of Result instances, loop over them all and return:
+ * - An [index, err] tuple, indicating the (index of the) first Err instance
+ *   encountered; or
+ * - a new Ok with an array of all unwrapped Ok'ed values
+ */
+
+
+exports.poja = poja;
+
+function all(items, blobs) {
+  var results = [];
+
+  for (var index = 0; index < items.length; ++index) {
+    var result = items[index];
+
+    if (result.type === 'ok') {
+      results.push(result.value);
+    } else {
+      var ann = result.error; // Rewrite the annotation to include the index information, and inject it into the original blob
+
+      var clone = [].concat(blobs);
+      clone.splice(index, 1, (0, _annotate.annotate)(ann, ann.text ? ann.text + " (at index " + index + ")" : "index " + index)); // const errValue = [];
+      // if (index > 0) {
+      //     errValue.push('...'); // TODO: make special mark, not string!
+      // }
+      // errValue.push(
+      // );
+      // if (index < iterable.length - 1) {
+      //     errValue.push('...'); // TODO: make special mark, not string!
+      // }
+
+      return Result.err((0, _annotate.annotate)(clone));
+    }
+  }
+
+  return Result.ok(results);
+}
+/**
+ * Given a T, builds a decoder that assumes an array input and returns an
+ * Array<T>.
+ */
+
+
+function members(decoder) {
+  return function (blobs) {
+    var results = blobs.map(decoder);
+    var result = all(results, blobs);
+    return result;
+  };
+}
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, given a Decoder
+ * for `T`.  Err otherwise.
+ */
+
+
+function array(decoder) {
+  return (0, _composition.compose)(poja, members(decoder));
+}
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, but will reject
+ * empty arrays.
+ */
+
+
+function nonEmptyArray(decoder) {
+  return (0, _composition.compose)(array(decoder), (0, _composition.predicate)(function (arr) {
+    return arr.length > 0;
+  }, 'Must be non-empty array'));
+}

package/core/array.js.flow

@@ -0,0 +1,103 @@
+// @flow strict
+
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
+import type { Decoder, DecodeResult } from '../_types';
+
+/**
+ * Like a "Plain Old JavaScript Object", but for arrays: "Plain Old JavaScript
+ * Array" ^_^
+ */
+export const poja: Decoder<Array<mixed>> = (blob: mixed) => {
+    if (!Array.isArray(blob)) {
+        return Result.err(annotate(blob, 'Must be an array'));
+    }
+    return Result.ok(
+        // NOTE: Since Flow 0.98, Array.isArray() returns $ReadOnlyArray<mixed>
+        // instead of Array<mixed>.  For rationale, see
+        // https://github.com/facebook/flow/issues/7684.  In this case, we
+        // don't want to output read-only types because it's up to the user of
+        // decoders to determine what they want to do with the decoded output.
+        // If they want to write items into the array, that's fine!
+        // The fastest way to turn a read-only array into a normal array in
+        // Javascript is to use .slice() on it, see this benchmark:
+        // http://jsben.ch/lO6C5
+        blob.slice(),
+    );
+};
+
+/**
+ * Given an array of Result instances, loop over them all and return:
+ * - An [index, err] tuple, indicating the (index of the) first Err instance
+ *   encountered; or
+ * - a new Ok with an array of all unwrapped Ok'ed values
+ */
+function all<T>(
+    items: $ReadOnlyArray<DecodeResult<T>>,
+    blobs: $ReadOnlyArray<mixed>,
+): DecodeResult<Array<T>> {
+    const results: Array<T> = [];
+    for (let index = 0; index < items.length; ++index) {
+        const result = items[index];
+        if (result.type === 'ok') {
+            results.push(result.value);
+        } else {
+            const ann = result.error;
+
+            // Rewrite the annotation to include the index information, and inject it into the original blob
+            const clone = [...blobs];
+            clone.splice(
+                index,
+                1,
+                annotate(
+                    ann,
+                    ann.text ? `${ann.text} (at index ${index})` : `index ${index}`,
+                ),
+            );
+
+            // const errValue = [];
+            // if (index > 0) {
+            //     errValue.push('...'); // TODO: make special mark, not string!
+            // }
+            // errValue.push(
+            // );
+            // if (index < iterable.length - 1) {
+            //     errValue.push('...'); // TODO: make special mark, not string!
+            // }
+            return Result.err(annotate(clone));
+        }
+    }
+    return Result.ok(results);
+}
+
+/**
+ * Given a T, builds a decoder that assumes an array input and returns an
+ * Array<T>.
+ */
+function members<T>(decoder: Decoder<T>): Decoder<Array<T>, Array<mixed>> {
+    return (blobs: $ReadOnlyArray<mixed>) => {
+        const results = blobs.map(decoder);
+        const result = all(results, blobs);
+        return result;
+    };
+}
+
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, given a Decoder
+ * for `T`.  Err otherwise.
+ */
+export function array<T>(decoder: Decoder<T>): Decoder<Array<T>> {
+    return compose(poja, members(decoder));
+}
+
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, but will reject
+ * empty arrays.
+ */
+export function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<Array<T>> {
+    return compose(
+        array(decoder),
+        predicate((arr) => arr.length > 0, 'Must be non-empty array'),
+    );
+}

package/core/boolean.js

@@ -0,0 +1,44 @@
+"use strict";
+
+exports.__esModule = true;
+exports.truthy = exports.numericBoolean = exports["boolean"] = void 0;
+
+var Result = _interopRequireWildcard(require("../result"));
+
+var _annotate = require("../annotate");
+
+var _composition = require("./composition");
+
+var _number = require("./number");
+
+function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
+
+function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { "default": obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj["default"] = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
+
+/**
+ * Decoder that only returns Ok for boolean inputs.  Err otherwise.
+ */
+var _boolean = function _boolean(blob) {
+  return typeof blob === 'boolean' ? Result.ok(blob) : Result.err((0, _annotate.annotate)(blob, 'Must be boolean'));
+};
+/**
+ * Decoder that returns true for all truthy values, and false otherwise.  Never fails.
+ */
+
+
+exports["boolean"] = _boolean;
+
+var truthy = function truthy(blob) {
+  return Result.ok(!!blob);
+};
+/**
+ * Decoder that only returns Ok for numeric input values representing booleans.
+ * Returns their boolean representation.  Err otherwise.
+ */
+
+
+exports.truthy = truthy;
+var numericBoolean = (0, _composition.map)(_number.number, function (n) {
+  return !!n;
+});
+exports.numericBoolean = numericBoolean;

package/core/boolean.js.flow

@@ -0,0 +1,29 @@
+// @flow strict
+
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { map } from './composition';
+import { number } from './number';
+import type { Decoder } from '../_types';
+
+/**
+ * Decoder that only returns Ok for boolean inputs.  Err otherwise.
+ */
+export const boolean: Decoder<boolean> = (blob: mixed) => {
+    return typeof blob === 'boolean'
+        ? Result.ok(blob)
+        : Result.err(annotate(blob, 'Must be boolean'));
+};
+
+/**
+ * Decoder that returns true for all truthy values, and false otherwise.  Never fails.
+ */
+export const truthy: Decoder<boolean> = (blob: mixed) => {
+    return Result.ok(!!blob);
+};
+
+/**
+ * Decoder that only returns Ok for numeric input values representing booleans.
+ * Returns their boolean representation.  Err otherwise.
+ */
+export const numericBoolean: Decoder<boolean> = map(number, (n) => !!n);