New Pointer API

Let's you point to a specific index inside the array to do further actions on it.

given(['music', 'video', 'tech']).at(1) // returns pointer pointing to 'video'
given(['music', 'video', 'tech']).at(-1) // returns pointer pointing to 'tech'
given(['music', 'video', 'tech']).at(item => item === 'music') // returns pointer pointing to 'music'

append

Appends given value to array in between the currently pointed item and its next item.

given(['music', 'tech']).at(0).append('video') // ['music', 'video', 'tech']

prepend

Prepends given value to array in between the currently pointed item and its previous item.

given(['music', 'tech']).at(1).prepend('video') // ['music', 'video', 'tech']

added only() and except() to map

Added

only

Returns a new map with only the given keys.

  given({ one: 1, two: 2, three: 3 }).only(['one', 'two']) // Map { "one" → 1, "two" → 2 }

except

The inverse of only. Returns a new map with all keys except for the given keys.

  given({ one: 1, two: 2, three: 3 }).except(['one', 'two']) // Map { "three" → 3 }

Fixes

• Added TSDoc method descriptions to all Map methods
• Fix types for flooent Array.filter

New methods for map + support for any iterables

Features

pull

Returns the value for the given key and deletes the key value pair from the map (mutation).

const map = given({ key: 'value' })
map.pull('key') // 'value'
map.has('key') // false

mapKeys

Iterates the entries through the given callback and assigns each result as the key.

const map = given({ a: 1 }).mapKeys((value, key) => key + value)

map.get('a1') // 1

mapValues

Iterates the entries through the given callback and assigns each result as the value.

const map = given({ a: '1' }).mapValues((value, key) => key + value)

map.get('a') // a1

clone

Deep clones a map.

const map = given({ numbers: [1, 2, 3] })
const clone = map.clone()
console.log(map.get('numbers') === clone.get('numbers')) // false

arrange

Rearranges the map to the given keys. Any unmentioned keys will be appended to the end.

given({ strings: 2, numbers: 1, functions: 4 })
  .arrange('numbers', 'functions')
  .keys() // ['numbers', 'functions', 'strings']

Bug fixes

• can create arrayable not only out of arrays but out of any iterable except for map and string

Others

• add README note, types and tests for sorting array entries by index
• throw error when given invalid data type in given function

improved sorting and better flooent map/array integration

Features

sortAsc and sortDesc now accept a callback which result will be used as the compare key.

const numbers = [{ val: 3 }, { val: 1 }, { val: 2 }]
given(numbers).sortAsc(item => item.val) // [{ val: 1 }, { val: 2 }, { val: 3 }]
given(numbers).sortDesc(item => item.val) // [{ val: 3 }, { val: 2 }, { val: 1 }]

Maps

• map.keys(), map.entries(), map.values() now return a flooent array instead of just a normal Array.

toMap

Turns an array in the structure of [ ['key', 'value'] ] into a flooent map.

given({ key: 'value' }).entries().toMap()

So you can now turn the object into an array, do any array manipulation like sorting using the new callback, and finally turn the array back into a map. Common scenarios will later be added to flooent Map directly.

Others

• improved typing
• added a note in the readme about nested objects

Map support, Extending flooent & breaking changes

Features

object support!

Added new type Mappable (extending ES6 Maps) to handle both objects and maps.

The only new method it offers right now is toJSON to turn the map back into a normal object. More to come...

const map = given({ key: 'value' }) // Map { key → "value" }

map.toJSON() // { key: 'value' }

extend flooent as you wish

import { given } from 'flooent'

// first argument can be String, Number, Map, or Array
given.macro(String, 'scream', function() {
  return this.toUpperCase()
})

given('hello').scream() // Stringable { 'HELLO' }

Breaking changes

given(5).times(i => i) now returns an instance of Arrayable instead of a simple Array.

This should not break anything in 99.99% cases.

given(items).groupBy('name') now returns an instance of the new Mappable type instead of an object.

This makes it easier to chain things as you can now directly continue with .entries(), .values(), etc.

To get the old behavior you can chain .toJSON():

given(items).groupBy('name').toJSON()

Removed given(2).max(4, 5) and given(4).min(2, 8)

Instead, make use of the Math equivalents: Math.max(2, 4, 5), Math.min(4, 2, 8).

