feat: Add a toJS(doc, options?) method to nodes (#451)

.eslintrc.yaml

@@ -50,9 +50,6 @@ overrides:
     rules:
       camelcase: 0
       '@typescript-eslint/no-non-null-assertion': off
-      '@typescript-eslint/no-unsafe-return': off
-
-  - files: [tests/doc/**]
-    rules:
       '@typescript-eslint/no-unsafe-call': off
+      '@typescript-eslint/no-unsafe-return': off
       '@typescript-eslint/unbound-method': off

docs/03_options.md

@@ -119,7 +119,7 @@ parse('{[1, 2]: many}', { mapAsMap: true }) // Map { [ 1, 2 ] => 'many' }
 
 These options influence how the document is transformed into "native" JavaScript representation.
 
-Used by: `parse()` and `doc.toJS()`
+Used by: `parse()`, `doc.toJS()` and `node.toJS()`
 
 | Name          | Type                                  | Default | Description                                                                                                                                         |
 | ------------- | ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |

docs/05_content_nodes.md

@@ -21,7 +21,8 @@ class NodeBase {
       // a blank line before this node and its commentBefore
   tag?: string       // a fully qualified tag, if required
   clone(): NodeBase  // a copy of this node
-  toJSON(): any      // a plain JS or JSON representation of this node
+  toJS(doc, options?): any // a plain JS representation of this node
+  toJSON(): any      // a plain JSON representation of this node
 }
 ```
 

src/compose/compose-collection.ts

@@ -1,4 +1,5 @@
-import { isMap, isNode, ParsedNode } from '../nodes/Node.js'
+import { isMap, isNode } from '../nodes/identity.js'
+import type { ParsedNode } from '../nodes/Node.js'
 import { Scalar } from '../nodes/Scalar.js'
 import type { YAMLMap } from '../nodes/YAMLMap.js'
 import type { YAMLSeq } from '../nodes/YAMLSeq.js'

src/compose/compose-scalar.ts

@@ -1,4 +1,4 @@
-import { isScalar, SCALAR } from '../nodes/Node.js'
+import { isScalar, SCALAR } from '../nodes/identity.js'
 import { Scalar } from '../nodes/Scalar.js'
 import type { BlockScalar, FlowScalar, SourceToken } from '../parse/cst.js'
 import type { Schema } from '../schema/Schema.js'

src/compose/composer.ts

@@ -1,7 +1,8 @@
 import { Directives } from '../doc/directives.js'
 import { Document } from '../doc/Document.js'
 import { ErrorCode, YAMLParseError, YAMLWarning } from '../errors.js'
-import { isCollection, isPair, ParsedNode, Range } from '../nodes/Node.js'
+import { isCollection, isPair } from '../nodes/identity.js'
+import type { ParsedNode, Range } from '../nodes/Node.js'
 import type {
   DocumentOptions,
   ParseOptions,

src/compose/resolve-flow-collection.ts

@@ -1,4 +1,4 @@
-import { isPair } from '../nodes/Node.js'
+import { isPair } from '../nodes/identity.js'
 import { Pair } from '../nodes/Pair.js'
 import { YAMLMap } from '../nodes/YAMLMap.js'
 import { YAMLSeq } from '../nodes/YAMLSeq.js'

src/compose/util-map-includes.ts

@@ -1,6 +1,7 @@
-import { isScalar, ParsedNode } from '../nodes/Node'
-import { Pair } from '../nodes/Pair'
-import { ComposeContext } from './compose-node'
+import { isScalar } from '../nodes/identity.js'
+import type { ParsedNode } from '../nodes/Node.js'
+import type { Pair } from '../nodes/Pair.js'
+import type { ComposeContext } from './compose-node.js'
 
 export function mapIncludes(
   ctx: ComposeContext,

src/doc/Document.ts

@@ -6,12 +6,9 @@ import {
   isCollection,
   isNode,
   isScalar,
-  Node,
-  NodeType,
-  NODE_TYPE,
-  ParsedNode,
-  Range
-} from '../nodes/Node.js'
+  NODE_TYPE
+} from '../nodes/identity.js'
+import type { Node, NodeType, ParsedNode, Range } from '../nodes/Node.js'
 import { Pair } from '../nodes/Pair.js'
 import type { Scalar } from '../nodes/Scalar.js'
 import { toJS, ToJSContext } from '../nodes/toJS.js'
@@ -26,7 +23,6 @@ import type {
   ToStringOptions
 } from '../options.js'
 import { Schema } from '../schema/Schema.js'
-import { stringify } from '../stringify/stringify.js'
 import { stringifyDocument } from '../stringify/stringifyDocument.js'
 import { anchorNames, createNodeAnchors, findNewAnchor } from './anchors.js'
 import { applyReviver } from './applyReviver.js'
@@ -434,8 +430,7 @@ export class Document<
       keep: !json,
       mapAsMap: mapAsMap === true,
       mapKeyWarned: false,
-      maxAliasCount: typeof maxAliasCount === 'number' ? maxAliasCount : 100,
-      stringify
+      maxAliasCount: typeof maxAliasCount === 'number' ? maxAliasCount : 100
     }
     const res = toJS(this.contents, jsonArg ?? '', ctx)
     if (typeof onAnchor === 'function')

src/doc/anchors.ts

@@ -1,4 +1,5 @@
-import { isCollection, isScalar, Node } from '../nodes/Node.js'
+import { isCollection, isScalar } from '../nodes/identity.js'
+import type { Node } from '../nodes/Node.js'
 import type { Scalar } from '../nodes/Scalar.js'
 import type { YAMLMap } from '../nodes/YAMLMap.js'
 import type { YAMLSeq } from '../nodes/YAMLSeq.js'

src/doc/createNode.ts

@@ -1,5 +1,6 @@
 import { Alias } from '../nodes/Alias.js'
-import { isDocument, isNode, isPair, MAP, Node, SEQ } from '../nodes/Node.js'
+import { isDocument, isNode, isPair, MAP, SEQ } from '../nodes/identity.js'
+import type { Node } from '../nodes/Node.js'
 import { Scalar } from '../nodes/Scalar.js'
 import type { YAMLMap } from '../nodes/YAMLMap.js'
 import type { Schema } from '../schema/Schema.js'

src/doc/directives.ts

@@ -1,4 +1,4 @@
-import { isNode } from '../nodes/Node.js'
+import { isNode } from '../nodes/identity.js'
 import { visit } from '../visit.js'
 import type { Document } from './Document.js'
 

src/index.ts

@@ -14,11 +14,9 @@ export {
   isNode,
   isPair,
   isScalar,
-  isSeq,
-  Node,
-  ParsedNode,
-  Range
-} from './nodes/Node.js'
+  isSeq
+} from './nodes/identity.js'
+export { Node, ParsedNode, Range } from './nodes/Node.js'
 export { Pair } from './nodes/Pair.js'
 export { Scalar } from './nodes/Scalar.js'
 export { YAMLMap } from './nodes/YAMLMap.js'

src/nodes/Alias.ts

@@ -3,17 +3,10 @@ import type { Document } from '../doc/Document.js'
 import type { FlowScalar } from '../parse/cst.js'
 import type { StringifyContext } from '../stringify/stringify.js'
 import { visit } from '../visit.js'
-import {
-  ALIAS,
-  isAlias,
-  isCollection,
-  isPair,
-  Node,
-  NodeBase,
-  Range
-} from './Node.js'
+import { ALIAS, isAlias, isCollection, isPair } from './identity.js'
+import { Node, NodeBase, Range } from './Node.js'
 import type { Scalar } from './Scalar'
-import type { ToJSContext } from './toJS.js'
+import { toJS, ToJSContext } from './toJS.js'
 import type { YAMLMap } from './YAMLMap.js'
 import type { YAMLSeq } from './YAMLSeq.js'
 
@@ -62,7 +55,12 @@ export class Alias extends NodeBase {
       const msg = `Unresolved alias (the anchor must be set before the alias): ${this.source}`
       throw new ReferenceError(msg)
     }
-    const data = anchors.get(source)
+    let data = anchors.get(source)
+    if (!data) {
+      // Resolve anchors for Node.prototype.toJS()
+      toJS(source, null, ctx)
+      data = anchors.get(source)
+    }
     /* istanbul ignore if */
     if (!data || data.res === undefined) {
       const msg = 'This should not happen: Alias anchor was not resolved?'

src/nodes/Collection.ts

@@ -5,9 +5,9 @@ import {
   isNode,
   isPair,
   isScalar,
-  NodeBase,
   NODE_TYPE
-} from './Node.js'
+} from './identity.js'
+import { NodeBase } from './Node.js'
 
 export function collectionFromPath(
   schema: Schema,

src/nodes/Node.ts

@@ -1,9 +1,12 @@
+import { applyReviver } from '../doc/applyReviver.js'
 import type { Document } from '../doc/Document.js'
+import type { ToJSOptions } from '../options.js'
 import { Token } from '../parse/cst.js'
 import type { StringifyContext } from '../stringify/stringify.js'
 import type { Alias } from './Alias.js'
-import type { Pair } from './Pair.js'
+import { NODE_TYPE } from './identity.js'
 import type { Scalar } from './Scalar.js'
+import { toJS, ToJSContext } from './toJS.js'
 import type { YAMLMap } from './YAMLMap.js'
 import type { YAMLSeq } from './YAMLSeq.js'
 
@@ -40,67 +43,6 @@ export type ParsedNode =
 
 export type Range = [number, number, number]
 
-export const ALIAS = Symbol.for('yaml.alias')
-export const DOC = Symbol.for('yaml.document')
-export const MAP = Symbol.for('yaml.map')
-export const PAIR = Symbol.for('yaml.pair')
-export const SCALAR = Symbol.for('yaml.scalar')
-export const SEQ = Symbol.for('yaml.seq')
-export const NODE_TYPE = Symbol.for('yaml.node.type')
-
-export const isAlias = (node: any): node is Alias =>
-  !!node && typeof node === 'object' && node[NODE_TYPE] === ALIAS
-
-export const isDocument = <T extends Node = Node>(
-  node: any
-): node is Document<T> =>
-  !!node && typeof node === 'object' && node[NODE_TYPE] === DOC
-
-export const isMap = <K = unknown, V = unknown>(
-  node: any
-): node is YAMLMap<K, V> =>
-  !!node && typeof node === 'object' && node[NODE_TYPE] === MAP
-
-export const isPair = <K = unknown, V = unknown>(
-  node: any
-): node is Pair<K, V> =>
-  !!node && typeof node === 'object' && node[NODE_TYPE] === PAIR
-
-export const isScalar = <T = unknown>(node: any): node is Scalar<T> =>
-  !!node && typeof node === 'object' && node[NODE_TYPE] === SCALAR
-
-export const isSeq = <T = unknown>(node: any): node is YAMLSeq<T> =>
-  !!node && typeof node === 'object' && node[NODE_TYPE] === SEQ
-
-export function isCollection<K = unknown, V = unknown>(
-  node: any
-): node is YAMLMap<K, V> | YAMLSeq<V> {
-  if (node && typeof node === 'object')
-    switch (node[NODE_TYPE]) {
-      case MAP:
-      case SEQ:
-        return true
-    }
-  return false
-}
-
-export function isNode<T = unknown>(node: any): node is Node<T> {
-  if (node && typeof node === 'object')
-    switch (node[NODE_TYPE]) {
-      case ALIAS:
-      case MAP:
-      case SCALAR:
-      case SEQ:
-        return true
-    }
-  return false
-}
-
-export const hasAnchor = <K = unknown, V = unknown>(
-  node: unknown
-): node is Scalar<V> | YAMLMap<K, V> | YAMLSeq<V> =>
-  (isScalar(node) || isCollection(node)) && !!node.anchor
-
 export abstract class NodeBase {
   declare readonly [NODE_TYPE]: symbol
 
@@ -149,4 +91,25 @@ export abstract class NodeBase {
     if (this.range) copy.range = this.range.slice() as NodeBase['range']
     return copy
   }
+
+  /** A plain JavaScript representation of this node. */
+  toJS(
+    doc: Document<Node, boolean>,
+    { mapAsMap, maxAliasCount, onAnchor, reviver }: ToJSOptions = {}
+  ): any {
+    const ctx: ToJSContext = {
+      anchors: new Map(),
+      doc,
+      keep: true,
+      mapAsMap: mapAsMap === true,
+      mapKeyWarned: false,
+      maxAliasCount: typeof maxAliasCount === 'number' ? maxAliasCount : 100
+    }
+    const res = toJS(this, '', ctx)
+    if (typeof onAnchor === 'function')
+      for (const { count, res } of ctx.anchors.values()) onAnchor(res, count)
+    return typeof reviver === 'function'
+      ? applyReviver(reviver, { '': res }, '', res)
+      : res
+  }
 }

src/nodes/Pair.ts

@@ -4,7 +4,7 @@ import type { Schema } from '../schema/Schema.js'
 import type { StringifyContext } from '../stringify/stringify.js'
 import { stringifyPair } from '../stringify/stringifyPair.js'
 import { addPairToJSMap } from './addPairToJSMap.js'
-import { isNode, NODE_TYPE, PAIR } from './Node.js'
+import { isNode, NODE_TYPE, PAIR } from './identity.js'
 import type { ToJSContext } from './toJS.js'
 
 export function createPair(

src/nodes/Scalar.ts

@@ -1,5 +1,6 @@
 import type { BlockScalar, FlowScalar } from '../parse/cst.js'
-import { NodeBase, Range, SCALAR } from './Node.js'
+import { SCALAR } from './identity.js'
+import { NodeBase, Range } from './Node.js'
 import { toJS, ToJSContext } from './toJS.js'
 
 export const isScalarValue = (value: unknown) =>

src/nodes/YAMLMap.ts

@@ -4,7 +4,8 @@ import type { StringifyContext } from '../stringify/stringify.js'
 import { stringifyCollection } from '../stringify/stringifyCollection.js'
 import { addPairToJSMap } from './addPairToJSMap.js'
 import { Collection } from './Collection.js'
-import { isPair, isScalar, MAP, ParsedNode, Range } from './Node.js'
+import { isPair, isScalar, MAP } from './identity.js'
+import type { ParsedNode, Range } from './Node.js'
 import { Pair } from './Pair.js'
 import { isScalarValue, Scalar } from './Scalar.js'
 import type { ToJSContext } from './toJS.js'

src/nodes/YAMLSeq.ts

@@ -3,7 +3,8 @@ import type { Schema } from '../schema/Schema.js'
 import type { StringifyContext } from '../stringify/stringify.js'
 import { stringifyCollection } from '../stringify/stringifyCollection.js'
 import { Collection } from './Collection.js'
-import { isScalar, ParsedNode, Range, SEQ } from './Node.js'
+import { isScalar, SEQ } from './identity.js'
+import type { ParsedNode, Range } from './Node.js'
 import type { Pair } from './Pair.js'
 import { isScalarValue, Scalar } from './Scalar.js'
 import { toJS, ToJSContext } from './toJS.js'

src/nodes/addPairToJSMap.ts

@@ -1,6 +1,6 @@
 import { warn } from '../log.js'
 import { createStringifyContext } from '../stringify/stringify.js'
-import { isAlias, isMap, isNode, isScalar, isSeq } from './Node.js'
+import { isAlias, isMap, isNode, isScalar, isSeq } from './identity.js'
 import type { Pair } from './Pair.js'
 import { Scalar } from './Scalar.js'
 import { toJS, ToJSContext } from './toJS.js'