Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
89 additions
and
121 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,149 +1,117 @@ | ||
| # Rollup Template | ||
| # JS Utils | ||
|
|
||
| This project contains the configuration and build scripts for most of | ||
| my Typescript projects, with scripts to create a new project and keep | ||
| existing ones up-to-date. Even this readme is a template for others. | ||
|
|
||
| ## Features | ||
|
|
||
| - build scripts with `make` | ||
| - build pipeline with `gitlab` | ||
| - update github commit status | ||
| - publish docker images from branches & tags | ||
| - publish npm packages from tags | ||
| - bundled with `rollup` | ||
| - type checked with `typescript` | ||
| - style checked with `eslint` (with `tslint` rules and other plugins) | ||
| - tested with `mocha` (with source map support and helpers for async leak tracking) | ||
| - code coverage measured with `nyc` | ||
| - changelog generated with `standard-release` | ||
|
|
||
| ### Intentionally Omitted Features | ||
|
|
||
| - everything frontend: React, CSS, etc | ||
| - heavy backend libraries: ORMs, etc | ||
| This project is a collection of utilities meant to extend lodash, collected from my | ||
| other Typescript projects, lightly documented, and heavily tested. | ||
|
|
||
| ## Contents | ||
|
|
||
| - [Rollup Template](#rollup-template) | ||
| - [Features](#features) | ||
| - [Intentionally Omitted Features](#intentionally-omitted-features) | ||
| - [JS Utils](#js-utils) | ||
| - [Contents](#contents) | ||
| - [Status](#status) | ||
| - [Releases](#releases) | ||
| - [Usage](#usage) | ||
| - [To Setup](#to-setup) | ||
| - [To Build](#to-build) | ||
| - [To Release](#to-release) | ||
| - [External Services](#external-services) | ||
| - [Maintenance Bots](#maintenance-bots) | ||
| - [External Secrets](#external-secrets) | ||
| - [Features](#features) | ||
|
|
||
| ## Status | ||
|
|
||
| [](https://git.apextoaster.com/ssube/rollup-template/commits/master) | ||
| [](https://sonarcloud.io/dashboard?id=ssube_rollup-template) | ||
| [](https://codecov.io/gh/ssube/rollup-template) | ||
| [](https://github.com/ssube/rollup-template/blob/master/LICENSE.md) | ||
| [](https://app.fossa.com/projects/git%2Bgithub.com%2Fssube%2Frollup-template?ref=badge_shield) | ||
| [](https://git.apextoaster.com/ssube/js-utils/commits/master) | ||
| [](https://sonarcloud.io/dashboard?id=ssube_js-utils) | ||
| [](https://codecov.io/gh/ssube/js-utils) | ||
| [](https://github.com/ssube/js-utils/blob/master/LICENSE.md) | ||
| [](https://app.fossa.com/projects/git%2Bgithub.com%2Fssube%2Fjs-utils?ref=badge_shield) | ||
|
|
||
| [](https://github.com/ssube/rollup-template/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fbug) | ||
| [](https://github.com/ssube/rollup-template/issues?q=is%3Aopen+is%3Aissue) | ||
| [](https://github.com/ssube/rollup-template/issues?q=is%3Aissue+is%3Aclosed) | ||
| [](https://github.com/ssube/js-utils/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fbug) | ||
| [](https://github.com/ssube/js-utils/issues?q=is%3Aopen+is%3Aissue) | ||
| [](https://github.com/ssube/js-utils/issues?q=is%3Aissue+is%3Aclosed) | ||
|
|
||
| [](https://renovatebot.com) | ||
| [](https://david-dm.org/ssube/rollup-template) | ||
| [](https://david-dm.org/ssube/rollup-template?type=dev) | ||
| [](https://snyk.io/test/github/ssube/rollup-template) | ||
| [](https://renovatebot.com) | ||
| [](https://david-dm.org/ssube/js-utils) | ||
| [](https://david-dm.org/ssube/js-utils?type=dev) | ||
| [](https://snyk.io/test/github/ssube/js-utils) | ||
|
|
||
| [](https://codeclimate.com/github/ssube/rollup-template/maintainability) | ||
| [](https://codeclimate.com/github/ssube/rollup-template/trends/technical_debt) | ||
| [](https://codeclimate.com/github/ssube/rollup-template/issues) | ||
| [](https://lgtm.com/projects/g/ssube/rollup-template/context:javascript) | ||
| [](https://lgtm.com/projects/g/ssube/rollup-template/alerts/) | ||
| [](https://codeclimate.com/github/ssube/js-utils/maintainability) | ||
| [](https://codeclimate.com/github/ssube/js-utils/trends/technical_debt) | ||
| [](https://codeclimate.com/github/ssube/js-utils/issues) | ||
| [](https://lgtm.com/projects/g/ssube/js-utils/context:javascript) | ||
| [](https://lgtm.com/projects/g/ssube/js-utils/alerts/) | ||
|
|
||
| ## Releases | ||
|
|
||
| [](https://github.com/ssube/rollup-template/releases) | ||
| [](https://github.com/ssube/rollup-template/releases) | ||
| [](https://github.com/ssube/rollup-template/compare/v0.2.4...master) | ||
| [](https://github.com/ssube/js-utils/releases) | ||
| [](https://github.com/ssube/js-utils/releases) | ||
| [](https://github.com/ssube/js-utils/compare/v0.1.6...master) | ||
|
|
||
| [](https://www.npmjs.com/package/@apextoaster/rollup-template) | ||
| [](https://www.npmjs.com/package/@apextoaster/rollup-template) | ||
| [](https://www.npmjs.com/package/@apextoaster/rollup-template) | ||
| [](https://www.npmjs.com/package/@apextoaster/js-utils) | ||
| [](https://www.npmjs.com/package/@apextoaster/js-utils) | ||
| [](https://www.npmjs.com/package/@apextoaster/js-utils) | ||
|
|
||
| ## Usage | ||
|
|
||
| ### To Setup | ||
|
|
||
| To create a new repository from this template: | ||
|
|
||
| - create your new repo on Github & Gitlab (your server or Gitlab.com) | ||
| - `git clone git@github.com:ssube/rollup-template.git your-project` | ||
| - `cd your-project` | ||
| - `git remote add github git@github.com:yourname/your-project.git` | ||
| - `git remote add gitlab git@gitlab.com:yourname/your-project.git` | ||
| - set up repository mirroring in Gitlab | ||
| - set up [some maintenance bots](#maintenance-bots) | ||
| - `make git-push` | ||
| - install your dependencies | ||
| - write some code | ||
|
|
||
| ### To Build | ||
|
|
||
| Once your project is set up: | ||
| Install: | ||
|
|
||
| - `make` to bundle and test | ||
| - commit | ||
| - `make git-push` | ||
| ```shell | ||
| yarn add -D @apextoaster/js-utils | ||
| ``` | ||
|
|
||
| The `git-push` target pushes to Github first, to avoid conflicts with changes | ||
| from bots and other contributors. | ||
| And import: | ||
|
|
||
| ### To Release | ||
| ```typescript | ||
| import { mustExist } from '@apextoaster/js-utils'; | ||
| ``` | ||
|
|
||
| When your project is ready to release: | ||
| The library is bundled and depends on lodash, linked in a vendor module. | ||
|
|
||
| - `make release-dry` to make sure your changelog and options look right | ||
| - `make release` | ||
|
|
||
| Additional options can be passed with the `RELEASE_OPTS` variable. Frequently | ||
| used options include `--release-as minor` and `--prerelease`. | ||
|
|
||
| ## External Services | ||
|
|
||
| This template works with or expects a few external services, namely a Gitlab | ||
| CI server (self-hosted or using Gitlab.com). | ||
|
|
||
| ### Maintenance Bots | ||
|
|
||
| Good tests and clever bots can eliminate the most painful parts of project | ||
| maintenance. This repository is configured to work with: | ||
|
|
||
| - [CodeCov](https://codecov.io/) | ||
| - [Code Climate](https://codeclimate.com/) | ||
| - [LGTM](https://lgtm.com/) | ||
| - [Renovate](https://renovatebot.com/) | ||
| - [Snyk](https://snyk.io/) | ||
| - [SonarCloud](https://sonarcloud.io/) | ||
|
|
||
| None of these are required, but Renovate and Snyk can be very helpful when | ||
| dependencies release a security patch. | ||
|
|
||
| ## External Secrets | ||
|
|
||
| This template expects a few secrets to exist in the environment, including | ||
| tokens for the [external services](#external-services). | ||
| ## Features | ||
|
|
||
| | Name | Description | | ||
| | ------------------- | ----------------------------------------------------- | | ||
| | CC_TEST_REPORTER_ID | code climate ID | | ||
| | CODECLIMATE_SECRET | code climate token | | ||
| | CODECOV_SECRET | codecov token | | ||
| | DOCKER_SECRET | docker config, required for publishing images | | ||
| | GITHUB_SECRET | github.com token, required for publishing status | | ||
| | NPM_SECRET | npmjs.com token, required for publishing npm packages | | ||
| | SONAR_SECRET | sonarcloud token | | ||
| - array mapper | ||
| - map elements to keys by order | ||
| - skip initial, gather remaining | ||
| - async | ||
| - defer | ||
| - promise timeout | ||
| - wait for predicate | ||
| - async tracker | ||
| - track and log leaking async resources for tests | ||
| - buffer | ||
| - checklist | ||
| - include/exclude mode (whitelist/blacklist) | ||
| - child process | ||
| - wait for exit and gather output | ||
| - write and flush | ||
| - env | ||
| - check `DEBUG` | ||
| - list | ||
| - concat lists | ||
| - logger | ||
| - get test logger (null or console depending on `DEBUG`) | ||
| - map | ||
| - must get (assertion) | ||
| - get or default | ||
| - get head from list value | ||
| - get head or default | ||
| - set or push to key | ||
| - merge maps | ||
| - push-merge maps | ||
| - convert dict to map and vice versa | ||
| - normalize map values to lists | ||
| - create map from name-value pairs | ||
| - maybe | ||
| - is nil test (negative nil test) | ||
| - count array or maybe | ||
| - filter nil from list | ||
| - must find (assertion) | ||
| - does exist (positive nil test) | ||
| - must exist (assertion) | ||
| - must default (assertion) | ||
| - pid file | ||
| - write pid file | ||
| - delete pid file | ||
| - reflect | ||
| - get constructor name | ||
| - get methods from prototype chain | ||
| - signals | ||
| - wait for OS signal | ||
| - string | ||
| - left pad (please don't import just for this) | ||
| - trim with suffix | ||
|
|
||
| Secrets should be provided as environment variables, with the secret value | ||
| `base64`-encoded. |