space-lift "Lift your values into space for infinite possibilities"

Note: Starting from version 1.0.0, space-lift no longer contains the Option and Result monads. You can find these at space-monad

Rich Array, Object, Map, Set wrapper

Design goals

100% immutable, no magic, no overwhelming polymorphism or dynamic operators
Fun to use
Correctness and first-class typescript typings
Tiny and performant (space-lift weights 7.2 kB minified for roughly the same scope as lodash (70.0 kB) AND immerjs (15.6 kB)) and no amount of tree shaking can save you from heavy abstractions imported by all modules.
Small set of functions, configurable with lambdas
Cover 95% of frontend data transformation needs without becoming a bloated lib just to cover the remaining 5%

spacelift lib size

How to use
Examples
API
- Array
- Object
- Map
- Set
- update
- createEnum
- createUnion
- Result
- toDraft]
Auto unwrap

How to use

Here's everything that can be imported from space-lift:

import {
  lift,
  update,
  range,
  is,
  createUnion,
  createEnum,
  identity,
  noop,
  Result,
  Ok,
  Err,
  Immutable
} from 'space-lift'

lift is the main attraction and is used to wrap an Array, Object, Map or Set to give it extra functionalities
update can update an Object, Array, Map or Set without modifying the original
range is a factory function for Arrays of numbers
is is a helper used to determine if an instance is of a particular type (e.g is.array([]) === true)
createUnion creates a bunch of useful things when working with discriminated unions.
createEnum creates a bunch of useful things when working with a string based enum.
identity the identity function
noop a function that does nothing
Result, Ok, Err are used to work with computation that may fail
Immutable a helper type that will recursively make a tree Readonly.

Some Examples

Update an object inside an Array

import { update } from 'space-lift'

const people = [
  { id: 1, name: 'jon' },
  { id: 2, name: 'sarah' },
  { id: 3, name: 'nina' }
]

const updatedPeople = update(people, draft => {
  draft.updateIf(
    p => p.id === 2,
    personDraft => {personDraft.name = 'Nick'})
})

Sort on two fields

import lift from 'space-lift'

const people = [
  { first: 'jon',   last: 'haggis' },
  { first: 'sarah', last: 'john' },
  { first: 'nina',  last: 'pedro' }
]

// This will create an Array sorted by first name, then by last name
const sortedPeople = lift(people)
  .sort(p => p.first, p => p.last)
  .value()

API

Array

append
appendAll
compact
count
collect
distinct
drop
dropRight
filter
first
flatMap
flatten
reduce
get
groupBy
grouped
insert
last
map
removeAt
reverse
sort
take
takeRight
toSet
updateAt
pipe

Array.append

Appends one item at the end of the Array.

import {lift} from 'space-lift'
const updated = lift([1, 2, 3]).append(4).value() // [1, 2, 3, 4]

Array.appendAll

Appends an Iterable of items at the end of the Array.

import {lift} from 'space-lift'
const updated = lift([1, 2, 3]).appendAll([4, 5]).value() // [1, 2, 3, 4, 5]

Array.compact

Filters all the falsy elements out of this Array.
All occurences of false, null, undefined, 0, "" will be removed.

import {lift} from 'space-lift'
const updated = lift([1, null, 2, 3, undefined]).compact().value() // [1, 2, 3]

Array.count

Counts the items satisfying a predicate.

import {lift} from 'space-lift'
const count = lift([1, 2, 3]).count(n => n > 1) // 2

Array.collect

Maps this Array's items, unless void or undefined is returned, in which case the item is filtered.
This is effectively a filter + map combined in one.

import {lift} from 'space-lift'
const count = lift([1, 2, 3]).collect(n => {
  if (n === 1) return;
  return `${n*10}`
}).value() // ['20', '30']

Array.distinct

Creates an array without any duplicate item.
If a key function is passed, items will be compared based on the result of that function;
if not, they will be compared using strict equality.

import {lift} from 'space-lift'

const people = [{id: 1, name: 'Alexios'}, {id: 2, name: 'Bob'}, {id: 1, name: 'Alessia'}]

// [{id: 1, name: 'Alexios'}, {id: 2, name: 'Bob'}]
const deduped = lift(people).distinct(p => p.id).value()

Array.drop

Drops the first 'count' items from this Array.

import {lift} from 'space-lift'
const updated = lift([1, 2, 3]).drop(2).value() // [3]

Array.dropRight

Drops the last 'count' items from this Array.

import {lift} from 'space-lift'
const updated = lift([1, 2, 3]).dropRight(2).value() // [1]

Array.filter

Filters this array by aplying a predicate to all items and refine its type.

import {lift} from 'space-lift'
const filtered = lift([1, 2, 3]).filter(n => n > 1).value() // [2, 3]

Array.first

Returns the first element in this Array or undefined.

import {lift} from 'space-lift'
const first = lift([1, 2, 3]).first() // 1

Array.flatMap

Maps this Array to an Array of Array | ArrayWrapper using a mapper function then flattens it.

import {lift} from 'space-lift'
const mapped = lift([1, 2, 3]).flatMap(n => [n + 1, n + 2]).value() // [2, 3, 3, 4, 4, 5]

Array.flatten

Flattens this Array of Arrays.

import {lift} from 'space-lift'
const flattened = lift([1, [2], [3, 4]]).flatten().value() // [1, 2, 3, 4]

Array.reduce

Reduces this Array into a single value, using a starting value.

import {lift} from 'space-lift'
const count = lift([1, 2, 3]).reduce(0, (count, n) => count + n) // 6

Array.get

Returns the item found at the provided index or undefined.

import {lift} from 'space-lift'
const secondItem = lift([1, 2, 3]).get(1) // 2

Array.groupBy

Creates a Map where keys are the results of running each element through a discriminator function.
The corresponding value of each key is an array of the elements responsible for generating the key.

import {lift} from 'space-lift'
const people = [
  { age: 10, name: 'jon' },
  { age: 30, name: 'momo' },
  { age: 10, name: 'kiki' },
  { age: 28, name: 'jesus' },
  { age: 29, name: 'frank' },
  { age: 30, name: 'michel' }
]

// Map<number, Array<{age: number, name: string}>>
const peopleByAge = lift(people).groupBy(p => p.age).value()

Array.grouped

Creates a new Array where each sub array contains at most 'bySize' elements.

import {lift} from 'space-lift'
const numbers = [1, 2, 3, 4, 5, 6, 7]

// [[1, 2], [3, 4], [5, 6], [7]]
const groupedNumbers = lift(numbers).grouped(2).value()

Array.insert

Inserts an item at a specified index.

import {lift} from 'space-lift'
const updated = lift(['1', '2', '3']).insert(1, '20').value() // [1, 20, 2, 3]

Array.last

Returns the item found at the last index or undefined.

import {lift} from 'space-lift'
const last = lift(['1', '2', '3']).last() // '3'

Array.map

Maps this Array using a mapper function.

import {lift} from 'space-lift'
const mapped = lift(['1', '2', '3']).map(str => '0' + str).value() // ['01', '02', '03']

Array.removeAt

Removes the item found at the specified index.

import {lift} from 'space-lift'
const updated = lift(['1', '2', '3']).removeAt(1).value() // ['1', '3']

Array.reverse

Reverses the Array.

import {lift} from 'space-lift'
const updated = lift(['1', '2', '3']).reverse().value() // ['3', '2', '1']

Array.sort

Sorts the Array in ascending order, using one or more iterators specifying which field to compare.
For strings, localCompare is used.
The sort is stable if the browser uses a stable sort (all modern engines do)

import {lift} from 'space-lift'

const people = [
  { name: 'Jesse', creationDate: 2 },
  { name: 'Walt', creationDate: 1 },
  { name: 'Mike', creationDate: 4 },
  { name: 'Skyler', creationDate: 3 }
]

const sorted = lift(people)
  .sort(p => p.creationDate)
  .map(p => p.name)
  .value() // ['Walt', 'Jesse', 'Skyler', '

Spacelift

Install / Use

README