decoders 1.25.4 → 2.0.0-beta1

package/es/stdlib/object.js

@@ -0,0 +1,175 @@
+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); }
+
+import * as Result from '../result';
+import { annotate, annotateObject, merge, updateText } from '../annotate';
+import { compose, map } from './composition';
+
+function isPojo(o) {
+  return o !== null && o !== undefined && typeof o === 'object' && // This still seems to be the only reliable way to determine whether
+  // something is a pojo... ¯\_(ツ)_/¯
+  // $FlowFixMe[method-unbinding]
+  Object.prototype.toString.call(o) === '[object Object]';
+}
+
+function subtract(xs, ys) {
+  var result = new Set();
+  xs.forEach(function (x) {
+    if (!ys.has(x)) {
+      result.add(x);
+    }
+  });
+  return result;
+}
+
+export var pojo = function pojo(blob) {
+  return isPojo(blob) ? Result.ok( // NOTE:
+  // Since Flow 0.98, typeof o === 'object' refines to
+  //     {| +[string]: mixed |}
+  // instead of
+  //     {| [string]: mixed |}
+  //
+  // For rationale, see https://github.com/facebook/flow/issues/7685.
+  // In this case, we don't want to output a read-only version of
+  // the object 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 Object to a writeable one in ES6 seems
+  // to be to use object-spread. (Going off this benchmark:
+  // https://thecodebarbarian.com/object-assign-vs-object-spread.html)
+  _extends({}, blob)) : Result.err(annotate(blob, 'Must be an object'));
+};
+/**
+ * Given a mapping of fields-to-decoders, builds a decoder for an object type.
+ *
+ * For example, given decoders for a number and a string, we can construct an
+ * "object description" like so:
+ *
+ *   { id: number, name: string }
+ *
+ * Which is of type:
+ *
+ *   { id: Decoder<number>, name: Decoder<string> }
+ *
+ * Passing this to object() will produce the following return type:
+ *
+ *   Decoder<{ id: number, name: string }>
+ *
+ * Put simply: it'll "peel off" all of the nested Decoders, puts them together
+ * in an object, and wraps it in a Decoder<...>.
+ */
+
+export function object(mapping) {
+  var known = new Set(Object.keys(mapping));
+  return compose(pojo, function (blob) {
+    var actual = new Set(Object.keys(blob)); // At this point, "missing" will also include all fields that may
+    // validly be optional.  We'll let the underlying decoder decide and
+    // remove the key from this missing set if the decoder accepts the
+    // value.
+
+    var missing = subtract(known, actual);
+    var record = {};
+    var errors = null;
+    Object.keys(mapping).forEach(function (key) {
+      var decoder = mapping[key];
+      var rawValue = blob[key];
+      var result = decoder(rawValue);
+
+      if (result.type === 'ok') {
+        var value = result.value;
+
+        if (value !== undefined) {
+          record[key] = value;
+        } // If this succeeded, remove the key from the missing keys
+        // tracker
+
+
+        missing["delete"](key);
+      } else {
+        var ann = result.error; // Keep track of the annotation, but don't return just yet. We
+        // want to collect more error information.
+
+        if (rawValue === undefined) {
+          // Explicitly add it to the missing set if the value is
+          // undefined.  This covers explicit undefineds to be
+          // treated the same as implicit undefineds (aka missing
+          // keys).
+          missing.add(key);
+        } else {
+          if (errors === null) {
+            errors = {};
+          }
+
+          errors[key] = ann;
+        }
+      }
+    }); // Deal with errors now. There are two classes of errors we want to
+    // report.  First of all, we want to report any inline errors in this
+    // object.  Lastly, any fields that are missing should be annotated on
+    // the outer object itself.
+
+    if (errors || missing.size > 0) {
+      var objAnn = annotateObject(blob);
+
+      if (errors) {
+        objAnn = merge(objAnn, errors);
+      }
+
+      if (missing.size > 0) {
+        var errMsg = Array.from(missing).map(function (key) {
+          return "\"" + key + "\"";
+        }).join(', ');
+        var pluralized = missing.size > 1 ? 'keys' : 'key';
+        objAnn = updateText(objAnn, "Missing " + pluralized + ": " + errMsg);
+      }
+
+      return Result.err(objAnn);
+    }
+
+    return Result.ok(record);
+  });
+}
+export function exact(mapping) {
+  // Check the inputted object for any superfluous keys
+  var allowed = new Set(Object.keys(mapping));
+  var checked = compose(pojo, function (blob) {
+    var actual = new Set(Object.keys(blob));
+    var superfluous = subtract(actual, allowed);
+
+    if (superfluous.size > 0) {
+      return Result.err(annotate(blob, "Superfluous keys: " + Array.from(superfluous).join(', ')));
+    }
+
+    return Result.ok(blob);
+  }); // Defer to the "object" decoder for doing the real decoding work.  Since
+  // we made sure there are no superfluous keys in this structure, it's now
+  // safe to force-cast it to an $Exact<> type.
+
+  var decoder = object(mapping);
+  return compose(checked, decoder);
+}
+export function inexact(mapping) {
+  return compose(pojo, function (blob) {
+    var allkeys = new Set(Object.keys(blob));
+    var decoder = map(object(mapping), function (safepart) {
+      var safekeys = new Set(Object.keys(mapping)); // To account for hard-coded keys that aren't part of the input
+
+      safekeys.forEach(function (k) {
+        return allkeys.add(k);
+      });
+      var rv = {};
+      allkeys.forEach(function (k) {
+        if (safekeys.has(k)) {
+          var value = safepart[k];
+
+          if (value !== undefined) {
+            rv[k] = value;
+          }
+        } else {
+          rv[k] = blob[k];
+        }
+      });
+      return rv;
+    });
+    return decoder(blob);
+  });
+}

