Class HList<Value>

A mutable haystack list that uses generics and the JavaScript proxy pattern.

A list implements the JavaScript proxy pattern to make it easy to work with...


// If you want the list to hold any value then use `new HList<HVal>(...)` instead.
const list = new HList<HStr>([ HStr.make('alpha'), HStr.make('beta') ])

// Write 'gamma'
list.set(0, HStr.make('gamma'))

// Read 'gamma'
console.log(list.get(0))

A list is also iterable...

// Iterate a list
for (let value of list) {
  console.log(value)
}

// Get the list as an array...
const array = list.toArray()

Type Parameters

Value extends OptionalHVal = OptionalHVal

Hierarchy

HList

Implements

HVal
Iterable<Value>

Indexable

[prop: number]: Value

Index

Constructors

constructor

new HList<Value>(...values): HList<Value>

Creates a new list.

// A single haystack value array.
const list0 = new HList([HStr.make('foo), HMarker.make()])

// Pass in multiple arguments instead of an array.
const list1 = new HList(HStr.make('foo'), HMarker.make())

// Create a list using Hayson.
const list2 = new HList(['foo', { _kind: Kind.Marker }])
const list2 = new HList('foo', { _kind: Kind.Marker })

Type Parameters

Value extends OptionalHVal = OptionalHVal

Parameters

Rest ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]

Returns HList<Value>

Properties

values

values: Value[]

The list values.

Accessors

avg

get avg(): number
Convience method for averaging all the numbers in a list.

If there are no numbers then Number.NaN is returned.
```
// 2
const avg = new HList<HNum>(1, 2, 3).avg
```
Returns number
The average of all the numbers.
- Defined in src/core/HList.ts:1074

length

get length(): number
Return the length of the list.

Returns number
- Defined in src/core/HList.ts:234

max

get max(): number
Convience method for getting the maximum number in a list.
```
// 3
const max = new HList<HNum>(1, 2, 3).max
```
If there are no numbers then Number.MIN_SAFE_INTEGER is returned.
Returns number
A maximum number in a list.
- Defined in src/core/HList.ts:1036

min

get min(): number
Convience method for getting the minimum number in a list.
```
// 1
const min = new HList<HNum>(1, 2, 3).min
```
If there are no numbers then Number.MAX_SAFE_INTEGER is returned.
Returns number
A minimum number in a list.
- Defined in src/core/HList.ts:1055

sum

get sum(): number
Convience method for summing a list of numbers in a list.
```
// Sums to 6
const sum = new HList<HNum>(1, 2, 3).sum
```
Returns number
A sum of all the numbers in the list.
- Defined in src/core/HList.ts:1017

Methods

[iterator]

[iterator](): Iterator<Value, any, undefined>
Iterate over a list.

This enables a 'for ... of' loop to be used directly on an iterator.

Returns Iterator<Value, any, undefined>
A new iterator for a list.
```
// Iterate a list
for (let value of list) {
  console.log(value)
}

// Destructure a list into a real array
const array = [...list]
```
Implementation of Iterable.[iterator]
- Defined in src/core/HList.ts:985

add

add(...values): HList<Value>
Adds an element to the list.

This method can add multiple values at once...
```
list.add(HStr.make('foo'))
list.add(HStr.make('foo'), HStr.make('boo))

// Using an array...
list.add([HStr.make('foo'), HStr.make('boo)])

// Same but using hayson...
list.add('foo')
list.add('foo', 'boo')
list.add(['foo', 'boo'])
```
Parameters
- Rest ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]
  
  The values to add to the list.
Returns HList<Value>
The list instance.
- Defined in src/core/HList.ts:322

all

all(val, cx?): boolean

Test to see if the list contains all the same value or the filter matches all elements.


const list = new HList([ HStr.make('a'), HStr.make('a'), HStr.make('a') ])

if (list.all(HStr.make('a'))) {
  // Do something
}

// Also use a haystack filter...
if (list.all('item == "a"')) {
  // Do something
}

// Same again but use the shorter 'it'...
if (list.all('it == "all"')) {
  // Do something
}

list.push(HStr.make('b'))

// All will now return false as the values aren't all the same...
if (list.all('it == "a"')) {
  // Do something
}

Parameters

val: string | Node | Value

The value to test, a haystack filter or AST node.
Optional cx: Partial<EvalContext>

Optional haystack filter evaluation context.

Returns boolean

True if the list contains the value.

any

any(val, cx?): boolean

Test to see if the list contains the value or matches the filter at least once.

const list = new HList([ HStr.make('a'), HStr.make('b'), HStr.make('c') ])

if (list.any(HStr.make(a))) {
  // Do something
}

// Or use a haystack filter...
if (list.any('item == "a"')) {
 // Do something
}

// It use the shortened item name in a haystack filter...
if (list.any('it == "a"')) {
 // Do something
}

Parameters

val: string | Node | Value

The value to test, a haystack filter or AST node.
Optional cx: Partial<EvalContext>

Optional haystack filter evaluation context.

Returns boolean

True if the list contains the value.

asArrayLike

asArrayLike(): ArrayLike<HaysonVal | Value>
Returns ArrayLike<HaysonVal | Value>
The list as an array like object.
- Defined in src/core/HList.ts:992

clear

clear(): void
Clear all entries from the list.
```
// Makes a list completely empty.
list.clear()
```
Returns void
- Defined in src/core/HList.ts:297

compareTo

compareTo(value): number
Compares two values.
Parameters
- value: unknown
  
  The value to compare against.
Returns number
The sort order as negative, 0, or positive.
Implementation of HVal.compareTo
- Defined in src/core/HList.ts:944

concat

concat(list): HList<Value>
Concatenate two lists together and return the new list.
```
const newList = listA.concat(listB)
```
Parameters
- list: HList<Value>
  
  The list to concatenate.
Returns HList<Value>
The new list.
- Defined in src/core/HList.ts:344

equals

equals(value): boolean
Value equality check.
Parameters
- value: unknown
  
  The value to test.
Returns boolean
True if the value is the same.
Implementation of HVal.equals
- Defined in src/core/HList.ts:917

filter

filter(filter, cx?): HList<Value>
Filter the list via a haystack filter or callback function and return a new list.

If a Haystack filter is used, the array list is referenced as either 'it' or 'item.
```
const list = HList<HStr>.make([ HStr.make('foo'), HStr.make('boo'), HStr.make('foo') ])

const filteredList = list.filter('item == "foo"')

// Or use the shorter it...

const anotherList = list.filter('it == "foo"')
```
A classic filter function callback can also be used...
```
const anotherList= list.filter((val: HStr): boolean => val.value === 'foo')
```
Parameters
- filter: string | Node | FilterCallback<Value>
  
  A haystack filter or AST node.
- Optional cx: Partial<EvalContext>
  
  Optional haystack filter evaluation context.
Returns HList<Value>
A new haystack list.
- Defined in src/core/HList.ts:642

find

find(callback, thisArg?): undefined | Value
Find an item in the list and return it or undefiend if not found.
```
const foundItem = list.find((val) => val.someItem.equals(foo))
```
Parameters
- callback: FindCallback<Value>
  
  The find callback.
- Optional thisArg: any
  
  Optional this argument.
Returns undefined | Value
The item or undefined.
- Defined in src/core/HList.ts:849

flat

flat<NewValue>(): HList<NewValue>
```
// Creates an HList with HNums - [1, 2, 3, 4, 5, 6]
const list = new HList<HNum>([[1, 2, 3], [4, 5], 6]).flat()
```
Type Parameters
- NewValue extends OptionalHVal = OptionalHVal
Returns HList<NewValue>
A flattened list.
- Defined in src/core/HList.ts:755

forEach

forEach(callback, thisArg?): void
Loop through a list's values.
Parameters
- callback: ((value, index, array) => void)
  
  The function to execute on each haystack value.
  - - (value, index, array): void
    - Parameters
      
      value: Value
      
      index: number
      
      array: Value[]
      
      Returns void
- Optional thisArg: any
  
  Optional value to use as this when executing callback.
Returns void
- Defined in src/core/HList.ts:831

get

get(index): undefined | Value
Returns a haystack value from the list or undefined if it can't be found.
```
const val = list.get(0)
if (val) {
  // Do something
}
```
Parameters
- index: number
  
  The index number of the value to get.
Returns undefined | Value
The value, null or undefined if it can't be found.
- Defined in src/core/HList.ts:252

getKind

getKind(): Kind
Returns Kind
The value's kind.
Implementation of HVal.getKind
- Defined in src/core/HList.ts:217

includes

includes(val, fromIndex?): boolean
Find a value to search for and returns true if it's found.
```
if (list.includes(HNum.make(24, 'm'))) {
  // Do something...
}
```
Parameters
- val: HaysonVal | Value
  
  The value to search for.
- Optional fromIndex: number
  
  Optional index number to search from.
Returns boolean
true if the value is found.
- Defined in src/core/HList.ts:810

insert

insert(index, ...values): HList<Value>

Inserts an element into the list.

This method can insert multiple values at once...

list.insert(1, HStr.make('foo'))
list.insert(1, HStr.make('foo'), HStr.make('boo))

// Using an array...
list.insert(1, [HStr.make('foo'), HStr.make('boo)])

// Same but using hayson...
list.insert(1, 'foo')
list.insert(1, 'foo', 'boo')
list.insert(1, ['foo', 'boo'])

Parameters

index: number
Rest ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]

The values to insert into the list.

Returns HList<Value>

The list instance.

inspect

inspect(message?): HList<Value>
Dump the value to the local console output.
Parameters
- Optional message: string
  
  An optional message to display before the value.
Returns HList<Value>
The value instance.
Implementation of HVal.inspect
- Defined in src/core/HList.ts:1124

isEmpty

isEmpty(): boolean
```
if (list.isEmpty()) {
  // List is empty.
}
```
Returns boolean
True when there are no entries in the list.
- Defined in src/core/HList.ts:477

isKind

isKind(kind): boolean
Compares the value's kind.
Parameters
- kind: Kind
  
  The kind to compare against.
Returns boolean
True if the kind matches.
Implementation of HVal.isKind
- Defined in src/core/HList.ts:227

map

map<NewValue>(callback): NewValue[]
Use an array style map function on a list.
```
// Using React, map a list to some DOM elements...
list.make((str: HStr): any => <div>{str.value}</div>)
```
Type Parameters
- NewValue
Parameters
- callback: MapCallback<Value, NewValue>
  
  The map callback.
Returns NewValue[]
A new list with the mapped value.
- Defined in src/core/HList.ts:719

matches

matches(filter, cx?): boolean
Returns true if the haystack filter matches the value.

This method is the same as any.
Parameters
- filter: string | Node
  
  The filter to test.
- Optional cx: Partial<EvalContext>
  
  Optional haystack filter evaluation context.
Returns boolean
True if the filter matches ok.
Implementation of HVal.matches
- Defined in src/core/HList.ts:545

newCopy

newCopy(): HList<Value>
Returns HList<Value>
Returns a copy of the list.
Implementation of HVal.newCopy
- Defined in src/core/HList.ts:1136

pop

pop(): undefined | Value
Pops removes the last element of the array and returns it. If the array is empty then undefined is returned.
```
const lastValue = list.pop()

if (lastValue) {
  // Do something
}
```
Returns undefined | Value
The popped value or undefined.
- Defined in src/core/HList.ts:425

push

push(val): HList<Value>
Pushes a value onto the end of the list.
```
list.push(HStr.make('A new string'))

// Same but using Hayson...
list.push('A new string')
```
Parameters
- val: HaysonVal | Value
  
  The value to add to the list.
Returns HList<Value>
The list instance.
- Defined in src/core/HList.ts:407

reduce

reduce<NewValue>(callback, initialValue?): NewValue
Use an array style reduce function on a list.
```
const numList = new HList<HNum>([1, 2, 3])

const total = numList.reduce(
  (prev, cur): number => prev + cur.value), 0
)
```
Type Parameters
- NewValue = Value
Parameters
- callback: ReduceCallback<NewValue, Value>
  
  the reduce callback.
- Optional initialValue: NewValue
  
  The initial value for the reduce operation.
Returns NewValue
The reduced value.
- Defined in src/core/HList.ts:738

remove

remove(index): void
Removes a value from the list.
```
// Removes the first element of the list.
list.remove(0)
```
Parameters
- index: number
  
  The index of the item in the list.
Returns void
- Defined in src/core/HList.ts:285

reverse

reverse(): HList<Value>
Reverse the order of all the values in the list.
```
const listInDescendingOrder = list.sort().reverse()
```
Returns HList<Value>
The list instance.
- Defined in src/core/HList.ts:463

set

set(index, value): HList<Value>
Set a haystack value in the list.
```
list.set(0, HStr.make('A new string'))

// Or use Hayson...
list.set(0, 'A new string')
```
Parameters
- index: number
  
  The index of the item in the list.
- value: HaysonVal | Value
  
  The haystack value or hayson value to set.
Returns HList<Value>
The list instance.
- Defined in src/core/HList.ts:270

sort

sort(): HList<Value>
Sort the list in ascending order.
```
const sortedList = list.sort()
```
Returns HList<Value>
The list instance.
- Defined in src/core/HList.ts:438

toArray

toArray(): Value[]
Returns Value[]
A copy of the underlying array.
- Defined in src/core/HList.ts:964

toAxon

toAxon(): string
Returns string
An Axon encoded string.
Implementation of HVal.toAxon
- Defined in src/core/HList.ts:905

toDict

toDict(): HDict
Return the list as a dict.

The dict has one key called 'val' that stores the list.

Returns HDict
A dict.
Implementation of HVal.toDict
- Defined in src/core/HList.ts:1096

toFilter

toFilter(): string
Encodes to an encoded zinc value that can be used in a haystack filter string.

A list isn't supported in filter so throw an error.

Returns string
The encoded value that can be used in a haystack filter.
Implementation of HVal.toFilter
- Defined in src/core/HList.ts:889

toGrid

toGrid(): HGrid<HDict>
Return the list as a grid.

The grid has one row and one column called 'val'.

Returns HGrid<HDict>
A grid.
Implementation of HVal.toGrid
- Defined in src/core/HList.ts:1107

toJSON

toJSON(): HaysonList
Returns the list in a Hayson format.

Returns HaysonList
A JSON reprentation of the object.
Implementation of HVal.toJSON
- Defined in src/core/HList.ts:861

toJSONv3

toJSONv3(): JsonV3List
Returns JsonV3List
A JSON v3 representation of the object.
Implementation of HVal.toJSONv3
- Defined in src/core/HList.ts:868

toList

toList(): HList<Value>
Returns HList<Value>
The value as a list.
Implementation of HVal.toList
- Defined in src/core/HList.ts:1114

toString

toString(): string
Returns string
A string representation of the value.
Implementation of HVal.toString
- Defined in src/core/HList.ts:875

toZinc

toZinc(): string
Returns string
The encoded zinc string.
Implementation of HVal.toZinc
- Defined in src/core/HList.ts:896

unique

unique(): HList<Value>

// Create a unique list with HStr - [ 'a', 'b' ]
const list = new HList<HStr>('a', 'a', 'b').unique()

Returns HList<Value>

A new filtered list of unique values.

validate

validate(): void
Iterates through the list to ensure we have a valid set of haystack values.

As the list's array is directly exposed calling this method will ensure all the values held in the list are haystack values.

Returns void
- Defined in src/core/HList.ts:1150

`Static` make

make<Value>(...values): HList<Value>
Make a list.
Type Parameters
- Value extends OptionalHVal = OptionalHVal
Parameters
- Rest ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]
  
  A value or list of values.
Returns HList<Value>
A list.
- Defined in src/core/HList.ts:179

Class HList<Value>

Type Parameters

Value extends OptionalHVal = OptionalHVal

Hierarchy

Implements

Indexable

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Value extends OptionalHVal = OptionalHVal

Parameters

Rest ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]

Returns HList<Value>

Properties

values

Accessors

avg

Returns number

length

Returns number

max

Returns number

min

Returns number

sum

Returns number

Methods

[iterator]

Returns Iterator<Value, any, undefined>

add

Parameters

Rest ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]

Returns HList<Value>

all

Parameters

val: string | Node | Value

Optional cx: Partial<EvalContext>

Returns boolean

any

Parameters

val: string | Node | Value

Optional cx: Partial<EvalContext>

Returns boolean

asArrayLike

Returns ArrayLike<HaysonVal | Value>

clear

Returns void

compareTo

Parameters

value: unknown

Returns number

concat

Parameters

list: HList<Value>

Returns HList<Value>

equals

Parameters

value: unknown

Returns boolean

filter

Parameters

filter: string | Node | FilterCallback<Value>

Optional cx: Partial<EvalContext>

Returns HList<Value>

find

Parameters

callback: FindCallback<Value>

Optional thisArg: any

Returns undefined | Value

flat

Type Parameters

NewValue extends OptionalHVal = OptionalHVal

Returns HList<NewValue>

forEach

Parameters

`Rest` ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]

`Rest` ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]

`Optional` cx: Partial<EvalContext>

`Optional` cx: Partial<EvalContext>

`Optional` cx: Partial<EvalContext>

`Optional` thisArg: any

`Optional` thisArg: any

`Optional` fromIndex: number

`Rest` ...values: (HaysonVal | Value | (HaysonVal | Value)[])[]

`Optional` message: string

`Optional` cx: Partial<EvalContext>

`Optional` initialValue: NewValue