decoders 1.25.5 → 2.0.0-beta2

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## v2.0.0-beta
+
+Potentially breaking changes:
+
+-   Drop support for all Node versions below 12.x
+-   Drop support for Flow versions below 0.142.0
+-   Drop all package dependencies
+
+New features:
+
+-   Include ES modules in published NPM builds (yay tree-shaking! 🍃)
+-   Much smaller total bundle size
+-   Better error messages for nested `either`s
+-   Guard API now has a simpler way to specify formatters
+
+Implementation changes:
+
+-   Major reorganization of internal module structure
+-   Various simplification of internals
+
 ## v1.25.5
 
 -   Fix compatibility issue with TypeScript projects configured with
@@ -322,7 +342,7 @@ to upgrade:
     ```javascript
     const mydecoder: Decoder<string> = predicate(
         (s) => s.startsWith('x'),
-        'Must start with "x"'
+        'Must start with "x"',
     );
     ```
 
@@ -332,7 +352,7 @@ to upgrade:
     const mydecoder: Decoder<string, string> = predicate(
         //                               ^^^^^^ Provide the input type to predicate() decoders
         (s) => s.startsWith('x'),
-        'Must start with "x"'
+        'Must start with "x"',
     );
     ```
 
@@ -556,6 +576,6 @@ to upgrade:
         object({
             name: string,
             age: number,
-        })
+        }),
     );
     ```

package/_esm/_guard.js

@@ -0,0 +1,15 @@
+import * as Result from './result';
+import { formatInline } from './format';
+export function guard(decoder, formatter) {
+  if (formatter === void 0) {
+    formatter = formatInline;
+  }
+
+  return function (blob) {
+    return Result.unwrap(Result.mapError(decoder(blob), function (annotation) {
+      var err = new Error('\n' + formatter(annotation));
+      err.name = 'Decoding error';
+      return err;
+    }));
+  };
+}

package/_esm/_guard.js.flow

@@ -0,0 +1,20 @@
+// @flow strict
+
+import * as Result from './result';
+import { formatInline } from './format';
+import type { Annotation } from './annotate';
+import type { Decoder, Guard } from './_types';
+
+export function guard<T>(
+    decoder: Decoder<T>,
+    formatter: (Annotation) => string = formatInline,
+): Guard<T> {
+    return (blob: mixed) =>
+        Result.unwrap(
+            Result.mapError(decoder(blob), (annotation) => {
+                const err = new Error('\n' + formatter(annotation));
+                err.name = 'Decoding error';
+                return err;
+            }),
+        );
+}

package/_esm/_types.js.flow

@@ -0,0 +1,20 @@
+// @flow strict
+
+import type { Annotation } from './annotate';
+import type { Result } from './result';
+
+export type Scalar = string | number | boolean | symbol | void | null;
+
+export type Predicate<T> = (T) => boolean;
+export type DecodeResult<T> = Result<T, Annotation>;
+
+export type Decoder<T, F = mixed> = (F) => DecodeResult<T>;
+export type Guard<T> = (mixed) => T;
+
+/**
+ * A "type function" which informs Flow about how a type will be modified at runtime.
+ * Read this as "given a Guard of type T, I can produce a value of type T".  This
+ * definition helps construct $ObjMap types.
+ */
+export type DecoderType = <T>(Decoder<T>) => T;
+export type GuardType = <T>(Guard<T>) => T;

package/_esm/_utils.js

@@ -0,0 +1,93 @@
+// $FlowFixMe[unclear-type] - deliberate casting
+// Two spaces of indentation
+export var INDENT = '  ';
+/**
+ * `x instanceof Date` checks are unreliable across stack frames (that information
+ * might get lost by the JS runtime), so we'll have to reside to more runtime
+ * inspection checks.
+ *
+ * Taken from https://stackoverflow.com/a/44198641
+ */
+
+export function isDate(value) {
+  return !!value && // $FlowFixMe[method-unbinding]
+  Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value);
+}
+/**
+ * Is value is a valid Date instance, then return that.  If not, then return
+ * null.
+ */
+
+export function asDate(value) {
+  return isDate(value) ? value : null;
+}
+export function isMultiline(s) {
+  return s.indexOf('\n') >= 0;
+}
+export function indent(s, prefix) {
+  if (prefix === void 0) {
+    prefix = INDENT;
+  }
+
+  if (isMultiline(s)) {
+    return s.split('\n').map(function (line) {
+      return prefix + line;
+    }).join('\n');
+  } else {
+    return prefix + s;
+  }
+}
+/**
+ * Walks the annotation tree and emits the annotation's key path within the
+ * object tree, and the message as a series of messages (array of strings).
+ */
+
+export function summarize(ann, keypath) {
+  if (keypath === void 0) {
+    keypath = [];
+  }
+
+  var result = [];
+
+  if (ann.type === 'array') {
+    var items = ann.items;
+    var index = 0;
+    items.forEach(function (ann) {
+      summarize(ann, [].concat(keypath, [index++])).forEach(function (item) {
+        return (// Collect to results
+          result.push(item)
+        );
+      });
+    });
+  } else if (ann.type === 'object') {
+    var fields = ann.fields;
+    Object.keys(fields).forEach(function (key) {
+      var value = fields[key];
+      summarize(value, [].concat(keypath, [key])).forEach(function (item) {
+        return (// Collect to results
+          result.push(item)
+        );
+      });
+    });
+  }
+
+  var text = ann.text;
+
+  if (!text) {
+    return result;
+  }
+
+  var prefix;
+
+  if (keypath.length === 0) {
+    prefix = '';
+  } else if (keypath.length === 1) {
+    prefix = typeof keypath[0] === 'number' ? "Value at index " + keypath[0] + ": " : "Value at key " + JSON.stringify(keypath[0]) + ": ";
+  } else {
+    prefix = "Value at keypath " + keypath.map(function (x) {
+      return x.toString();
+    }).join('.') + ": ";
+  }
+
+  return [].concat(result, [prefix + text]);
+}

