chore: add website and move docs

Author: the-spyke

.eslintrc.json

@@ -99,6 +99,12 @@
 			}
 		],
 		"import/no-extraneous-dependencies": "error",
+		"import/no-unresolved": [
+			"error",
+			{
+				"commonjs": true
+			}
+		],
 		"indent": [
 			"error",
 			"tab",

README.md

@@ -15,24 +15,13 @@ JavaScript data processing pipelines and utilities. Use native Iterators/Generat
 - Lazy evaluation when possible
 - Tree shaking friendliness
 
-## Quicklinks
-
-- [Installation](#installation)
-- [Usage](#usage)
-- [Concepts](#concepts)
-- [Pull](packages/undercut-pull/README.md)
-- [Push](packages/undercut-push/README.md)
-- [Operations](operations.md)
-- [Utilities](packages/undercut-utils/README.md)
-- [License](#license)
-
 ## Installation
 
 There are 3 main packages:
 
-- [`@undercut/pull`](https://www.npmjs.com/package/@undercut/pull) -- exports Pull Lines (Iterables). [\[documentation\]](packages/undercut-pull/README.md)
-- [`@undercut/push`](https://www.npmjs.com/package/@undercut/push) -- exports Push Lines (Observers). [\[documentation\]](packages/undercut-push/README.md)
-- [`@undercut/utils`](https://www.npmjs.com/package/@undercut/utils) -- exports all the various JavaScript utilities. [\[documentation\]](packages/undercut-utils/README.md)
+- [`@undercut/pull`](https://www.npmjs.com/package/@undercut/pull) -- exports Pull Lines (Iterables).
+- [`@undercut/push`](https://www.npmjs.com/package/@undercut/push) -- exports Push Lines (Observers).
+- [`@undercut/utils`](https://www.npmjs.com/package/@undercut/utils) -- exports all the various JavaScript utilities.
 
 These packages are the intended way to use `undercut`. They carry `stable ES Next` code. It is very convenient for apps using Webpack/Babel/etc, and will help to avoid double compilation and deoptimization. Only [finished proposals (Stage 4)](https://github.com/tc39/proposals/blob/master/finished-proposals.md) may be used in its codebase. The code is universal and may be used in Node/Browser/microwave.
 
@@ -48,11 +37,11 @@ yarn add @undercut/pull
 
 ### Additional packages
 
-Several precompiled packages are available for older projects or quick experiments. They do not require any sort of compilaton:
+Several precompiled packages are available:
 
-- [`@undercut/cli`](https://www.npmjs.com/package/@undercut/cli) -- provides a command line interface for processing data with JavaScript and `undercut` in a shell. Accepts string items from `stdin` and puts results as strings into `stdout`. This package is compiled for Node.js 10 LTS and upwards. [\[documentation\]](packages/undercut-cli/README.md)
-- [`@undercut/node-10`](https://www.npmjs.com/package/@undercut/node-10) -- a precompiled CommonJS version for Node.js 10 LTS and upwards. Requires stable polyfills from `core-js@3`. [\[documentation\]](packages/undercut-node-10/README.md)
-- [`@undercut/web-2019`](https://www.npmjs.com/package/@undercut/web-2019) -- a precompiled version for web browsers not older than 2019-01-01. Creates `undercut` property in the `window`, may also be used by CJS/AMD loaders. Requires stable polyfills from `core-js@3`. [\[documentation\]](packages/undercut-web-2019/README.md)
+- [`@undercut/cli`](https://www.npmjs.com/package/@undercut/cli) -- provides a command line interface for processing data with JavaScript and `undercut` in a shell. Accepts string items from `stdin` and puts results as strings into `stdout`. Works on Node.js 10.13 and upwards.
+- [`@undercut/node-10`](https://www.npmjs.com/package/@undercut/node-10) -- a precompiled CommonJS version for Node.js 10.13 and upwards. Requires stable polyfills from `core-js@3`.
+- [`@undercut/web-2019`](https://www.npmjs.com/package/@undercut/web-2019) -- a precompiled version for web browsers not older than `2019-01-01`. Creates `undercut` variable in the global scope, may also be used by CJS/AMD loaders. Requires stable polyfills from `core-js@3`.
 
 ### Updating `undercut`
 
@@ -76,6 +65,8 @@ console.log(result); // [8, 10, 14]
 
 ## Concepts
 
+*\* Please visit the website for full documentation or look in the `docs` folder.*
+
 `Undercut` helps constructing pipelines for data processing. Instead of creating new concepts it leverages existing JavaScript protocols and features like [Iteration protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and [Generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*).
 
 `Pipelines` is just a term for ordered sequences of operations (just like a conveyor on a factory). Imagine you want to process a bunch of `source` items and put the result items somewhere (`target`).
@@ -105,14 +96,6 @@ Push line -- push items into an Observer
 
 Of course, you can process synchronous items with `Push Lines` too, but `Pull Lines` are easier to operate and write operations for.
 
-## [Pull](packages/undercut-pull/README.md)
-
-## [Push](packages/undercut-push/README.md)
-
-## [Operations](operations.md)
-
-## [Utilities](packages/undercut-utils/README.md)
-
 ## License
 
 Licensed under the MIT License, see [LICENSE](LICENSE) for more information.

docs/cli/examples.md

@@ -0,0 +1,40 @@
+---
+title: CLI Examples
+---
+
+### Pipe data through like you usually do in a shell
+
+```bash
+$ cat strings.txt | undercut 'map(s => s.trim())' 'filter(s => s.length > 10)'
+Hello world!
+A very long string...
+```
+
+Use an Iterable as a `source` instead of `stdin`:
+
+```bash
+$ undercut -s 'range(0, 5)' 'map(Math.sqrt)' 'sum()'
+6.146264369941973
+```
+
+### Import an installed `npm` package and use it
+
+```bash
+$ undercut -i 'pad::left-pad' -s 'range(0, 3)' 'map(x => pad(x, 3))'
+000
+001
+002
+```
+
+### Enter text data from keyboard by skipping a source
+
+Results will be printed to `stdout` after you signal the end of input with `Ctrl + D`:
+
+```bash
+$ undercut 'map(s => s.toUpperCase(s))'
+Tom
+Sam
+# Ctrl + D to finish the input.
+TOM
+SAM
+```

docs/cli/overview.md

@@ -0,0 +1,43 @@
+---
+title: CLI Overview
+---
+
+`@undercut/cli` is a command line utility for data processing using `undercut`'s Push Lines and any valid JavaScript expressions.
+
+## Installation
+
+```bash
+npm install --global @undercut/cli
+# or
+yarn global add @undercut/cli
+```
+
+You may also install it locally, but don't forget to add `node_modules/.bin` to the `PATH`.
+
+## Usage
+
+The name of the installed command is `undercut`. You may also import the `run` function from the `@undercut/cli` to call it programmatically.
+
+```bash
+undercut [...options] [...operations]
+```
+
+You're building a `Push Line` where the source is `stdin` and the target is `stdout`. Operations should be quoted (prevents parsing by the shell) and separated by spaces. You can use everything that is available in the global context of Node.js. `undercut`'s packages are available too under their names: `pull`, `push`, and `utils`.
+
+```bash
+undercut 'map(s => parseInt(s, 10))' 'filter(utils.isNumberValue)'
+```
+
+If your expression starts with a call to a `push` exported function, you may omit `"push."` prefix there:
+
+```bash
+undercut 'composeOperations([push.sortStrings(utils.desc)])'
+          ^                  ^--- but not here
+          |--- skip prefix here
+```
+
+Any valid JavaScript expression resulting into a `PushOperation` works:
+
+```bash
+undercut 'observer => observer' # Does nothing useful, but works.
+```

docs/concepts.md

@@ -0,0 +1,32 @@
+---
+title: Concepts
+---
+
+`Undercut` helps constructing pipelines for data processing. Instead of creating new concepts it leverages existing JavaScript protocols and features like [Iteration protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and [Generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*).
+
+`Pipelines` is just a term for ordered sequences of operations (just like a conveyor on a factory). Imagine you want to process a bunch of `source` items and put the result items into a `target`.
+
+```text
+source ----> [ op_0 | op_1 | ... | op_N ] ----> target
+                       pipeline
+```
+
+Depending on the fact whether the `source` items are or aren't yet available you will have two different approaches: `pull` and `push`.
+
+If `source` items **are** available at the moment of execution, we can *pull* items from it one by one and process them synchronously. `Undercut` call this a `Pull Line`. It is created by combining a `source` and a `pipeline` into an `Iterable`. This `Iterable` may be passed around and used by any native ES construct like `for-of` loop to read the result. `Undercut` also provides a bunch of `target` helpers for one-line extracting results out of Iterables into common structures like arrays/objects/maps/etc.
+
+```text
+Pull Line -- pull items from an Iterable
+
+( source + pipeline = Iterable )
+```
+
+If `source` items are **not** available at the moment of execution, we have to process items as they appear. We can do this by *pushing* items into a `Push Line`. It is created by combining a `pipeline` and a `target` into an `Observer`. `Observers` are convenient in use cases like reacting on a button click and may be passed around or used by several producers.
+
+```text
+Push line -- push items into an Observer
+
+( pipeline + target = Observer )
+```
+
+Of course, you can process synchronous items with `Push Lines` too, but `Pull Lines` are easier to operate and write operations for.

docs/introduction.md

@@ -0,0 +1,61 @@
+---
+title: Introduction
+---
+
+`Undercut` is a JavaScript library for building data processing pipelines. It also provides general purpose utilities.
+
+- Based on existing JS protocols and language features
+- Balanced API: not too imperative, not too functional
+- Easy operation extensibility and composability
+- Pure ES Modules with Node 13 loader compliance
+- Raw code in the packages + precompiled versions
+- Lazy evaluation when possible
+- Tree shaking friendliness
+
+## Installation
+
+There are 3 main packages:
+
+- [`@undercut/pull`](pull/overview) -- exports Pull Lines (Iterables).
+- [`@undercut/push`](push/overview) -- exports Push Lines (Observers).
+- [`@undercut/utils`](utils/overview) -- exports all the various JavaScript utilities.
+
+These packages are the intended way to use `undercut` and carry `stable ES Next` code. It is very convenient for apps using Webpack/Babel/etc, and will help to avoid double compilation and deoptimization. Only [finished proposals (Stage 4)](https://github.com/tc39/proposals/blob/master/finished-proposals.md) may be used in its codebase. The code is universal and may be used in Node/Browser/microwave.
+
+Don't forget to check that `/node_modules/@undercut/` isn't excluded from compilation and `core-js@3` polyfill or analogue is in place.
+
+Package main entry points are stable, so any export removal/renaming is as a breaking change.
+
+```bash
+npm install @undercut/pull
+# or
+yarn add @undercut/pull
+```
+
+### Additional packages
+
+Several [precompiled packages](precompiled) are available too:
+
+- `@undercut/cli`
+- `@undercut/node-10`
+- `@undercut/web-2019`
+
+### Updating `undercut`
+
+If you're updating `undercut` to a newer version, please update `@babel/preset-env` and `core-js` packages to the latest versions too.
+
+## Usage
+
+```js
+import { pullArray, filter, map, skip } from "@undercut/pull";
+
+const source = [1, 2, 3, 4, 5, 6, 7];
+
+const result = pullArray([
+    skip(2),
+    filter(x => x % 3 === 0),
+    map(x => x * 2) // Will be executed only 3 times.
+], source);
+
+console.log(result); // [8, 10, 14]
+```

docs/operations/overview.md

@@ -1,8 +1,8 @@
-# Operations
+---
+title: Operations List
+---
 
-## Common operations
-
-These operations exist in both `pull` and `push` versions:
+Currently all operations exist in both `pull` and `push` versions:
 
 - `append(...items)` -- adds its arguments to the end of the sequence.
 - `average()` -- reduces the sequence into a number by calculating the average of it.
@@ -64,11 +64,3 @@ These operations exist in both `pull` and `push` versions:
 - `unzipWith(itemsExtractor)` -- reverse to the `zip` producing a sequence of sources by getting their items from the `extractor`.
 - `zip(...sources)` -- transforms the sequence into a new one by combining by one item from it and the sources into an array.
 - `zipWith(itemFactory, ...sources)` -- transforms the sequence into a new one by combining by one item from it and the source into a value returned by the `itemFactory`.
-
-## Pull-only operations
-
-- N/A
-
-## Push-only operations
-
-- N/A

docs/packages.md

@@ -0,0 +1,62 @@
+---
+title: Precompiled Packages
+---
+
+### `@undercut/cli`
+
+Provides a command line interface for processing data with JavaScript and `undercut` in a shell. Accepts string items from `stdin` and puts results as strings into `stdout`. This package works on Node.js 10.13 and upwards.
+
+[Full documentation.](cli/overview)
+
+### `@undercut/node-10`
+
+A precompiled CommonJS version of `pull/push/utils` packages for Node.js 10.13 and upwards. Requires stable polyfills from `core-js@3`.
+
+Usage is similar to original packages:
+
+```js
+const { pullArray, filter, map, skip } = require("@undercut/node-10/pull");
+
+const source = [1, 2, 3, 4, 5, 6, 7];
+
+const result = pullArray([
+    skip(2),
+    filter(x => x % 3 === 0),
+    map(x => x * 2) // Will be executed only 3 times.
+], source);
+
+console.log(result); // [8, 10, 14]
+```
+
+### `@undercut/web-2019`
+
+A precompiled version of `pull/push/utils` packages for web browsers not older than `2019-01-01`. Creates `undercut` variable in the global scope, may also be used by CJS/AMD loaders. Requires stable polyfills from `core-js@3`.
+
+Usage is similar to original packages, but supports different loading styles. Import desired entry first:
+
+```js
+// When using as a script tag and its global variable:
+const { pullArray, filter, map, skip } = undercut.pull;
+// When using as a CommonJS module:
+const { pullArray, filter, map, skip } = require("@undercut/web-2019/pull");
+// When using local copy as an AMD module:
+require(["scripts/undercut/pull.js"], function ({ pullArray, filter, map, skip }) {
+    /* Your code */
+});
+```
+
+*\* There're [example HTML pages](https://github.com/the-spyke/undercut/tree/master/packages/undercut-web-2019/examples) in the repository.*
+
+And then use it in your code:
+
+```js
+const source = [1, 2, 3, 4, 5, 6, 7];
+
+const result = pullArray([
+    skip(2),
+    filter(x => x % 3 === 0),
+    map(x => x * 2) // Will be executed only 3 times.
+], source);
+
+console.log(result); // [8, 10, 14]
+```