fix(docs): write a basic readme
This commit is contained in:
parent
64621f7f10
commit
9c5b750c15
GPG Key ID:
3EED7B957D362AF1
210
README.md
210
README.md
|
|
@ -1,149 +1,117 @@
|
||||||
# Rollup Template
|
# JS Utils
|
||||||
|
|
||||||
This project contains the configuration and build scripts for most of
|
This project is a collection of utilities meant to extend lodash, collected from my
|
||||||
my Typescript projects, with scripts to create a new project and keep
|
other Typescript projects, lightly documented, and heavily tested.
|
||||||
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
|
|
||||||
|
|
||||||
## Contents
|
## Contents
|
||||||
|
|
||||||
- [Rollup Template](#rollup-template)
|
- [JS Utils](#js-utils)
|
||||||
- [Features](#features)
|
|
||||||
- [Intentionally Omitted Features](#intentionally-omitted-features)
|
|
||||||
- [Contents](#contents)
|
- [Contents](#contents)
|
||||||
- [Status](#status)
|
- [Status](#status)
|
||||||
- [Releases](#releases)
|
- [Releases](#releases)
|
||||||
- [Usage](#usage)
|
- [Usage](#usage)
|
||||||
- [To Setup](#to-setup)
|
- [Features](#features)
|
||||||
- [To Build](#to-build)
|
|
||||||
- [To Release](#to-release)
|
|
||||||
- [External Services](#external-services)
|
|
||||||
- [Maintenance Bots](#maintenance-bots)
|
|
||||||
- [External Secrets](#external-secrets)
|
|
||||||
|
|
||||||
## Status
|
## Status
|
||||||
|
|
||||||
[](https://git.apextoaster.com/ssube/rollup-template/commits/master)
|
[](https://git.apextoaster.com/ssube/js-utils/commits/master)
|
||||||
[](https://sonarcloud.io/dashboard?id=ssube_rollup-template)
|
[](https://sonarcloud.io/dashboard?id=ssube_js-utils)
|
||||||
[](https://codecov.io/gh/ssube/rollup-template)
|
[](https://codecov.io/gh/ssube/js-utils)
|
||||||
[](https://github.com/ssube/rollup-template/blob/master/LICENSE.md)
|
[](https://github.com/ssube/js-utils/blob/master/LICENSE.md)
|
||||||
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fssube%2Frollup-template?ref=badge_shield)
|
[](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/js-utils/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/js-utils/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%3Aissue+is%3Aclosed)
|
||||||
|
|
||||||
[](https://renovatebot.com)
|
[](https://renovatebot.com)
|
||||||
[](https://david-dm.org/ssube/rollup-template)
|
[](https://david-dm.org/ssube/js-utils)
|
||||||
[](https://david-dm.org/ssube/rollup-template?type=dev)
|
[](https://david-dm.org/ssube/js-utils?type=dev)
|
||||||
[](https://snyk.io/test/github/ssube/rollup-template)
|
[](https://snyk.io/test/github/ssube/js-utils)
|
||||||
|
|
||||||
[](https://codeclimate.com/github/ssube/rollup-template/maintainability)
|
[](https://codeclimate.com/github/ssube/js-utils/maintainability)
|
||||||
[](https://codeclimate.com/github/ssube/rollup-template/trends/technical_debt)
|
[](https://codeclimate.com/github/ssube/js-utils/trends/technical_debt)
|
||||||
[](https://codeclimate.com/github/ssube/rollup-template/issues)
|
[](https://codeclimate.com/github/ssube/js-utils/issues)
|
||||||
[](https://lgtm.com/projects/g/ssube/rollup-template/context:javascript)
|
[](https://lgtm.com/projects/g/ssube/js-utils/context:javascript)
|
||||||
[](https://lgtm.com/projects/g/ssube/rollup-template/alerts/)
|
[](https://lgtm.com/projects/g/ssube/js-utils/alerts/)
|
||||||
|
|
||||||
## Releases
|
## Releases
|
||||||
|
|
||||||
[](https://github.com/ssube/rollup-template/releases)
|
[](https://github.com/ssube/js-utils/releases)
|
||||||
[](https://github.com/ssube/rollup-template/releases)
|
[](https://github.com/ssube/js-utils/releases)
|
||||||
[](https://github.com/ssube/rollup-template/compare/v0.2.4...master)
|
[](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/js-utils)
|
||||||
[](https://www.npmjs.com/package/@apextoaster/rollup-template)
|
[](https://www.npmjs.com/package/@apextoaster/js-utils)
|
||||||
[](https://www.npmjs.com/package/@apextoaster/rollup-template)
|
[](https://www.npmjs.com/package/@apextoaster/js-utils)
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
### To Setup
|
Install:
|
||||||
|
|
||||||
To create a new repository from this template:
|
```shell
|
||||||
|
yarn add -D @apextoaster/js-utils
|
||||||
|
```
|
||||||
|
|
||||||
- create your new repo on Github & Gitlab (your server or Gitlab.com)
|
And import:
|
||||||
- `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
|
```typescript
|
||||||
|
import { mustExist } from '@apextoaster/js-utils';
|
||||||
|
```
|
||||||
|
|
||||||
Once your project is set up:
|
The library is bundled and depends on lodash, linked in a vendor module.
|
||||||
|
|
||||||
- `make` to bundle and test
|
## Features
|
||||||
- commit
|
|
||||||
- `make git-push`
|
|
||||||
|
|
||||||
The `git-push` target pushes to Github first, to avoid conflicts with changes
|
- array mapper
|
||||||
from bots and other contributors.
|
- 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
|
||||||
|
|
||||||
### To Release
|
|
||||||
|
|
||||||
When your project is ready to release:
|
|
||||||
|
|
||||||
- `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).
|
|
||||||
|
|
||||||
| 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 |
|
|
||||||
|
|
||||||
Secrets should be provided as environment variables, with the secret value
|
|
||||||
`base64`-encoded.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue