init: version 1.0.0

.babelrc

@@ -0,0 +1,14 @@
+{
+    "comments": false,
+    "presets": [
+        [
+            "@babel/preset-env",
+            {
+                "targets": {
+                    "node": "8.0.0"
+                }
+            }
+        ]
+    ],
+    "plugins": []
+}

.editorconfig

@@ -0,0 +1,16 @@
+# editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_style = space

.eslintrc.yml

@@ -0,0 +1,5 @@
+# YAML allows comments.
+root: true
+extends: [fullstack, prettier, prettier/react]
+rules:
+    id-length: 0

.github/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing to this Project
+
+Thank you for your interest! Please note that for pull requests to be merged, you should:
+
+*   Include unit tests
+*   Add any relevant documentation
+*   Reference any relevant issues

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,9 @@
+_Write your issue description here_
+
+---
+
+For bugs, please include the following:
+
+*   What is the expected behavior?
+*   What is the actual behavior?
+*   What steps reproduce the behavior?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+_Write your PR notes here_
+
+---
+
+### Assignee Tasks
+
+*   [ ] added unit tests
+*   [ ] written relevant docs
+*   [ ] referenced any relevant issues

.gitignore

@@ -0,0 +1,37 @@
+# Precommit build flag hack
+.commit
+
+# Build
+build
+dist
+
+# Cache
+.eslintcache
+
+# Packages
+node_modules
+bower_components
+
+# OS-generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs and databases
+*.log
+*.sqlite
+
+# Vim swap files
+*.sw?
+
+# IDE files
+.idea
+.vscode
+
+# repos / submodules
+.git
+.svn

.npmignore

@@ -0,0 +1,37 @@
+# Precommit build flag hack
+.commit
+
+# Build
+!build
+dist
+
+# Cache
+.eslintcache
+
+# Packages
+node_modules
+bower_components
+
+# OS-generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs and databases
+*.log
+*.sqlite
+
+# Vim swap files
+*.sw?
+
+# IDE files
+.idea
+.vscode
+
+# repos / submodules
+.git
+.svn

.prettierignore

@@ -0,0 +1,2 @@
+package.json
+package-lock.json

.prettierrc.yml

@@ -0,0 +1,9 @@
+# printWidth: 80 # 80
+# tabWidth: 4 # 2
+# useTabs: false # false
+semi: false # true
+singleQuote: true # false
+trailingComma: es5 # none | es5 | all
+# bracketSpacing: true # true
+# jsxBracketSameLine: false # false
+# arrowParens: avoid # avoid | always

.travis.yml

