Simplify annotation internals a bit

Author: nvie

src/core/annotate.ts

@@ -20,29 +20,17 @@ export interface ScalarAnnotation {
   readonly text?: string;
 }
 
-export interface FunctionAnnotation {
-  readonly type: 'function';
-  readonly text?: string;
-}
-
-export interface CircularRefAnnotation {
-  readonly type: 'circular-ref';
-  readonly text?: string;
-}
-
-export interface UnknownAnnotation {
-  readonly type: 'unknown';
-  readonly value: unknown;
+export interface OpaqueAnnotation {
+  readonly type: 'opaque';
+  readonly value: string; // e.g. '???' | '<function>' | '<circular ref>'
   readonly text?: string;
 }
 
 export type Annotation =
   | ObjectAnnotation
   | ArrayAnnotation
   | ScalarAnnotation
-  | FunctionAnnotation
-  | CircularRefAnnotation
-  | UnknownAnnotation;
+  | OpaqueAnnotation;
 
 /** @internal */
 function brand<A extends Annotation>(ann: A): A {
@@ -67,25 +55,15 @@ export function makeArrayAnn(
 }
 
 /** @internal */
-export function makeFunctionAnn(text?: string): FunctionAnnotation {
-  return brand({ type: 'function', text });
-}
-
-/** @internal */
-export function makeUnknownAnn(value: unknown, text?: string): UnknownAnnotation {
-  return brand({ type: 'unknown', value, text });
+export function makeOpaqueAnn(value: string, text?: string): OpaqueAnnotation {
+  return brand({ type: 'opaque', value, text });
 }
 
 /** @internal */
 export function makeScalarAnn(value: unknown, text?: string): ScalarAnnotation {
   return brand({ type: 'scalar', value, text });
 }
 
-/** @internal */
-export function makeCircularRefAnn(text?: string): CircularRefAnnotation {
-  return brand({ type: 'circular-ref', text });
-}
-
 /**
  * @internal
  * Given an existing Annotation, set the annotation's text to a new value.
@@ -122,7 +100,7 @@ function annotateArray(
   arr: readonly unknown[],
   text: string | undefined,
   seen: RefSet,
-): ArrayAnnotation | CircularRefAnnotation {
+): ArrayAnnotation | OpaqueAnnotation {
   seen.add(arr);
 
   // Cannot use .map() here because it won't work correctly if `arr` is
@@ -171,7 +149,7 @@ function annotate(value: unknown, text: string | undefined, seen: RefSet): Annot
   if (Array.isArray(value)) {
     // "Circular references" can only exist in objects or arrays
     if (seen.has(value)) {
-      return makeCircularRefAnn(text);
+      return makeOpaqueAnn('<circular ref>', text);
     } else {
       return annotateArray(value, text, seen);
     }
@@ -180,17 +158,17 @@ function annotate(value: unknown, text: string | undefined, seen: RefSet): Annot
   if (isPojo(value)) {
     // "Circular references" can only exist in objects or arrays
     if (seen.has(value)) {
-      return makeCircularRefAnn(text);
+      return makeOpaqueAnn('<circular ref>', text);
     } else {
       return annotateObject(value, text, seen);
     }
   }
 
   if (typeof value === 'function') {
-    return makeFunctionAnn(text);
+    return makeOpaqueAnn('<function>', text);
   }
 
-  return makeUnknownAnn(value, text);
+  return makeOpaqueAnn('???', text);
 }
 
 function public_annotate(value: unknown, text?: string): Annotation {

src/core/format.ts

@@ -1,7 +1,12 @@
 import { INDENT, indent, isMultiline, quote } from '~/lib/text';
 import { isDate } from '~/lib/utils';
 
-import type { Annotation, ArrayAnnotation, ObjectAnnotation } from './annotate';
+import type {
+  Annotation,
+  ArrayAnnotation,
+  ObjectAnnotation,
+  OpaqueAnnotation,
+} from './annotate';
 
 export type Formatter = (err: Annotation) => string | Error;
 
@@ -138,19 +143,17 @@ export function serializeAnnotation(
   prefix: string = '',
 ): [string, string | undefined] {
   // The serialized data (the input object echoed back)
-  let serialized;
+  let serialized: string;
+
   if (ann.type === 'array') {
     serialized = serializeArray(ann, prefix);
   } else if (ann.type === 'object') {
     serialized = serializeObject(ann, prefix);
-  } else if (ann.type === 'function') {
-    serialized = '<function>';
-  } else if (ann.type === 'circular-ref') {
-    serialized = '<circular ref>';
-  } else if (ann.type === 'unknown') {
-    serialized = '???';
-  } else {
+  } else if (ann.type === 'scalar') {
     serialized = serializeValue(ann.value);
+  } else {
+    ((_: OpaqueAnnotation) => {})(ann); // Serves as an exhaustiveness check
+    serialized = ann.value;
   }
 
   const text = ann.text;

test/core/annotate.test.ts

@@ -4,7 +4,7 @@ import type { Annotation, ObjectAnnotation } from '~/core/annotate';
 import {
   annotate,
   makeArrayAnn,
-  makeCircularRefAnn,
+  makeOpaqueAnn,
   makeObjectAnn as makeObjectAnnOriginal,
   makeScalarAnn,
   merge as mergeOriginal,
@@ -153,7 +153,7 @@ describe('annotating circular objects', () => {
 
     const expected = makeArrayAnn([
       makeScalarAnn('foo'),
-      makeArrayAnn([makeScalarAnn(42), makeCircularRefAnn()]),
+      makeArrayAnn([makeScalarAnn(42), makeOpaqueAnn('<circular ref>')]),
     ]);
 
     expect(annotate(circularArray)).toEqual(expected);
@@ -174,9 +174,9 @@ describe('annotating circular objects', () => {
       foo: makeScalarAnn(42),
       bar: makeObjectAnn({
         qux: makeScalarAnn('hello'),
-        self: makeCircularRefAnn(),
+        self: makeOpaqueAnn('<circular ref>'),
       }),
-      self: makeCircularRefAnn(),
+      self: makeOpaqueAnn('<circular ref>'),
     });
 
     expect(annotate(circularObject)).toEqual(expected);