package/es/stdlib/optional.js

@@ -0,0 +1,38 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { either } from './either';
+import { null_, undefined_ } from './constants';
+
+/**
+ * Builds a Decoder that returns Ok for either `undefined` or `T` values,
+ * given a Decoder for `T`.  Err otherwise.
+ */
+export function optional(decoder) {
+  return either(undefined_, decoder);
+}
+/**
+ * Builds a Decoder that returns Ok for either `null` or `T` values,
+ * given a Decoder for `T`.  Err otherwise.
+ */
+
+export function nullable(decoder) {
+  return either(null_, decoder);
+}
+/**
+ * Decoder that only returns Ok for `null` or `undefined` inputs.
+ * This is effectively equivalent to either(null_, undefined_), but combines
+ * their error message output into a single line for convenience.
+ */
+
+var undefined_or_null = function undefined_or_null(blob) {
+  return blob === undefined || blob === null ? Result.ok(blob) : // Combine error message into a single line
+  Result.err(annotate(blob, 'Must be undefined or null'));
+};
+/**
+ * Decoder that only returns Ok for `null` or `undefined` inputs.
+ */
+
+
+export function maybe(decoder) {
+  return either(undefined_or_null, decoder);
+}

package/{string.js → es/stdlib/string.js}

@@ -1,17 +1,6 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.nonEmptyString = exports.email = void 0;
-exports.regex = regex;
-exports.url = exports.string = void 0;
-
-var _debrief = require("debrief");
-
-var _Result = require("lemons/Result");
-
-var _utils = require("./utils");
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
 
 /** Match groups in this regex:
  * \1 - the scheme
@@ -27,26 +16,22 @@ var DEFAULT_SCHEMES = ['https'];
  * Decoder that only returns Ok for string inputs.  Err otherwise.
  */
 