@@ -0,0 +1,11 @@
+dist: trusty # uses trusty environment
+sudo: false # when on trusty, uses Docker containers for speed
+notifications:
+  email:
+    on_success: change # default: change (only when going from broken to fixed)
+    on_failure: always # default: always (which is annoying, as it should be)
+language: node_js
+node_js:
+  - node # uses most recent stable node version
+install:
+  - npm ci # faster, goes only from package-lock

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age,
+body size, disability, ethnicity, gender identity and expression, level of
+experience, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+*   Using welcoming and inclusive language
+*   Being respectful of differing viewpoints and experiences
+*   Gracefully accepting constructive criticism
+*   Focusing on what is best for the community
+*   Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+*   The use of sexualized language or imagery and unwelcome sexual attention
+    or advances
+*   Trolling, insulting/derogatory comments, and personal or political attacks
+*   Public or private harassment
+*   Publishing others' private information, such as a physical or electronic
+    address, without explicit permission
+*   Other conduct which could reasonably be considered inappropriate in a
+    professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an
+appointed representative at an online or offline event. Representation of a
+project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team lead or repo owner. All complaints will
+be reviewed and investigated and will result in a response that is deemed
+necessary and appropriate to the circumstances. The project team is obligated
+to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at [http://contributor-covenant.org/version/1/4][vrsn]
+
+[homepage]: http://contributor-covenant.org
+[vrsn]: http://contributor-covenant.org/version/1/4/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Gabriel Lebec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,91 @@
+# Batching-Toposort
+
+Efficiently sort interdependent tasks into a sequence of concurrently-executable batches.
+
+```hs
+batchingToposort :: { DependencyId : [DependentId] } -> [[TaskId]]
+```
+
+*   `O(t + d)` time complexity (for `t` tasks and `d` dependency relationships)
+*   `O(t)` space complexity
+*   Zero package dependencies
+*   Thoroughly tested
+*   Errors on cyclic graphs
+
+## Motivation
+
+Often one needs to schedule interdependent tasks. In order to determine task order, the classic solution is to use [topological sort](https://en.wikipedia.org/wiki/Topological_sorting). However, toposort typically outputs a list of individual tasks, without grouping those that can be executed concurrently. Batching-Toposort takes this additional consideration into account, producing a list of lists of tasks. The outer list is ordered; each inner list is unordered.
+
+## Usage
+
+```sh
+npm install batching-toposort
+```
+
+<img align="right" width="250" src="images/graph.png">
+
+Batching-Toposort expects a [directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) implemented via [adjacency list](https://en.wikipedia.org/wiki/Adjacency_list). In other words, construct an object whose keys are dependency IDs, and whose values are lists of dependent IDs.
+
+```js
+const batchingToposort = require('batching-toposort')
+
+// DAG :: { DependencyId : [DependentId] }
+const DAG = {
+    a: ['c', 'f'], // `a` is a dependency of `c` and `f`
+    b: ['d', 'e'],
+    c: ['f'],
+    d: ['f', 'g'],
+    e: ['h'],
+    f: ['i'],
+    g: ['j'],
+    h: ['j'],
+    i: [],
+    j: [],
+}
+
+// batchingToposort :: DAG -> [[TaskId]]
+const taskBatches = batchingToposort(DAG)
+// [['a', 'b'], ['c', 'd', 'e'], ['f', 'g', 'h'], ['i', 'j']]
+```
+
+(If there is demand, Batching-Toposort may one day include a small DAG API and/or [DOT](<https://en.wikipedia.org/wiki/DOT_(graph_description_language)>) support for convenience, but as of now it is the developer's role to construct the graph.)
+
+## Implementation
+
+In short, Batching-Toposort adapts [Kahn's Algorithm](https://en.wikipedia.org/wiki/Topological_sorting#Kahn's_algorithm) by inserting each round of root tasks into sublists rather than appending tasks directly to the main output list.
+
+The classic DAG toposort keeps track of each task's in-degree (number of dependencies). As root tasks (those with no dependencies) are added to the output list, their dependents' in-degree counts are decremented. For a task to become a root, all of its dependencies must have been accounted for. The core algorithm is illustrated below in pseudocode (the actual implementation is in [`src/index.js`](src/index.js)).
+
+```
+given G = adjacency list of tasks and dependents (~O(1) lookup):
+
+let N = map from tasks to in-degree counts (~O(1) lookup / update)
+let L = [] (empty output list) (~O(1) append)
+let R1 = list of root tasks (~O(1) addition, ~O(n) iteration)
+
+while R1 is nonempty
+    append R1 to L
+    let R2 = [] (empty list for next batch) (~O(1) append)
+    for each task T in R1
+        for each dependent D of T (as per G)
+            decrement in-degree count for D (in N)
+            if D's in-degree (as per N) is 0
+                add D to R2
+    R1 = R2
+
+return L
+```
+
+### Performance
+
+The time complexity is `O(|V| + |E|)` for `V` task vertices and `E` dependency edges.
+
+*   The algorithm loops through rounds of roots, and every task is only a root only once, contributing to `O(|V|)` rounds (worst case is a linked list of tasks).
+*   Each round handles a disjoint set of dependency edges (those rooted in that round's tasks), so the `O(|E|)` handling of all edges is effectively distributed across rounds.
+*   Other operations, e.g. querying a node's in-degree (average case `O(1)`), are carefully managed to preserve the time complexity.
+
+The space complexity is slightly better at `O(|V|)`.
+
+*   The in-degree map size is proportional to the number of vertices `|V|`, but not edges, as those are folded into an integer count during map construction.
+*   The output by definition contains `|V|` tasks (distributed among as many or fewer lists).
+*   Again, other operations are controlled to keep space complexity low.