winterbe/sequency

Type-safe functional sequences for processing iterable data in TypeScript and JavaScript.

★★★ Like this project? Leave a star and follow on Twitter! Thanks. ★★★

About Sequency

Sequency is a lightweight (5 KB minified), intensely tested (200+ tests, 99% coverage), type-safe functional programming library for processing iterable data such as arrays, sets and maps. It's written in TypeScript, compiles to ES5-compatible JavaScript and works in all current browsers and Node applications. The API is inspired by Sequences from the programming language Kotlin.

Try Sequency right in your browser.

Getting started

Download the latest release from GitHub or install Sequency from NPM:

npm install --save sequency

Alternatively use Sequency from CDN by adding this to your HTML:

<script src="https://unpkg.com/sequency"></script>

How Sequency works

Sequency is centered around a single class called Sequence to process any kind of iterable data such as arrays, sets or maps. The API is inspired by Kotlin Sequences.

Sequences can be created by utilizing one of the following functions:

import {
    asSequence,
    sequenceOf, 
    emptySequence, 
    range,
    generateSequence,
    extendSequence
} from 'sequency';

• sequenceOf accepts one or many values and returns a new sequence.
• asSequence accepts an iterable (e.g. an array, set or map) and returns a new sequence.
• emptySequence returns a new empty sequence.
• range returns as number sequence consisting of all numbers between startInclusive and endExclusive.
• generateSequence returns a sequence generated from the given generator function.
• extendSequence allows extending sequences with user-defined operations (see example).

Each Sequence provides a fluent functional API consisting of intermediate and terminal operations. Intermediate functions (e.g. filter, map, sorted) return a new sequence, thus enabling method chaining. Terminal functions (e.g. toArray, groupBy, findLast) return an arbitrary result. Detailed descriptions of all operations are available in the API docs.

Sequences are lazily evaluated to avoid examining all of the input data when it's not necessary. Sequences always perform the minimal amount of operations to gain results. E.g. in a filter - map - find sequence both map and find are executed just one time before returning the single result.

API documentation

Sequency is fully documented via inline JSDoc comments. The docs are also available online. When using an IDE like Intellij IDEA or Webstorm the docs are available inline right inside your editor.

Why Sequency?

I've built Sequency because I'm using Kotlin for server-side code but for some reasons still use TypeScript and JavaScript for client-side browser code. I find that using the same APIs for collection processing both on client and server is a huge gain in productivity for me.

License

MIT © winterbe