-var string = function string(blob) {
-  return typeof blob === 'string' ? (0, _Result.Ok)(blob) : (0, _Result.Err)((0, _debrief.annotate)(blob, 'Must be string'));
+export var string = function string(blob) {
+  return typeof blob === 'string' ? Result.ok(blob) : Result.err(annotate(blob, 'Must be string'));
 };
 /**
  * Decoder that only returns Ok for non-empty string inputs.  Err otherwise.
  */
 
-
-exports.string = string;
-var nonEmptyString = regex(/\S/, 'Must be non-empty string');
+export var nonEmptyString = regex(/\S/, 'Must be non-empty string');
 /**
  * Decoder that only returns Ok for string inputs that match the regular
  * expression.  Err otherwise.  Will always validate that the input is a string
  * before testing the regex.
  */
 
-exports.nonEmptyString = nonEmptyString;
-
-function regex(regex, msg) {
-  return (0, _utils.compose)(string, (0, _utils.predicate)(function (s) {
+export function regex(regex, msg) {
+  return compose(string, predicate(function (s) {
     return regex.test(s);
   }, msg));
 }
@@ -55,8 +40,7 @@ function regex(regex, msg) {
  * email regex, taken from http://emailregex.com.  Err otherwise.
  */
 
-
-var email = regex(/^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/, 'Must be email');
+export var email = regex(/^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/, 'Must be email');
 /**
  * Decoder that only returns Ok for string inputs that match URLs of the
  * expected scheme.  Defaults to only accept HTTPS URLs.  Err otherwise.
@@ -69,25 +53,24 @@ var email = regex(/^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@(
  * - url(['https', 'git+ssh'])  accepts both https:// and git+ssh:// URLs
  */
 
-exports.email = email;
+export var url = function url(schemes) {
+  if (schemes === void 0) {
+    schemes = DEFAULT_SCHEMES;
+  }
 
-var url = function url() {
-  var schemes = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : DEFAULT_SCHEMES;
-  return (0, _utils.compose)(string, function (value) {
+  return compose(string, function (value) {
     var matches = value.match(url_re);
 
     if (!matches) {
-      return (0, _Result.Err)((0, _debrief.annotate)(value, 'Must be URL'));
+      return Result.err(annotate(value, 'Must be URL'));
     } else {
       var scheme = matches[1];
 
       if (schemes.length === 0 || schemes.includes(scheme.toLowerCase())) {
-        return (0, _Result.Ok)(value);
+        return Result.ok(value);
       } else {
-        return (0, _Result.Err)((0, _debrief.annotate)(value, "URL scheme must be any of: ".concat(schemes.join(', '))));
+        return Result.err(annotate(value, "URL scheme must be any of: " + schemes.join(', ')));
       }
     }
   });
-};
-
-exports.url = url;
+};

package/es/stdlib/tuple.js

@@ -0,0 +1,155 @@
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
+import { err, errValue, isErr, ok, unwrap, value } from '../result';
+import { poja } from './array';
+
+var ntuple = function ntuple(n) {
+  return compose(poja, predicate(function (arr) {
+    return arr.length === n;
+  }, "Must be a " + n + "-tuple"));
+};
+/**
+ * Builds a Decoder that returns Ok for 1-tuple of [T], given a Decoder for T.
+ * Err otherwise.
+ */
+
+
+export function tuple1(decoder1) {
+  return compose(ntuple(1), function (blobs) {
+    var blob1 = blobs[0];
+    var result1 = decoder1(blob1);
+
+    try {
+      return ok([unwrap(result1)]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return err(annotate(errValue(result1)));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 2-tuples of [T1, T2], given Decoders
+ * for T1 and T2.  Err otherwise.
+ */
+
+export function tuple2(decoder1, decoder2) {
+  return compose(ntuple(2), function (blobs) {
+    var blob1 = blobs[0],
+        blob2 = blobs[1];
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+
+    try {
+      return ok([unwrap(result1), unwrap(result2)]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2)]));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 3-tuples of [T1, T2, T3], given
+ * Decoders for T1, T2, and T3.  Err otherwise.
+ */
+
+export function tuple3(decoder1, decoder2, decoder3) {
+  return compose(ntuple(3), function (blobs) {
+    var blob1 = blobs[0],
+        blob2 = blobs[1],
+        blob3 = blobs[2];
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+    var result3 = decoder3(blob3);
+
+    try {
+      return ok([unwrap(result1), unwrap(result2), unwrap(result3)]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2), isErr(result3) ? errValue(result3) : value(result3)]));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 4-tuples of [T1, T2, T3, T4], given
+ * Decoders for T1, T2, T3, and T4.  Err otherwise.
+ */
+
+export function tuple4(decoder1, decoder2, decoder3, decoder4) {
+  return compose(ntuple(4), function (blobs) {
+    var blob1 = blobs[0],
+        blob2 = blobs[1],
+        blob3 = blobs[2],
+        blob4 = blobs[3];
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+    var result3 = decoder3(blob3);
+    var result4 = decoder4(blob4);
+
+    try {
+      return ok([unwrap(result1), unwrap(result2), unwrap(result3), unwrap(result4)]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2), isErr(result3) ? errValue(result3) : value(result3), isErr(result4) ? errValue(result4) : value(result4)]));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 5-tuples of [T1, T2, T3, T4, T5], given
+ * Decoders for T1, T2, T3, T4, and T5.  Err otherwise.
+ */
+
+export function tuple5(decoder1, decoder2, decoder3, decoder4, decoder5) {
+  return compose(ntuple(5), function (blobs) {
+    var blob1 = blobs[0],
+        blob2 = blobs[1],
+        blob3 = blobs[2],
+        blob4 = blobs[3],
+        blob5 = blobs[4];
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+    var result3 = decoder3(blob3);
+    var result4 = decoder4(blob4);
+    var result5 = decoder5(blob5);
+
+    try {
+      return ok([unwrap(result1), unwrap(result2), unwrap(result3), unwrap(result4), unwrap(result5)]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2), isErr(result3) ? errValue(result3) : value(result3), isErr(result4) ? errValue(result4) : value(result4), isErr(result5) ? errValue(result5) : value(result5)]));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 5-tuples of [T1, T2, T3, T4, T5], given
+ * Decoders for T1, T2, T3, T4, T5, and T6.  Err otherwise.
+ */
+
+export function tuple6(decoder1, decoder2, decoder3, decoder4, decoder5, decoder6) {
+  return compose(ntuple(6), function (blobs) {
+    var blob1 = blobs[0],
+        blob2 = blobs[1],
+        blob3 = blobs[2],
+        blob4 = blobs[3],
+        blob5 = blobs[4],
+        blob6 = blobs[5];
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+    var result3 = decoder3(blob3);
+    var result4 = decoder4(blob4);
+    var result5 = decoder5(blob5);
+    var result6 = decoder6(blob6);
+
+    try {
+      return ok([unwrap(result1), unwrap(result2), unwrap(result3), unwrap(result4), unwrap(result5), unwrap(result6)]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2), isErr(result3) ? errValue(result3) : value(result3), isErr(result4) ? errValue(result4) : value(result4), isErr(result5) ? errValue(result5) : value(result5), isErr(result6) ? errValue(result6) : value(result6)]));
+    }
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decoders",
-    "version": "1.25.4",
+    "version": "2.0.0-beta1",
     "description": "Elegant and battle-tested validation library for type-safe input data (for TypeScript and Flow)",
     "license": "MIT",
     "repository": {
@@ -12,7 +12,16 @@
     "bugs": {
         "url": "https://github.com/nvie/decoders/issues"
     },
-    "main": "./index.js",
+    "main": "./cjs/index.js",
+    "module": "./es/index.js",
+    "type": "module",
+    "exports": {
+        "require": "./cjs/index.js",
+        "import": "./es/index.js"
+    },
+    "engines": {
+        "node": ">=12"
+    },
     "keywords": [
         "decoder",
         "decoders",
@@ -39,11 +48,7 @@
         "map",
         "predicate"
     ],
-    "dependencies": {
-        "debrief": "^1.5.0",
-        "lemons": "^1.4.0"
-    },
-    "types": "./index.d.ts",
+    "types": "./ts/index.d.ts",
     "githubUrl": "https://github.com/nvie/decoders",
     "sideEffects": false
 }

package/ts/_guard.d.ts

@@ -0,0 +1,7 @@
+import { Annotation } from './annotate';
+import { Decoder, Guard } from './_types';
+
+export function guard<T>(
+    decoder: Decoder<T>,
+    formatter?: (annotation: Annotation) => string,
+): Guard<T>;

package/ts/_helpers.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Given a type like:
+ *
+ *   {
+ *     a: string;
+ *     b: number | undefined;
+ *     c: null | undefined;
+ *     d: null;
+ *     e: undefined;
+ *   }
+ *
+ * Will drop all the "undefined" types. In this case, only "e":
+ *
+ *   {
+ *     a: string;
+ *     b: number | undefined;
+ *     c: null | undefined;
+ *     d: null;
+ *   }
+ *
+ */
+type Compact<T> = { [K in IsDefined<T, keyof T>]: T[K] };
+
+type IsDefined<T, K extends keyof T> = K extends any
+    ? T[K] extends undefined
+        ? never
+        : K
+    : never;
+
+//
+// HACK:
+// These weird conditionals test whether TypeScript is configured with the
+// `strictNullChecks` compiler option. We use these definitions to influence
+// what's considered a "required" vs an "optional" key for the AllowImplicit
+// type.
+//
+// If strictNullChecks is false, then we should not be emitting any `?` fields
+// and consider all fields "required" because everything is optional by default
+// in that mode anyway.
+//
+type NoStrictNullChecks = undefined extends string ? 1 : undefined;
+//                        ^^^^^^^^^^^^^^^^^^^^^^^^
+type StrictNullChecks = undefined extends string ? undefined : 1;
+//                      ^^^^^^^^^^^^^^^^^^^^^^^^
+
+export type RequiredKeys<T> = keyof Compact<{
+    [K in keyof T]: undefined extends T[K] ? NoStrictNullChecks : 1;
+}>;
+
+export type OptionalKeys<T> = keyof Compact<{
+    [K in keyof T]: undefined extends T[K] ? 1 : StrictNullChecks;
+}>;
+
+/**
+ * Transforms an object type, by marking all fields that contain "undefined"
+ * with a question mark, i.e. allowing implicit-undefineds when
+ * explicit-undefined are also allowed.
+ *
+ * For example, if:
+ *
+ *   type User = {
+ *     name: string;
+ *     age: number | null | undefined;
+ *   }
+ *
+ * Then AllowImplicit<User> will become equivalent to:
+ *
+ *   {
+ *     name: string;
+ *     age?: number | null;
+ *        ^
+ *        Note the question mark
+ *   }
+ */
+type AllowImplicit<T> = { [K in RequiredKeys<T>]-?: T[K] } & {
+    [K in OptionalKeys<T>]+?: Exclude<T[K], undefined>;
+};
+
+export { AllowImplicit };

package/{types.d.ts → ts/_types.d.ts}

@@ -1,5 +1,5 @@
-import { Annotation } from 'debrief';
-import Result from 'lemons/Result';
+import { Annotation } from './annotate';
+import { Result } from './result';
 
 export type Scalar = string | number | boolean | symbol | undefined | null;
 
@@ -7,12 +7,10 @@ export interface Guard<T> {
     (blob: unknown): T;
 }
 export type Predicate<T> = (value: T) => boolean;
-export type DecodeResult<T> = Result<Annotation, T>;
+export type DecodeResult<T> = Result<T, Annotation>;
 export interface Decoder<T, F = unknown> {
     (blob: F): DecodeResult<T>;
 }
 
 export type DecoderType<T> = T extends Decoder<infer V> ? V : never;
-export type $DecoderType<T> = DecoderType<T>; // Alias for backward compatibility
-
 export type GuardType<T> = T extends Guard<infer V> ? V : never;

package/{utils.d.ts → ts/_utils.d.ts}

@@ -1,13 +1,13 @@
-import { Decoder } from './types';
+import { Decoder } from './_types';
 
 export function isDate(value: unknown): boolean;
 export function map<T, V>(decoder: Decoder<T>, mapper: (value: T) => V): Decoder<V>;
 export function compose<T, V>(decoder: Decoder<T>, next: Decoder<V, T>): Decoder<V>;
 export function predicate<T extends F, F = unknown>(
     predicate: (value: F) => value is T,
-    msg: string
+    msg: string,
 ): Decoder<T, F>;
 export function predicate<T>(
     predicate: (value: T) => boolean,
-    msg: string
+    msg: string,
 ): Decoder<T, T>;

package/ts/annotate.d.ts

@@ -0,0 +1,58 @@
+export interface ObjectAnnotation {
+    type: 'object';
+    fields: { [key: string]: Annotation };
+    text?: string;
+}
+
+export interface ArrayAnnotation {
+    type: 'array';
+    items: readonly Annotation[];
+    text?: string;
+}
+
+export interface ScalarAnnotation {
+    type: 'scalar';
+    value: unknown;
+    text?: string;
+}
+
+export interface FunctionAnnotation {
+    type: 'function';
+    text?: string;
+}
+
+export interface CircularRefAnnotation {
+    type: 'circular-ref';
+    text?: string;
+}
+
+export type Annotation =
+    | ObjectAnnotation
+    | ArrayAnnotation
+    | ScalarAnnotation
+    | FunctionAnnotation
+    | CircularRefAnnotation;
+
+export function object(
+    fields: { [key: string]: Annotation },
+    text?: string,
+): ObjectAnnotation;
+export function array(items: readonly Annotation[], text?: string): ArrayAnnotation;
+export function func(text?: string): FunctionAnnotation;
+export function scalar(value: unknown, text?: string): ScalarAnnotation;
+export function circularRef(text?: string): CircularRefAnnotation;
+
+export function updateText<A extends Annotation>(annotation: A, text?: string): A;
+
+export function merge(
+    objAnnotation: ObjectAnnotation,
+    fields: { [key: string]: Annotation },
+): ObjectAnnotation;
+
+export function asAnnotation(thing: unknown): Annotation | void;
+
+export function annotate(value: unknown, text?: string): Annotation;
+export function annotateObject(
+    obj: { [key: string]: unknown },
+    text?: string,
+): ObjectAnnotation;