From f7d0042b69d92bdb4d8d617a8eec62c9fd759dac Mon Sep 17 00:00:00 2001 From: Oleg Gaidarenko Date: Tue, 19 Jun 2018 18:15:05 +0300 Subject: [PATCH] Various improvements for the docs and stuff (#7) * Simplifing documentation a bit - make it less formal * Run tests in newer versions of node as well * Add coveralls integration --- .travis.yml | 5 ++++ COMPARE.md | 6 ++--- CONTRIBUTING.md | 42 ++++++++++++++++--------------- README.md | 66 ++++++++++++++++++++++--------------------------- package.json | 7 ++++-- 5 files changed, 65 insertions(+), 61 deletions(-) diff --git a/.travis.yml b/.travis.yml index 4909f83c..4e122a4a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,3 +1,8 @@ language: node_js node_js: - "6" + - "8" + - "10" +script: + - npm run test:ci + \ No newline at end of file diff --git a/COMPARE.md b/COMPARE.md index 21f57b15..7829a5a0 100644 --- a/COMPARE.md +++ b/COMPARE.md @@ -1,7 +1,7 @@ # Comparison with other libraries ## [Ramda](http://ramdajs.com/) -Ramda was a massive influence on Tinkoff Utils It borrowed the same functional programming approach, naming, and many other things. However, Tinkoff Utils doesn't provide placeholders, lenses and some other less popular stuff. +Ramda was a huge inspiration for Tinkoff Utils! it has a lot of similarities with naming style, uses same functional programming approach and many other things, with lack of some less popular design ideas like `__` prefixes, lenses and etc | Ramda | Utils | | --- | ------ | @@ -114,8 +114,8 @@ Ramda was a massive influence on Tinkoff Utils It borrowed the same functional p ## [Lodash](https://lodash.com/) -Be careful when migrating from lodash to Utils: -1. Check function signature, since Utils uses data as the last argument in contrast with lodash +When migrating from lodash to Utils, keep in mind that – +1. Lodash has different function signatures, since Utils uses data as the last argument in contrast with lodash 1. Singular lodash methods can accept various argument types when Utils functions are focused and cohesive 1. Some Lodash functions mutate passed arguments diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c19d4063..2c49336b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,31 +1,34 @@ # Contributing -1. Fork this repository. -1. Install dependencies with `npm install`. -1. Make sure tests are passing running `npm run test`. -1. Make your changes. Make sure the commands `npm run build` and `npm run test` are not failing. -1. Finally send a GitHub Pull Request with a clear list of what you've done (read more [about pull requests](https://help.github.com/articles/about-pull-requests/)). Make sure all of your commits are atomic (one feature per commit). +1. Fork this repository +1. Create a future branch (don't make changes in master branch) +1. Install dependencies with `npm install` +1. Make sure tests are passing by running `npm test` +1. Make your changes. Make sure `npm run build` and `npm test` will not fail +1. Send us pull request with a clear list of what you've done (read more [about pull requests](https://help.github.com/articles/about-pull-requests/)). Make sure all of your commits are atomic (one feature per commit) and have tests ## How to add new utility -1. Decide where to place new utility according to the structure of the library. -1. Pick the name of the new utility (corresponding to the functionality or well-known name if there is analog in other libraries (ramda, lodash)) -1. Create a new file with picked named in the corresponding directory, and add a file with the same name to the '_\_tests__' directory. -1. Implement new functionality. For autocurrying wrap utility to `/function/curry` or `/function/curryN` (`curry` doesn't support default and rest arguments, so prefer `curryN`). -1. Add tests (don't forget edge cases and exceptions). -1. Add JSDoc with the description of functionality, arguments types and a little example. +1. Pick the descriptive name for the new utility +1. Decide where to place it +1. Create a new file with the same name at the proper path, and add a file with the same name to the `__tests__` directory +1. Implement new functionality +1. Add tests (don't forget edge cases and exceptions) +1. Add JSDoc with the description of functionality, arguments types and a small example -## How to write JSDoc right -List of supported tags is [here](https://esdoc.org/manual/tags.html). +**Protip**: For autocurrying wrap utility to `/function/curry` or `/function/curryN` (`curry` doesn't support default and rest arguments, so for the most cases use `curryN`) + +## How to write JSDoc +First, check out [documentation](https://esdoc.org/manual/tags.html) for all supported tags. JSDoc should contain the following: -1. The description of a utility. -1. Add arguments types and description for them (see @param). -1. Add the type and the description of the return value (see @return). -1. Add an example to demonstrate the usage of a utility (see @example). +1. Description of a utility +1. Arguments types and description for them (see [`@param`](http://usejsdoc.org/tags-param.html)) +1. Add type and description for the return value (see [`@return`](http://usejsdoc.org/tags-returns.html)) +1. Add an example to demonstrate the usage of a utility (see [`@example`](http://usejsdoc.org/tags-example.html)) -If there is some additional information you want to add, prepend it with `**Note:**`. +If there is some additional information you want to add, prepend it with `**Note:**` ### Example -```javascript +```js import curryN from '../function/curryN'; /** @@ -37,7 +40,6 @@ import curryN from '../function/curryN'; * @return {Boolean} `true` if the predicate is satisfied by at least one element, `false` * otherwise. * @example - * * var lessThan0 = x => x < 0; * var lessThan2 = x => x < 2; * any(lessThan0)([1, 2]); //=> false diff --git a/README.md b/README.md index 7ed44dd2..2cc0a550 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,31 @@ -# Tinkoff Utils -[![Build Status](https://travis-ci.org/TinkoffCreditSystems/utils.js.svg?branch=master)](https://travis-ci.org/TinkoffCreditSystems/utils.js) +# Tinkoff Utils [![Build](https://travis-ci.org/TinkoffCreditSystems/utils.js.svg?branch=master)](https://travis-ci.org/TinkoffCreditSystems/utils.js) [![Coverage Status](https://coveralls.io/repos/github/TinkoffCreditSystems/utils.js/badge.svg?branch=master&t=CdowK8)](https://coveralls.io/github/TinkoffCreditSystems/utils.js?branch=master) -JavaScript utility library with the primary task to simplify work with data, functions, promises, and more. -The main goals of the library are modularity, functional style, performance, and simplicity. +> Fast, small and purely functional utility library -## Example -Installation -```bash -$ npm i --save @tinkoff/utils +## Install +``` +$ npm install @tinkoff/utils ``` -Usage -```javascript +## Features +- [Fast](#benchmarks) +- [Small](#bundle-size) +- [Fully tested](https://coveralls.io/github/TinkoffCreditSystems/utils.js) +- [Documented](https://tinkoffcreditsystems.github.io/utils.js) +- Purely functional +- Modern codebase + +## Structure of the library +* [`/object`](./src/object) – for objects +* [`/string`](./src/string) – for strings +* [`/promise`](./src/promise) – for promises +* [`/array`](./src/array) – for arrays or array-like objects +* [`/function`](./src/function) – for functions – composition, currying and so on, also a set of simple functions (noop, T, F) +* [`/is`](./src/is) – set of type checking methods +* [`/`](./src) – root contains utilities which don't satisfy any of the above categories or are universal + +## Usage +```js import pathOr from '@tinkoff/utils/object/pathOr'; import compose from '@tinkoff/utils/function/compose'; import toLower from '@tinkoff/utils/string/toLower'; @@ -24,29 +38,10 @@ const toLowerName = compose( const result = map(toLowerName)([{name: 'testA'}, {name: 'testb'}]) ``` -## Features -- Modular structure: utilities are located each in its file, structured by type. -- Written with performance in mind. -- Suitable for functional programming: every utility is a pure function with the order of arguments, convenient for currying. -- Modern codebase: project is written in ES2015+. -- Safe and secure to use: every utility is documented and covered with tests. - -## The structure of the library -* `/array`: a set of utilities to operate on arrays or array-like objects; -* `/function`: a set of utilities to operate on functions (composition, currying and so on), also a set of simple functions (noop, T, F); -* `/is`: a set of type-checking utilities; -* `/object`: a set of utilities to operate on objects; -* `/promise`: a set of promise utilities; -* `/string`: a set of utilities to work with strings; -* `/`: the root contains utilities that don't satisfy any of the above categories or are universal. - -## Comparison with other libraries -The comparison is between Tinkoff Utils and the following libraries: -* lodash 4.7.14 -* ramda 0.22.1 - -### Benchmarks -You can find benchmarks in the `__benchmarks__` directory. +## Benchmarks +```bash +$ npm run benchmark +``` | Utility | Lodash | Ramda | Utils | | --- | --- | --- | --- | @@ -57,8 +52,7 @@ You can find benchmarks in the `__benchmarks__` directory. | object/path | 12,023,128 ops/sec | 8,894,639 ops/sec | 7,587,076 ops/sec | | string/trim | 4,215,928 ops/sec | 1,034,655 ops/sec | 6,029,794 ops/sec | -### Bundle size -Bubdle size is compared to each other with the assumption that we need only a small subset of library methods (see details [here](./bundleSize)): +## Bundle size | Library | Bundle size | | --- | --- | | import _ from 'lodash' | 70.1 kb | @@ -67,4 +61,4 @@ Bubdle size is compared to each other with the assumption that we need only a sm | import ... from 'ramda/src/...' | 10 kb | | import ... from '@tinkoff/utils/...' | 2.32 kb | -The detailed comparison with specific library see [COMPARE.md](./COMPARE.md) +For detailed comparison with specific libraries see [COMPARE.md](./COMPARE.md) diff --git a/package.json b/package.json index 6fe6fcf9..08e1ee14 100644 --- a/package.json +++ b/package.json @@ -8,10 +8,11 @@ "prebenchmark": "npm install --no-save lodash ramda lazy.js underscore", "docs": "esdoc", "test": "jest --coverage", - "pretest": "npm install --no-save react" + "test:ci": "npm run test && cat ./coverage/lcov.info | coveralls" }, - "description": "JavaScript utility library for simplifying the work with data, functions, promises, etc.", + "description": "Fast, small and purely functional utility library", "repository": "https://github.com/TinkoffCreditSystems/utils.js", + "bugs": "https://github.com/TinkoffCreditSystems/utils.js/issues", "keywords": [ "tinkoff", "utils", @@ -28,6 +29,7 @@ "babel-preset-react": "^6.24.1", "benchmark": "^2.1.4", "chalk": "^2.4.1", + "coveralls": "^3.0.1", "esdoc": "^1.1.0", "esdoc-ecmascript-proposal-plugin": "^1.0.0", "esdoc-importpath-plugin": "^1.0.2", @@ -37,6 +39,7 @@ "inquirer": "^5.2.0", "jest": "^23.0.0", "ora": "^2.1.0", + "react": "^16.4.1", "walker": "^1.0.7" } }