Implement iterators on Record (#530)

This PR adds various iterables to the Record class: values(), entries(), [Symbol.iterator]().

The new functionality allows, among other things, getting values lazily, on-demand, and / or in pairs:

const queryResult = await session.run(query);

for (const record of queryResult.records)
  for (const [ key, value ] of record.entries())
    // do something with 'key' and 'value'

for (const record of queryResult.records)
  for (const value of record)
    // each queried value is accessible as 'value'

Author: parzhitsky

src/record.js

@@ -80,8 +80,8 @@ class Record {
    * @param {function(value: Object, key: string, record: Record)} visitor the function to apply to each field.
    */
   forEach (visitor) {
-    for (let i = 0; i < this.keys.length; i++) {
-      visitor(this._fields[i], this.keys[i], this)
+    for (const [key, value] of this.entries()) {
+      visitor(value, key, this)
     }
   }
 
@@ -98,23 +98,59 @@ class Record {
   map (visitor) {
     const resultArray = []
 
-    for (let i = 0; i < this.keys.length; i++) {
-      resultArray.push(visitor(this._fields[i], this.keys[i], this))
+    for (const [key, value] of this.entries()) {
+      resultArray.push(visitor(value, key, this))
     }
 
     return resultArray
   }
 
+  /**
+   * Iterate over results. Each iteration will yield an array
+   * of exactly two items - the key, and the value (in order).
+   *
+   * @generator
+   * @returns {IterableIterator<[string, Object]>}
+   */
+  * entries () {
+    for (let i = 0; i < this.keys.length; i++) {
+      yield [this.keys[i], this._fields[i]]
+    }
+  }
+
+  /**
+   * Iterate over values.
+   *
+   * @generator
+   * @returns {IterableIterator<Object>}
+   */
+  * values () {
+    for (let i = 0; i < this.keys.length; i++) {
+      yield this._fields[i]
+    }
+  }
+
+  /**
+   * Iterate over values. Delegates to {@link Record#values}
+   *
+   * @generator
+   * @returns {IterableIterator<Object>}
+   */
+  * [Symbol.iterator] () {
+    yield * this.values()
+  }
+
   /**
    * Generates an object out of the current Record
    *
    * @returns {Object}
    */
   toObject () {
     const object = {}
-    this.forEach((value, key) => {
+
+    for (const [key, value] of this.entries()) {
       object[key] = value
-    })
+    }
 
     return object
   }

test/record.test.js

@@ -126,4 +126,67 @@ describe('#unit Record', () => {
     // Then
     expect(result).toEqual([['Bob', 'name', record], [45, 'age', record]])
   })
+
+  it('should allow taking values lazily', () => {
+    // Given
+    const record = new Record(['name', 'age'], ['Bob', 45])
+    const values = record.values()
+
+    // When
+    const first = values.next()
+    const second = values.next()
+    const third = values.next()
+
+    // Then
+    expect(first.value).toEqual('Bob')
+    expect(first.done).toBeFalsy()
+    expect(second.value).toEqual(45)
+    expect(second.done).toBeFalsy()
+    expect(third.value).toBeUndefined()
+    expect(third.done).toBeTruthy()
+  })
+
+  it('should allow taking key-value pairs lazily', () => {
+    // Given
+    const record = new Record(['name', 'age'], ['Bob', 45])
+    const entries = record.entries()
+
+    // When
+    const first = entries.next()
+    const second = entries.next()
+    const third = entries.next()
+
+    // Then
+    expect(first.value).toEqual(['name', 'Bob'])
+    expect(first.done).toBeFalsy()
+    expect(second.value).toEqual(['age', 45])
+    expect(second.done).toBeFalsy()
+    expect(third.value).toBeUndefined()
+    expect(third.done).toBeTruthy()
+  })
+
+  it('should allow directly creating array from record', () => {
+    // Given
+    const record = new Record(['name', 'age'], ['Bob', 45])
+
+    // When
+    const values = Array.from(record)
+
+    // Then
+    expect(values).toEqual(['Bob', 45])
+  })
+
+  it('should allow iterating over values using for..of loop', () => {
+    // Given
+    const record = new Record(['name', 'age'], ['Bob', 45])
+    const values = []
+
+    // When
+    for (const value of record) {
+      values.push(value)
+    }
+
+    // Then
+    expect(values).toEqual(['Bob', 45])
+  })
 })

test/types/record.test.ts

@@ -37,6 +37,15 @@ record1.forEach((value: any, key: string) => {})
 
 record1.forEach((value: any, key: string, record: Record) => {})
 
+const record1Entries: IterableIterator<[string, any]> = record1.entries()
+const record2Entries: IterableIterator<[string, any]> = record2.entries()
+
+const record1Values: IterableIterator<any> = record1.values()
+const record2Values: IterableIterator<any> = record2.values()
+
+const record1ToArray: any[] = [...record1]
+const record2ToArray: any[] = [...record2]
+
 const record1Has: boolean = record1.has(42)
 const record2Has: boolean = record1.has('key')
 

types/record.d.ts

@@ -35,6 +35,12 @@ declare class Record {
 
   map<T>(visitor: MapVisitor<T>): T[]
 
+  entries(): IterableIterator<[string, Object]>
+
+  values(): IterableIterator<Object>
+
+  [Symbol.iterator](): IterableIterator<Object>
+
   toObject(): object
 
   get(key: string | number): any