package/_esm/_utils.js.flow

@@ -0,0 +1,97 @@
+// @flow strict
+
+import type { Annotation } from './annotate';
+
+// $FlowFixMe[unclear-type] - deliberate casting
+type cast = any;
+
+// Two spaces of indentation
+export const INDENT = '  ';
+
+/**
+ * `x instanceof Date` checks are unreliable across stack frames (that information
+ * might get lost by the JS runtime), so we'll have to reside to more runtime
+ * inspection checks.
+ *
+ * Taken from https://stackoverflow.com/a/44198641
+ */
+export function isDate(value: mixed): boolean {
+    return (
+        !!value &&
+        // $FlowFixMe[method-unbinding]
+        Object.prototype.toString.call(value) === '[object Date]' &&
+        !isNaN(value)
+    );
+}
+
+/**
+ * Is value is a valid Date instance, then return that.  If not, then return
+ * null.
+ */
+export function asDate(value: mixed): Date | null {
+    return isDate(value) ? ((value: cast): Date) : null;
+}
+
+export function isMultiline(s: string): boolean {
+    return s.indexOf('\n') >= 0;
+}
+
+export function indent(s: string, prefix: string = INDENT): string {
+    if (isMultiline(s)) {
+        return s
+            .split('\n')
+            .map((line) => prefix + line)
+            .join('\n');
+    } else {
+        return prefix + s;
+    }
+}
+
+/**
+ * Walks the annotation tree and emits the annotation's key path within the
+ * object tree, and the message as a series of messages (array of strings).
+ */
+export function summarize(
+    ann: Annotation,
+    keypath: $ReadOnlyArray<number | string> = [],
+): Array<string> {
+    const result: Array<string> = [];
+
+    if (ann.type === 'array') {
+        const items = ann.items;
+        let index = 0;
+        items.forEach((ann) => {
+            summarize(ann, [...keypath, index++]).forEach((item) =>
+                // Collect to results
+                result.push(item),
+            );
+        });
+    } else if (ann.type === 'object') {
+        const fields = ann.fields;
+        Object.keys(fields).forEach((key) => {
+            const value = fields[key];
+            summarize(value, [...keypath, key]).forEach((item) =>
+                // Collect to results
+                result.push(item),
+            );
+        });
+    }
+
+    const text = ann.text;
+    if (!text) {
+        return result;
+    }
+
+    let prefix: string;
+    if (keypath.length === 0) {
+        prefix = '';
+    } else if (keypath.length === 1) {
+        prefix =
+            typeof keypath[0] === 'number'
+                ? `Value at index ${keypath[0]}: `
+                : `Value at key ${JSON.stringify(keypath[0])}: `;
+    } else {
+        prefix = `Value at keypath ${keypath.map((x) => x.toString()).join('.')}: `;
+    }
+    return [...result, prefix + text];
+}

package/_esm/annotate.js

@@ -0,0 +1,144 @@
+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;
+}
+
+export function object(fields, text) {
+  return brand({
+    type: 'object',
+    fields: fields,
+    text: text
+  });
+}
+export function array(items, text) {
+  return brand({
+    type: 'array',
+    items: items,
+    text: text
+  });
+}
+export function func(text) {
+  return brand({
+    type: 'function',
+    text: text
+  });
+}
+export function unknown(value, text) {
+  return brand({
+    type: 'unknown',
+    value: value,
+    text: text
+  });
+}
+export function scalar(value, text) {
+  return brand({
+    type: 'scalar',
+    value: value,
+    text: text
+  });
+}
+export function circularRef(text) {
+  return brand({
+    type: 'circular-ref',
+    text: text
+  });
+}
+/**
+ * Given an existing Annotation, set the annotation's text to a new value.
+ */
+
+export 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.
+ */
+
+export function merge(objAnnotation, fields) {
+  var newFields = _extends({}, objAnnotation.fields, fields);
+
+  return object(newFields, objAnnotation.text);
+}
+export 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());
+}
+
+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/_esm/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,
+};