feat!: Have YAMLMap & YAMLSeq extend Array, rather than containing an .items Array

Author: eemeli

.github/vitest.browserstack.config.js

@@ -42,6 +42,7 @@ export default defineConfig({
       instances
     },
     globals: true,
+    setupFiles: ['tests/_setup.ts'],
     include: ['tests/**/*.{js,ts}'],
     exclude: [
       'tests/_*',

src/compose/composer.ts

@@ -111,8 +111,8 @@ export class Composer<
         doc.comment = doc.comment ? `${doc.comment}\n${comment}` : comment
       } else if (afterEmptyLine || doc.directives.docStart) {
         doc.commentBefore = comment
-      } else if (isCollection(dc) && !dc.flow && dc.items.length > 0) {
-        let it = dc.items[0]
+      } else if (isCollection(dc) && !dc.flow && dc.length > 0) {
+        let it = dc[0]
         if (it instanceof Pair) it = it.key
         const cb = it.commentBefore
         it.commentBefore = cb ? `${comment}\n${cb}` : comment

src/compose/resolve-block-map.ts

@@ -76,7 +76,7 @@ export function resolveBlockMap(
     if (ctx.schema.compat) flowIndentCheck(bm.indent, key, onError)
     ctx.atKey = false
 
-    if (mapIncludes(ctx, map.items, keyNode))
+    if (mapIncludes(ctx, map, keyNode))
       onError(keyStart, 'DUPLICATE_KEY', 'Map keys must be unique')
 
     // value properties
@@ -116,7 +116,7 @@ export function resolveBlockMap(
       offset = valueNode.range![2]
       const pair = new Pair(keyNode, valueNode)
       if (ctx.options.keepSourceTokens) pair.srcToken = collItem
-      map.items.push(pair)
+      map.push(pair)
     } else {
       // key with no value
       if (implicitKey)
@@ -131,7 +131,7 @@ export function resolveBlockMap(
       }
       const pair = new Pair(keyNode)
       if (ctx.options.keepSourceTokens) pair.srcToken = collItem
-      map.items.push(pair)
+      map.push(pair)
     }
   }
 

src/compose/resolve-block-seq.ts

@@ -50,7 +50,7 @@ export function resolveBlockSeq(
       : composeEmptyNode(ctx, props.end, start, null, props, onError)
     if (ctx.schema.compat) flowIndentCheck(bs.indent, value, onError)
     offset = node.range![2]
-    seq.items.push(node)
+    seq.push(node)
   }
   seq.range = [bs.offset, offset, commentEnd ?? offset]
   return seq

src/compose/resolve-flow-collection.ts

@@ -23,8 +23,9 @@ export function resolveFlowCollection(
 ): YAMLMap | YAMLSeq {
   const isMap = fc.start.source === '{'
   const fcName = isMap ? 'flow map' : 'flow sequence'
-  const NodeClass = tag?.nodeClass ?? (isMap ? YAMLMap : YAMLSeq)
-  const coll = new NodeClass(ctx.schema) as YAMLMap | YAMLSeq
+  let coll
+  if (tag?.nodeClass) coll = new tag.nodeClass(ctx.schema) as YAMLMap | YAMLSeq
+  else coll = isMap ? new YAMLMap(ctx.schema) : new YAMLSeq(ctx.schema)
   coll.flow = true
   const atRoot = ctx.atRoot
   if (atRoot) ctx.atRoot = false
@@ -93,7 +94,7 @@ export function resolveFlowCollection(
           }
         }
         if (prevItemComment) {
-          let prev = coll.items[coll.items.length - 1]
+          let prev = coll[coll.length - 1]
           if (prev instanceof Pair) prev = prev.value ?? prev.key
           if (prev.comment) prev.comment += '\n' + prevItemComment
           else prev.comment = prevItemComment
@@ -108,7 +109,7 @@ export function resolveFlowCollection(
       const valueNode = value
         ? composeNode(ctx, value, props, onError)
         : composeEmptyNode(ctx, props.end, sep, null, props, onError)
-      ;(coll as YAMLSeq).items.push(valueNode)
+      ;(coll as YAMLSeq).push(valueNode)
       offset = valueNode.range![2]
       if (isBlock(value)) onError(valueNode.range!, 'BLOCK_IN_FLOW', blockMsg)
     } else {
@@ -190,16 +191,16 @@ export function resolveFlowCollection(
       if (ctx.options.keepSourceTokens) pair.srcToken = collItem
       if (isMap) {
         const map = coll as YAMLMap
-        if (mapIncludes(ctx, map.items, keyNode))
+        if (mapIncludes(ctx, map, keyNode))
           onError(keyStart, 'DUPLICATE_KEY', 'Map keys must be unique')
-        map.items.push(pair)
+        map.push(pair)
       } else {
         const map = new YAMLMap(ctx.schema)
         map.flow = true
-        map.items.push(pair)
+        map.push(pair)
         const endRange = (valueNode ?? keyNode).range!
         map.range = [keyNode.range![0], endRange[1], endRange[2]]
-        ;(coll as YAMLSeq).items.push(map)
+        ;(coll as YAMLSeq).push(map)
       }
       offset = valueNode ? valueNode.range![2] : valueProps.end
     }

src/doc/NodeCreator.ts

@@ -62,7 +62,7 @@ export class NodeCreator {
     if (isNode(value)) return value
     if (value instanceof Pair) {
       const map = this.schema.map.createNode(this, null)
-      map.items.push(value)
+      map.push(value)
       return map
     }
     if (

src/nodes/Alias.ts

@@ -153,9 +153,9 @@ function getAliasCount(
     const kc = getAliasCount(doc, node.key, anchors)
     const vc = getAliasCount(doc, node.value, anchors)
     return Math.max(kc, vc)
-  } else if (node && 'items' in node) {
+  } else if (Array.isArray(node)) {
     let count = 0
-    for (const item of node.items) {
+    for (const item of node) {
       const c = getAliasCount(doc, item, anchors)
       if (c > count) count = c
     }

src/nodes/Collection.ts

@@ -48,3 +48,19 @@ export interface CollectionBase extends NodeBase {
   /** Sets a value in this collection.  */
   set(key: unknown, value: unknown): void
 }
+
+export function copyCollection<T extends Collection>(
+  orig: T,
+  schema: Schema | undefined
+): T {
+  const copy = (orig.constructor as typeof YAMLMap).from(orig, it =>
+    it.clone(schema)
+  ) as typeof orig
+  if (orig.range) copy.range = [...orig.range]
+  const propDesc = Object.getOwnPropertyDescriptors(orig)
+  for (const [name, prop] of Object.entries(propDesc)) {
+    if (!(name in copy)) Object.defineProperty(copy, name, prop)
+  }
+  if (schema) copy.schema = schema
+  return copy
+}

src/nodes/Pair.ts

@@ -15,6 +15,10 @@ export class Pair<
   key: NodeOf<K>
   value: NodeOf<V> | null
 
+  declare comment?: never
+  declare commentBefore?: never
+  declare spaceBefore?: never
+
   /** The CST token that was composed into this pair.  */
   declare srcToken?: CollectionItem
 

src/nodes/YAMLMap.ts

@@ -6,7 +6,12 @@ import type { Schema } from '../schema/Schema.ts'
 import type { StringifyContext } from '../stringify/stringify.ts'
 import { stringifyCollection } from '../stringify/stringifyCollection.ts'
 import { addPairToJSMap } from './addPairToJSMap.ts'
-import type { CollectionBase, NodeOf, Primitive } from './Collection.ts'
+import {
+  copyCollection,
+  type CollectionBase,
+  type NodeOf,
+  type Primitive
+} from './Collection.ts'
 import { isNode } from './identity.ts'
 import type { Node, Range } from './Node.ts'
 import { Pair } from './Pair.ts'
@@ -33,9 +38,10 @@ export function findPair<
 export class YAMLMap<
   K extends Primitive | Node = Primitive | Node,
   V extends Primitive | Node = Primitive | Node
-> implements CollectionBase {
-  items: Pair<K, V>[] = []
-
+>
+  extends Array<Pair<K, V>>
+  implements CollectionBase
+{
   schema: Schema | undefined
 
   /** An optional anchor on this collection. Used by alias nodes. */
@@ -84,20 +90,21 @@ export class YAMLMap<
       if (typeof replacer === 'function') value = replacer.call(obj, key, value)
       else if (Array.isArray(replacer) && !replacer.includes(key)) return
       if (value !== undefined || nc.keepUndefined)
-        map.items.push(nc.createPair(key, value))
+        map.push(nc.createPair(key, value))
     }
     if (obj instanceof Map) {
       for (const [key, value] of obj) add(key, value)
     } else if (obj && typeof obj === 'object') {
       for (const key of Object.keys(obj)) add(key, (obj as any)[key])
     }
     if (typeof nc.schema.sortMapEntries === 'function') {
-      map.items.sort(nc.schema.sortMapEntries)
+      map.sort(nc.schema.sortMapEntries)
     }
     return map
   }
 
-  constructor(schema?: Schema) {
+  constructor(schema?: Schema, elements: Array<Pair<K, V>> = []) {
+    super(...elements)
     Object.defineProperty(this, 'schema', {
       value: schema,
       configurable: true,
@@ -112,14 +119,7 @@ export class YAMLMap<
    * @param schema - If defined, overwrites the original's schema
    */
   clone(schema?: Schema): this {
-    const copy: this = Object.create(
-      Object.getPrototypeOf(this),
-      Object.getOwnPropertyDescriptors(this)
-    )
-    if (schema) copy.schema = schema
-    copy.items = copy.items.map(it => it.clone(schema))
-    if (this.range) copy.range = [...this.range]
-    return copy
+    return copyCollection(this, schema)
   }
 
   /**
@@ -130,36 +130,36 @@ export class YAMLMap<
   add(pair: Pair<K, V>): void {
     if (!(pair instanceof Pair)) throw new TypeError('Expected a Pair')
 
-    const prev = findPair(this.items, pair.key)
+    const prev = findPair(this, pair.key)
     const sortEntries = this.schema?.sortMapEntries
     if (prev) {
       // For scalars, keep the old node & its comments and anchors
       if (prev.value instanceof Scalar && pair.value instanceof Scalar)
         prev.value.value = pair.value.value
       else prev.value = pair.value
     } else if (sortEntries) {
-      const i = this.items.findIndex(item => sortEntries(pair, item) < 0)
-      if (i === -1) this.items.push(pair)
-      else this.items.splice(i, 0, pair)
+      const i = this.findIndex(item => sortEntries(pair, item) < 0)
+      if (i === -1) this.push(pair)
+      else this.splice(i, 0, pair)
     } else {
-      this.items.push(pair)
+      this.push(pair)
     }
   }
 
   delete(key: unknown): boolean {
-    const it = findPair(this.items, key)
+    const it = findPair(this, key)
     if (!it) return false
-    const del = this.items.splice(this.items.indexOf(it), 1)
+    const del = this.splice(this.indexOf(it), 1)
     return del.length > 0
   }
 
   get(key: unknown): NodeOf<V> | undefined {
-    const it = findPair(this.items, key)
+    const it = findPair(this, key)
     return it?.value ?? undefined
   }
 
   has(key: unknown): boolean {
-    return !!findPair(this.items, key)
+    return !!findPair(this, key)
   }
 
   set(
@@ -203,7 +203,7 @@ export class YAMLMap<
     ctx ??= new ToJSContext()
     const map = Type ? new Type() : ctx?.mapAsMap ? new Map() : {}
     if (this.anchor) ctx.setAnchor(this, map)
-    for (const item of this.items) addPairToJSMap(doc, ctx, map, item)
+    for (const item of this) addPairToJSMap(doc, ctx, map, item)
     return map
   }
 
@@ -213,7 +213,7 @@ export class YAMLMap<
     onChompKeep?: () => void
   ): string {
     if (!ctx) return JSON.stringify(this)
-    for (const item of this.items) {
+    for (const item of this) {
       if (!(item instanceof Pair))
         throw new Error(
           `Map items must all be pairs; found ${JSON.stringify(item)} instead`