| 1 | #  [](https://travis-ci.org/winterbe/sequency)
|
| 2 |
|
| 3 | > Type-safe functional sequences for processing iterable data in TypeScript and JavaScript.
|
| 4 |
|
| 5 | 
|
| 6 |
|
| 7 | ---
|
| 8 |
|
| 9 | <p align="center">
|
| 10 | <strong>★★★ Like this project? <a href="https://github.com/winterbe/sequency/stargazers">Leave a star</a>, <a href="https://twitter.com/winterbe_">follow on Twitter</a> or <a href="https://www.paypal.me/winterbe">donate</a> to support my work! Thanks. ★★★</strong>
|
| 11 | </p>
|
| 12 |
|
| 13 | ## About Sequency
|
| 14 |
|
| 15 | 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](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.sequences/-sequence/) from the programming language [Kotlin](https://kotlinlang.org/).
|
| 16 |
|
| 17 | > Not convinced? [Try Sequency](https://npm.runkit.com/sequency) right in your browser.
|
| 18 |
|
| 19 | ## Getting started
|
| 20 |
|
| 21 | Download the [latest release](https://github.com/winterbe/sequency/releases) from GitHub or install Sequency from [NPM](https://www.npmjs.com/package/sequency):
|
| 22 |
|
| 23 | ```bash
|
| 24 | npm install --save sequency
|
| 25 | ```
|
| 26 |
|
| 27 | Alternatively use Sequency from [CDN](https://unpkg.com/sequency/) by adding this to your HTML:
|
| 28 |
|
| 29 | ```html
|
| 30 | <script src="https://unpkg.com/sequency"></script>
|
| 31 | ```
|
| 32 |
|
| 33 | ## How Sequency works
|
| 34 |
|
| 35 | 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](https://kotlinlang.org/) [Sequences](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.sequences/-sequence/index.html).
|
| 36 |
|
| 37 | Sequences can be created by utilizing one of the following functions:
|
| 38 |
|
| 39 | ```js
|
| 40 | import {
|
| 41 | asSequence,
|
| 42 | sequenceOf,
|
| 43 | emptySequence,
|
| 44 | range,
|
| 45 | generateSequence,
|
| 46 | extendSequence
|
| 47 | } from 'sequency';
|
| 48 | ```
|
| 49 |
|
| 50 | - `sequenceOf` accepts one or many values and returns a new sequence.
|
| 51 | - `asSequence` accepts an iterable (e.g. an array, set or map) and returns a new sequence.
|
| 52 | - `emptySequence` returns a new empty sequence.
|
| 53 | - `range` returns as number sequence consisting of all numbers between `startInclusive` and `endExclusive`.
|
| 54 | - `generateSequence` returns a sequence generated from the given generator function.
|
| 55 | - `extendSequence` allows extending sequences with user-defined operations (see [example](https://github.com/winterbe/sequency/blob/ac3dbb0f212bb08783d970472c7a76dc921b60ba/test/extendSequence.test.ts)).
|
| 56 |
|
| 57 | 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](https://winterbe.github.io/sequency/).
|
| 58 |
|
| 59 | 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.
|
| 60 |
|
| 61 | ## [API documentation](https://winterbe.github.io/sequency/interfaces/_sequence_.sequence.html)
|
| 62 |
|
| 63 | Sequency is fully documented via inline JSDoc comments. [The docs are also available online](https://winterbe.github.io/sequency/interfaces/_sequence_.sequence.html). When using an IDE like Intellij IDEA or Webstorm the docs are available inline right inside your editor.
|
| 64 |
|
| 65 | ## Why Sequency?
|
| 66 |
|
| 67 | 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.
|
| 68 |
|
| 69 | ## License
|
| 70 |
|
| 71 | MIT © [Benjamin Winterberg](https://twitter.com/winterbe_)
|