Add chunk(), pad(), isEmpty(), forPage and opposite of find()

Features

chunk

Breaks the array into multiple, smaller arrays of a given size:

given([1, 2, 3, 4, 5]).chunk(3) // [[1, 2, 3], [4, 5]]

forPage

Returns the items for the given page and size.

given(['a', 'b', 'c', 'd', 'e', 'f', 'g']).forPage(1, 3) // ['a', 'b', 'c']
given(['a', 'b', 'c', 'd', 'e', 'f', 'g']).forPage(2, 3) // ['d', 'e', 'f']
given(['a', 'b', 'c', 'd', 'e', 'f', 'g']).forPage(3, 3) // ['g']
given(['a', 'b', 'c', 'd', 'e', 'f', 'g']).forPage(4, 3) // []

pad

Fills up the array with the given value.

given([1, 2, 3]).pad(5, 0) // [1, 2, 3, 0, 0]

isEmpty

Returns a boolean whether the array is empty or not.

given([]).isEmpty() // true
given([1]).isEmpty() // false

last

You can now pass in a callback to get the last item that passes the given truth test. (opposite of find)

given([1, 2, 3]).last(item => item > 1) // 3

Added until() & better type support

Features

until()

Returns the items until either the given value is found, or the given callback returns true.

given(['a', 'b', 'c']).until('c') // ['a', 'b']
given(['a', 'b', 'c']).until(item => item === 'c') // ['a', 'b']

Others

• improved type support

isBetween(), isBetweenOr() and includedIn() added

Features

includedIn

Checks if string is included in the given array.

given('flooent').includedIn(['flooent', 'string'])

isBetween / isBetweenOr

Check if the number is between two given numbers. isBetweenOr is inclusive, while isBetween is exclusive.

given(5).isBetween(1, 10) // true
given(5).isBetween(5, 10) // false
given(5).isBetweenOr(5, 10) // true

Bug fixes

• make given callback optional for TS

when(), sortAsc(), sortDesc() and sum() added to Arrays

when

Executes callback if first given value evaluates to true. Result will get transformed back into a flooent array.

// can be a boolean
given([]).when(true, str => str.append(1)) // [1]
given([]).when(false, str => str.append(1)) // []

// or a method
given([]).when(array => array.is([]), array => array.append('called')) // ['called']
given([]).when(array => array.is([1]), array => array.append('called')) // []

sum

Returns the sum of the array.

given([2, 2, 1]).sum() // 5

For arrays of objects:

Returns the sum of the given field/result of callback in the array.

  const users = [{ id: 1, points: 10 }, { id: 2, points: 10 }, { id: 3, points: 10 }]

  given(users).sum('points') // 30
  given(users).sum(user => user.points * 10) // 300

sortAsc / sortDesc

Sorts an array in their respective order and returns a new array.

given([3, 1, 2]).sortAsc() // [1, 2, 3]
given([3, 1, 2]).sortDesc() // [3, 2, 1]

const numbers = [{ val: 3 }, { val: 1 }, { val: 2 }]
given(numbers).sortAsc('val') // [{ val: 1 }, { val: 2 }, { val: 3 }]
given(numbers).sortDesc('val') // [{ val: 3 }, { val: 2 }, { val: 1 }]

tap(), pipe() and improved groupBy() and unique() added to Array

Folllowing flooent Strings, flooent Arrays now also provide the tap() and pipe() methods:

pipe

Executes callback and transforms result back into a flooent array.

const someMethodToBePipedThrough = array => array.append(1)

given([]).pipe(someMethodToBePipedThrough) // [1]

tap

Tap into the chain without modifying the array.

given([])
  .append(1)
  .tap(array => console.log(array))
  .append(2)
  // ...

---

Both groupBy() and unique() have been given the option to pass in a callback as the key to be used for comparison.

const items = [{ id: 1, name: 'music' }, { id: 2, name: 'movie' }, { id: 3, name: 'MUSIC' }]
given(items).unique(item => item.name.toLowerCase()) // [{ id: 1, name: 'music' }, { id: 2, name: 'movie' }]

const items = [{ id: 1, name: 'Music' }, { id: 2, name: 'movie' }, { id: 3, name: 'music' }]
given(items).groupBy(item => item.name.toUpperCase())