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

Implements

HVal
Iterable<Value>

Indexable

[prop: number]: Value
Numerical index access.

Index

Constructors

constructor

new HList<Value extends OptionalHVal = OptionalHVal>(
    values?:
        | ListStore<Value>
        | (HaysonVal | Value | (HaysonVal | Value)[])[],
): HList<Value>

Creates a new list.

// A single haystack value array.
const list0 = 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

Optionalvalues: ListStore<Value> | (HaysonVal | Value | (HaysonVal | Value)[])[]

Returns HList<Value>

Properties

$store

$store: ListStore<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/list/HList.ts:1094

length

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

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

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/list/HList.ts:1056

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/list/HList.ts:1075

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/list/HList.ts:1037

values

get values(): Value[]
Returns Value[]
- Defined in src/core/list/HList.ts:176
set values(values: Value[]): void
Parameters
- values: Value[]
Returns void
- Defined in src/core/list/HList.ts:180

Methods

[iterator]

"[iterator]"(): Iterator<Value>
Iterate over a list.

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

Returns Iterator<Value>
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/list/HList.ts:1005

add

add(...values: (HaysonVal | Value | (HaysonVal | Value)[])[]): this

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

...values: (HaysonVal | Value | (HaysonVal | Value)[])[]
The values to add to the list.

Returns this

The list instance.

all

all(val: string | Node | Value, cx?: Partial<EvalContext>): 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.
Optionalcx: Partial<EvalContext>
Optional haystack filter evaluation context.

Returns boolean

True if the list contains the value.

any

any(val: string | Node | Value, cx?: Partial<EvalContext>): 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.
Optionalcx: 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/list/HList.ts:1012

clear

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

compareTo

compareTo(value: unknown): 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/list/HList.ts:964

concat

concat(list: HList<Value>): 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/list/HList.ts:355

equals

equals(value: unknown): 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/list/HList.ts:937

filter

filter(
filter: string | Node | FilterCallback<Value>,
cx?: Partial<EvalContext>,
): 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.
- Optionalcx: Partial<EvalContext>
  Optional haystack filter evaluation context.
Returns HList<Value>
A new haystack list.
- Defined in src/core/list/HList.ts:653

find

find(callback: FindCallback<Value>, thisArg?: any): 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.
- OptionalthisArg: any
  Optional this argument.
Returns undefined | Value
The item or undefined.
- Defined in src/core/list/HList.ts:858

flat

flat<NewValue extends OptionalHVal = OptionalHVal>(): 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/list/HList.ts:766

forEach

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

get

get(index: number): 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/list/HList.ts:263

getKind

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

includes

includes(val: HaysonVal | Value, fromIndex?: number): 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.
- OptionalfromIndex: number
  Optional index number to search from.
Returns boolean
true if the value is found.
- Defined in src/core/list/HList.ts:819

insert

insert(
index: number,
...values: (HaysonVal | Value | (HaysonVal | Value)[])[],
): this

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
...values: (HaysonVal | Value | (HaysonVal | Value)[])[]
The values to insert into the list.

Returns this

The list instance.

inspect

inspect(message?: string): this
Dump the value to the local console output.
Parameters
- Optionalmessage: string
  An optional message to display before the value.
Returns this
The value instance.
Implementation of HVal.inspect
- Defined in src/core/list/HList.ts:1144

isEmpty

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

isKind

isKind(kind: 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/list/HList.ts:238

map

map<NewValue>(callback: MapCallback<Value, NewValue>): 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/list/HList.ts:730

matches

matches(filter: string | Node, cx?: Partial<EvalContext>): 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.
- Optionalcx: Partial<EvalContext>
  Optional haystack filter evaluation context.
Returns boolean
True if the filter matches ok.
Implementation of HVal.matches
- Defined in src/core/list/HList.ts:556

newCopy

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

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/list/HList.ts:436

push

push(val: HaysonVal | Value): this
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 this
The list instance.
- Defined in src/core/list/HList.ts:418

reduce

reduce<NewValue = Value>(
callback: ReduceCallback<NewValue, Value>,
initialValue?: NewValue,
): 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.
- OptionalinitialValue: NewValue
  The initial value for the reduce operation.
Returns NewValue
The reduced value.
- Defined in src/core/list/HList.ts:749

remove

remove(index: number): 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/list/HList.ts:296

reverse

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

set

set(index: number, value: HaysonVal | Value): this
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 this
The list instance.
- Defined in src/core/list/HList.ts:281

sort

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

toArray

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

toAxon

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

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/list/HList.ts:1116

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/list/HList.ts:909

toGrid

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

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

Returns HGrid
A grid.
Implementation of HVal.toGrid
- Defined in src/core/list/HList.ts:1127

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/list/HList.ts:867

toJSONString

toJSONString(): string
Returns string
A string containing the JSON representation of the object.
Implementation of HVal.toJSONString
- Defined in src/core/list/HList.ts:874

toJSONUint8Array

toJSONUint8Array(): Uint8Array
Returns Uint8Array
A byte buffer that has an encoded JSON string representation of the object.
Implementation of HVal.toJSONUint8Array
- Defined in src/core/list/HList.ts:881

toJSONv3

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

toList

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

toString

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

toZinc

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

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.

`Static`make

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

Class HList<Value>

Type Parameters

Implements

Indexable

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns HList<Value>

Properties

$store

Accessors

avg

Returns number

length

Returns number

max

Returns number

min

Returns number

sum

Returns number

values

Returns Value[]

Parameters

Returns void

Methods

[iterator]

Returns Iterator<Value>

add

Parameters

Returns this

all

Parameters

Returns boolean

any

Parameters

Returns boolean

asArrayLike

Returns ArrayLike<HaysonVal | Value>

clear

Returns void

compareTo

Parameters

Returns number

concat

Parameters

Returns HList<Value>

equals

Parameters

Returns boolean

filter

Parameters

Returns HList<Value>

find

Parameters

Returns undefined | Value

flat

Type Parameters

Returns HList<NewValue>

forEach

Parameters

Returns void

get

Parameters

Returns undefined | Value

getKind

Returns Kind

includes

Parameters

Returns boolean

insert

Parameters

Returns this

inspect

`Static`make