chore(release): v3.6.0

releases/v3 v3.6.0
Conventional Changelog Action 2020-12-15 17:25:11 +00:00
parent 78c22d5f5d
commit f69ac72a98
410 changed files with 42127 additions and 775 deletions

View File

@ -1,3 +1,23 @@
# [3.6.0](https://github.com/TriPSs/conventional-changelog-action/compare/v3.5.0...v3.6.0) (2020-12-15)
### Bug Fixes
* Add pre-changelog-generation input in README ([46a1a68](https://github.com/TriPSs/conventional-changelog-action/commit/46a1a68683081dbea9a2545e842caf17bf0ddab1))
* Fixed awaits missing ([35206c5](https://github.com/TriPSs/conventional-changelog-action/commit/35206c51048844fb3e645398b5c9a0f692f8bb56))
* Fixed command output empty ([b985fd6](https://github.com/TriPSs/conventional-changelog-action/commit/b985fd640ab6d046da88a5817b9f3437d67696f5))
* Fixed isShallow not working correctly anymore ([d68d2f2](https://github.com/TriPSs/conventional-changelog-action/commit/d68d2f2010d17f69267400f329baee761a8e8428))
* Fixed silent git errors [#74](https://github.com/TriPSs/conventional-changelog-action/issues/74) ([7c35f3c](https://github.com/TriPSs/conventional-changelog-action/commit/7c35f3c2863828a71323a49e16c5542c789591f9))
* Fixes for pre changelog generation ([484cf10](https://github.com/TriPSs/conventional-changelog-action/commit/484cf104714fbe499d83bd2818038e8c14e8ce98))
* Only run ci on PRs to master ([9f0d3d7](https://github.com/TriPSs/conventional-changelog-action/commit/9f0d3d7508a2dd13f6289944ddae48aca0510d6d))
### Features
* Added more logging ([d46daa9](https://github.com/TriPSs/conventional-changelog-action/commit/d46daa9a537c6d12a6ec4d859e55ef76372a15a8))
# [3.5.0](https://github.com/TriPSs/conventional-changelog-action/compare/v3.4.1...v3.5.0) (2020-12-14) # [3.5.0](https://github.com/TriPSs/conventional-changelog-action/compare/v3.4.1...v3.5.0) (2020-12-14)
@ -50,18 +70,3 @@
# [3.2.0](https://github.com/TriPSs/conventional-changelog-action/compare/v3.1.2...v3.2.0) (2020-08-03)
### Bug Fixes
* Test name ([f66f6a2](https://github.com/TriPSs/conventional-changelog-action/commit/f66f6a29a71c9b5ee636cef9ee022f127da37304))
### Features
* Added 'multiple-files' test workflow ([bb40f54](https://github.com/TriPSs/conventional-changelog-action/commit/bb40f54b50fdae3a1a084b597370e7e0f95c28ab))
* Added support for comma-separated version files ([3ba65fd](https://github.com/TriPSs/conventional-changelog-action/commit/3ba65fd7f7bff6e1c60178d49632067c6a8d6bfa))

View File

@ -3,6 +3,14 @@
All notable changes to this project will be documented in this file. All notable changes to this project will be documented in this file.
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
## [2.0.8](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-atom@2.0.7...conventional-changelog-atom@2.0.8) (2020-11-05)
**Note:** Version bump only for package conventional-changelog-atom
## [2.0.7](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-atom@2.0.3...conventional-changelog-atom@2.0.7) (2020-05-08) ## [2.0.7](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-atom@2.0.3...conventional-changelog-atom@2.0.7) (2020-05-08)
**Note:** Version bump only for package conventional-changelog-atom **Note:** Version bump only for package conventional-changelog-atom

View File

@ -1,6 +1,6 @@
{ {
"name": "conventional-changelog-atom", "name": "conventional-changelog-atom",
"version": "2.0.7", "version": "2.0.8",
"description": "conventional-changelog atom preset", "description": "conventional-changelog atom preset",
"main": "index.js", "main": "index.js",
"scripts": { "scripts": {
@ -35,9 +35,9 @@
"dependencies": { "dependencies": {
"q": "^1.5.1" "q": "^1.5.1"
}, },
"gitHead": "83643c5a0d2c4d7c9ba14cbf990ffbc577a51e8c" "gitHead": "cc567b98facf71315f4b1620d81ce01d155efaca"
,"_resolved": "https://registry.npmjs.org/conventional-changelog-atom/-/conventional-changelog-atom-2.0.7.tgz" ,"_resolved": "https://registry.npmjs.org/conventional-changelog-atom/-/conventional-changelog-atom-2.0.8.tgz"
,"_integrity": "sha512-7dOREZwzB+tCEMjRTDfen0OHwd7vPUdmU0llTy1eloZgtOP4iSLVzYIQqfmdRZEty+3w5Jz+AbhfTJKoKw1JeQ==" ,"_integrity": "sha512-xo6v46icsFTK3bb7dY/8m2qvc8sZemRgdqLb/bjpBsH2UyOS8rKNTgcb5025Hri6IpANPApbXMg15QLb1LJpBw=="
,"_from": "conventional-changelog-atom@2.0.7" ,"_from": "conventional-changelog-atom@2.0.8"
} }

View File

@ -3,6 +3,14 @@
All notable changes to this project will be documented in this file. All notable changes to this project will be documented in this file.
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
## [2.0.8](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-codemirror@2.0.7...conventional-changelog-codemirror@2.0.8) (2020-11-05)
**Note:** Version bump only for package conventional-changelog-codemirror
## [2.0.7](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-codemirror@2.0.3...conventional-changelog-codemirror@2.0.7) (2020-05-08) ## [2.0.7](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-codemirror@2.0.3...conventional-changelog-codemirror@2.0.7) (2020-05-08)
**Note:** Version bump only for package conventional-changelog-codemirror **Note:** Version bump only for package conventional-changelog-codemirror

View File

@ -1,5 +1,5 @@
'use strict' 'use strict'
var Q = require('q') const Q = require('q')
const conventionalChangelog = require('./conventional-changelog') const conventionalChangelog = require('./conventional-changelog')
const parserOpts = require('./parser-opts') const parserOpts = require('./parser-opts')
const recommendedBumpOpts = require('./conventional-recommended-bump') const recommendedBumpOpts = require('./conventional-recommended-bump')

View File

@ -1,6 +1,6 @@
{ {
"name": "conventional-changelog-codemirror", "name": "conventional-changelog-codemirror",
"version": "2.0.7", "version": "2.0.8",
"description": "conventional-changelog CodeMirror preset", "description": "conventional-changelog CodeMirror preset",
"main": "index.js", "main": "index.js",
"scripts": { "scripts": {
@ -35,9 +35,9 @@
"dependencies": { "dependencies": {
"q": "^1.5.1" "q": "^1.5.1"
}, },
"gitHead": "83643c5a0d2c4d7c9ba14cbf990ffbc577a51e8c" "gitHead": "cc567b98facf71315f4b1620d81ce01d155efaca"
,"_resolved": "https://registry.npmjs.org/conventional-changelog-codemirror/-/conventional-changelog-codemirror-2.0.7.tgz" ,"_resolved": "https://registry.npmjs.org/conventional-changelog-codemirror/-/conventional-changelog-codemirror-2.0.8.tgz"
,"_integrity": "sha512-Oralk1kiagn3Gb5cR5BffenWjVu59t/viE6UMD/mQa1hISMPkMYhJIqX+CMeA1zXgVBO+YHQhhokEj99GP5xcg==" ,"_integrity": "sha512-z5DAsn3uj1Vfp7po3gpt2Boc+Bdwmw2++ZHa5Ak9k0UKsYAO5mH1UBTN0qSCuJZREIhX6WU4E1p3IW2oRCNzQw=="
,"_from": "conventional-changelog-codemirror@2.0.7" ,"_from": "conventional-changelog-codemirror@2.0.8"
} }

View File

@ -3,6 +3,18 @@
All notable changes to this project will be documented in this file. All notable changes to this project will be documented in this file.
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
## [4.2.1](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-core@4.2.0...conventional-changelog-core@4.2.1) (2020-11-05)
### Bug Fixes
* **deps:** update dependency normalize-package-data to v3 ([#687](https://github.com/conventional-changelog/conventional-changelog/issues/687)) ([7b6ec0a](https://github.com/conventional-changelog/conventional-changelog/commit/7b6ec0add30915bc1569f82a007bb4d1d6df8e3e))
* **deps:** update dependency through2 to v4 ([#657](https://github.com/conventional-changelog/conventional-changelog/issues/657)) ([7ae618c](https://github.com/conventional-changelog/conventional-changelog/commit/7ae618c81491841e5b1d796d3933aac0c54bc312))
# [4.2.0](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-core@4.1.8...conventional-changelog-core@4.2.0) (2020-08-12) # [4.2.0](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-changelog-core@4.1.8...conventional-changelog-core@4.2.0) (2020-08-12)

View File

@ -13,14 +13,14 @@ const mergeConfig = require('./lib/merge-config')
function conventionalChangelog (options, context, gitRawCommitsOpts, parserOpts, writerOpts, gitRawExecOpts) { function conventionalChangelog (options, context, gitRawCommitsOpts, parserOpts, writerOpts, gitRawExecOpts) {
writerOpts = writerOpts || {} writerOpts = writerOpts || {}
var readable = new stream.Readable({ const readable = new stream.Readable({
objectMode: writerOpts.includeDetails objectMode: writerOpts.includeDetails
}) })
readable._read = function () { } readable._read = function () { }
var commitsErrorThrown = false let commitsErrorThrown = false
var commitsStream = new stream.Readable({ let commitsStream = new stream.Readable({
objectMode: true objectMode: true
}) })
commitsStream._read = function () { } commitsStream._read = function () { }
@ -48,7 +48,7 @@ function conventionalChangelog (options, context, gitRawCommitsOpts, parserOpts,
gitRawExecOpts = data.gitRawExecOpts gitRawExecOpts = data.gitRawExecOpts
if (shell.exec('git rev-parse --verify HEAD', { silent: true }).code === 0) { if (shell.exec('git rev-parse --verify HEAD', { silent: true }).code === 0) {
var reverseTags = context.gitSemverTags.slice(0).reverse() let reverseTags = context.gitSemverTags.slice(0).reverse()
reverseTags.push('HEAD') reverseTags.push('HEAD')
if (gitRawCommitsOpts.from) { if (gitRawCommitsOpts.from) {
@ -59,7 +59,7 @@ function conventionalChangelog (options, context, gitRawCommitsOpts, parserOpts,
} }
} }
var streams = reverseTags.map((to, i) => { let streams = reverseTags.map((to, i) => {
const from = i > 0 const from = i > 0
? reverseTags[i - 1] ? reverseTags[i - 1]
: '' : ''

View File

@ -1,10 +1,10 @@
'use strict' 'use strict'
var dateFormat = require('dateformat') const dateFormat = require('dateformat')
var getPkgRepo = require('get-pkg-repo') const getPkgRepo = require('get-pkg-repo')
var gitSemverTags = require('git-semver-tags') const gitSemverTags = require('git-semver-tags')
var normalizePackageData = require('normalize-package-data') const normalizePackageData = require('normalize-package-data')
var Q = require('q') const Q = require('q')
var gitRemoteOriginUrl let gitRemoteOriginUrl
try { try {
gitRemoteOriginUrl = require('git-remote-origin-url') gitRemoteOriginUrl = require('git-remote-origin-url')
} catch (err) { } catch (err) {
@ -12,12 +12,12 @@ try {
return Q.reject(err) return Q.reject(err)
} }
} }
var readPkg = require('read-pkg') const readPkg = require('read-pkg')
var readPkgUp = require('read-pkg-up') const readPkgUp = require('read-pkg-up')
var URL = require('url').URL const URL = require('url').URL
var _ = require('lodash') const _ = require('lodash')
var rhosts = /github|bitbucket|gitlab/i const rhosts = /github|bitbucket|gitlab/i
function semverTagsPromise (options) { function semverTagsPromise (options) {
return Q.Promise(function (resolve, reject) { return Q.Promise(function (resolve, reject) {
@ -52,15 +52,14 @@ function guessNextTag (previousTag, version) {
} }
function mergeConfig (options, context, gitRawCommitsOpts, parserOpts, writerOpts, gitRawExecOpts) { function mergeConfig (options, context, gitRawCommitsOpts, parserOpts, writerOpts, gitRawExecOpts) {
var configPromise let configPromise
var pkgPromise let pkgPromise
var gitRemoteOriginUrlPromise
context = context || {} context = context || {}
gitRawCommitsOpts = gitRawCommitsOpts || {} gitRawCommitsOpts = gitRawCommitsOpts || {}
gitRawExecOpts = gitRawExecOpts || {} gitRawExecOpts = gitRawExecOpts || {}
var rtag = options && options.tagPrefix ? new RegExp(`tag:\\s*[=]?${options.tagPrefix}(.+?)[,)]`, 'gi') : /tag:\s*[v=]?(.+?)[,)]/gi const rtag = options && options.tagPrefix ? new RegExp(`tag:\\s*[=]?${options.tagPrefix}(.+?)[,)]`, 'gi') : /tag:\s*[v=]?(.+?)[,)]/gi
options = _.merge({ options = _.merge({
pkg: { pkg: {
@ -74,7 +73,7 @@ function mergeConfig (options, context, gitRawCommitsOpts, parserOpts, writerOpt
debug: function () {}, debug: function () {},
transform: function (commit, cb) { transform: function (commit, cb) {
if (_.isString(commit.gitTags)) { if (_.isString(commit.gitTags)) {
var match = rtag.exec(commit.gitTags) const match = rtag.exec(commit.gitTags)
rtag.lastIndex = 0 rtag.lastIndex = 0
if (match) { if (match) {
@ -109,18 +108,18 @@ function mergeConfig (options, context, gitRawCommitsOpts, parserOpts, writerOpt
} }
} }
gitRemoteOriginUrlPromise = Q(gitRemoteOriginUrl()) const gitRemoteOriginUrlPromise = Q(gitRemoteOriginUrl())
return Q.allSettled([configPromise, pkgPromise, semverTagsPromise(options), gitRemoteOriginUrlPromise]) return Q.allSettled([configPromise, pkgPromise, semverTagsPromise(options), gitRemoteOriginUrlPromise])
.spread(function (configObj, pkgObj, tagsObj, gitRemoteOriginUrlObj) { .spread(function (configObj, pkgObj, tagsObj, gitRemoteOriginUrlObj) {
var config let config
var pkg let pkg
var fromTag let fromTag
var repo let repo
var hostOpts let hostOpts
var gitSemverTags = [] let gitSemverTags = []
if (configPromise) { if (configPromise) {
if (configObj.state === 'fulfilled') { if (configObj.state === 'fulfilled') {
@ -166,10 +165,10 @@ function mergeConfig (options, context, gitRawCommitsOpts, parserOpts, writerOpt
} }
if (repo.browse) { if (repo.browse) {
var browse = repo.browse() const browse = repo.browse()
if (!context.host) { if (!context.host) {
if (repo.domain) { if (repo.domain) {
var parsedBrowse = new URL(browse) const parsedBrowse = new URL(browse)
if (parsedBrowse.origin.indexOf('//') !== -1) { if (parsedBrowse.origin.indexOf('//') !== -1) {
context.host = parsedBrowse.protocol + '//' + repo.domain context.host = parsedBrowse.protocol + '//' + repo.domain
} else { } else {
@ -192,7 +191,7 @@ function mergeConfig (options, context, gitRawCommitsOpts, parserOpts, writerOpt
if (tagsObj.state === 'fulfilled') { if (tagsObj.state === 'fulfilled') {
gitSemverTags = context.gitSemverTags = tagsObj.value gitSemverTags = context.gitSemverTags = tagsObj.value
fromTag = gitSemverTags[options.releaseCount - 1] fromTag = gitSemverTags[options.releaseCount - 1]
var lastTag = gitSemverTags[0] const lastTag = gitSemverTags[0]
if (lastTag === context.version || lastTag === 'v' + context.version) { if (lastTag === context.version || lastTag === 'v' + context.version) {
if (options.outputUnreleased) { if (options.outputUnreleased) {
@ -208,10 +207,10 @@ function mergeConfig (options, context, gitRawCommitsOpts, parserOpts, writerOpt
} }
if (context.host && (!context.issue || !context.commit || !parserOpts || !parserOpts.referenceActions)) { if (context.host && (!context.issue || !context.commit || !parserOpts || !parserOpts.referenceActions)) {
var type let type
if (context.host) { if (context.host) {
var match = context.host.match(rhosts) const match = context.host.match(rhosts)
if (match) { if (match) {
type = match[0] type = match[0]
} }
@ -268,22 +267,22 @@ function mergeConfig (options, context, gitRawCommitsOpts, parserOpts, writerOpt
writerOpts = _.assign({ writerOpts = _.assign({
finalizeContext: function (context, writerOpts, filteredCommits, keyCommit, originalCommits) { finalizeContext: function (context, writerOpts, filteredCommits, keyCommit, originalCommits) {
var firstCommit = originalCommits[0] const firstCommit = originalCommits[0]
var lastCommit = originalCommits[originalCommits.length - 1] const lastCommit = originalCommits[originalCommits.length - 1]
var firstCommitHash = firstCommit ? firstCommit.hash : null const firstCommitHash = firstCommit ? firstCommit.hash : null
var lastCommitHash = lastCommit ? lastCommit.hash : null const lastCommitHash = lastCommit ? lastCommit.hash : null
if ((!context.currentTag || !context.previousTag) && keyCommit) { if ((!context.currentTag || !context.previousTag) && keyCommit) {
var match = /tag:\s*(.+?)[,)]/gi.exec(keyCommit.gitTags) const match = /tag:\s*(.+?)[,)]/gi.exec(keyCommit.gitTags)
var currentTag = context.currentTag const currentTag = context.currentTag
context.currentTag = currentTag || match ? match[1] : null context.currentTag = currentTag || match ? match[1] : null
var index = gitSemverTags.indexOf(context.currentTag) const index = gitSemverTags.indexOf(context.currentTag)
// if `keyCommit.gitTags` is not a semver // if `keyCommit.gitTags` is not a semver
if (index === -1) { if (index === -1) {
context.currentTag = currentTag || null context.currentTag = currentTag || null
} else { } else {
var previousTag = context.previousTag = gitSemverTags[index + 1] const previousTag = context.previousTag = gitSemverTags[index + 1]
if (!previousTag) { if (!previousTag) {
if (options.append) { if (options.append) {

View File

@ -0,0 +1 @@
../conventional-commits-parser/cli.js

View File

@ -0,0 +1 @@
../git-semver-tags/cli.js

View File

@ -0,0 +1,435 @@
# Change Log
All notable changes to this project will be documented in this file.
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
# [3.2.0](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.1.0...conventional-commits-parser@3.2.0) (2020-11-05)
### Bug Fixes
* ignore gpg lines ([#685](https://github.com/conventional-changelog/conventional-changelog/issues/685)) ([f8fcbc2](https://github.com/conventional-changelog/conventional-changelog/commit/f8fcbc2e8b0834c29178ace6382b438a020ad828))
* **deps:** update dependency through2 to v4 ([#657](https://github.com/conventional-changelog/conventional-changelog/issues/657)) ([7ae618c](https://github.com/conventional-changelog/conventional-changelog/commit/7ae618c81491841e5b1d796d3933aac0c54bc312))
### Features
* allows notes pattern to be customized ([#586](https://github.com/conventional-changelog/conventional-changelog/issues/586)) ([9c00f32](https://github.com/conventional-changelog/conventional-changelog/commit/9c00f3242d916be1774a618d943f908f8d9699a6))
# [3.1.0](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.0.8...conventional-commits-parser@3.1.0) (2020-05-08)
### Bug Fixes
* **deps:** update yargs-parser to move off a flagged-vulnerable version. ([#635](https://github.com/conventional-changelog/conventional-changelog/issues/635)) ([aafc0f0](https://github.com/conventional-changelog/conventional-changelog/commit/aafc0f00412c3e4b23b8418300e5a570a48fe24d))
### Features
* **conventional-commits-parser:** add issuePrefixesCaseSensitive parser option ([#580](https://github.com/conventional-changelog/conventional-changelog/issues/580)) ([526b282](https://github.com/conventional-changelog/conventional-changelog/commit/526b28214d12c55158eb2e4d44408378587ceb97))
* support slash in headerPattern default options ([93a547d](https://github.com/conventional-changelog/conventional-changelog/commit/93a547d742634d8676f499cfa2a274bc3792d020))
## [3.0.8](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.0.7...conventional-commits-parser@3.0.8) (2019-11-14)
### Bug Fixes
* add types for cli flags ([#551](https://github.com/conventional-changelog/conventional-changelog/issues/551)) ([bf1d64a](https://github.com/conventional-changelog/conventional-changelog/commit/bf1d64aeaf8f262d4b2beec02d2aebb78df7343b))
## [3.0.7](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.0.6...conventional-commits-parser@3.0.7) (2019-11-07)
### Bug Fixes
* **conventional-commits-parser:** add breaking change notes if header match `breakingHeaderPattern` ([#544](https://github.com/conventional-changelog/conventional-changelog/issues/544)) ([efdf3cb](https://github.com/conventional-changelog/conventional-changelog/commit/efdf3cbc9de3278b180a48beebb74e596e3c5f94))
* **conventional-commits-parser:** add missing separator pipe to non tty parser ([#546](https://github.com/conventional-changelog/conventional-changelog/issues/546)) ([c522743](https://github.com/conventional-changelog/conventional-changelog/commit/c5227437b0b300f30a57e8ba5df2a8ab8d163af0))
## [3.0.6](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.0.5...conventional-commits-parser@3.0.6) (2019-10-24)
### Bug Fixes
* **conventional-commits-parser:** downgrade is-text-path due to node 6 incompatibility ([#536](https://github.com/conventional-changelog/conventional-changelog/issues/536)) ([3aa2637](https://github.com/conventional-changelog/conventional-changelog/commit/3aa2637a1c65bb4db3d8bf2c6ce17e6f5abe1ca1))
* **deps:** update lodash to fix security issues ([#535](https://github.com/conventional-changelog/conventional-changelog/issues/535)) ([ac43f51](https://github.com/conventional-changelog/conventional-changelog/commit/ac43f51de1f3b597c32f7f8442917a2d06199018))
## [3.0.4](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.0.3...conventional-commits-parser@3.0.4) (2019-10-02)
**Note:** Version bump only for package conventional-commits-parser
## [3.0.3](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.0.2...conventional-commits-parser@3.0.3) (2019-05-18)
### Bug Fixes
* **deps:** update dependency is-text-path to v2 ([#455](https://github.com/conventional-changelog/conventional-changelog/issues/455)) ([0f40ec3](https://github.com/conventional-changelog/conventional-changelog/commit/0f40ec3))
## [3.0.2](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.0.1...conventional-commits-parser@3.0.2) (2019-04-10)
### Bug Fixes
* **deps:** update dependency through2 to v3 ([#392](https://github.com/conventional-changelog/conventional-changelog/issues/392)) ([26fe91f](https://github.com/conventional-changelog/conventional-changelog/commit/26fe91f))
## [3.0.1](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@3.0.0...conventional-commits-parser@3.0.1) (2018-11-01)
### Bug Fixes
* Upgrade to Lerna 3, fix Node.js v11 error ([#385](https://github.com/conventional-changelog/conventional-changelog/issues/385)) ([cdef282](https://github.com/conventional-changelog/conventional-changelog/commit/cdef282))
<a name="3.0.0"></a>
# [3.0.0](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@2.1.7...conventional-commits-parser@3.0.0) (2018-05-29)
### Chores
* **package:** set Node requirement to oldest supported LTS ([#329](https://github.com/conventional-changelog/conventional-changelog/issues/329)) ([cae2fe0](https://github.com/conventional-changelog/conventional-changelog/commit/cae2fe0))
### BREAKING CHANGES
* **package:** Set the package's minimum required Node version to be the oldest LTS
currently supported by the Node Release working group. At this time,
that is Node 6 (which is in its Maintenance LTS phase).
<a name="2.1.7"></a>
## [2.1.7](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@2.1.6...conventional-commits-parser@2.1.7) (2018-03-27)
**Note:** Version bump only for package conventional-commits-parser
<a name="2.1.6"></a>
## [2.1.6](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@2.1.5...conventional-commits-parser@2.1.6) (2018-03-22)
**Note:** Version bump only for package conventional-commits-parser
<a name="2.1.5"></a>
## [2.1.5](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@2.1.4...conventional-commits-parser@2.1.5) (2018-02-24)
**Note:** Version bump only for package conventional-commits-parser
<a name="2.1.4"></a>
## [2.1.4](https://github.com/conventional-changelog/conventional-changelog/compare/conventional-commits-parser@2.1.3...conventional-commits-parser@2.1.4) (2018-02-20)
**Note:** Version bump only for package conventional-commits-parser
<a name="2.1.3"></a>
## [2.1.3](https://github.com/conventional-changelog/conventional-commits-parser/compare/conventional-commits-parser@2.1.2...conventional-commits-parser@2.1.3) (2018-02-13)
**Note:** Version bump only for package conventional-commits-parser
<a name="2.1.2"></a>
## [2.1.2](https://github.com/conventional-changelog/conventional-commits-parser/compare/conventional-commits-parser@2.1.1...conventional-commits-parser@2.1.2) (2018-02-13)
**Note:** Version bump only for package conventional-commits-parser
<a name="2.1.1"></a>
## [2.1.1](https://github.com/conventional-changelog/conventional-commits-parser/compare/conventional-commits-parser@2.1.0...conventional-commits-parser@2.1.1) (2018-02-05)
### Bug Fixes
* truncate after scissors line ([#267](https://github.com/conventional-changelog/conventional-commits-parser/issues/267)) ([e09df10](https://github.com/conventional-changelog/conventional-commits-parser/commit/e09df10))
<a name="2.1.0"></a>
# [2.1.0](https://github.com/conventional-changelog/conventional-commits-parser/compare/conventional-commits-parser@2.0.1...conventional-commits-parser@2.1.0) (2017-12-08)
### Bug Fixes
* always parse references ([e84a9ae](https://github.com/conventional-changelog/conventional-commits-parser/commit/e84a9ae)), closes [#248](https://github.com/conventional-changelog/conventional-commits-parser/issues/248)
### Features
* make comment stripping optional ([db5b711](https://github.com/conventional-changelog/conventional-commits-parser/commit/db5b711)), closes [#251](https://github.com/conventional-changelog/conventional-commits-parser/issues/251)
<a name="2.0.1"></a>
## [2.0.1](https://github.com/conventional-changelog/conventional-commits-parser/compare/conventional-commits-parser@2.0.0...conventional-commits-parser@2.0.1) (2017-11-13)
### Bug Fixes
* **conventional-commits-parser:** ignore comments ([#231](https://github.com/conventional-changelog/conventional-commits-parser/issues/231)) ([9db53e3](https://github.com/conventional-changelog/conventional-commits-parser/commit/9db53e3)), closes [#224](https://github.com/conventional-changelog/conventional-commits-parser/issues/224)
<a name="2.0.0"></a>
# 2.0.0 (2017-07-17)
### Bug Fixes
* **cli:** commit can be split when testing a commit file ([f3b3a3f](https://github.com/conventional-changelog/conventional-commits-parser/commit/f3b3a3f))
* **cli:** error handling for ENOENT is fixed ([3c92233](https://github.com/conventional-changelog/conventional-commits-parser/commit/3c92233))
* **cli:** fix "undefined" in json string ([0680e42](https://github.com/conventional-changelog/conventional-commits-parser/commit/0680e42))
* **cli:** options format ([491357e](https://github.com/conventional-changelog/conventional-commits-parser/commit/491357e))
* **deps:** require split2 ([1941c37](https://github.com/conventional-changelog/conventional-commits-parser/commit/1941c37))
* **error:** change error type and wordings ([d8be5e5](https://github.com/conventional-changelog/conventional-commits-parser/commit/d8be5e5))
* **footer:** notes contains more than one paragraphs after references ([d744ec7](https://github.com/conventional-changelog/conventional-commits-parser/commit/d744ec7))
* **headerCorrespondence:** string value for cli ([fb774fc](https://github.com/conventional-changelog/conventional-commits-parser/commit/fb774fc))
* **headerPattern:** change how capturing groups works ([fe1fe0c](https://github.com/conventional-changelog/conventional-commits-parser/commit/fe1fe0c))
* **issuePrefixes:** should return noMatch if falsy ([72db2bf](https://github.com/conventional-changelog/conventional-commits-parser/commit/72db2bf))
* **mention:** fix mention matching ([965986b](https://github.com/conventional-changelog/conventional-commits-parser/commit/965986b)), closes [#26](https://github.com/conventional-changelog/conventional-commits-parser/issues/26)
* **newlines:** preserve newlines in a part ([06b8c7c](https://github.com/conventional-changelog/conventional-commits-parser/commit/06b8c7c)), closes [#15](https://github.com/conventional-changelog/conventional-commits-parser/issues/15)
* **notes:** note keywords must appear at the beginning of a sentence ([5a2059e](https://github.com/conventional-changelog/conventional-commits-parser/commit/5a2059e)), closes [#23](https://github.com/conventional-changelog/conventional-commits-parser/issues/23)
* **parser:** do not trim spaces but newlines ([1e8c4c5](https://github.com/conventional-changelog/conventional-commits-parser/commit/1e8c4c5))
* **parser:** it returns null if there is no header ([8571c9e](https://github.com/conventional-changelog/conventional-commits-parser/commit/8571c9e))
* **regex:** do not treat it as note if there are texts after keywords ([571b03e](https://github.com/conventional-changelog/conventional-commits-parser/commit/571b03e))
* **regex:** make getReferencePartsRegex stricter ([62adf54](https://github.com/conventional-changelog/conventional-commits-parser/commit/62adf54)), closes [#27](https://github.com/conventional-changelog/conventional-commits-parser/issues/27) [#30](https://github.com/conventional-changelog/conventional-commits-parser/issues/30) [#27](https://github.com/conventional-changelog/conventional-commits-parser/issues/27) [#28](https://github.com/conventional-changelog/conventional-commits-parser/issues/28)
* **revertPattern:** correct regex ([8628983](https://github.com/conventional-changelog/conventional-commits-parser/commit/8628983))
* **util:** remove an accidentally commited file ([3710a8c](https://github.com/conventional-changelog/conventional-commits-parser/commit/3710a8c))
* **warn:** should tell which commit cannot be parsed ([04b0a9b](https://github.com/conventional-changelog/conventional-commits-parser/commit/04b0a9b))
### Chores
* init ([a529841](https://github.com/conventional-changelog/conventional-commits-parser/commit/a529841))
### Code Refactoring
* **breaks:** change `breaks` to `notes` ([5189a61](https://github.com/conventional-changelog/conventional-commits-parser/commit/5189a61)), closes [#2](https://github.com/conventional-changelog/conventional-commits-parser/issues/2)
* **merge:** pull-request should be merge ([4e7c61c](https://github.com/conventional-changelog/conventional-commits-parser/commit/4e7c61c))
* **regex:** regex now takes `options` ([eea319a](https://github.com/conventional-changelog/conventional-commits-parser/commit/eea319a))
### Features
* **cli:** able to have two files, separator works for interactive ([db1e3b5](https://github.com/conventional-changelog/conventional-commits-parser/commit/db1e3b5))
* **cli:** add aliases, more help details and tests ([eb654a2](https://github.com/conventional-changelog/conventional-commits-parser/commit/eb654a2))
* **cli:** add missing options ([8ac1cf7](https://github.com/conventional-changelog/conventional-commits-parser/commit/8ac1cf7))
* **cli:** add warn function for interactive shell ([84fe31f](https://github.com/conventional-changelog/conventional-commits-parser/commit/84fe31f))
* **correspondence:** add `headerCorrespondence` and improve commit parts ([aca9e95](https://github.com/conventional-changelog/conventional-commits-parser/commit/aca9e95)), closes [#6](https://github.com/conventional-changelog/conventional-commits-parser/issues/6)
* **fieldPattern:** should support string format ([b6b6b52](https://github.com/conventional-changelog/conventional-commits-parser/commit/b6b6b52))
* **hash:** drop support ([1ccc751](https://github.com/conventional-changelog/conventional-commits-parser/commit/1ccc751))
* **headerParts:** headerParts can be anything ([31e1c11](https://github.com/conventional-changelog/conventional-commits-parser/commit/31e1c11)), closes [#10](https://github.com/conventional-changelog/conventional-commits-parser/issues/10)
* **issuePrefixes:** init and referenceKeywords -> referenceActions ([86bf798](https://github.com/conventional-changelog/conventional-commits-parser/commit/86bf798)), closes [#11](https://github.com/conventional-changelog/conventional-commits-parser/issues/11)
* **maxSubjectLength:** removed ([3448582](https://github.com/conventional-changelog/conventional-commits-parser/commit/3448582))
* **mentions:** [@someone](https://github.com/someone) in commit ([d60fe76](https://github.com/conventional-changelog/conventional-commits-parser/commit/d60fe76)), closes [#24](https://github.com/conventional-changelog/conventional-commits-parser/issues/24)
* **newline:** fields does not contain leading or trailing newlines ([6db453b](https://github.com/conventional-changelog/conventional-commits-parser/commit/6db453b)), closes [#14](https://github.com/conventional-changelog/conventional-commits-parser/issues/14)
* **note:** noteKeywords is case insensitive ([f779a29](https://github.com/conventional-changelog/conventional-commits-parser/commit/f779a29)), closes [#21](https://github.com/conventional-changelog/conventional-commits-parser/issues/21)
* **options:** all options can be a string ([0fa17b4](https://github.com/conventional-changelog/conventional-commits-parser/commit/0fa17b4))
* **otherFields:** other fields are possible to be included ([9e06278](https://github.com/conventional-changelog/conventional-commits-parser/commit/9e06278))
* improvements and bug fixes ([1cde104](https://github.com/conventional-changelog/conventional-commits-parser/commit/1cde104)), closes [#5](https://github.com/conventional-changelog/conventional-commits-parser/issues/5)
* migrate repo to lerna mono-repo ([793e823](https://github.com/conventional-changelog/conventional-commits-parser/commit/793e823))
* **regex:** matching JIRA-123 like references ([20f1f7a](https://github.com/conventional-changelog/conventional-commits-parser/commit/20f1f7a)), closes [#19](https://github.com/conventional-changelog/conventional-commits-parser/issues/19)
* support squash commits ([#31](https://github.com/conventional-changelog/conventional-changelog/issues/31)) ([fff60c0](https://github.com/conventional-changelog/conventional-commits-parser/commit/fff60c0))
* **owner:** yield owner field ([d8d0334](https://github.com/conventional-changelog/conventional-commits-parser/commit/d8d0334)), closes [#12](https://github.com/conventional-changelog/conventional-commits-parser/issues/12)
* **parser:** notes can have more than one paragraph ([733bfa9](https://github.com/conventional-changelog/conventional-commits-parser/commit/733bfa9)), closes [#3](https://github.com/conventional-changelog/conventional-commits-parser/issues/3)
* **pullRequest:** Allow to skip and parse pull request header ([a2e929f](https://github.com/conventional-changelog/conventional-commits-parser/commit/a2e929f)), closes [#20](https://github.com/conventional-changelog/conventional-commits-parser/issues/20)
* **reference:** able to reference an issue without an action ([6474123](https://github.com/conventional-changelog/conventional-commits-parser/commit/6474123)), closes [#22](https://github.com/conventional-changelog/conventional-commits-parser/issues/22)
* **reference:** expose prefix ([47df766](https://github.com/conventional-changelog/conventional-commits-parser/commit/47df766)), closes [#17](https://github.com/conventional-changelog/conventional-commits-parser/issues/17)
* **references:** allow header to reference an issue ([df18a24](https://github.com/conventional-changelog/conventional-commits-parser/commit/df18a24))
* **references:** support other formats of references ([7c70213](https://github.com/conventional-changelog/conventional-commits-parser/commit/7c70213)), closes [#4](https://github.com/conventional-changelog/conventional-commits-parser/issues/4) [#8](https://github.com/conventional-changelog/conventional-commits-parser/issues/8)
* **regex:** leading and trailing space for closes and breaks keywords are trimmed ([9639860](https://github.com/conventional-changelog/conventional-commits-parser/commit/9639860))
* **revert:** parse a commit that reverts ([2af7233](https://github.com/conventional-changelog/conventional-commits-parser/commit/2af7233))
* **stream:** emmit an empty string to down stream if commit cannot be parsed ([76bf84e](https://github.com/conventional-changelog/conventional-commits-parser/commit/76bf84e))
* **sync:** add the sync function ([82071c6](https://github.com/conventional-changelog/conventional-commits-parser/commit/82071c6)), closes [#13](https://github.com/conventional-changelog/conventional-commits-parser/issues/13)
* **warn:** optionally warn user what is wrong when commit cannot be parsed ([32b3cda](https://github.com/conventional-changelog/conventional-commits-parser/commit/32b3cda))
### Performance Improvements
* **regex:** regex should be constructed in index.html ([15afd26](https://github.com/conventional-changelog/conventional-commits-parser/commit/15afd26))
### BREAKING CHANGES
* **merge:** `pull request` should be `merge`. Also make the parsed result to be consistent with other parts.
* This module is imported from https://github.com/ajoslin/conventional-changelog, and is originally written by @vojtajina, @btford and @ajoslin.
* **hash:** hash is no longer supported. This parser should just parse raw commit messages. Also text fields are appended with a newline "
".
* **regex:** It returns a nomatch regex if it's keywords are missing.
* **headerParts:** `headerParts` does not limit to `type`, `scope` and `subject`. They can now be defined in `options.headerCorrespondence` and the order is the order of capturing group in `options.headerPattern`. If part is missing in `options.headerCorrespondence` it is `undefined`. If part is not captured but is not missing in `options.headerCorrespondence` it is `null`.
* **maxSubjectLength:** `maxSubjectLength` is not available any more.
* **issuePrefixes:** `options.referenceKeywords` is now `options.referenceActions`
* **references:** `closes` now becomes `references` and it is loosely based the links above.
* **parser:** The regex for matching notes are loosen. The semicolon and space are optional. The `notes` object is no longer a key-value object but an array of note object, such as
```js
{
title: 'BREAKING AMEND',
text: 'some breaking change'
}
```
The detection of notes, closes, continueNote and isBody are mutually exclusive.
* **breaks:** Variable name related to `breaks` changes to `notes`, because "Important Notes" a more generic term. There is no functional changes.
* **stream:** It no longer skips the chunk if commit cannot be parsed. An empty string is passed to down stream
* **correspondence:** body and footer will be null if they are not found. type and subject are nullable too.
<a name="1.3.0"></a>
# [1.3.0](https://github.com/conventional-changelog/conventional-commits-parser/compare/v1.2.3...v1.3.0) (2016-10-15)
### Features
* support squash commits (#31) ([860c7a1](https://github.com/conventional-changelog/conventional-commits-parser/commit/860c7a1))
<a name="1.2.3"></a>
## [1.2.3](https://github.com/conventional-changelog/conventional-commits-parser/compare/v1.2.2...v1.2.3) (2016-08-06)
### Bug Fixes
* **regex:** do not treat it as note if there are texts after keywords ([9cb56bc](https://github.com/conventional-changelog/conventional-commits-parser/commit/9cb56bc))
<a name="1.2.2"></a>
## [1.2.2](https://github.com/conventional-changelog/conventional-commits-parser/compare/v1.2.1...v1.2.2) (2016-05-04)
### Bug Fixes
* **regex:** make getReferencePartsRegex stricter ([b8a9fda](https://github.com/conventional-changelog/conventional-commits-parser/commit/b8a9fda)), closes [#27](https://github.com/conventional-changelog/conventional-commits-parser/issues/27) [(#30](https://github.com/(/issues/30) [#27](https://github.com/conventional-changelog/conventional-commits-parser/issues/27) [#28](https://github.com/conventional-changelog/conventional-commits-parser/issues/28)
<a name="1.2.1"></a>
## [1.2.1](https://github.com/conventional-changelog/conventional-commits-parser/compare/v1.2.0...v1.2.1) (2016-04-24)
### Bug Fixes
* **mention:** fix mention matching ([43b32e7](https://github.com/conventional-changelog/conventional-commits-parser/commit/43b32e7)), closes [#26](https://github.com/conventional-changelog/conventional-commits-parser/issues/26)
<a name="1.2.0"></a>
# [1.2.0](https://github.com/conventional-changelog/conventional-commits-parser/compare/v1.1.0...v1.2.0) (2016-04-15)
### Features
* **mentions:** @someone in commit ([b2eabbf](https://github.com/conventional-changelog/conventional-commits-parser/commit/b2eabbf)), closes [#24](https://github.com/conventional-changelog/conventional-commits-parser/issues/24)
<a name="1.1.0"></a>
# [1.1.0](https://github.com/conventional-changelog/conventional-commits-parser/compare/v1.0.1...v1.1.0) (2016-04-10)
### Bug Fixes
* **notes:** note keywords must appear at the beginning of a sentence ([6e13789](https://github.com/conventional-changelog/conventional-commits-parser/commit/6e13789)), closes [#23](https://github.com/conventional-changelog/conventional-commits-parser/issues/23)
### Features
* **reference:** able to reference an issue without an action ([cf847b1](https://github.com/conventional-changelog/conventional-commits-parser/commit/cf847b1)), closes [#22](https://github.com/conventional-changelog/conventional-commits-parser/issues/22)
<a name="1.0.1"></a>
## [1.0.1](https://github.com/stevemao/conventional-commits-parser/compare/v1.0.0...v1.0.1) (2016-02-05)
### Bug Fixes
* **deps:** require split2 ([ad55810](https://github.com/stevemao/conventional-commits-parser/commit/ad55810))
<a name="1.0.0"></a>
# [1.0.0](https://github.com/stevemao/conventional-commits-parser/compare/v0.2.0...v1.0.0) (2016-02-05)
<a name="0.2.0"></a>
# [0.2.0](https://github.com/stevemao/conventional-commits-parser/compare/v0.1.2...v0.2.0) (2016-02-04)
### Features
* **note:** noteKeywords is case insensitive ([4442b86](https://github.com/stevemao/conventional-commits-parser/commit/4442b86)), closes [#21](https://github.com/stevemao/conventional-commits-parser/issues/21)
* **pullRequest:** Allow to skip and parse pull request header ([aa85033](https://github.com/stevemao/conventional-commits-parser/commit/aa85033)), closes [#20](https://github.com/stevemao/conventional-commits-parser/issues/20)
* **regex:** matching JIRA-123 like references ([5342f45](https://github.com/stevemao/conventional-commits-parser/commit/5342f45)), closes [#19](https://github.com/stevemao/conventional-commits-parser/issues/19)
<a name="0.1.2"></a>
## [0.1.2](https://github.com/stevemao/conventional-commits-parser/compare/v0.1.1...v0.1.2) (2015-09-18)
### Bug Fixes
* **parser:** do not trim spaces but newlines ([62e7bf5](https://github.com/stevemao/conventional-commits-parser/commit/62e7bf5))
<a name="0.1.1"></a>
## [0.1.1](https://github.com/stevemao/conventional-commits-parser/compare/v0.1.0...v0.1.1) (2015-09-12)
### Bug Fixes
* **newlines:** preserve newlines in a part ([beb3d05](https://github.com/stevemao/conventional-commits-parser/commit/beb3d05)), closes [#15](https://github.com/stevemao/conventional-commits-parser/issues/15)
### Features
* **reference:** expose prefix ([9962dda](https://github.com/stevemao/conventional-commits-parser/commit/9962dda)), closes [#17](https://github.com/stevemao/conventional-commits-parser/issues/17)

View File

@ -0,0 +1,21 @@
### MIT License
Copyright © [conventional-changelog team](https://github.com/conventional-changelog)
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.

View File

@ -0,0 +1,382 @@
# [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage Status][coveralls-image]][coveralls-url]
> Parse raw conventional commits
## Conventional Commit Message Format
A minimum input should contain a raw message.
Each commit message consists of a **merge header**, a **header** (mandatory), a **body** and a **footer**. **Mention** (optional) someone using the `@` notation.
```
<merge>
<header>
<body>
<footer>
```
### merge
The merge header may optionally have a special format that includes other parts, such as **branch**, **issueId** or **source**.
```
Merge branch <branch>
Merge pull request <issue-id> from <source>
```
### header
The header may optionally have a special format that includes other parts, such as **type**, **scope** and **subject**. You could **reference** (optional) issues here.
```
<type>(<scope>): <subject>
```
### footer
The footer should contain any information about **Important Notes** (optional) and is also the place to **reference** (optional) issues.
```
<important note>
<references>
```
### other parts
This module will only parse the message body. However, it is possible to include other fields such as hash, committer or date.
```
My commit message
-sideNotes-
It should warn the correct unfound file names.
Also it should continue if one file cannot be found.
Tests are added for these
```
Then `sideNotes` will be `It should warn the correct unfound file names.\nAlso it should continue if one file cannot be found.\nTests are added for these`. You can customize the `fieldPattern`.
## Install
```sh
$ npm install --save conventional-commits-parser
```
## Usage
```js
var conventionalCommitsParser = require('conventional-commits-parser');
conventionalCommitsParser(options);
```
It returns a transform stream and expects an upstream that looks something like this:
```
'feat(scope): broadcast $destroy event on scope destruction\nCloses #1'
'feat(ng-list): Allow custom separator\nbla bla bla\n\nBREAKING CHANGE: some breaking change.\nThanks @stevemao\n'
```
Each chunk should be a commit. The downstream will look something like this:
```js
{ type: 'feat',
scope: 'scope',
subject: 'broadcast $destroy event on scope destruction',
merge: null,
header: 'feat(scope): broadcast $destroy event on scope destruction',
body: null,
footer: 'Closes #1',
notes: [],
references:
[ { action: 'Closes',
owner: null,
repository: null,
issue: '1',
raw: '#1',
prefix: '#' } ],
mentions: [],
revert: null }
{ type: 'feat',
scope: 'ng-list',
subject: 'Allow custom separator',
merge: null,
header: 'feat(ng-list): Allow custom separator',
body: 'bla bla bla',
footer: 'BREAKING CHANGE: some breaking change.\nThanks @stevemao',
notes:
[ { title: 'BREAKING CHANGE',
text: 'some breaking change.\nThanks @stevemao' } ],
references: [],
mentions: [ 'stevemao' ],
revert: null }
```
## API
### conventionalCommitsParser([options])
Returns an transform stream. If there is any malformed commits it will be gracefully ignored (an empty data will be emitted so down stream can notice).
#### options
Type: `object`
##### mergePattern
Type: `regex` or `string` Default: null
Pattern to match merge headers. EG: branch merge, GitHub or GitLab like pull requests headers. When a merge header is parsed, the next line is used for conventional header parsing.
For example, if we have a commit
```
Merge pull request #1 from user/feature/feature-name
feat(scope): broadcast $destroy event on scope destruction
```
We can parse it with these options and the default headerPattern:
```js
{
mergePattern: /^Merge pull request #(\d+) from (.*)$/,
mergeCorrespondence: ['id', 'source']
}
```
##### mergeCorrespondence
Type: `array` of `string` or `string` Default: null
Used to define what capturing group of `mergePattern`.
If it's a `string` it will be converted to an `array` separated by a comma.
##### headerPattern
Type: `regex` or `string` Default: `/^(\w*)(?:\(([\w\$\.\-\* ]*)\))?\: (.*)$/`
Used to match header pattern.
##### headerCorrespondence
Type: `array` of `string` or `string` Default `['type', 'scope', 'subject']`
Used to define what capturing group of `headerPattern` captures what header part. The order of the array should correspond to the order of `headerPattern`'s capturing group. If the part is not captured it is `null`. If it's a `string` it will be converted to an `array` separated by a comma.
##### referenceActions
Type: `array` of `string` or `string` Default:
`[
'close',
'closes',
'closed',
'fix',
'fixes',
'fixed',
'resolve',
'resolves',
'resolved'
]`
Keywords to reference an issue. This value is case **insensitive**. If it's a `string` it will be converted to an `array` separated by a comma.
Set it to `null` to reference an issue without any action.
##### issuePrefixes
Type: `array` of `string` or `string` Default: `['#']`
The prefixes of an issue. EG: In `gh-123` `gh-` is the prefix.
##### issuePrefixesCaseSensitive
Type: `boolean` Default: false
Used to define if `issuePrefixes` should be considered case sensitive.
##### noteKeywords
Type: `array` of `string` or `string` Default: `['BREAKING CHANGE']`
Keywords for important notes. This value is case **insensitive**. If it's a `string` it will be converted to an `array` separated by a comma.
##### notesPattern
Type: `function` Default: `noteKeywordsSelection => ^[\\s|*]*(' + noteKeywordsSelection + ')[:\\s]+(.*)` where `noteKeywordsSelection` is `join(noteKeywords, '|')`
A function that takes `noteKeywordsSelection` and returns a `RegExp` to be matched against the notes.
##### fieldPattern
Type: `regex` or `string` Default: `/^-(.*?)-$/`
Pattern to match other fields.
##### revertPattern
Type: `regex` or `string` Default: `/^Revert\s"([\s\S]*)"\s*This reverts commit (\w*)\./`
Pattern to match what this commit reverts.
##### revertCorrespondence
Type: `array` of `string` or `string` Default: `['header', 'hash']`
Used to define what capturing group of `revertPattern` captures what reverted commit fields. The order of the array should correspond to the order of `revertPattern`'s capturing group.
For example, if we had commit
```
Revert "throw an error if a callback is passed"
This reverts commit 9bb4d6c.
```
If configured correctly, the parsed result would be
```js
{
revert: {
header: 'throw an error if a callback is passed',
hash: '9bb4d6c'
}
}
```
It implies that this commit reverts a commit with header `'throw an error if a callback is passed'` and hash `'9bb4d6c'`.
If it's a `string` it will be converted to an `array` separated by a comma.
##### commentChar
Type: `string` or `null` Default: null
What commentChar to use. By default it is `null`, so no comments are stripped.
Set to `#` if you pass the contents of `.git/COMMIT_EDITMSG` directly.
If you have configured the git commentchar via `git config core.commentchar` you'll want to pass what you have set there.
##### warn
Type: `function` or `boolean` Default: `function() {}`
What warn function to use. For example, `console.warn.bind(console)` or `grunt.log.writeln`. By default, it's a noop. If it is `true`, it will error if commit cannot be parsed (strict).
### conventionalCommitsParser.sync(commit, [options])
The sync version. Useful when parsing a single commit. Returns the result.
#### commit
A single commit to be parsed.
#### options
Same as the `options` of `conventionalCommitsParser`.
## CLI
You can use cli to practice writing commit messages or parse messages from files. Note: the sample output might be different. It's just for demonstration purposes.
```sh
$ npm install --global conventional-commits-parser
```
If you run `conventional-commits-parser` without any arguments
```sh
$ conventional-commits-parser
```
You will enter an interactive shell. To show your parsed output enter "return" three times (or enter your specified separator).
```sh
> fix(title): a title is fixed
{"type":"fix","scope":"title","subject":"a title is fixed","header":"fix(title): a title is fixed","body":null,"footer":null,"notes":[],"references":[],"revert":null}
```
You can also use cli to parse messages from files.
If you have log.txt
```text
feat(ngMessages): provide support for dynamic message resolution
Prior to this fix it was impossible to apply a binding to a the ngMessage directive to represent the name of the error.
BREAKING CHANGE: The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.
Closes #10036
Closes #9338
```
And you run
```sh
$ conventional-commits-parser log.txt
# or
$ cat log.txt | conventional-commits-parser
```
An array of json will be printed to stdout.
```sh
[
{"type":"feat","scope":"ngMessages","subject":"provide support for dynamic message resolution","header":"feat(ngMessages): provide support for dynamic message resolution","body":"Prior to this fix it was impossible to apply a binding to a the ngMessage directive to represent the name of the error.","footer":"BREAKING CHANGE: The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.\nCloses #10036\nCloses #9338","notes":[{"title":"BREAKING CHANGE","text":"The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive."}],"references":[{"action":"Closes","owner":null,"repository":null,"issue":"10036","raw":"#10036"},{"action":"Closes","owner":null,"repository":null,"issue":"9338","raw":"#9338"}],"revert":null}
]
```
Commits should be split by at least three newlines (`\n\n\n`) or you can specify a separator as the second argument.
Eg: in log2.txt
```text
docs(ngMessageExp): split ngMessage docs up to show its alias more clearly
===
fix($animate): applyStyles from options on leave
Closes #10068
```
And you run
```sh
$ conventional-commits-parser log2.txt '==='
```
```sh
[
{"type":"docs","scope":"ngMessageExp","subject":"split ngMessage docs up to show its alias more clearly","header":"docs(ngMessageExp): split ngMessage docs up to show its alias more clearly","body":null,"footer":null,"notes":[],"references":[],"revert":null}
,
{"type":"fix","scope":"$animate","subject":"applyStyles from options on leave","header":"fix($animate): applyStyles from options on leave","body":null,"footer":"Closes #10068","notes":[],"references":[{"action":"Closes","owner":null,"repository":null,"issue":"10068","raw":"#10068"}],"revert":null}
]
```
Will be printed out.
You can specify one or more files. The output array will be in order of the input file paths. If you specify more than one separator, the last one will be used.
## License
MIT © [Steve Mao](https://github.com/stevemao)
[npm-image]: https://badge.fury.io/js/conventional-commits-parser.svg
[npm-url]: https://npmjs.org/package/conventional-commits-parser
[travis-image]: https://travis-ci.org/conventional-changelog/conventional-commits-parser.svg?branch=master
[travis-url]: https://travis-ci.org/conventional-changelog/conventional-commits-parser
[daviddm-image]: https://david-dm.org/conventional-changelog/conventional-commits-parser.svg?theme=shields.io
[daviddm-url]: https://david-dm.org/conventional-changelog/conventional-commits-parser
[coveralls-image]: https://coveralls.io/repos/conventional-changelog/conventional-commits-parser/badge.svg
[coveralls-url]: https://coveralls.io/r/conventional-changelog/conventional-commits-parser

View File

@ -0,0 +1,165 @@
#!/usr/bin/env node
'use strict'
const conventionalCommitsParser = require('./')
const forEach = require('lodash').forEach
const fs = require('fs')
const isTextPath = require('is-text-path')
const JSONStream = require('JSONStream')
const meow = require('meow')
const readline = require('readline')
const split = require('split2')
const through = require('through2')
const filePaths = []
let separator = '\n\n\n'
const cli = meow(`
Practice writing commit messages or parse messages from files.
If used without specifying a text file path, you will enter an interactive shell.
Otherwise the commit messages in the files are parsed and printed
By default, commits will be split by three newlines ('\\n\\n\\n') or you can specify a separator.
Usage
conventional-commits-parser [<commit-separator>]
conventional-commits-parser [<commit-separator>] <path> [<path> ...]
cat <path> | conventional-commits-parser [<commit-separator>]
Example
conventional-commits-parser
conventional-commits-parser log.txt
cat log.txt | conventional-commits-parser
conventional-commits-parser log2.txt '===' >> parsed.txt
Options
-p, --header-pattern Regex to match header pattern
-c, --header-correspondence Comma separated parts used to define what capturing group of 'headerPattern' captures what
-r, --reference-actions Comma separated keywords that used to reference issues
-i, --issue-prefixes Comma separated prefixes of an issue
--issue-prefixes-case-sensitive Treat issue prefixes as case sensitive
-n, --note-keywords Comma separated keywords for important notes
-f, --field-pattern Regex to match other fields
--revert-pattern Regex to match revert pattern
--revert-correspondence Comma separated fields used to define what the commit reverts
-v, --verbose Verbose output
`, {
flags: {
'header-pattern': {
alias: 'p',
type: 'string'
},
'header-correspondence': {
alias: 'c',
type: 'string'
},
'reference-actions': {
alias: 'r',
type: 'string'
},
'issue-prefixes': {
alias: 'i',
type: 'string'
},
'issue-prefixes-case-sensitive': {
type: 'boolean'
},
'note-keywords': {
alias: 'n',
type: 'string'
},
'field-pattern': {
alias: 'f',
type: 'string'
},
'revert-pattern': {
type: 'string'
},
'revert-correspondence': {
type: 'string'
},
verbose: {
alias: 'v',
type: 'boolean'
}
}
})
forEach(cli.input, function (arg) {
if (isTextPath(arg)) {
filePaths.push(arg)
} else {
separator = arg
}
})
const length = filePaths.length
const options = cli.flags
if (options.verbose) {
options.warn = console.log.bind(console)
}
function processFile (fileIndex) {
const filePath = filePaths[fileIndex]
fs.createReadStream(filePath)
.on('error', function (err) {
console.warn('Failed to read file ' + filePath + '\n' + err)
if (++fileIndex < length) {
processFile(fileIndex)
}
})
.pipe(split(separator))
.pipe(conventionalCommitsParser(options))
.pipe(JSONStream.stringify())
.on('end', function () {
if (++fileIndex < length) {
processFile(fileIndex)
}
})
.pipe(process.stdout)
}
if (process.stdin.isTTY) {
if (length > 0) {
processFile(0)
} else {
let commit = ''
const stream = through()
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
terminal: true
})
stream.pipe(conventionalCommitsParser(options))
.pipe(JSONStream.stringify('', '', ''))
.pipe(through(function (chunk, enc, cb) {
if (chunk.toString() === '""') {
cb(null, 'Commit cannot be parsed\n')
} else {
cb(null, chunk + '\n')
}
}))
.pipe(process.stdout)
rl.on('line', function (line) {
commit += line + '\n'
if (commit.indexOf(separator) === -1) {
return
}
stream.write(commit)
commit = ''
})
}
} else {
options.warn = true
process.stdin
.pipe(split(separator))
.pipe(conventionalCommitsParser(options))
.on('error', function (err) {
console.error(err.toString())
process.exit(1)
})
.pipe(JSONStream.stringify())
.pipe(process.stdout)
}

View File

@ -0,0 +1,101 @@
'use strict'
const parser = require('./lib/parser')
const regex = require('./lib/regex')
const through = require('through2')
const _ = require('lodash')
function assignOpts (options) {
options = _.extend({
headerPattern: /^(\w*)(?:\(([\w$.\-*/ ]*)\))?: (.*)$/,
headerCorrespondence: ['type', 'scope', 'subject'],
referenceActions: [
'close',
'closes',
'closed',
'fix',
'fixes',
'fixed',
'resolve',
'resolves',
'resolved'
],
issuePrefixes: ['#'],
noteKeywords: ['BREAKING CHANGE'],
fieldPattern: /^-(.*?)-$/,
revertPattern: /^Revert\s"([\s\S]*)"\s*This reverts commit (\w*)\./,
revertCorrespondence: ['header', 'hash'],
warn: function () {},
mergePattern: null,
mergeCorrespondence: null
}, options)
if (typeof options.headerPattern === 'string') {
options.headerPattern = new RegExp(options.headerPattern)
}
if (typeof options.headerCorrespondence === 'string') {
options.headerCorrespondence = options.headerCorrespondence.split(',')
}
if (typeof options.referenceActions === 'string') {
options.referenceActions = options.referenceActions.split(',')
}
if (typeof options.issuePrefixes === 'string') {
options.issuePrefixes = options.issuePrefixes.split(',')
}
if (typeof options.noteKeywords === 'string') {
options.noteKeywords = options.noteKeywords.split(',')
}
if (typeof options.fieldPattern === 'string') {
options.fieldPattern = new RegExp(options.fieldPattern)
}
if (typeof options.revertPattern === 'string') {
options.revertPattern = new RegExp(options.revertPattern)
}
if (typeof options.revertCorrespondence === 'string') {
options.revertCorrespondence = options.revertCorrespondence.split(',')
}
if (typeof options.mergePattern === 'string') {
options.mergePattern = new RegExp(options.mergePattern)
}
return options
}
function conventionalCommitsParser (options) {
options = assignOpts(options)
const reg = regex(options)
return through.obj(function (data, enc, cb) {
let commit
try {
commit = parser(data.toString(), options, reg)
cb(null, commit)
} catch (err) {
if (options.warn === true) {
cb(err)
} else {
options.warn(err.toString())
cb(null, '')
}
}
})
}
function sync (commit, options) {
options = assignOpts(options)
const reg = regex(options)
return parser(commit, options, reg)
}
module.exports = conventionalCommitsParser
module.exports.sync = sync

View File

@ -0,0 +1,301 @@
'use strict'
const trimOffNewlines = require('trim-off-newlines')
const _ = require('lodash')
const CATCH_ALL = /()(.+)/gi
const SCISSOR = '# ------------------------ >8 ------------------------'
function append (src, line) {
if (src) {
src += '\n' + line
} else {
src = line
}
return src
}
function getCommentFilter (char) {
return function (line) {
return line.charAt(0) !== char
}
}
function truncateToScissor (lines) {
const scissorIndex = lines.indexOf(SCISSOR)
if (scissorIndex === -1) {
return lines
}
return lines.slice(0, scissorIndex)
}
function getReferences (input, regex) {
const references = []
let referenceSentences
let referenceMatch
const reApplicable = input.match(regex.references) !== null
? regex.references
: CATCH_ALL
while ((referenceSentences = reApplicable.exec(input))) {
const action = referenceSentences[1] || null
const sentence = referenceSentences[2]
while ((referenceMatch = regex.referenceParts.exec(sentence))) {
let owner = null
let repository = referenceMatch[1] || ''
const ownerRepo = repository.split('/')
if (ownerRepo.length > 1) {
owner = ownerRepo.shift()
repository = ownerRepo.join('/')
}
const reference = {
action: action,
owner: owner,
repository: repository || null,
issue: referenceMatch[3],
raw: referenceMatch[0],
prefix: referenceMatch[2]
}
references.push(reference)
}
}
return references
}
function passTrough () {
return true
}
function parser (raw, options, regex) {
if (!raw || !raw.trim()) {
throw new TypeError('Expected a raw commit')
}
if (_.isEmpty(options)) {
throw new TypeError('Expected options')
}
if (_.isEmpty(regex)) {
throw new TypeError('Expected regex')
}
let currentProcessedField
let mentionsMatch
const otherFields = {}
const commentFilter = typeof options.commentChar === 'string'
? getCommentFilter(options.commentChar)
: passTrough
const gpgFilter = line => !line.match(/^\s*gpg:/)
const rawLines = trimOffNewlines(raw).split(/\r?\n/)
const lines = truncateToScissor(rawLines).filter(commentFilter).filter(gpgFilter)
let continueNote = false
let isBody = true
const headerCorrespondence = _.map(options.headerCorrespondence, function (part) {
return part.trim()
})
const revertCorrespondence = _.map(options.revertCorrespondence, function (field) {
return field.trim()
})
const mergeCorrespondence = _.map(options.mergeCorrespondence, function (field) {
return field.trim()
})
let body = null
let footer = null
let header = null
const mentions = []
let merge = null
const notes = []
const references = []
let revert = null
if (lines.length === 0) {
return {
body: body,
footer: footer,
header: header,
mentions: mentions,
merge: merge,
notes: notes,
references: references,
revert: revert,
scope: null,
subject: null,
type: null
}
}
// msg parts
merge = lines.shift()
const mergeParts = {}
const headerParts = {}
body = ''
footer = ''
const mergeMatch = merge.match(options.mergePattern)
if (mergeMatch && options.mergePattern) {
merge = mergeMatch[0]
header = lines.shift()
while (!header.trim()) {
header = lines.shift()
}
_.forEach(mergeCorrespondence, function (partName, index) {
const partValue = mergeMatch[index + 1] || null
mergeParts[partName] = partValue
})
} else {
header = merge
merge = null
_.forEach(mergeCorrespondence, function (partName) {
mergeParts[partName] = null
})
}
const headerMatch = header.match(options.headerPattern)
if (headerMatch) {
_.forEach(headerCorrespondence, function (partName, index) {
const partValue = headerMatch[index + 1] || null
headerParts[partName] = partValue
})
} else {
_.forEach(headerCorrespondence, function (partName) {
headerParts[partName] = null
})
}
Array.prototype.push.apply(references, getReferences(header, {
references: regex.references,
referenceParts: regex.referenceParts
}))
// body or footer
_.forEach(lines, function (line) {
if (options.fieldPattern) {
const fieldMatch = options.fieldPattern.exec(line)
if (fieldMatch) {
currentProcessedField = fieldMatch[1]
return
}
if (currentProcessedField) {
otherFields[currentProcessedField] = append(otherFields[currentProcessedField], line)
return
}
}
let referenceMatched
// this is a new important note
const notesMatch = line.match(regex.notes)
if (notesMatch) {
continueNote = true
isBody = false
footer = append(footer, line)
const note = {
title: notesMatch[1],
text: notesMatch[2]
}
notes.push(note)
return
}
const lineReferences = getReferences(line, {
references: regex.references,
referenceParts: regex.referenceParts
})
if (lineReferences.length > 0) {
isBody = false
referenceMatched = true
continueNote = false
}
Array.prototype.push.apply(references, lineReferences)
if (referenceMatched) {
footer = append(footer, line)
return
}
if (continueNote) {
notes[notes.length - 1].text = append(notes[notes.length - 1].text, line)
footer = append(footer, line)
return
}
if (isBody) {
body = append(body, line)
} else {
footer = append(footer, line)
}
})
if (options.breakingHeaderPattern && notes.length === 0) {
const breakingHeader = header.match(options.breakingHeaderPattern)
if (breakingHeader) {
const noteText = breakingHeader[3] // the description of the change.
notes.push({
title: 'BREAKING CHANGE',
text: noteText
})
}
}
while ((mentionsMatch = regex.mentions.exec(raw))) {
mentions.push(mentionsMatch[1])
}
// does this commit revert any other commit?
const revertMatch = raw.match(options.revertPattern)
if (revertMatch) {
revert = {}
_.forEach(revertCorrespondence, function (partName, index) {
const partValue = revertMatch[index + 1] || null
revert[partName] = partValue
})
} else {
revert = null
}
_.map(notes, function (note) {
note.text = trimOffNewlines(note.text)
return note
})
const msg = _.merge(headerParts, mergeParts, {
merge: merge,
header: header,
body: body ? trimOffNewlines(body) : null,
footer: footer ? trimOffNewlines(footer) : null,
notes: notes,
references: references,
mentions: mentions,
revert: revert
}, otherFields)
return msg
}
module.exports = parser

View File

@ -0,0 +1,61 @@
'use strict'
const reNomatch = /(?!.*)/
function join (array, joiner) {
return array
.map(function (val) {
return val.trim()
})
.filter(function (val) {
return val.length
})
.join(joiner)
}
function getNotesRegex (noteKeywords, notesPattern) {
if (!noteKeywords) {
return reNomatch
}
const noteKeywordsSelection = join(noteKeywords, '|')
if (!notesPattern) {
return new RegExp('^[\\s|*]*(' + noteKeywordsSelection + ')[:\\s]+(.*)', 'i')
}
return notesPattern(noteKeywordsSelection)
}
function getReferencePartsRegex (issuePrefixes, issuePrefixesCaseSensitive) {
if (!issuePrefixes) {
return reNomatch
}
const flags = issuePrefixesCaseSensitive ? 'g' : 'gi'
return new RegExp('(?:.*?)??\\s*([\\w-\\.\\/]*?)??(' + join(issuePrefixes, '|') + ')([\\w-]*\\d+)', flags)
}
function getReferencesRegex (referenceActions) {
if (!referenceActions) {
// matches everything
return /()(.+)/gi
}
const joinedKeywords = join(referenceActions, '|')
return new RegExp('(' + joinedKeywords + ')(?:\\s+(.*?))(?=(?:' + joinedKeywords + ')|$)', 'gi')
}
module.exports = function (options) {
options = options || {}
const reNotes = getNotesRegex(options.noteKeywords, options.notesPattern)
const reReferenceParts = getReferencePartsRegex(options.issuePrefixes, options.issuePrefixesCaseSensitive)
const reReferences = getReferencesRegex(options.referenceActions)
return {
notes: reNotes,
referenceParts: reReferenceParts,
references: reReferences,
mentions: /@([\w-]+)/g
}
}

View File

@ -0,0 +1,58 @@
{
"name": "conventional-commits-parser",
"version": "3.2.0",
"description": "Parse raw conventional commits",
"bugs": {
"url": "https://github.com/conventional-changelog/conventional-changelog/issues"
},
"homepage": "https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#readme",
"author": {
"name": "Steve Mao",
"email": "maochenyan@gmail.com",
"url": "https://github.com/stevemao"
},
"repository": {
"type": "git",
"url": "https://github.com/conventional-changelog/conventional-changelog.git"
},
"license": "MIT",
"engines": {
"node": ">=10"
},
"files": [
"index.js",
"cli.js",
"lib"
],
"keywords": [
"conventional-commits-parser",
"changelog",
"conventional",
"parser",
"parsing",
"logs"
],
"dependencies": {
"JSONStream": "^1.0.4",
"is-text-path": "^1.0.1",
"lodash": "^4.17.15",
"meow": "^8.0.0",
"split2": "^2.0.0",
"through2": "^4.0.0",
"trim-off-newlines": "^1.0.0"
},
"scripts": {
"test-windows": "echo 'make work on windows'"
},
"bin": {
"conventional-commits-parser": "cli.js"
},
"devDependencies": {
"forceable-tty": "^0.1.0"
},
"gitHead": "cc567b98facf71315f4b1620d81ce01d155efaca"
,"_resolved": "https://registry.npmjs.org/conventional-commits-parser/-/conventional-commits-parser-3.2.0.tgz"
,"_integrity": "sha512-XmJiXPxsF0JhAKyfA2Nn+rZwYKJ60nanlbSWwwkGwLQFbugsc0gv1rzc7VbbUWAzJfR1qR87/pNgv9NgmxtBMQ=="
,"_from": "conventional-commits-parser@3.2.0"
}

View File

@ -0,0 +1,206 @@
# Change Log
All notable changes to this project will be documented in this file.
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
## [4.1.1](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@4.1.0...git-semver-tags@4.1.1) (2020-11-05)
### Bug Fixes
* bug in unstableTagTest causing a mismatch on beta release higher then beta-9 ([#679](https://github.com/conventional-changelog/conventional-changelog/issues/679)) ([cd4c726](https://github.com/conventional-changelog/conventional-changelog/commit/cd4c726b1ca227a132ec2eadac5d0cfdd75d9e81))
# [4.1.0](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@4.0.0...git-semver-tags@4.1.0) (2020-08-12)
### Features
* add support for '--skip-unstable' option ([#656](https://github.com/conventional-changelog/conventional-changelog/issues/656)) ([#656](https://github.com/conventional-changelog/conventional-changelog/issues/656)) ([0679d7a](https://github.com/conventional-changelog/conventional-changelog/commit/0679d7a1d7a8715918326f31ec3f6168c2341fd6))
# [4.0.0](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@3.0.1...git-semver-tags@4.0.0) (2020-05-08)
### Bug Fixes
* **deps:** update yargs-parser to move off a flagged-vulnerable version. ([#635](https://github.com/conventional-changelog/conventional-changelog/issues/635)) ([aafc0f0](https://github.com/conventional-changelog/conventional-changelog/commit/aafc0f00412c3e4b23b8418300e5a570a48fe24d))
* **git-semver-tags:** change --tagPrefix flag to --tag-prefix ([#566](https://github.com/conventional-changelog/conventional-changelog/issues/566)) ([490cda6](https://github.com/conventional-changelog/conventional-changelog/commit/490cda6cff74abe63617f982765b63aebdf3b4b6)), closes [#553](https://github.com/conventional-changelog/conventional-changelog/issues/553)
### BREAKING CHANGES
* **git-semver-tags:** --tagPrefix flag was changed to --tag-prefix
## [3.0.1](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@3.0.0...git-semver-tags@3.0.1) (2019-11-14)
### Bug Fixes
* add types for cli flags ([#551](https://github.com/conventional-changelog/conventional-changelog/issues/551)) ([bf1d64a](https://github.com/conventional-changelog/conventional-changelog/commit/bf1d64aeaf8f262d4b2beec02d2aebb78df7343b))
# [3.0.0](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@2.0.3...git-semver-tags@3.0.0) (2019-07-29)
* refactor!: modify gitSemverTags to take options first (#390) ([dc8aeda](https://github.com/conventional-changelog/conventional-changelog/commit/dc8aeda)), closes [#390](https://github.com/conventional-changelog/conventional-changelog/issues/390)
### BREAKING CHANGES
* gitSemverTags now takes options followed by callback.
## [2.0.3](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@2.0.2...git-semver-tags@2.0.3) (2019-05-18)
### Bug Fixes
* **deps:** update dependency semver to v6 ([#458](https://github.com/conventional-changelog/conventional-changelog/issues/458)) ([efaa7bb](https://github.com/conventional-changelog/conventional-changelog/commit/efaa7bb))
## [2.0.2](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@2.0.1...git-semver-tags@2.0.2) (2018-11-01)
### Bug Fixes
* bad release of git-semver-tags ([8827ae4](https://github.com/conventional-changelog/conventional-changelog/commit/8827ae4))
## [2.0.1](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@2.0.0...git-semver-tags@2.0.1) (2018-11-01)
### Bug Fixes
* Upgrade to Lerna 3, fix Node.js v11 error ([#385](https://github.com/conventional-changelog/conventional-changelog/issues/385)) ([cdef282](https://github.com/conventional-changelog/conventional-changelog/commit/cdef282))
<a name="2.0.0"></a>
# [2.0.0](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@1.3.6...git-semver-tags@2.0.0) (2018-05-29)
### Chores
* **package:** set Node requirement to oldest supported LTS ([#329](https://github.com/conventional-changelog/conventional-changelog/issues/329)) ([cae2fe0](https://github.com/conventional-changelog/conventional-changelog/commit/cae2fe0))
### BREAKING CHANGES
* **package:** Set the package's minimum required Node version to be the oldest LTS
currently supported by the Node Release working group. At this time,
that is Node 6 (which is in its Maintenance LTS phase).
<a name="1.3.6"></a>
## [1.3.6](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@1.3.5...git-semver-tags@1.3.6) (2018-03-27)
**Note:** Version bump only for package git-semver-tags
<a name="1.3.5"></a>
## [1.3.5](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@1.3.4...git-semver-tags@1.3.5) (2018-03-22)
**Note:** Version bump only for package git-semver-tags
<a name="1.3.4"></a>
## [1.3.4](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@1.3.3...git-semver-tags@1.3.4) (2018-02-24)
**Note:** Version bump only for package git-semver-tags
<a name="1.3.3"></a>
## [1.3.3](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@1.3.2...git-semver-tags@1.3.3) (2018-02-20)
**Note:** Version bump only for package git-semver-tags
<a name="1.3.2"></a>
## [1.3.2](https://github.com/stevemao/git-semver-tags/compare/git-semver-tags@1.3.1...git-semver-tags@1.3.2) (2018-02-13)
**Note:** Version bump only for package git-semver-tags
<a name="1.3.1"></a>
## [1.3.1](https://github.com/stevemao/git-semver-tags/compare/git-semver-tags@1.3.0...git-semver-tags@1.3.1) (2018-02-13)
**Note:** Version bump only for package git-semver-tags
<a name="1.3.0"></a>
# [1.3.0](https://github.com/stevemao/git-semver-tags/compare/git-semver-tags@1.2.3...git-semver-tags@1.3.0) (2018-01-29)
### Features
* allow to specify a tagPrefix in conventional-recommended-bump ([f60f86f](https://github.com/stevemao/git-semver-tags/commit/f60f86f))
<a name="1.2.3"></a>
## [1.2.3](https://github.com/stevemao/git-semver-tags/compare/git-semver-tags@1.2.2...git-semver-tags@1.2.3) (2017-11-13)
**Note:** Version bump only for package git-semver-tags
<a name="1.2.2"></a>
## [1.2.2](https://github.com/stevemao/git-semver-tags/compare/git-semver-tags@1.2.1...git-semver-tags@1.2.2) (2017-10-01)
### Bug Fixes
* **lerna tags:** support multi-digit version tags ([#223](https://github.com/conventional-changelog/conventional-changelog/issues/223)) ([67012fb](https://github.com/stevemao/git-semver-tags/commit/67012fb))
<a name="1.2.1"></a>
## [1.2.1](https://github.com/stevemao/git-semver-tags/compare/git-semver-tags@1.2.0...git-semver-tags@1.2.1) (2017-07-17)
<a name="1.2.0"></a>
# [1.0.0](https://github.com/conventional-changelog/conventional-changelog/compare/git-semver-tags@1.1.2...v1.2.0) (2017-03-10)
### Features
* add support for listing lerna style tags (project[@version](https://github.com/version)) ([#161](https://github.com/conventional-changelog/conventional-changelog/issues/161)) ([b245f9d](https://github.com/conventional-changelog/conventional-changelog/commit/b245f9d))
* migrate repo to lerna mono-repo ([793e823](https://github.com/conventional-changelog/conventional-changelog/commit/793e823))

View File

@ -0,0 +1,21 @@
### MIT License
Copyright © [conventional-changelog team](https://github.com/conventional-changelog)
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.

View File

@ -0,0 +1,54 @@
# [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage Status][coveralls-image]][coveralls-url]
> Get all git semver tags of your repository in reverse chronological order
*Note:* since lightweight tags do not store date information, the date of a tag is the date of the commit that is tagged on. If two tags on one commit, the order is not guaranteed.
## Install
```sh
$ npm install --save git-semver-tags
```
## Usage
```js
var gitSemverTags = require('git-semver-tags');
// gitSemverTags([options,] callback)
gitSemverTags(function(err, tags) {
console.log(tags);
//=> [ 'v2.0.0', 'v1.0.0' ]
});
```
```sh
$ npm install --global git-semver-tags
$ git-semver-tags
v2.0.0
v1.0.0
```
## Options
* `opts.lernaTags`: extract lerna style tags (`foo-package@2.0.0`) from the
git history, rather than `v1.0.0` format.
* `opts.package`: what package should lerna style tags be listed for, e.g.,
`foo-package`.
* `opts.tagPrefix`: specify a prefix for the git tag to be ignored from the semver checks
## License
MIT © [Steve Mao](https://github.com/stevemao)
[npm-image]: https://badge.fury.io/js/git-semver-tags.svg
[npm-url]: https://npmjs.org/package/git-semver-tags
[travis-image]: https://travis-ci.org/conventional-changelog/git-semver-tags.svg?branch=master
[travis-url]: https://travis-ci.org/conventional-changelog/git-semver-tags
[daviddm-image]: https://david-dm.org/stevemao/git-semver-tags.svg?theme=shields.io
[daviddm-url]: https://david-dm.org/stevemao/git-semver-tags
[coveralls-image]: https://coveralls.io/repos/stevemao/git-semver-tags/badge.svg
[coveralls-url]: https://coveralls.io/r/stevemao/git-semver-tags

View File

@ -0,0 +1,43 @@
#!/usr/bin/env node
'use strict'
const meow = require('meow')
const gitSemverTags = require('./')
const args = meow(`
Usage
git-semver-tags
Options
--cwd path to git repository to be searched
--lerna parse lerna style git tags
--package <name> when listing lerna style tags, filter by a package
--tag-prefix <prefix> prefix to remove from the tags during their processing`,
{
booleanDefault: undefined,
flags: {
cwd: {
type: 'string'
},
lerna: {
type: 'boolean'
},
package: {
type: 'string'
},
tagPrefix: {
type: 'string'
}
}
})
gitSemverTags({
lernaTags: args.flags.lerna,
package: args.flags.package,
tagPrefix: args.flags.tagPrefix
}, function (err, tags) {
if (err) {
console.error(err.toString())
process.exit(1)
}
console.log(tags.join('\n'))
})

View File

@ -0,0 +1,68 @@
'use strict'
const proc = require('process')
const exec = require('child_process').exec
const semverValid = require('semver').valid
const regex = /tag:\s*(.+?)[,)]/gi
const cmd = 'git log --decorate --no-color'
const unstableTagTest = /.+-\w+\.\d+$/
function lernaTag (tag, pkg) {
if (pkg && !(new RegExp('^' + pkg + '@')).test(tag)) {
return false
} else {
return /^.+@[0-9]+\.[0-9]+\.[0-9]+(-.+)?$/.test(tag)
}
}
module.exports = function gitSemverTags (opts, callback) {
if (typeof opts === 'function') {
callback = opts
opts = {}
}
const options = Object.assign({ maxBuffer: Infinity, cwd: proc.cwd() }, opts)
if (options.package && !options.lernaTags) {
callback(new Error('opts.package should only be used when running in lerna mode'))
return
}
exec(cmd, options, function (err, data) {
if (err) {
callback(err)
return
}
const tags = []
let tagPrefixRegexp
if (options.tagPrefix) {
tagPrefixRegexp = new RegExp('^' + options.tagPrefix + '(.*)')
}
data.split('\n').forEach(function (decorations) {
let match
while ((match = regex.exec(decorations))) {
const tag = match[1]
if (options.skipUnstable && unstableTagTest.test(tag)) {
// skip unstable tag
continue
}
if (options.lernaTags) {
if (lernaTag(tag, options.package)) {
tags.push(tag)
}
} else if (options.tagPrefix) {
const matches = tag.match(tagPrefixRegexp)
if (matches && semverValid(matches[1])) {
tags.push(tag)
}
} else if (semverValid(tag)) {
tags.push(tag)
}
}
})
callback(null, tags)
})
}

View File

@ -0,0 +1 @@
../semver/bin/semver.js

View File

@ -0,0 +1,70 @@
# changes log
## 6.2.0
* Coerce numbers to strings when passed to semver.coerce()
* Add `rtl` option to coerce from right to left
## 6.1.3
* Handle X-ranges properly in includePrerelease mode
## 6.1.2
* Do not throw when testing invalid version strings
## 6.1.1
* Add options support for semver.coerce()
* Handle undefined version passed to Range.test
## 6.1.0
* Add semver.compareBuild function
* Support `*` in semver.intersects
## 6.0
* Fix `intersects` logic.
This is technically a bug fix, but since it is also a change to behavior
that may require users updating their code, it is marked as a major
version increment.
## 5.7
* Add `minVersion` method
## 5.6
* Move boolean `loose` param to an options object, with
backwards-compatibility protection.
* Add ability to opt out of special prerelease version handling with
the `includePrerelease` option flag.
## 5.5
* Add version coercion capabilities
## 5.4
* Add intersection checking
## 5.3
* Add `minSatisfying` method
## 5.2
* Add `prerelease(v)` that returns prerelease components
## 5.1
* Add Backus-Naur for ranges
* Remove excessively cute inspection methods
## 5.0
* Remove AMD/Browserified build artifacts
* Fix ltr and gtr when using the `*` range
* Fix for range `*` with a prerelease identifier

View File

@ -0,0 +1,15 @@
The ISC License
Copyright (c) Isaac Z. Schlueter and Contributors
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

View File

@ -0,0 +1,443 @@
semver(1) -- The semantic versioner for npm
===========================================
## Install
```bash
npm install semver
````
## Usage
As a node module:
```js
const semver = require('semver')
semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean(' =v1.2.3 ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```
As a command-line utility:
```
$ semver -h
A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter
Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence
Options:
-r --range <range>
Print versions that match the specified range.
-i --increment [<level>]
Increment a version by the specified level. Level can
be one of: major, minor, patch, premajor, preminor,
prepatch, or prerelease. Default level is 'patch'.
Only one version may be specified.
--preid <identifier>
Identifier to be used to prefix premajor, preminor,
prepatch or prerelease version increments.
-l --loose
Interpret versions and ranges loosely
-p --include-prerelease
Always include prerelease versions in range matching
-c --coerce
Coerce a string into SemVer if possible
(does not imply --loose)
--rtl
Coerce version strings right to left
--ltr
Coerce version strings left to right (default)
Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.
If no satisfying versions are found, then exits failure.
Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```
## Versions
A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.
A leading `"="` or `"v"` character is stripped off and ignored.
## Ranges
A `version range` is a set of `comparators` which specify versions
that satisfy the range.
A `comparator` is composed of an `operator` and a `version`. The set
of primitive `operators` is:
* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal. If no operator is specified, then equality is assumed,
so this operator is optional, but MAY be included.
For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`.
Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.
A range is composed of one or more comparator sets, joined by `||`. A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.
For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.
The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.
### Prerelease Tags
If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.
For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules. The version
range only accepts prerelease tags on the `1.2.3` version. The
version `3.4.5` *would* satisfy the range, because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.
The purpose for this behavior is twofold. First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range matching
semantics.
Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use *that specific* set of
alpha/beta/rc versions. By including a prerelease tag in the range,
the user is indicating that they are aware of the risk. However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.
Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.
#### Prerelease Identifiers
The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:
```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```
command-line example:
```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```
Which then can be used to increment further:
```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```
### Advanced Range Syntax
Advanced range syntax desugars to primitive comparators in
deterministic ways.
Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.
#### Hyphen Ranges `X.Y.Z - A.B.C`
Specifies an inclusive set.
* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`
If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.
* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`
If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.
* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`
#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.
* `*` := `>=0.0.0` (Any version satisfies)
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)
A partial version range is treated as an X-Range, so the special
character is in fact optional.
* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`
#### Tilde Ranges `~1.2.3` `~1.2` `~1`
Allows patch-level changes if a minor version is specified on the
comparator. Allows minor-level changes if not.
* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
the `1.2.3` version will be allowed, if they are greater than or
equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
`1.2.4-beta.2` would not, because it is a prerelease of a
different `[major, minor, patch]` tuple.
#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple. In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.
Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`. It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.
* `^1.2.3` := `>=1.2.3 <2.0.0`
* `^0.2.3` := `>=0.2.3 <0.3.0`
* `^0.0.3` := `>=0.0.3 <0.0.4`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
the `1.2.3` version will be allowed, if they are greater than or
equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
`1.2.4-beta.2` would not, because it is a prerelease of a
different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4` Note that prereleases in the
`0.0.3` version *only* will be allowed, if they are greater than or
equal to `beta`. So, `0.0.3-pr.2` would be allowed.
When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.
* `^1.2.x` := `>=1.2.0 <2.0.0`
* `^0.0.x` := `>=0.0.0 <0.1.0`
* `^0.0` := `>=0.0.0 <0.1.0`
A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.
* `^1.x` := `>=1.0.0 <2.0.0`
* `^0.x` := `>=0.0.0 <1.0.0`
### Range Grammar
Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:
```bnf
range-set ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range ::= hyphen | simple ( ' ' simple ) * | ''
hyphen ::= partial ' - ' partial
simple ::= primitive | partial | tilde | caret
primitive ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr ::= 'x' | 'X' | '*' | nr
nr ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde ::= '~' partial
caret ::= '^' partial
qualifier ::= ( '-' pre )? ( '+' build )?
pre ::= parts
build ::= parts
parts ::= part ( '.' part ) *
part ::= nr | [-0-9A-Za-z]+
```
## Functions
All methods and classes take a final `options` object argument. All
options in this object are `false` by default. The options supported
are:
- `loose` Be more forgiving about not-quite-valid semver strings.
(Any resulting output will always be 100% strict compliant, of
course.) For backwards compatibility reasons, if the `options`
argument is a boolean value instead of an object, it is interpreted
to be the `loose` param.
- `includePrerelease` Set to suppress the [default
behavior](https://github.com/npm/node-semver#prerelease-tags) of
excluding prerelease tagged versions from ranges unless they are
explicitly opted into.
Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.
* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, release)`: Return the version incremented by the release
type (`major`, `premajor`, `minor`, `preminor`, `patch`,
`prepatch`, or `prerelease`), or null if it's not valid
* `premajor` in one call will bump the version up to the next major
version and down to a prerelease of that major version.
`preminor`, and `prepatch` work the same way.
* If called from a non-prerelease version, the `prerelease` will work the
same as `prepatch`. It increments the patch version, then makes a
prerelease. If the input version is already a prerelease it simply
increments it.
* `prerelease(v)`: Returns an array of prerelease components, or null
if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
a `SemVer` object or `null`.
### Comparison
* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
even if they're not the exact same string. You already know how to
compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
the corresponding function above. `"==="` and `"!=="` do simple
string comparison, but are included for completeness. Throws if an
invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
`v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions
in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
are equal. Sorts in ascending order if passed to `Array.sort()`.
`v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
* `diff(v1, v2)`: Returns difference between two versions by the release type
(`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
or null if the versions are the same.
### Comparators
* `intersects(comparator)`: Return true if the comparators intersect
### Ranges
* `validRange(range)`: Return the valid range or null if it's not valid
* `satisfies(version, range)`: Return true if the version satisfies the
range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can possibly match
the given range.
* `gtr(version, range)`: Return `true` if version is greater than all the
versions possible in the range.
* `ltr(version, range)`: Return `true` if version is less than all the
versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
the bounds of the range in either the high or low direction. The
`hilo` argument must be either the string `'>'` or `'<'`. (This is
the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the ranges comparators intersect
Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range! For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so the version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.
If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.
### Coercion
* `coerce(version, options)`: Coerces a string to semver if possible
This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters). Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`). All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`). Only text which lacks digits will fail coercion (`version one`
is not valid). The maximum length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`). The maximum value for any
semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).
If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple. For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`. `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.
### Clean
* `clean(version)`: Clean a string to be a valid semver if possible
This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges.
ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean(' =v2.1.5')`: `2.1.5`
* `s.clean(' 2.1.5 ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`

View File

@ -0,0 +1,174 @@
#!/usr/bin/env node
// Standalone semver comparison program.
// Exits successfully and prints matching version(s) if
// any supplied version is valid and passes all tests.
var argv = process.argv.slice(2)
var versions = []
var range = []
var inc = null
var version = require('../package.json').version
var loose = false
var includePrerelease = false
var coerce = false
var rtl = false
var identifier
var semver = require('../semver')
var reverse = false
var options = {}
main()
function main () {
if (!argv.length) return help()
while (argv.length) {
var a = argv.shift()
var indexOfEqualSign = a.indexOf('=')
if (indexOfEqualSign !== -1) {
a = a.slice(0, indexOfEqualSign)
argv.unshift(a.slice(indexOfEqualSign + 1))
}
switch (a) {
case '-rv': case '-rev': case '--rev': case '--reverse':
reverse = true
break
case '-l': case '--loose':
loose = true
break
case '-p': case '--include-prerelease':
includePrerelease = true
break
case '-v': case '--version':
versions.push(argv.shift())
break
case '-i': case '--inc': case '--increment':
switch (argv[0]) {
case 'major': case 'minor': case 'patch': case 'prerelease':
case 'premajor': case 'preminor': case 'prepatch':
inc = argv.shift()
break
default:
inc = 'patch'
break
}
break
case '--preid':
identifier = argv.shift()
break
case '-r': case '--range':
range.push(argv.shift())
break
case '-c': case '--coerce':
coerce = true
break
case '--rtl':
rtl = true
break
case '--ltr':
rtl = false
break
case '-h': case '--help': case '-?':
return help()
default:
versions.push(a)
break
}
}
var options = { loose: loose, includePrerelease: includePrerelease, rtl: rtl }
versions = versions.map(function (v) {
return coerce ? (semver.coerce(v, options) || { version: v }).version : v
}).filter(function (v) {
return semver.valid(v)
})
if (!versions.length) return fail()
if (inc && (versions.length !== 1 || range.length)) { return failInc() }
for (var i = 0, l = range.length; i < l; i++) {
versions = versions.filter(function (v) {
return semver.satisfies(v, range[i], options)
})
if (!versions.length) return fail()
}
return success(versions)
}
function failInc () {
console.error('--inc can only be used on a single version with no range')
fail()
}
function fail () { process.exit(1) }
function success () {
var compare = reverse ? 'rcompare' : 'compare'
versions.sort(function (a, b) {
return semver[compare](a, b, options)
}).map(function (v) {
return semver.clean(v, options)
}).map(function (v) {
return inc ? semver.inc(v, inc, options, identifier) : v
}).forEach(function (v, i, _) { console.log(v) })
}
function help () {
console.log(['SemVer ' + version,
'',
'A JavaScript implementation of the https://semver.org/ specification',
'Copyright Isaac Z. Schlueter',
'',
'Usage: semver [options] <version> [<version> [...]]',
'Prints valid versions sorted by SemVer precedence',
'',
'Options:',
'-r --range <range>',
' Print versions that match the specified range.',
'',
'-i --increment [<level>]',
' Increment a version by the specified level. Level can',
' be one of: major, minor, patch, premajor, preminor,',
" prepatch, or prerelease. Default level is 'patch'.",
' Only one version may be specified.',
'',
'--preid <identifier>',
' Identifier to be used to prefix premajor, preminor,',
' prepatch or prerelease version increments.',
'',
'-l --loose',
' Interpret versions and ranges loosely',
'',
'-p --include-prerelease',
' Always include prerelease versions in range matching',
'',
'-c --coerce',
' Coerce a string into SemVer if possible',
' (does not imply --loose)',
'',
'--rtl',
' Coerce version strings right to left',
'',
'--ltr',
' Coerce version strings left to right (default)',
'',
'Program exits successfully if any valid version satisfies',
'all supplied ranges, and prints all satisfying versions.',
'',
'If no satisfying versions are found, then exits failure.',
'',
'Versions are printed in ascending order, so supplying',
'multiple versions to the utility will just sort them.'
].join('\n'))
}

View File

@ -0,0 +1,32 @@
{
"name": "semver",
"version": "6.3.0",
"description": "The semantic version parser used by npm.",
"main": "semver.js",
"scripts": {
"test": "tap",
"preversion": "npm test",
"postversion": "npm publish",
"postpublish": "git push origin --follow-tags"
},
"devDependencies": {
"tap": "^14.3.1"
},
"license": "ISC",
"repository": "https://github.com/npm/node-semver",
"bin": {
"semver": "./bin/semver.js"
},
"files": [
"bin",
"range.bnf",
"semver.js"
],
"tap": {
"check-coverage": true
}
,"_resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz"
,"_integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw=="
,"_from": "semver@6.3.0"
}

View File

@ -0,0 +1,16 @@
range-set ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range ::= hyphen | simple ( ' ' simple ) * | ''
hyphen ::= partial ' - ' partial
simple ::= primitive | partial | tilde | caret
primitive ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr ::= 'x' | 'X' | '*' | nr
nr ::= '0' | [1-9] ( [0-9] ) *
tilde ::= '~' partial
caret ::= '^' partial
qualifier ::= ( '-' pre )? ( '+' build )?
pre ::= parts
build ::= parts
parts ::= part ( '.' part ) *
part ::= nr | [-0-9A-Za-z]+

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,49 @@
{
"name": "git-semver-tags",
"version": "4.1.1",
"description": "Get all git semver tags of your repository in reverse chronological order",
"bugs": {
"url": "https://github.com/conventional-changelog/conventional-changelog/issues"
},
"homepage": "https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-semver-tags#readme",
"author": {
"name": "Steve Mao",
"email": "maochenyan@gmail.com",
"url": "https://github.com/stevemao"
},
"repository": {
"type": "git",
"url": "https://github.com/conventional-changelog/conventional-changelog.git"
},
"license": "MIT",
"engines": {
"node": ">=10"
},
"files": [
"index.js",
"cli.js"
],
"keywords": [
"git-semver-tags",
"order",
"semver",
"tag",
"git-tag",
"git"
],
"dependencies": {
"meow": "^8.0.0",
"semver": "^6.0.0"
},
"scripts": {
"test-windows": "mocha --timeout 30000"
},
"bin": {
"git-semver-tags": "cli.js"
},
"gitHead": "cc567b98facf71315f4b1620d81ce01d155efaca"
,"_resolved": "https://registry.npmjs.org/git-semver-tags/-/git-semver-tags-4.1.1.tgz"
,"_integrity": "sha512-OWyMt5zBe7xFs8vglMmhM9lRQzCWL3WjHtxNNfJTMngGym7pC1kh8sP6jevfydJ6LP3ZvGxfb6ABYgPUM0mtsA=="
,"_from": "git-semver-tags@4.1.1"
}

View File

@ -0,0 +1,175 @@
# Change Log
All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
<a name="3.0.7"></a>
## [3.0.7](https://github.com/npm/hosted-git-info/compare/v3.0.6...v3.0.7) (2020-10-15)
### Bug Fixes
* correctly filter out urls for tarballs in gitlab ([eb5bd5a](https://github.com/npm/hosted-git-info/commit/eb5bd5a)), closes [#69](https://github.com/npm/hosted-git-info/issues/69)
<a name="3.0.6"></a>
## [3.0.6](https://github.com/npm/hosted-git-info/compare/v3.0.5...v3.0.6) (2020-10-12)
### Bug Fixes
* support to github gist legacy hash length ([c067102](https://github.com/npm/hosted-git-info/commit/c067102)), closes [#68](https://github.com/npm/hosted-git-info/issues/68)
<a name="3.0.5"></a>
## [3.0.5](https://github.com/npm/hosted-git-info/compare/v3.0.4...v3.0.5) (2020-07-11)
<a name="3.0.4"></a>
## [3.0.4](https://github.com/npm/hosted-git-info/compare/v3.0.3...v3.0.4) (2020-02-26)
### Bug Fixes
* Do not pass scp-style URLs to the WhatWG url.URL ([0835306](https://github.com/npm/hosted-git-info/commit/0835306)), closes [#60](https://github.com/npm/hosted-git-info/issues/60) [#63](https://github.com/npm/hosted-git-info/issues/63)
<a name="3.0.3"></a>
## [3.0.3](https://github.com/npm/hosted-git-info/compare/v3.0.2...v3.0.3) (2020-02-25)
<a name="3.0.2"></a>
## [3.0.2](https://github.com/npm/hosted-git-info/compare/v3.0.1...v3.0.2) (2019-10-08)
### Bug Fixes
* do not encodeURIComponent the domain ([3e5fbec](https://github.com/npm/hosted-git-info/commit/3e5fbec)), closes [#53](https://github.com/npm/hosted-git-info/issues/53)
<a name="3.0.1"></a>
## [3.0.1](https://github.com/npm/hosted-git-info/compare/v3.0.0...v3.0.1) (2019-10-07)
### Bug Fixes
* update pathmatch for gitlab ([e3e3054](https://github.com/npm/hosted-git-info/commit/e3e3054)), closes [#52](https://github.com/npm/hosted-git-info/issues/52)
* updated pathmatch for gitlab ([fa87af7](https://github.com/npm/hosted-git-info/commit/fa87af7))
<a name="3.0.0"></a>
# [3.0.0](https://github.com/npm/hosted-git-info/compare/v2.8.3...v3.0.0) (2019-08-12)
### Bug Fixes
* **cache:** Switch to lru-cache to save ourselves from unlimited memory consumption ([37c2891](https://github.com/npm/hosted-git-info/commit/37c2891)), closes [#38](https://github.com/npm/hosted-git-info/issues/38)
### BREAKING CHANGES
* **cache:** Drop support for node 0.x
<a name="2.8.3"></a>
## [2.8.3](https://github.com/npm/hosted-git-info/compare/v2.8.2...v2.8.3) (2019-08-12)
<a name="2.8.2"></a>
## [2.8.2](https://github.com/npm/hosted-git-info/compare/v2.8.1...v2.8.2) (2019-08-05)
### Bug Fixes
* http protocol use sshurl by default ([3b1d629](https://github.com/npm/hosted-git-info/commit/3b1d629)), closes [#48](https://github.com/npm/hosted-git-info/issues/48)
<a name="2.8.1"></a>
## [2.8.1](https://github.com/npm/hosted-git-info/compare/v2.8.0...v2.8.1) (2019-08-05)
### Bug Fixes
* ignore noCommittish on tarball url generation ([5d4a8d7](https://github.com/npm/hosted-git-info/commit/5d4a8d7))
* use gist tarball url that works for anonymous gists ([1692435](https://github.com/npm/hosted-git-info/commit/1692435))
<a name="2.8.0"></a>
# [2.8.0](https://github.com/npm/hosted-git-info/compare/v2.7.1...v2.8.0) (2019-08-05)
### Bug Fixes
* Allow slashes in gitlab project section ([bbcf7b2](https://github.com/npm/hosted-git-info/commit/bbcf7b2)), closes [#46](https://github.com/npm/hosted-git-info/issues/46) [#43](https://github.com/npm/hosted-git-info/issues/43)
* **git-host:** disallow URI-encoded slash (%2F) in `path` ([3776fa5](https://github.com/npm/hosted-git-info/commit/3776fa5)), closes [#44](https://github.com/npm/hosted-git-info/issues/44)
* **gitlab:** Do not URL encode slashes in project name for GitLab https URL ([cbf04f9](https://github.com/npm/hosted-git-info/commit/cbf04f9)), closes [#47](https://github.com/npm/hosted-git-info/issues/47)
* do not allow invalid gist urls ([d5cf830](https://github.com/npm/hosted-git-info/commit/d5cf830))
* **cache:** Switch to lru-cache to save ourselves from unlimited memory consumption ([e518222](https://github.com/npm/hosted-git-info/commit/e518222)), closes [#38](https://github.com/npm/hosted-git-info/issues/38)
### Features
* give these objects a name ([60abaea](https://github.com/npm/hosted-git-info/commit/60abaea))
<a name="2.7.1"></a>
## [2.7.1](https://github.com/npm/hosted-git-info/compare/v2.7.0...v2.7.1) (2018-07-07)
### Bug Fixes
* **index:** Guard against non-string types ([5bc580d](https://github.com/npm/hosted-git-info/commit/5bc580d))
* **parse:** Crash on strings that parse to having no host ([c931482](https://github.com/npm/hosted-git-info/commit/c931482)), closes [#35](https://github.com/npm/hosted-git-info/issues/35)
<a name="2.7.0"></a>
# [2.7.0](https://github.com/npm/hosted-git-info/compare/v2.6.1...v2.7.0) (2018-07-06)
### Bug Fixes
* **github tarball:** update github tarballtemplate ([6efd582](https://github.com/npm/hosted-git-info/commit/6efd582)), closes [#34](https://github.com/npm/hosted-git-info/issues/34)
* **gitlab docs:** switched to lowercase anchors for readmes ([701bcd1](https://github.com/npm/hosted-git-info/commit/701bcd1))
### Features
* **all:** Support www. prefixes on hostnames ([3349575](https://github.com/npm/hosted-git-info/commit/3349575)), closes [#32](https://github.com/npm/hosted-git-info/issues/32)
<a name="2.6.1"></a>
## [2.6.1](https://github.com/npm/hosted-git-info/compare/v2.6.0...v2.6.1) (2018-06-25)
### Bug Fixes
* **Revert:** "compat: remove Object.assign fallback ([#25](https://github.com/npm/hosted-git-info/issues/25))" ([cce5a62](https://github.com/npm/hosted-git-info/commit/cce5a62))
* **Revert:** "git-host: fix forgotten extend()" ([a815ec9](https://github.com/npm/hosted-git-info/commit/a815ec9))
<a name="2.6.0"></a>
# [2.6.0](https://github.com/npm/hosted-git-info/compare/v2.5.0...v2.6.0) (2018-03-07)
### Bug Fixes
* **compat:** remove Object.assign fallback ([#25](https://github.com/npm/hosted-git-info/issues/25)) ([627ab55](https://github.com/npm/hosted-git-info/commit/627ab55))
* **git-host:** fix forgotten extend() ([eba1f7b](https://github.com/npm/hosted-git-info/commit/eba1f7b))
### Features
* **browse:** fragment support for browse() ([#28](https://github.com/npm/hosted-git-info/issues/28)) ([cd5e5bb](https://github.com/npm/hosted-git-info/commit/cd5e5bb))

View File

@ -0,0 +1,13 @@
Copyright (c) 2015, Rebecca Turner
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

View File

@ -0,0 +1,133 @@
# hosted-git-info
This will let you identify and transform various git hosts URLs between
protocols. It also can tell you what the URL is for the raw path for
particular file for direct access without git.
## Example
```javascript
var hostedGitInfo = require("hosted-git-info")
var info = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git", opts)
/* info looks like:
{
type: "github",
domain: "github.com",
user: "npm",
project: "hosted-git-info"
}
*/
```
If the URL can't be matched with a git host, `null` will be returned. We
can match git, ssh and https urls. Additionally, we can match ssh connect
strings (`git@github.com:npm/hosted-git-info`) and shortcuts (eg,
`github:npm/hosted-git-info`). Github specifically, is detected in the case
of a third, unprefixed, form: `npm/hosted-git-info`.
If it does match, the returned object has properties of:
* info.type -- The short name of the service
* info.domain -- The domain for git protocol use
* info.user -- The name of the user/org on the git host
* info.project -- The name of the project on the git host
## Version Contract
The major version will be bumped any time…
* The constructor stops accepting URLs that it previously accepted.
* A method is removed.
* A method can no longer accept the number and type of arguments it previously accepted.
* A method can return a different type than it currently returns.
Implications:
* I do not consider the specific format of the urls returned from, say
`.https()` to be a part of the contract. The contract is that it will
return a string that can be used to fetch the repo via HTTPS. But what
that string looks like, specifically, can change.
* Dropping support for a hosted git provider would constitute a breaking
change.
## Usage
### var info = hostedGitInfo.fromUrl(gitSpecifier[, options])
* *gitSpecifer* is a URL of a git repository or a SCP-style specifier of one.
* *options* is an optional object. It can have the following properties:
* *noCommittish* — If true then committishes won't be included in generated URLs.
* *noGitPlus* — If true then `git+` won't be prefixed on URLs.
## Methods
All of the methods take the same options as the `fromUrl` factory. Options
provided to a method override those provided to the constructor.
* info.file(path, opts)
Given the path of a file relative to the repository, returns a URL for
directly fetching it from the githost. If no committish was set then
`master` will be used as the default.
For example `hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git#v1.0.0").file("package.json")`
would return `https://raw.githubusercontent.com/npm/hosted-git-info/v1.0.0/package.json`
* info.shortcut(opts)
eg, `github:npm/hosted-git-info`
* info.browse(path, fragment, opts)
eg, `https://github.com/npm/hosted-git-info/tree/v1.2.0`,
`https://github.com/npm/hosted-git-info/tree/v1.2.0/package.json`,
`https://github.com/npm/hosted-git-info/tree/v1.2.0/REAMDE.md#supported-hosts`
* info.bugs(opts)
eg, `https://github.com/npm/hosted-git-info/issues`
* info.docs(opts)
eg, `https://github.com/npm/hosted-git-info/tree/v1.2.0#readme`
* info.https(opts)
eg, `git+https://github.com/npm/hosted-git-info.git`
* info.sshurl(opts)
eg, `git+ssh://git@github.com/npm/hosted-git-info.git`
* info.ssh(opts)
eg, `git@github.com:npm/hosted-git-info.git`
* info.path(opts)
eg, `npm/hosted-git-info`
* info.tarball(opts)
eg, `https://github.com/npm/hosted-git-info/archive/v1.2.0.tar.gz`
* info.getDefaultRepresentation()
Returns the default output type. The default output type is based on the
string you passed in to be parsed
* info.toString(opts)
Uses the getDefaultRepresentation to call one of the other methods to get a URL for
this resource. As such `hostedGitInfo.fromUrl(url).toString()` will give
you a normalized version of the URL that still uses the same protocol.
Shortcuts will still be returned as shortcuts, but the special case github
form of `org/project` will be normalized to `github:org/project`.
SSH connect strings will be normalized into `git+ssh` URLs.
## Supported hosts
Currently this supports Github, Bitbucket and Gitlab. Pull requests for
additional hosts welcome.

View File

@ -0,0 +1,79 @@
'use strict'
var gitHosts = module.exports = {
github: {
// First two are insecure and generally shouldn't be used any more, but
// they are still supported.
'protocols': [ 'git', 'http', 'git+ssh', 'git+https', 'ssh', 'https' ],
'domain': 'github.com',
'treepath': 'tree',
'filetemplate': 'https://{auth@}raw.githubusercontent.com/{user}/{project}/{committish}/{path}',
'bugstemplate': 'https://{domain}/{user}/{project}/issues',
'gittemplate': 'git://{auth@}{domain}/{user}/{project}.git{#committish}',
'tarballtemplate': 'https://codeload.{domain}/{user}/{project}/tar.gz/{committish}'
},
bitbucket: {
'protocols': [ 'git+ssh', 'git+https', 'ssh', 'https' ],
'domain': 'bitbucket.org',
'treepath': 'src',
'tarballtemplate': 'https://{domain}/{user}/{project}/get/{committish}.tar.gz'
},
gitlab: {
'protocols': [ 'git+ssh', 'git+https', 'ssh', 'https' ],
'domain': 'gitlab.com',
'treepath': 'tree',
'bugstemplate': 'https://{domain}/{user}/{project}/issues',
'httpstemplate': 'git+https://{auth@}{domain}/{user}/{projectPath}.git{#committish}',
'tarballtemplate': 'https://{domain}/{user}/{project}/repository/archive.tar.gz?ref={committish}',
'pathmatch': /^\/([^/]+)\/((?!.*(\/-\/|\/repository(\/[^/]+)?\/archive\.tar\.gz)).*?)(?:\.git|\/)?$/
},
gist: {
'protocols': [ 'git', 'git+ssh', 'git+https', 'ssh', 'https' ],
'domain': 'gist.github.com',
'pathmatch': /^[/](?:([^/]+)[/])?([a-z0-9]{7,})(?:[.]git)?$/,
'filetemplate': 'https://gist.githubusercontent.com/{user}/{project}/raw{/committish}/{path}',
'bugstemplate': 'https://{domain}/{project}',
'gittemplate': 'git://{domain}/{project}.git{#committish}',
'sshtemplate': 'git@{domain}:/{project}.git{#committish}',
'sshurltemplate': 'git+ssh://git@{domain}/{project}.git{#committish}',
'browsetemplate': 'https://{domain}/{project}{/committish}',
'browsefiletemplate': 'https://{domain}/{project}{/committish}{#path}',
'docstemplate': 'https://{domain}/{project}{/committish}',
'httpstemplate': 'git+https://{domain}/{project}.git{#committish}',
'shortcuttemplate': '{type}:{project}{#committish}',
'pathtemplate': '{project}{#committish}',
'tarballtemplate': 'https://codeload.github.com/gist/{project}/tar.gz/{committish}',
'hashformat': function (fragment) {
return 'file-' + formatHashFragment(fragment)
}
}
}
var gitHostDefaults = {
'sshtemplate': 'git@{domain}:{user}/{project}.git{#committish}',
'sshurltemplate': 'git+ssh://git@{domain}/{user}/{project}.git{#committish}',
'browsetemplate': 'https://{domain}/{user}/{project}{/tree/committish}',
'browsefiletemplate': 'https://{domain}/{user}/{project}/{treepath}/{committish}/{path}{#fragment}',
'docstemplate': 'https://{domain}/{user}/{project}{/tree/committish}#readme',
'httpstemplate': 'git+https://{auth@}{domain}/{user}/{project}.git{#committish}',
'filetemplate': 'https://{domain}/{user}/{project}/raw/{committish}/{path}',
'shortcuttemplate': '{type}:{user}/{project}{#committish}',
'pathtemplate': '{user}/{project}{#committish}',
'pathmatch': /^[/]([^/]+)[/]([^/]+?)(?:[.]git|[/])?$/,
'hashformat': formatHashFragment
}
Object.keys(gitHosts).forEach(function (name) {
Object.keys(gitHostDefaults).forEach(function (key) {
if (gitHosts[name][key]) return
gitHosts[name][key] = gitHostDefaults[key]
})
gitHosts[name].protocols_re = RegExp('^(' +
gitHosts[name].protocols.map(function (protocol) {
return protocol.replace(/([\\+*{}()[\]$^|])/g, '\\$1')
}).join('|') + '):$')
})
function formatHashFragment (fragment) {
return fragment.toLowerCase().replace(/^\W+|\/|\W+$/g, '').replace(/\W+/g, '-')
}

View File

@ -0,0 +1,156 @@
'use strict'
var gitHosts = require('./git-host-info.js')
/* eslint-disable node/no-deprecated-api */
// copy-pasta util._extend from node's source, to avoid pulling
// the whole util module into peoples' webpack bundles.
/* istanbul ignore next */
var extend = Object.assign || function _extend (target, source) {
// Don't do anything if source isn't an object
if (source === null || typeof source !== 'object') return target
const keys = Object.keys(source)
let i = keys.length
while (i--) {
target[keys[i]] = source[keys[i]]
}
return target
}
module.exports = GitHost
function GitHost (type, user, auth, project, committish, defaultRepresentation, opts) {
var gitHostInfo = this
gitHostInfo.type = type
Object.keys(gitHosts[type]).forEach(function (key) {
gitHostInfo[key] = gitHosts[type][key]
})
gitHostInfo.user = user
gitHostInfo.auth = auth
gitHostInfo.project = project
gitHostInfo.committish = committish
gitHostInfo.default = defaultRepresentation
gitHostInfo.opts = opts || {}
}
GitHost.prototype.hash = function () {
return this.committish ? '#' + this.committish : ''
}
GitHost.prototype._fill = function (template, opts) {
if (!template) return
var vars = extend({}, opts)
vars.path = vars.path ? vars.path.replace(/^[/]+/g, '') : ''
opts = extend(extend({}, this.opts), opts)
var self = this
Object.keys(this).forEach(function (key) {
if (self[key] != null && vars[key] == null) vars[key] = self[key]
})
var rawAuth = vars.auth
var rawcommittish = vars.committish
var rawFragment = vars.fragment
var rawPath = vars.path
var rawProject = vars.project
Object.keys(vars).forEach(function (key) {
var value = vars[key]
if ((key === 'path' || key === 'project') && typeof value === 'string') {
vars[key] = value.split('/').map(function (pathComponent) {
return encodeURIComponent(pathComponent)
}).join('/')
} else if (key !== 'domain') {
vars[key] = encodeURIComponent(value)
}
})
vars['auth@'] = rawAuth ? rawAuth + '@' : ''
vars['#fragment'] = rawFragment ? '#' + this.hashformat(rawFragment) : ''
vars.fragment = vars.fragment ? vars.fragment : ''
vars['#path'] = rawPath ? '#' + this.hashformat(rawPath) : ''
vars['/path'] = vars.path ? '/' + vars.path : ''
vars.projectPath = rawProject.split('/').map(encodeURIComponent).join('/')
if (opts.noCommittish) {
vars['#committish'] = ''
vars['/tree/committish'] = ''
vars['/committish'] = ''
vars.committish = ''
} else {
vars['#committish'] = rawcommittish ? '#' + rawcommittish : ''
vars['/tree/committish'] = vars.committish
? '/' + vars.treepath + '/' + vars.committish
: ''
vars['/committish'] = vars.committish ? '/' + vars.committish : ''
vars.committish = vars.committish || 'master'
}
var res = template
Object.keys(vars).forEach(function (key) {
res = res.replace(new RegExp('[{]' + key + '[}]', 'g'), vars[key])
})
if (opts.noGitPlus) {
return res.replace(/^git[+]/, '')
} else {
return res
}
}
GitHost.prototype.ssh = function (opts) {
return this._fill(this.sshtemplate, opts)
}
GitHost.prototype.sshurl = function (opts) {
return this._fill(this.sshurltemplate, opts)
}
GitHost.prototype.browse = function (P, F, opts) {
if (typeof P === 'string') {
if (typeof F !== 'string') {
opts = F
F = null
}
return this._fill(this.browsefiletemplate, extend({
fragment: F,
path: P
}, opts))
} else {
return this._fill(this.browsetemplate, P)
}
}
GitHost.prototype.docs = function (opts) {
return this._fill(this.docstemplate, opts)
}
GitHost.prototype.bugs = function (opts) {
return this._fill(this.bugstemplate, opts)
}
GitHost.prototype.https = function (opts) {
return this._fill(this.httpstemplate, opts)
}
GitHost.prototype.git = function (opts) {
return this._fill(this.gittemplate, opts)
}
GitHost.prototype.shortcut = function (opts) {
return this._fill(this.shortcuttemplate, opts)
}
GitHost.prototype.path = function (opts) {
return this._fill(this.pathtemplate, opts)
}
GitHost.prototype.tarball = function (opts_) {
var opts = extend({}, opts_, { noCommittish: false })
return this._fill(this.tarballtemplate, opts)
}
GitHost.prototype.file = function (P, opts) {
return this._fill(this.filetemplate, extend({ path: P }, opts))
}
GitHost.prototype.getDefaultRepresentation = function () {
return this.default
}
GitHost.prototype.toString = function (opts) {
if (this.default && typeof this[this.default] === 'function') return this[this.default](opts)
return this.sshurl(opts)
}

View File

@ -0,0 +1,146 @@
'use strict'
var url = require('url')
var gitHosts = require('./git-host-info.js')
var GitHost = module.exports = require('./git-host.js')
var LRU = require('lru-cache')
var cache = new LRU({max: 1000})
var protocolToRepresentationMap = {
'git+ssh:': 'sshurl',
'git+https:': 'https',
'ssh:': 'sshurl',
'git:': 'git'
}
function protocolToRepresentation (protocol) {
return protocolToRepresentationMap[protocol] || protocol.slice(0, -1)
}
var authProtocols = {
'git:': true,
'https:': true,
'git+https:': true,
'http:': true,
'git+http:': true
}
module.exports.fromUrl = function (giturl, opts) {
if (typeof giturl !== 'string') return
var key = giturl + JSON.stringify(opts || {})
if (!cache.has(key)) {
cache.set(key, fromUrl(giturl, opts))
}
return cache.get(key)
}
function fromUrl (giturl, opts) {
if (giturl == null || giturl === '') return
var url = fixupUnqualifiedGist(
isGitHubShorthand(giturl) ? 'github:' + giturl : giturl
)
var parsed = parseGitUrl(url)
var shortcutMatch = url.match(new RegExp('^([^:]+):(?:(?:[^@:]+(?:[^@]+)?@)?([^/]*))[/](.+?)(?:[.]git)?($|#)'))
var matches = Object.keys(gitHosts).map(function (gitHostName) {
try {
var gitHostInfo = gitHosts[gitHostName]
var auth = null
if (parsed.auth && authProtocols[parsed.protocol]) {
auth = parsed.auth
}
var committish = parsed.hash ? decodeURIComponent(parsed.hash.substr(1)) : null
var user = null
var project = null
var defaultRepresentation = null
if (shortcutMatch && shortcutMatch[1] === gitHostName) {
user = shortcutMatch[2] && decodeURIComponent(shortcutMatch[2])
project = decodeURIComponent(shortcutMatch[3])
defaultRepresentation = 'shortcut'
} else {
if (parsed.host && parsed.host !== gitHostInfo.domain && parsed.host.replace(/^www[.]/, '') !== gitHostInfo.domain) return
if (!gitHostInfo.protocols_re.test(parsed.protocol)) return
if (!parsed.path) return
var pathmatch = gitHostInfo.pathmatch
var matched = parsed.path.match(pathmatch)
if (!matched) return
/* istanbul ignore else */
if (matched[1] !== null && matched[1] !== undefined) {
user = decodeURIComponent(matched[1].replace(/^:/, ''))
}
project = decodeURIComponent(matched[2])
defaultRepresentation = protocolToRepresentation(parsed.protocol)
}
return new GitHost(gitHostName, user, auth, project, committish, defaultRepresentation, opts)
} catch (ex) {
/* istanbul ignore else */
if (ex instanceof URIError) {
} else throw ex
}
}).filter(function (gitHostInfo) { return gitHostInfo })
if (matches.length !== 1) return
return matches[0]
}
function isGitHubShorthand (arg) {
// Note: This does not fully test the git ref format.
// See https://www.kernel.org/pub/software/scm/git/docs/git-check-ref-format.html
//
// The only way to do this properly would be to shell out to
// git-check-ref-format, and as this is a fast sync function,
// we don't want to do that. Just let git fail if it turns
// out that the commit-ish is invalid.
// GH usernames cannot start with . or -
return /^[^:@%/\s.-][^:@%/\s]*[/][^:@\s/%]+(?:#.*)?$/.test(arg)
}
function fixupUnqualifiedGist (giturl) {
// necessary for round-tripping gists
var parsed = url.parse(giturl)
if (parsed.protocol === 'gist:' && parsed.host && !parsed.path) {
return parsed.protocol + '/' + parsed.host
} else {
return giturl
}
}
function parseGitUrl (giturl) {
var matched = giturl.match(/^([^@]+)@([^:/]+):[/]?((?:[^/]+[/])?[^/]+?)(?:[.]git)?(#.*)?$/)
if (!matched) {
var legacy = url.parse(giturl)
if (legacy.auth) {
// git urls can be in the form of scp-style/ssh-connect strings, like
// git+ssh://user@host.com:some/path, which the legacy url parser
// supports, but WhatWG url.URL class does not. However, the legacy
// parser de-urlencodes the username and password, so something like
// https://user%3An%40me:p%40ss%3Aword@x.com/ becomes
// https://user:n@me:p@ss:word@x.com/ which is all kinds of wrong.
// Pull off just the auth and host, so we dont' get the confusing
// scp-style URL, then pass that to the WhatWG parser to get the
// auth properly escaped.
const authmatch = giturl.match(/[^@]+@[^:/]+/)
/* istanbul ignore else - this should be impossible */
if (authmatch) {
var whatwg = new url.URL(authmatch[0])
legacy.auth = whatwg.username || ''
if (whatwg.password) legacy.auth += ':' + whatwg.password
}
}
return legacy
}
return {
protocol: 'git+ssh:',
slashes: true,
auth: matched[1],
host: matched[2],
port: null,
hostname: matched[2],
hash: matched[4],
search: null,
query: null,
pathname: '/' + matched[3],
path: '/' + matched[3],
href: 'git+ssh://' + matched[1] + '@' + matched[2] +
'/' + matched[3] + (matched[4] || '')
}
}

View File

@ -0,0 +1,50 @@
{
"name": "hosted-git-info",
"version": "3.0.7",
"description": "Provides metadata and conversions from repository urls for Github, Bitbucket and Gitlab",
"main": "index.js",
"repository": {
"type": "git",
"url": "git+https://github.com/npm/hosted-git-info.git"
},
"keywords": [
"git",
"github",
"bitbucket",
"gitlab"
],
"author": "Rebecca Turner <me@re-becca.org> (http://re-becca.org)",
"license": "ISC",
"bugs": {
"url": "https://github.com/npm/hosted-git-info/issues"
},
"homepage": "https://github.com/npm/hosted-git-info",
"scripts": {
"prerelease": "npm t",
"postrelease": "npm publish && git push --follow-tags",
"posttest": "standard",
"release": "standard-version -s",
"test:coverage": "tap --coverage-report=html -J --100 --no-esm test/*.js",
"test": "tap -J --100 --no-esm test/*.js"
},
"dependencies": {
"lru-cache": "^6.0.0"
},
"devDependencies": {
"standard": "^11.0.1",
"standard-version": "^4.4.0",
"tap": "^12.7.0"
},
"files": [
"index.js",
"git-host.js",
"git-host-info.js"
],
"engines": {
"node": ">=10"
}
,"_resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-3.0.7.tgz"
,"_integrity": "sha512-fWqc0IcuXs+BmE9orLDyVykAG9GJtGLGuZAAqgcckPgv5xad4AcXGIv8galtQvlwutxSlaMcdw7BUtq2EIvqCQ=="
,"_from": "hosted-git-info@3.0.7"
}

View File

@ -0,0 +1,306 @@
import {PackageJson} from 'type-fest';
declare namespace meow {
type FlagType = 'string' | 'boolean' | 'number';
/**
Callback function to determine if a flag is required during runtime.
@param flags - Contains the flags converted to camel-case excluding aliases.
@param input - Contains the non-flag arguments.
@returns True if the flag is required, otherwise false.
*/
type IsRequiredPredicate = (flags: Readonly<AnyFlags>, input: readonly string[]) => boolean;
interface Flag<Type extends FlagType, Default> {
readonly type?: Type;
readonly alias?: string;
readonly default?: Default;
readonly isRequired?: boolean | IsRequiredPredicate;
readonly isMultiple?: boolean;
}
type StringFlag = Flag<'string', string>;
type BooleanFlag = Flag<'boolean', boolean>;
type NumberFlag = Flag<'number', number>;
type AnyFlag = StringFlag | BooleanFlag | NumberFlag;
type AnyFlags = Record<string, AnyFlag>;
interface Options<Flags extends AnyFlags> {
/**
Define argument flags.
The key is the flag name and the value is an object with any of:
- `type`: Type of value. (Possible values: `string` `boolean` `number`)
- `alias`: Usually used to define a short flag alias.
- `default`: Default value when the flag is not specified.
- `isRequired`: Determine if the flag is required.
If it's only known at runtime whether the flag is required or not you can pass a Function instead of a boolean, which based on the given flags and other non-flag arguments should decide if the flag is required.
- `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values are *not* supported.
@example
```
flags: {
unicorn: {
type: 'string',
alias: 'u',
default: ['rainbow', 'cat'],
isMultiple: true,
isRequired: (flags, input) => {
if (flags.otherFlag) {
return true;
}
return false;
}
}
}
```
*/
readonly flags?: Flags;
/**
Description to show above the help text. Default: The package.json `"description"` property.
Set it to `false` to disable it altogether.
*/
readonly description?: string | false;
/**
The help text you want shown.
The input is reindented and starting/ending newlines are trimmed which means you can use a [template literal](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/template_strings) without having to care about using the correct amount of indent.
The description will be shown above your help text automatically.
Set it to `false` to disable it altogether.
*/
readonly help?: string | false;
/**
Set a custom version output. Default: The package.json `"version"` property.
Set it to `false` to disable it altogether.
*/
readonly version?: string | false;
/**
Automatically show the help text when the `--help` flag is present. Useful to set this value to `false` when a CLI manages child CLIs with their own help text.
This option is only considered when there is only one argument in `process.argv`.
*/
readonly autoHelp?: boolean;
/**
Automatically show the version text when the `--version` flag is present. Useful to set this value to `false` when a CLI manages child CLIs with their own version text.
This option is only considered when there is only one argument in `process.argv`.
*/
readonly autoVersion?: boolean;
/**
`package.json` as an `Object`. Default: Closest `package.json` upwards.
_You most likely don't need this option._
*/
readonly pkg?: Record<string, unknown>;
/**
Custom arguments object.
@default process.argv.slice(2)
*/
readonly argv?: readonly string[];
/**
Infer the argument type.
By default, the argument `5` in `$ foo 5` becomes a string. Enabling this would infer it as a number.
@default false
*/
readonly inferType?: boolean;
/**
Value of `boolean` flags not defined in `argv`.
If set to `undefined`, the flags not defined in `argv` will be excluded from the result. The `default` value set in `boolean` flags take precedence over `booleanDefault`.
_Note: If used in conjunction with `isMultiple`, the default flag value is set to `[]`._
__Caution: Explicitly specifying `undefined` for `booleanDefault` has different meaning from omitting key itself.__
@example
```
import meow = require('meow');
const cli = meow(`
Usage
$ foo
Options
--rainbow, -r Include a rainbow
--unicorn, -u Include a unicorn
--no-sparkles Exclude sparkles
Examples
$ foo
🌈 unicorns✨🌈
`, {
booleanDefault: undefined,
flags: {
rainbow: {
type: 'boolean',
default: true,
alias: 'r'
},
unicorn: {
type: 'boolean',
default: false,
alias: 'u'
},
cake: {
type: 'boolean',
alias: 'c'
},
sparkles: {
type: 'boolean',
default: true
}
}
});
//{
// flags: {
// rainbow: true,
// unicorn: false,
// sparkles: true
// },
// unnormalizedFlags: {
// rainbow: true,
// r: true,
// unicorn: false,
// u: false,
// sparkles: true
// },
// …
//}
```
*/
readonly booleanDefault?: boolean | null | undefined;
/**
Whether to use [hard-rejection](https://github.com/sindresorhus/hard-rejection) or not. Disabling this can be useful if you need to handle `process.on('unhandledRejection')` yourself.
@default true
*/
readonly hardRejection?: boolean;
}
type TypedFlag<Flag extends AnyFlag> =
Flag extends {type: 'number'}
? number
: Flag extends {type: 'string'}
? string
: Flag extends {type: 'boolean'}
? boolean
: unknown;
type PossiblyOptionalFlag<Flag extends AnyFlag, FlagType> =
Flag extends {isRequired: true}
? FlagType
: Flag extends {default: any}
? FlagType
: FlagType | undefined;
type TypedFlags<Flags extends AnyFlags> = {
[F in keyof Flags]: Flags[F] extends {isMultiple: true}
? PossiblyOptionalFlag<Flags[F], Array<TypedFlag<Flags[F]>>>
: PossiblyOptionalFlag<Flags[F], TypedFlag<Flags[F]>>
};
interface Result<Flags extends AnyFlags> {
/**
Non-flag arguments.
*/
input: string[];
/**
Flags converted to camelCase excluding aliases.
*/
flags: TypedFlags<Flags> & Record<string, unknown>;
/**
Flags converted camelCase including aliases.
*/
unnormalizedFlags: TypedFlags<Flags> & Record<string, unknown>;
/**
The `package.json` object.
*/
pkg: PackageJson;
/**
The help text used with `--help`.
*/
help: string;
/**
Show the help text and exit with code.
@param exitCode - The exit code to use. Default: `2`.
*/
showHelp: (exitCode?: number) => void;
/**
Show the version text and exit.
*/
showVersion: () => void;
}
}
/**
@param helpMessage - Shortcut for the `help` option.
@example
```
#!/usr/bin/env node
'use strict';
import meow = require('meow');
import foo = require('.');
const cli = meow(`
Usage
$ foo <input>
Options
--rainbow, -r Include a rainbow
Examples
$ foo unicorns --rainbow
🌈 unicorns 🌈
`, {
flags: {
rainbow: {
type: 'boolean',
alias: 'r'
}
}
});
//{
// input: ['unicorns'],
// flags: {rainbow: true},
// ...
//}
foo(cli.input[0], cli.flags);
```
*/
declare function meow<Flags extends meow.AnyFlags>(helpMessage: string, options?: meow.Options<Flags>): meow.Result<Flags>;
declare function meow<Flags extends meow.AnyFlags>(options?: meow.Options<Flags>): meow.Result<Flags>;
export = meow;

View File

@ -0,0 +1,206 @@
'use strict';
const path = require('path');
const buildParserOptions = require('minimist-options');
const parseArguments = require('yargs-parser');
const camelCaseKeys = require('camelcase-keys');
const decamelizeKeys = require('decamelize-keys');
const trimNewlines = require('trim-newlines');
const redent = require('redent');
const readPkgUp = require('read-pkg-up');
const hardRejection = require('hard-rejection');
const normalizePackageData = require('normalize-package-data');
// Prevent caching of this module so module.parent is always accurate
delete require.cache[__filename];
const parentDir = path.dirname(module.parent && module.parent.filename ? module.parent.filename : '.');
const isFlagMissing = (flagName, definedFlags, receivedFlags, input) => {
const flag = definedFlags[flagName];
let isFlagRequired = true;
if (typeof flag.isRequired === 'function') {
isFlagRequired = flag.isRequired(receivedFlags, input);
if (typeof isFlagRequired !== 'boolean') {
throw new TypeError(`Return value for isRequired callback should be of type boolean, but ${typeof isFlagRequired} was returned.`);
}
}
if (typeof receivedFlags[flagName] === 'undefined') {
return isFlagRequired;
}
return flag.isMultiple && receivedFlags[flagName].length === 0;
};
const getMissingRequiredFlags = (flags, receivedFlags, input) => {
const missingRequiredFlags = [];
if (typeof flags === 'undefined') {
return [];
}
for (const flagName of Object.keys(flags)) {
if (flags[flagName].isRequired && isFlagMissing(flagName, flags, receivedFlags, input)) {
missingRequiredFlags.push({key: flagName, ...flags[flagName]});
}
}
return missingRequiredFlags;
};
const reportMissingRequiredFlags = missingRequiredFlags => {
console.error(`Missing required flag${missingRequiredFlags.length > 1 ? 's' : ''}`);
for (const flag of missingRequiredFlags) {
console.error(`\t--${flag.key}${flag.alias ? `, -${flag.alias}` : ''}`);
}
};
const buildParserFlags = ({flags, booleanDefault}) => {
const parserFlags = {};
for (const [flagKey, flagValue] of Object.entries(flags)) {
const flag = {...flagValue};
if (
typeof booleanDefault !== 'undefined' &&
flag.type === 'boolean' &&
!Object.prototype.hasOwnProperty.call(flag, 'default')
) {
flag.default = flag.isMultiple ? [booleanDefault] : booleanDefault;
}
if (flag.isMultiple) {
flag.type = flag.type ? `${flag.type}-array` : 'array';
flag.default = flag.default || [];
delete flag.isMultiple;
}
parserFlags[flagKey] = flag;
}
return parserFlags;
};
const validateFlags = (flags, options) => {
for (const [flagKey, flagValue] of Object.entries(options.flags)) {
if (flagKey !== '--' && !flagValue.isMultiple && Array.isArray(flags[flagKey])) {
throw new Error(`The flag --${flagKey} can only be set once.`);
}
}
};
const meow = (helpText, options) => {
if (typeof helpText !== 'string') {
options = helpText;
helpText = '';
}
const foundPkg = readPkgUp.sync({
cwd: parentDir,
normalize: false
});
options = {
pkg: foundPkg ? foundPkg.packageJson : {},
argv: process.argv.slice(2),
flags: {},
inferType: false,
input: 'string',
help: helpText,
autoHelp: true,
autoVersion: true,
booleanDefault: false,
hardRejection: true,
...options
};
if (options.hardRejection) {
hardRejection();
}
let parserOptions = {
arguments: options.input,
...buildParserFlags(options)
};
parserOptions = decamelizeKeys(parserOptions, '-', {exclude: ['stopEarly', '--']});
if (options.inferType) {
delete parserOptions.arguments;
}
parserOptions = buildParserOptions(parserOptions);
parserOptions.configuration = {
...parserOptions.configuration,
'greedy-arrays': false
};
if (parserOptions['--']) {
parserOptions.configuration['populate--'] = true;
}
const {pkg} = options;
const argv = parseArguments(options.argv, parserOptions);
let help = redent(trimNewlines((options.help || '').replace(/\t+\n*$/, '')), 2);
normalizePackageData(pkg);
process.title = pkg.bin ? Object.keys(pkg.bin)[0] : pkg.name;
let {description} = options;
if (!description && description !== false) {
({description} = pkg);
}
help = (description ? `\n ${description}\n` : '') + (help ? `\n${help}\n` : '\n');
const showHelp = code => {
console.log(help);
process.exit(typeof code === 'number' ? code : 2);
};
const showVersion = () => {
console.log(typeof options.version === 'string' ? options.version : pkg.version);
process.exit(0);
};
if (argv._.length === 0 && options.argv.length === 1) {
if (argv.version === true && options.autoVersion) {
showVersion();
}
if (argv.help === true && options.autoHelp) {
showHelp(0);
}
}
const input = argv._;
delete argv._;
const flags = camelCaseKeys(argv, {exclude: ['--', /^\w$/]});
const unnormalizedFlags = {...flags};
validateFlags(flags, options);
for (const flagValue of Object.values(options.flags)) {
delete flags[flagValue.alias];
}
const missingRequiredFlags = getMissingRequiredFlags(options.flags, flags, input);
if (missingRequiredFlags.length > 0) {
reportMissingRequiredFlags(missingRequiredFlags);
process.exit(2);
}
return {
input,
flags,
unnormalizedFlags,
pkg,
help,
showHelp,
showVersion
};
};
module.exports = meow;

View File

@ -0,0 +1,9 @@
MIT License
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
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.

View File

@ -0,0 +1 @@
../semver/bin/semver

View File

@ -0,0 +1,141 @@
# Change Log
All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
<a name="2.8.8"></a>
## [2.8.8](https://github.com/npm/hosted-git-info/compare/v2.8.7...v2.8.8) (2020-02-29)
### Bug Fixes
* [#61](https://github.com/npm/hosted-git-info/issues/61) & [#65](https://github.com/npm/hosted-git-info/issues/65) addressing issues w/ url.URL implmentation which regressed node 6 support ([5038b18](https://github.com/npm/hosted-git-info/commit/5038b18)), closes [#66](https://github.com/npm/hosted-git-info/issues/66)
<a name="2.8.7"></a>
## [2.8.7](https://github.com/npm/hosted-git-info/compare/v2.8.6...v2.8.7) (2020-02-26)
### Bug Fixes
* Do not attempt to use url.URL when unavailable ([2d0bb66](https://github.com/npm/hosted-git-info/commit/2d0bb66)), closes [#61](https://github.com/npm/hosted-git-info/issues/61) [#62](https://github.com/npm/hosted-git-info/issues/62)
* Do not pass scp-style URLs to the WhatWG url.URL ([f2cdfcf](https://github.com/npm/hosted-git-info/commit/f2cdfcf)), closes [#60](https://github.com/npm/hosted-git-info/issues/60)
<a name="2.8.6"></a>
## [2.8.6](https://github.com/npm/hosted-git-info/compare/v2.8.5...v2.8.6) (2020-02-25)
<a name="2.8.5"></a>
## [2.8.5](https://github.com/npm/hosted-git-info/compare/v2.8.4...v2.8.5) (2019-10-07)
### Bug Fixes
* updated pathmatch for gitlab ([e8325b5](https://github.com/npm/hosted-git-info/commit/e8325b5)), closes [#51](https://github.com/npm/hosted-git-info/issues/51)
* updated pathmatch for gitlab ([ffe056f](https://github.com/npm/hosted-git-info/commit/ffe056f))
<a name="2.8.4"></a>
## [2.8.4](https://github.com/npm/hosted-git-info/compare/v2.8.3...v2.8.4) (2019-08-12)
<a name="2.8.3"></a>
## [2.8.3](https://github.com/npm/hosted-git-info/compare/v2.8.2...v2.8.3) (2019-08-12)
<a name="2.8.2"></a>
## [2.8.2](https://github.com/npm/hosted-git-info/compare/v2.8.1...v2.8.2) (2019-08-05)
### Bug Fixes
* http protocol use sshurl by default ([3b1d629](https://github.com/npm/hosted-git-info/commit/3b1d629)), closes [#48](https://github.com/npm/hosted-git-info/issues/48)
<a name="2.8.1"></a>
## [2.8.1](https://github.com/npm/hosted-git-info/compare/v2.8.0...v2.8.1) (2019-08-05)
### Bug Fixes
* ignore noCommittish on tarball url generation ([5d4a8d7](https://github.com/npm/hosted-git-info/commit/5d4a8d7))
* use gist tarball url that works for anonymous gists ([1692435](https://github.com/npm/hosted-git-info/commit/1692435))
<a name="2.8.0"></a>
# [2.8.0](https://github.com/npm/hosted-git-info/compare/v2.7.1...v2.8.0) (2019-08-05)
### Bug Fixes
* Allow slashes in gitlab project section ([bbcf7b2](https://github.com/npm/hosted-git-info/commit/bbcf7b2)), closes [#46](https://github.com/npm/hosted-git-info/issues/46) [#43](https://github.com/npm/hosted-git-info/issues/43)
* **git-host:** disallow URI-encoded slash (%2F) in `path` ([3776fa5](https://github.com/npm/hosted-git-info/commit/3776fa5)), closes [#44](https://github.com/npm/hosted-git-info/issues/44)
* **gitlab:** Do not URL encode slashes in project name for GitLab https URL ([cbf04f9](https://github.com/npm/hosted-git-info/commit/cbf04f9)), closes [#47](https://github.com/npm/hosted-git-info/issues/47)
* do not allow invalid gist urls ([d5cf830](https://github.com/npm/hosted-git-info/commit/d5cf830))
* **cache:** Switch to lru-cache to save ourselves from unlimited memory consumption ([e518222](https://github.com/npm/hosted-git-info/commit/e518222)), closes [#38](https://github.com/npm/hosted-git-info/issues/38)
### Features
* give these objects a name ([60abaea](https://github.com/npm/hosted-git-info/commit/60abaea))
<a name="2.7.1"></a>
## [2.7.1](https://github.com/npm/hosted-git-info/compare/v2.7.0...v2.7.1) (2018-07-07)
### Bug Fixes
* **index:** Guard against non-string types ([5bc580d](https://github.com/npm/hosted-git-info/commit/5bc580d))
* **parse:** Crash on strings that parse to having no host ([c931482](https://github.com/npm/hosted-git-info/commit/c931482)), closes [#35](https://github.com/npm/hosted-git-info/issues/35)
<a name="2.7.0"></a>
# [2.7.0](https://github.com/npm/hosted-git-info/compare/v2.6.1...v2.7.0) (2018-07-06)
### Bug Fixes
* **github tarball:** update github tarballtemplate ([6efd582](https://github.com/npm/hosted-git-info/commit/6efd582)), closes [#34](https://github.com/npm/hosted-git-info/issues/34)
* **gitlab docs:** switched to lowercase anchors for readmes ([701bcd1](https://github.com/npm/hosted-git-info/commit/701bcd1))
### Features
* **all:** Support www. prefixes on hostnames ([3349575](https://github.com/npm/hosted-git-info/commit/3349575)), closes [#32](https://github.com/npm/hosted-git-info/issues/32)
<a name="2.6.1"></a>
## [2.6.1](https://github.com/npm/hosted-git-info/compare/v2.6.0...v2.6.1) (2018-06-25)
### Bug Fixes
* **Revert:** "compat: remove Object.assign fallback ([#25](https://github.com/npm/hosted-git-info/issues/25))" ([cce5a62](https://github.com/npm/hosted-git-info/commit/cce5a62))
* **Revert:** "git-host: fix forgotten extend()" ([a815ec9](https://github.com/npm/hosted-git-info/commit/a815ec9))
<a name="2.6.0"></a>
# [2.6.0](https://github.com/npm/hosted-git-info/compare/v2.5.0...v2.6.0) (2018-03-07)
### Bug Fixes
* **compat:** remove Object.assign fallback ([#25](https://github.com/npm/hosted-git-info/issues/25)) ([627ab55](https://github.com/npm/hosted-git-info/commit/627ab55))
* **git-host:** fix forgotten extend() ([eba1f7b](https://github.com/npm/hosted-git-info/commit/eba1f7b))
### Features
* **browse:** fragment support for browse() ([#28](https://github.com/npm/hosted-git-info/issues/28)) ([cd5e5bb](https://github.com/npm/hosted-git-info/commit/cd5e5bb))

View File

@ -0,0 +1,13 @@
Copyright (c) 2015, Rebecca Turner
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

View File

@ -0,0 +1,133 @@
# hosted-git-info
This will let you identify and transform various git hosts URLs between
protocols. It also can tell you what the URL is for the raw path for
particular file for direct access without git.
## Example
```javascript
var hostedGitInfo = require("hosted-git-info")
var info = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git", opts)
/* info looks like:
{
type: "github",
domain: "github.com",
user: "npm",
project: "hosted-git-info"
}
*/
```
If the URL can't be matched with a git host, `null` will be returned. We
can match git, ssh and https urls. Additionally, we can match ssh connect
strings (`git@github.com:npm/hosted-git-info`) and shortcuts (eg,
`github:npm/hosted-git-info`). Github specifically, is detected in the case
of a third, unprefixed, form: `npm/hosted-git-info`.
If it does match, the returned object has properties of:
* info.type -- The short name of the service
* info.domain -- The domain for git protocol use
* info.user -- The name of the user/org on the git host
* info.project -- The name of the project on the git host
## Version Contract
The major version will be bumped any time…
* The constructor stops accepting URLs that it previously accepted.
* A method is removed.
* A method can no longer accept the number and type of arguments it previously accepted.
* A method can return a different type than it currently returns.
Implications:
* I do not consider the specific format of the urls returned from, say
`.https()` to be a part of the contract. The contract is that it will
return a string that can be used to fetch the repo via HTTPS. But what
that string looks like, specifically, can change.
* Dropping support for a hosted git provider would constitute a breaking
change.
## Usage
### var info = hostedGitInfo.fromUrl(gitSpecifier[, options])
* *gitSpecifer* is a URL of a git repository or a SCP-style specifier of one.
* *options* is an optional object. It can have the following properties:
* *noCommittish* — If true then committishes won't be included in generated URLs.
* *noGitPlus* — If true then `git+` won't be prefixed on URLs.
## Methods
All of the methods take the same options as the `fromUrl` factory. Options
provided to a method override those provided to the constructor.
* info.file(path, opts)
Given the path of a file relative to the repository, returns a URL for
directly fetching it from the githost. If no committish was set then
`master` will be used as the default.
For example `hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git#v1.0.0").file("package.json")`
would return `https://raw.githubusercontent.com/npm/hosted-git-info/v1.0.0/package.json`
* info.shortcut(opts)
eg, `github:npm/hosted-git-info`
* info.browse(path, fragment, opts)
eg, `https://github.com/npm/hosted-git-info/tree/v1.2.0`,
`https://github.com/npm/hosted-git-info/tree/v1.2.0/package.json`,
`https://github.com/npm/hosted-git-info/tree/v1.2.0/REAMDE.md#supported-hosts`
* info.bugs(opts)
eg, `https://github.com/npm/hosted-git-info/issues`
* info.docs(opts)
eg, `https://github.com/npm/hosted-git-info/tree/v1.2.0#readme`
* info.https(opts)
eg, `git+https://github.com/npm/hosted-git-info.git`
* info.sshurl(opts)
eg, `git+ssh://git@github.com/npm/hosted-git-info.git`
* info.ssh(opts)
eg, `git@github.com:npm/hosted-git-info.git`
* info.path(opts)
eg, `npm/hosted-git-info`
* info.tarball(opts)
eg, `https://github.com/npm/hosted-git-info/archive/v1.2.0.tar.gz`
* info.getDefaultRepresentation()
Returns the default output type. The default output type is based on the
string you passed in to be parsed
* info.toString(opts)
Uses the getDefaultRepresentation to call one of the other methods to get a URL for
this resource. As such `hostedGitInfo.fromUrl(url).toString()` will give
you a normalized version of the URL that still uses the same protocol.
Shortcuts will still be returned as shortcuts, but the special case github
form of `org/project` will be normalized to `github:org/project`.
SSH connect strings will be normalized into `git+ssh` URLs.
## Supported hosts
Currently this supports Github, Bitbucket and Gitlab. Pull requests for
additional hosts welcome.

View File

@ -0,0 +1,79 @@
'use strict'
var gitHosts = module.exports = {
github: {
// First two are insecure and generally shouldn't be used any more, but
// they are still supported.
'protocols': [ 'git', 'http', 'git+ssh', 'git+https', 'ssh', 'https' ],
'domain': 'github.com',
'treepath': 'tree',
'filetemplate': 'https://{auth@}raw.githubusercontent.com/{user}/{project}/{committish}/{path}',
'bugstemplate': 'https://{domain}/{user}/{project}/issues',
'gittemplate': 'git://{auth@}{domain}/{user}/{project}.git{#committish}',
'tarballtemplate': 'https://codeload.{domain}/{user}/{project}/tar.gz/{committish}'
},
bitbucket: {
'protocols': [ 'git+ssh', 'git+https', 'ssh', 'https' ],
'domain': 'bitbucket.org',
'treepath': 'src',
'tarballtemplate': 'https://{domain}/{user}/{project}/get/{committish}.tar.gz'
},
gitlab: {
'protocols': [ 'git+ssh', 'git+https', 'ssh', 'https' ],
'domain': 'gitlab.com',
'treepath': 'tree',
'bugstemplate': 'https://{domain}/{user}/{project}/issues',
'httpstemplate': 'git+https://{auth@}{domain}/{user}/{projectPath}.git{#committish}',
'tarballtemplate': 'https://{domain}/{user}/{project}/repository/archive.tar.gz?ref={committish}',
'pathmatch': /^[/]([^/]+)[/]((?!.*(\/-\/|\/repository\/archive\.tar\.gz\?=.*|\/repository\/[^/]+\/archive.tar.gz$)).*?)(?:[.]git|[/])?$/
},
gist: {
'protocols': [ 'git', 'git+ssh', 'git+https', 'ssh', 'https' ],
'domain': 'gist.github.com',
'pathmatch': /^[/](?:([^/]+)[/])?([a-z0-9]{32,})(?:[.]git)?$/,
'filetemplate': 'https://gist.githubusercontent.com/{user}/{project}/raw{/committish}/{path}',
'bugstemplate': 'https://{domain}/{project}',
'gittemplate': 'git://{domain}/{project}.git{#committish}',
'sshtemplate': 'git@{domain}:/{project}.git{#committish}',
'sshurltemplate': 'git+ssh://git@{domain}/{project}.git{#committish}',
'browsetemplate': 'https://{domain}/{project}{/committish}',
'browsefiletemplate': 'https://{domain}/{project}{/committish}{#path}',
'docstemplate': 'https://{domain}/{project}{/committish}',
'httpstemplate': 'git+https://{domain}/{project}.git{#committish}',
'shortcuttemplate': '{type}:{project}{#committish}',
'pathtemplate': '{project}{#committish}',
'tarballtemplate': 'https://codeload.github.com/gist/{project}/tar.gz/{committish}',
'hashformat': function (fragment) {
return 'file-' + formatHashFragment(fragment)
}
}
}
var gitHostDefaults = {
'sshtemplate': 'git@{domain}:{user}/{project}.git{#committish}',
'sshurltemplate': 'git+ssh://git@{domain}/{user}/{project}.git{#committish}',
'browsetemplate': 'https://{domain}/{user}/{project}{/tree/committish}',
'browsefiletemplate': 'https://{domain}/{user}/{project}/{treepath}/{committish}/{path}{#fragment}',
'docstemplate': 'https://{domain}/{user}/{project}{/tree/committish}#readme',
'httpstemplate': 'git+https://{auth@}{domain}/{user}/{project}.git{#committish}',
'filetemplate': 'https://{domain}/{user}/{project}/raw/{committish}/{path}',
'shortcuttemplate': '{type}:{user}/{project}{#committish}',
'pathtemplate': '{user}/{project}{#committish}',
'pathmatch': /^[/]([^/]+)[/]([^/]+?)(?:[.]git|[/])?$/,
'hashformat': formatHashFragment
}
Object.keys(gitHosts).forEach(function (name) {
Object.keys(gitHostDefaults).forEach(function (key) {
if (gitHosts[name][key]) return
gitHosts[name][key] = gitHostDefaults[key]
})
gitHosts[name].protocols_re = RegExp('^(' +
gitHosts[name].protocols.map(function (protocol) {
return protocol.replace(/([\\+*{}()[\]$^|])/g, '\\$1')
}).join('|') + '):$')
})
function formatHashFragment (fragment) {
return fragment.toLowerCase().replace(/^\W+|\/|\W+$/g, '').replace(/\W+/g, '-')
}

View File

@ -0,0 +1,156 @@
'use strict'
var gitHosts = require('./git-host-info.js')
/* eslint-disable node/no-deprecated-api */
// copy-pasta util._extend from node's source, to avoid pulling
// the whole util module into peoples' webpack bundles.
/* istanbul ignore next */
var extend = Object.assign || function _extend (target, source) {
// Don't do anything if source isn't an object
if (source === null || typeof source !== 'object') return target
var keys = Object.keys(source)
var i = keys.length
while (i--) {
target[keys[i]] = source[keys[i]]
}
return target
}
module.exports = GitHost
function GitHost (type, user, auth, project, committish, defaultRepresentation, opts) {
var gitHostInfo = this
gitHostInfo.type = type
Object.keys(gitHosts[type]).forEach(function (key) {
gitHostInfo[key] = gitHosts[type][key]
})
gitHostInfo.user = user
gitHostInfo.auth = auth
gitHostInfo.project = project
gitHostInfo.committish = committish
gitHostInfo.default = defaultRepresentation
gitHostInfo.opts = opts || {}
}
GitHost.prototype.hash = function () {
return this.committish ? '#' + this.committish : ''
}
GitHost.prototype._fill = function (template, opts) {
if (!template) return
var vars = extend({}, opts)
vars.path = vars.path ? vars.path.replace(/^[/]+/g, '') : ''
opts = extend(extend({}, this.opts), opts)
var self = this
Object.keys(this).forEach(function (key) {
if (self[key] != null && vars[key] == null) vars[key] = self[key]
})
var rawAuth = vars.auth
var rawcommittish = vars.committish
var rawFragment = vars.fragment
var rawPath = vars.path
var rawProject = vars.project
Object.keys(vars).forEach(function (key) {
var value = vars[key]
if ((key === 'path' || key === 'project') && typeof value === 'string') {
vars[key] = value.split('/').map(function (pathComponent) {
return encodeURIComponent(pathComponent)
}).join('/')
} else {
vars[key] = encodeURIComponent(value)
}
})
vars['auth@'] = rawAuth ? rawAuth + '@' : ''
vars['#fragment'] = rawFragment ? '#' + this.hashformat(rawFragment) : ''
vars.fragment = vars.fragment ? vars.fragment : ''
vars['#path'] = rawPath ? '#' + this.hashformat(rawPath) : ''
vars['/path'] = vars.path ? '/' + vars.path : ''
vars.projectPath = rawProject.split('/').map(encodeURIComponent).join('/')
if (opts.noCommittish) {
vars['#committish'] = ''
vars['/tree/committish'] = ''
vars['/committish'] = ''
vars.committish = ''
} else {
vars['#committish'] = rawcommittish ? '#' + rawcommittish : ''
vars['/tree/committish'] = vars.committish
? '/' + vars.treepath + '/' + vars.committish
: ''
vars['/committish'] = vars.committish ? '/' + vars.committish : ''
vars.committish = vars.committish || 'master'
}
var res = template
Object.keys(vars).forEach(function (key) {
res = res.replace(new RegExp('[{]' + key + '[}]', 'g'), vars[key])
})
if (opts.noGitPlus) {
return res.replace(/^git[+]/, '')
} else {
return res
}
}
GitHost.prototype.ssh = function (opts) {
return this._fill(this.sshtemplate, opts)
}
GitHost.prototype.sshurl = function (opts) {
return this._fill(this.sshurltemplate, opts)
}
GitHost.prototype.browse = function (P, F, opts) {
if (typeof P === 'string') {
if (typeof F !== 'string') {
opts = F
F = null
}
return this._fill(this.browsefiletemplate, extend({
fragment: F,
path: P
}, opts))
} else {
return this._fill(this.browsetemplate, P)
}
}
GitHost.prototype.docs = function (opts) {
return this._fill(this.docstemplate, opts)
}
GitHost.prototype.bugs = function (opts) {
return this._fill(this.bugstemplate, opts)
}
GitHost.prototype.https = function (opts) {
return this._fill(this.httpstemplate, opts)
}
GitHost.prototype.git = function (opts) {
return this._fill(this.gittemplate, opts)
}
GitHost.prototype.shortcut = function (opts) {
return this._fill(this.shortcuttemplate, opts)
}
GitHost.prototype.path = function (opts) {
return this._fill(this.pathtemplate, opts)
}
GitHost.prototype.tarball = function (opts_) {
var opts = extend({}, opts_, { noCommittish: false })
return this._fill(this.tarballtemplate, opts)
}
GitHost.prototype.file = function (P, opts) {
return this._fill(this.filetemplate, extend({ path: P }, opts))
}
GitHost.prototype.getDefaultRepresentation = function () {
return this.default
}
GitHost.prototype.toString = function (opts) {
if (this.default && typeof this[this.default] === 'function') return this[this.default](opts)
return this.sshurl(opts)
}

View File

@ -0,0 +1,148 @@
'use strict'
var url = require('url')
var gitHosts = require('./git-host-info.js')
var GitHost = module.exports = require('./git-host.js')
var protocolToRepresentationMap = {
'git+ssh:': 'sshurl',
'git+https:': 'https',
'ssh:': 'sshurl',
'git:': 'git'
}
function protocolToRepresentation (protocol) {
return protocolToRepresentationMap[protocol] || protocol.slice(0, -1)
}
var authProtocols = {
'git:': true,
'https:': true,
'git+https:': true,
'http:': true,
'git+http:': true
}
var cache = {}
module.exports.fromUrl = function (giturl, opts) {
if (typeof giturl !== 'string') return
var key = giturl + JSON.stringify(opts || {})
if (!(key in cache)) {
cache[key] = fromUrl(giturl, opts)
}
return cache[key]
}
function fromUrl (giturl, opts) {
if (giturl == null || giturl === '') return
var url = fixupUnqualifiedGist(
isGitHubShorthand(giturl) ? 'github:' + giturl : giturl
)
var parsed = parseGitUrl(url)
var shortcutMatch = url.match(new RegExp('^([^:]+):(?:(?:[^@:]+(?:[^@]+)?@)?([^/]*))[/](.+?)(?:[.]git)?($|#)'))
var matches = Object.keys(gitHosts).map(function (gitHostName) {
try {
var gitHostInfo = gitHosts[gitHostName]
var auth = null
if (parsed.auth && authProtocols[parsed.protocol]) {
auth = parsed.auth
}
var committish = parsed.hash ? decodeURIComponent(parsed.hash.substr(1)) : null
var user = null
var project = null
var defaultRepresentation = null
if (shortcutMatch && shortcutMatch[1] === gitHostName) {
user = shortcutMatch[2] && decodeURIComponent(shortcutMatch[2])
project = decodeURIComponent(shortcutMatch[3])
defaultRepresentation = 'shortcut'
} else {
if (parsed.host && parsed.host !== gitHostInfo.domain && parsed.host.replace(/^www[.]/, '') !== gitHostInfo.domain) return
if (!gitHostInfo.protocols_re.test(parsed.protocol)) return
if (!parsed.path) return
var pathmatch = gitHostInfo.pathmatch
var matched = parsed.path.match(pathmatch)
if (!matched) return
/* istanbul ignore else */
if (matched[1] !== null && matched[1] !== undefined) {
user = decodeURIComponent(matched[1].replace(/^:/, ''))
}
project = decodeURIComponent(matched[2])
defaultRepresentation = protocolToRepresentation(parsed.protocol)
}
return new GitHost(gitHostName, user, auth, project, committish, defaultRepresentation, opts)
} catch (ex) {
/* istanbul ignore else */
if (ex instanceof URIError) {
} else throw ex
}
}).filter(function (gitHostInfo) { return gitHostInfo })
if (matches.length !== 1) return
return matches[0]
}
function isGitHubShorthand (arg) {
// Note: This does not fully test the git ref format.
// See https://www.kernel.org/pub/software/scm/git/docs/git-check-ref-format.html
//
// The only way to do this properly would be to shell out to
// git-check-ref-format, and as this is a fast sync function,
// we don't want to do that. Just let git fail if it turns
// out that the commit-ish is invalid.
// GH usernames cannot start with . or -
return /^[^:@%/\s.-][^:@%/\s]*[/][^:@\s/%]+(?:#.*)?$/.test(arg)
}
function fixupUnqualifiedGist (giturl) {
// necessary for round-tripping gists
var parsed = url.parse(giturl)
if (parsed.protocol === 'gist:' && parsed.host && !parsed.path) {
return parsed.protocol + '/' + parsed.host
} else {
return giturl
}
}
function parseGitUrl (giturl) {
var matched = giturl.match(/^([^@]+)@([^:/]+):[/]?((?:[^/]+[/])?[^/]+?)(?:[.]git)?(#.*)?$/)
if (!matched) {
var legacy = url.parse(giturl)
// If we don't have url.URL, then sorry, this is just not fixable.
// This affects Node <= 6.12.
if (legacy.auth && typeof url.URL === 'function') {
// git urls can be in the form of scp-style/ssh-connect strings, like
// git+ssh://user@host.com:some/path, which the legacy url parser
// supports, but WhatWG url.URL class does not. However, the legacy
// parser de-urlencodes the username and password, so something like
// https://user%3An%40me:p%40ss%3Aword@x.com/ becomes
// https://user:n@me:p@ss:word@x.com/ which is all kinds of wrong.
// Pull off just the auth and host, so we dont' get the confusing
// scp-style URL, then pass that to the WhatWG parser to get the
// auth properly escaped.
var authmatch = giturl.match(/[^@]+@[^:/]+/)
/* istanbul ignore else - this should be impossible */
if (authmatch) {
var whatwg = new url.URL(authmatch[0])
legacy.auth = whatwg.username || ''
if (whatwg.password) legacy.auth += ':' + whatwg.password
}
}
return legacy
}
return {
protocol: 'git+ssh:',
slashes: true,
auth: matched[1],
host: matched[2],
port: null,
hostname: matched[2],
hash: matched[4],
search: null,
query: null,
pathname: '/' + matched[3],
path: '/' + matched[3],
href: 'git+ssh://' + matched[1] + '@' + matched[2] +
'/' + matched[3] + (matched[4] || '')
}
}

View File

@ -0,0 +1,44 @@
{
"name": "hosted-git-info",
"version": "2.8.8",
"description": "Provides metadata and conversions from repository urls for Github, Bitbucket and Gitlab",
"main": "index.js",
"repository": {
"type": "git",
"url": "git+https://github.com/npm/hosted-git-info.git"
},
"keywords": [
"git",
"github",
"bitbucket",
"gitlab"
],
"author": "Rebecca Turner <me@re-becca.org> (http://re-becca.org)",
"license": "ISC",
"bugs": {
"url": "https://github.com/npm/hosted-git-info/issues"
},
"homepage": "https://github.com/npm/hosted-git-info",
"scripts": {
"prerelease": "npm t",
"postrelease": "npm publish --tag=ancient-legacy-fixes && git push --follow-tags",
"posttest": "standard",
"release": "standard-version -s",
"test:coverage": "tap --coverage-report=html -J --coverage=90 --no-esm test/*.js",
"test": "tap -J --coverage=90 --no-esm test/*.js"
},
"devDependencies": {
"standard": "^11.0.1",
"standard-version": "^4.4.0",
"tap": "^12.7.0"
},
"files": [
"index.js",
"git-host.js",
"git-host-info.js"
]
,"_resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-2.8.8.tgz"
,"_integrity": "sha512-f/wzC2QaWBs7t9IYqB4T3sR1xviIViXJRJTWBlx2Gf3g0Xi5vI7Yy4koXQ1c9OYDGHN9sBy1DQ2AB8fqZBWhUg=="
,"_from": "hosted-git-info@2.8.8"
}

View File

@ -0,0 +1,87 @@
import {Except} from 'type-fest';
import readPkg = require('read-pkg');
declare namespace readPkgUp {
type Options = {
/**
Directory to start looking for a package.json file.
@default process.cwd()
*/
cwd?: string;
} & Except<readPkg.Options, 'cwd'>;
type NormalizeOptions = {
/**
Directory to start looking for a package.json file.
@default process.cwd()
*/
cwd?: string;
} & Except<readPkg.NormalizeOptions, 'cwd'>;
type PackageJson = readPkg.PackageJson;
type NormalizedPackageJson = readPkg.NormalizedPackageJson;
interface ReadResult {
packageJson: PackageJson;
path: string;
}
interface NormalizedReadResult {
packageJson: NormalizedPackageJson;
path: string;
}
}
declare const readPkgUp: {
/**
Read the closest `package.json` file.
@example
```
import readPkgUp = require('read-pkg-up');
(async () => {
console.log(await readPkgUp());
// {
// packageJson: {
// name: 'awesome-package',
// version: '1.0.0',
// …
// },
// path: '/Users/sindresorhus/dev/awesome-package/package.json'
// }
})();
```
*/
(options?: readPkgUp.NormalizeOptions): Promise<
readPkgUp.NormalizedReadResult | undefined
>;
(options: readPkgUp.Options): Promise<readPkgUp.ReadResult | undefined>;
/**
Synchronously read the closest `package.json` file.
@example
```
import readPkgUp = require('read-pkg-up');
console.log(readPkgUp.sync());
// {
// packageJson: {
// name: 'awesome-package',
// version: '1.0.0',
// …
// },
// path: '/Users/sindresorhus/dev/awesome-package/package.json'
// }
```
*/
sync(
options?: readPkgUp.NormalizeOptions
): readPkgUp.NormalizedReadResult | undefined;
sync(options: readPkgUp.Options): readPkgUp.ReadResult | undefined;
};
export = readPkgUp;

View File

@ -0,0 +1,30 @@
'use strict';
const path = require('path');
const findUp = require('find-up');
const readPkg = require('read-pkg');
module.exports = async options => {
const filePath = await findUp('package.json', options);
if (!filePath) {
return;
}
return {
packageJson: await readPkg({...options, cwd: path.dirname(filePath)}),
path: filePath
};
};
module.exports.sync = options => {
const filePath = findUp.sync('package.json', options);
if (!filePath) {
return;
}
return {
packageJson: readPkg.sync({...options, cwd: path.dirname(filePath)}),
path: filePath
};
};

View File

@ -0,0 +1,9 @@
MIT License
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
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.

View File

@ -0,0 +1,20 @@
// Basic
export * from './source/basic';
// Utilities
export {Except} from './source/except';
export {Mutable} from './source/mutable';
export {Merge} from './source/merge';
export {MergeExclusive} from './source/merge-exclusive';
export {RequireAtLeastOne} from './source/require-at-least-one';
export {RequireExactlyOne} from './source/require-exactly-one';
export {PartialDeep} from './source/partial-deep';
export {ReadonlyDeep} from './source/readonly-deep';
export {LiteralUnion} from './source/literal-union';
export {Promisable} from './source/promisable';
export {Opaque} from './source/opaque';
export {SetOptional} from './source/set-optional';
export {SetRequired} from './source/set-required';
// Miscellaneous
export {PackageJson} from './source/package-json';

View File

@ -0,0 +1,9 @@
MIT License
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
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.

View File

@ -0,0 +1,55 @@
{
"name": "type-fest",
"version": "0.8.1",
"description": "A collection of essential TypeScript types",
"license": "(MIT OR CC0-1.0)",
"repository": "sindresorhus/type-fest",
"author": {
"name": "Sindre Sorhus",
"email": "sindresorhus@gmail.com",
"url": "sindresorhus.com"
},
"engines": {
"node": ">=8"
},
"scripts": {
"test": "xo && tsd"
},
"files": [
"index.d.ts",
"source"
],
"keywords": [
"typescript",
"ts",
"types",
"utility",
"util",
"utilities",
"omit",
"merge",
"json"
],
"devDependencies": {
"@sindresorhus/tsconfig": "^0.4.0",
"@typescript-eslint/eslint-plugin": "^2.2.0",
"@typescript-eslint/parser": "^2.2.0",
"eslint-config-xo-typescript": "^0.18.0",
"tsd": "^0.7.3",
"xo": "^0.24.0"
},
"xo": {
"extends": "xo-typescript",
"extensions": [
"ts"
],
"rules": {
"import/no-unresolved": "off",
"@typescript-eslint/indent": "off"
}
}
,"_resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.8.1.tgz"
,"_integrity": "sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA=="
,"_from": "type-fest@0.8.1"
}

View File

@ -0,0 +1,635 @@
<div align="center">
<br>
<br>
<img src="media/logo.svg" alt="type-fest" height="300">
<br>
<br>
<b>A collection of essential TypeScript types</b>
<br>
<hr>
</div>
<br>
<br>
[![Build Status](https://travis-ci.com/sindresorhus/type-fest.svg?branch=master)](https://travis-ci.com/sindresorhus/type-fest)
[![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://www.youtube.com/watch?v=9auOCbH5Ns4)
<!-- Commented out until they actually show anything
[![npm dependents](https://badgen.net/npm/dependents/type-fest)](https://www.npmjs.com/package/type-fest?activeTab=dependents) [![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)
-->
Many of the types here should have been built-in. You can help by suggesting some of them to the [TypeScript project](https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md).
Either add this package as a dependency or copy-paste the needed types. No credit required. 👌
PR welcome for additional commonly needed types and docs improvements. Read the [contributing guidelines](.github/contributing.md) first.
## Install
```
$ npm install type-fest
```
*Requires TypeScript >=3.2*
## Usage
```ts
import {Except} from 'type-fest';
type Foo = {
unicorn: string;
rainbow: boolean;
};
type FooWithoutRainbow = Except<Foo, 'rainbow'>;
//=> {unicorn: string}
```
## API
Click the type names for complete docs.
### Basic
- [`Primitive`](source/basic.d.ts) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
- [`Class`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
- [`TypedArray`](source/basic.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
- [`ObservableLike`](source/basic.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
### Utilities
- [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type).
- [`Mutable`](source/mutable.d.ts) - Convert an object with `readonly` keys into a mutable object. The inverse of `Readonly<T>`.
- [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
- [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
- [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
- [`RequireExactlyOne`](source/require-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
- [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) if you only need one level deep.
- [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) if you only need one level deep.
- [`LiteralUnion`](source/literal-union.d.ts) - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
- [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
- [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
- [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
- [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
### Miscellaneous
- [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
## Declined types
*If we decline a type addition, we will make sure to document the better solution here.*
- [`Diff` and `Spread`](https://github.com/sindresorhus/type-fest/pull/7) - The PR author didn't provide any real-world use-cases and the PR went stale. If you think this type is useful, provide some real-world use-cases and we might reconsider.
- [`Dictionary`](https://github.com/sindresorhus/type-fest/issues/33) - You only save a few characters (`Dictionary<number>` vs `Record<string, number>`) from [`Record`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434), which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have `Map` in JavaScript now.
## Tips
### Built-in types
There are many advanced types most users don't know about.
- [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) - Make all properties in `T` optional.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/KYOwrgtgBAMg9gcxsAbsANlA3gKClAeQDMiAaPKAEWACMwFz8BRAJxbhcagDEBDAF17ocAXxw4AliH7AWRXgGNgUAHJwAJsADCcEEQkJsFXgAcTK3hGAAuKAGd+LKQgDcFEx363wEGrLf46IjIaOi28EioGG5iOArovHZ2qhrAAIJmAEJgEuiaLEb4Jk4oAsoKuvoIYCwCErq2apo6egZQALyF+FCm5pY2UABETelmg1xFnrYAzAAM8xNQQZGh4cFR6AB0xEQUIm4UFa0IABRHVbYACrws-BJCADwjLVUAfACUXfhEHFBnug4oABrYAATygcCIhBoACtgAp+JsQaC7P9ju9Prhut0joCwCZ1GUAGpCMDKTrnAwAbWRPWSyMhKWalQMAF0Dtj8BIoSd8YSZCT0GSOu1OmAQJp9CBgOpPkc7uBgBzOfwABYSOybSnVWp3XQ0sF04FgxnPFkIVkdKB84mkpUUfCxbEsYD8GogKBqjUBKBiWIAen9UGut3u6CeqReBlePXQQQA7skwMl+HAoMU4CgJJoISB0ODeOmbvwIVC1cAcIGmdpzVApDI5IpgJscNL49WMiZsrl8id3lrzScsD0zBYrLZBgAVOCUOCdwa+95uIA)
```ts
interface NodeConfig {
appName: string;
port: number;
}
class NodeAppBuilder {
private configuration: NodeConfig = {
appName: 'NodeApp',
port: 3000
};
config(config: Partial<NodeConfig>) {
type NodeConfigKey = keyof NodeConfig;
for (const key of Object.keys(config) as NodeConfigKey[]) {
const updateValue = config[key];
if (updateValue === undefined) {
continue;
}
this.configuration[key] = updateValue;
}
return this;
}
}
// `Partial<NodeConfig>`` allows us to provide only a part of the
// NodeConfig interface.
new NodeAppBuilder().config({appName: 'ToDoApp'});
```
</details>
- [`Required<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1408-L1413) - Make all properties in `T` required.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/AQ4SwOwFwUwJwGYEMDGNgGED21VQGJZwC2wA3gFCjXAzFJgA2A-AFzADOUckA5gNxUaIYjA4ckvGG07c+g6gF8KQkAgCuEFFDA5O6gEbEwUbLm2ESwABQIixACJIoSdgCUYAR3Vg4MACYAPGYuFvYAfACU5Ko0APRxwADKMBD+wFAAFuh2Vv7OSBlYGdmc8ABu8LHKsRyGxqY4oQT21pTCIHQMjOwA5DAAHgACxAAOjDAAdChYxL0ANLHUouKSMH0AEmAAhJhY6ozpAJ77GTCMjMCiV0ToSAb7UJPPC9WRgrEJwAAqR6MwSRQPFGUFocDgRHYxnEfGAowh-zgUCOwF6KwkUl6tXqJhCeEsxDaS1AXSYfUGI3GUxmc0WSneQA)
```ts
interface ContactForm {
email?: string;
message?: string;
}
function submitContactForm(formData: Required<ContactForm>) {
// Send the form data to the server.
}
submitContactForm({
email: 'ex@mple.com',
message: 'Hi! Could you tell me more about…',
});
// TypeScript error: missing property 'message'
submitContactForm({
email: 'ex@mple.com',
});
```
</details>
- [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) - Make all properties in `T` readonly.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/AQ4UwOwVwW2AZA9gc3mAbmANsA3gKFCOAHkAzMgGkOJABEwAjKZa2kAUQCcvEu32AMQCGAF2FYBIAL4BufDRABLCKLBcywgMZgEKZOoDCiCGSXI8i4hGEwwALmABnUVxXJ57YFgzZHSVF8sT1BpBSItLGEnJz1kAy5LLy0TM2RHACUwYQATEywATwAeAITjU3MAPnkrCJMXLigtUT4AClxgGztKbyDgaX99I1TzAEokr1BRAAslJwA6FIqLAF48TtswHp9MHDla9hJGACswZvmyLjAwAC8wVpm5xZHkUZDaMKIwqyWXYCW0oN4sNlsA1h0ug5gAByACyBQAggAHJHQ7ZBIFoXbzBjMCz7OoQP5YIaJNYQMAAdziCVaALGNSIAHomcAACoFJFgADKWjcSNEwG4vC4ji0wggEEQguiTnMEGALWAV1yAFp8gVgEjeFyuKICvMrCTgVxnst5jtsGC4ljsPNhXxGaAWcAAOq6YRXYDCRg+RWIcA5JSC+kWdCepQ+v3RYCU3RInzRMCGwlpC19NYBW1Ye08R1AA)
```ts
enum LogLevel {
Off,
Debug,
Error,
Fatal
};
interface LoggerConfig {
name: string;
level: LogLevel;
}
class Logger {
config: Readonly<LoggerConfig>;
constructor({name, level}: LoggerConfig) {
this.config = {name, level};
Object.freeze(this.config);
}
}
const config: LoggerConfig = {
name: 'MyApp',
level: LogLevel.Debug
};
const logger = new Logger(config);
// TypeScript Error: cannot assign to read-only property.
logger.config.level = LogLevel.Error;
// We are able to edit config variable as we please.
config.level = LogLevel.Error;
```
</details>
- [`Pick<T, K>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1422-L1427) - From `T`, pick a set of properties whose keys are in the union `K`.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/AQ4SwOwFwUwJwGYEMDGNgEE5TCgNugN4BQoZwOUBAXMAM5RyQDmA3KeSFABYCuAtgCMISMHloMmENh04oA9tBjQJjFuzIBfYrOAB6PcADCcGElh1gEGAHcKATwAO6ebyjB5CTNlwFwSxFR0BX5HeToYABNgBDh5fm8cfBg6AHIKG3ldA2BHOOcfFNpUygJ0pAhokr4hETFUgDpswywkggAFUwA3MFtgAF5gQgowKhhVKTYKGuFRcXo1aVZgbTIoJ3RW3xhOmB6+wfbcAGsAHi3kgBpgEtGy4AAfG54BWfqAPnZm4AAlZUj4MAkMA8GAGB4vEgfMlLLw6CwPBA8PYRmMgZVgAC6CgmI4cIommQELwICh8RBgKZKvALh1ur0bHQABR5PYMui0Wk7em2ADaAF0AJS0AASABUALIAGQAogR+Mp3CROCAFBBwVC2ikBpj5CgBIqGjizLA5TAFdAmalImAuqlBRoVQh5HBgEy1eDWfs7J5cjzGYKhroVfpDEhHM4MV6GRR5NN0JrtnRg6BVirTFBeHAKYmYY6QNpdB73LmCJZBlSAXAubtvczeSmQMNSuMbmKNgBlHFgPEUNwusBIPAAQlS1xetTmxT0SDoESgdD0C4aACtHMwxytLrohawgA)
```ts
interface Article {
title: string;
thumbnail: string;
content: string;
}
// Creates new type out of the `Article` interface composed
// from the Articles' two properties: `title` and `thumbnail`.
// `ArticlePreview = {title: string; thumbnail: string}`
type ArticlePreview = Pick<Article, 'title' | 'thumbnail'>;
// Render a list of articles using only title and description.
function renderArticlePreviews(previews: ArticlePreview[]): HTMLElement {
const articles = document.createElement('div');
for (const preview of previews) {
// Append preview to the articles.
}
return articles;
}
const articles = renderArticlePreviews([
{
title: 'TypeScript tutorial!',
thumbnail: '/assets/ts.jpg'
}
]);
```
</details>
- [`Record<K, T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434) - Construct a type with a set of properties `K` of type `T`.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/AQ4ejYAUHsGcCWAXBMB2dgwGbAKYC2ADgDYwCeeemCaWArgE7ADGMxAhmuQHQBQoYEnJE8wALKEARnkaxEKdMAC8wAOS0kstGuAAfdQBM8ANzxlRjXQbVaWACwC0JPB0NqA3HwGgIwAJJoWozYHCxixnAsjAhStADmwESMMJYo1Fi4HMCIaPEu+MRklHj8gpqyoeHAAKJFFFTAAN4+giDYCIxwSAByHAR4AFw5SDF5Xm2gJBzdfQPD3WPxE5PAlBxdAPLYNQAelgh4aOHDaPQEMowrIAC+3oJ+AMKMrlrAXFhSAFZ4LEhC9g4-0BmA4JBISXgiCkBQABpILrJ5MhUGhYcATGD6Bk4Hh-jNgABrPDkOBlXyQAAq9ngYmJpOAAHcEOCRjAXqwYODfoo6DhakUSph+Uh7GI4P0xER4Cj0OSQGwMP8tP1hgAlX7swwAHgRl2RvIANALSA08ABtAC6AD4VM1Wm0Kow0MMrYaHYJjGYLLJXZb3at1HYnC43Go-QHQDcvA6-JsmEJXARgCDgMYWAhjIYhDAU+YiMAAFIwex0ZmilMITCGF79TLAGRsAgJYAAZRwSEZGzEABFTOZUrJ5Yn+jwnWgeER6HB7AAKJrADpdXqS4ZqYultTG6azVfqHswPBbtauLY7fayQ7HIbAAAMwBuAEoYw9IBq2Ixs9h2eFMOQYPQObALQKJgggABeYhghCIpikkKRpOQRIknAsZUiIeCttECBEP8NSMCkjDDAARMGziuIYxHwYOjDCMBmDNnAuTxA6irdCOBB1Lh5Dqpqn66tISIykawBnOCtqqC0gbjqc9DgpGkxegOliyfJDrRkAA)
```ts
// Positions of employees in our company.
type MemberPosition = 'intern' | 'developer' | 'tech-lead';
// Interface describing properties of a single employee.
interface Employee {
firstName: string;
lastName: string;
yearsOfExperience: number;
}
// Create an object that has all possible `MemberPosition` values set as keys.
// Those keys will store a collection of Employees of the same position.
const team: Record<MemberPosition, Employee[]> = {
intern: [],
developer: [],
'tech-lead': [],
};
// Our team has decided to help John with his dream of becoming Software Developer.
team.intern.push({
firstName: 'John',
lastName: 'Doe',
yearsOfExperience: 0
});
// `Record` forces you to initialize all of the property keys.
// TypeScript Error: "tech-lead" property is missing
const teamEmpty: Record<MemberPosition, null> = {
intern: null,
developer: null,
};
```
</details>
- [`Exclude<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1436-L1439) - Exclude from `T` those types that are assignable to `U`.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/JYOwLgpgTgZghgYwgAgMrQG7QMIHsQzADmyA3gFDLIAOuUYAXMiAK4A2byAPsgM5hRQJHqwC2AI2gBucgF9y5MAE9qKAEoQAjiwj8AEnBAATNtGQBeZAAooWphu26wAGmS3e93bRC8IASgsAPmRDJRlyAHoI5ABRAA8ENhYjFFYOZGVVZBgoXFFkAAM0zh5+QRBhZhYJaAKAOkjogEkQZAQ4X2QAdwALCFbaemRgXmQtFjhOMFwq9K6ULuB0lk6U+HYwZAxJnQaYFhAEMGB8ZCIIMAAFOjAANR2IK0HGWISklIAedCgsKDwCYgAbQA5M9gQBdVzFQJ+JhiSRQMiUYYwayZCC4VHPCzmSzAspCYEBWxgFhQAZwKC+FpgJ43VwARgADH4ZFQSWSBjcZPJyPtDsdTvxKWBvr8rD1DCZoJ5HPopaYoK4EPhCEQmGKcKriLCtrhgEYkVQVT5Nr4fmZLLZtMBbFZgT0wGBqES6ghbHBIJqoBKFdBWQpjfh+DQbhY2tqiHVsbjLMVkAB+ZAAZiZaeQTHOVxu9ySjxNaujNwDVHNvzqbBGkBAdPoAfkQA)
```ts
interface ServerConfig {
port: null | string | number;
}
type RequestHandler = (request: Request, response: Response) => void;
// Exclude `null` type from `null | string | number`.
// In case the port is equal to `null`, we will use default value.
function getPortValue(port: Exclude<ServerConfig['port'], null>): number {
if (typeof port === 'string') {
return parseInt(port, 10);
}
return port;
}
function startServer(handler: RequestHandler, config: ServerConfig): void {
const server = require('http').createServer(handler);
const port = config.port === null ? 3000 : getPortValue(config.port);
server.listen(port);
}
```
</details>
- [`Extract<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1441-L1444) - Extract from `T` those types that are assignable to `U`.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/CYUwxgNghgTiAEAzArgOzAFwJYHtXzSwEdkQBJYACgEoAueVZAWwCMQYBuAKDDwGcM8MgBF4AXngBlAJ6scESgHIRi6ty5ZUGdoihgEABXZ888AN5d48ANoiAuvUat23K6ihMQ9ATE0BzV3goPy8GZjZOLgBfLi4Aejj4AEEICBwAdz54MAALKFQQ+BxEeAAHY1NgKAwoIKy0grr4DByEUpgccpgMaXgAaxBerCzi+B9-ZulygDouFHRsU1z8kKMYE1RhaqgAHkt4AHkWACt4EAAPbVRgLLWNgBp9gGlBs8uQa6yAUUuYPQwdgNpKM7nh7mMML4CgA+R5WABqUAgpDeVxuhxO1he0jsXGh8EoOBO9COx3BQPo2PBADckaR6IjkSA6PBqTgsMBzPsicdrEC7OJWXSQNwYvFEgAVTS9JLXODpeDpKBZFg4GCoWa8VACIJykAKiQWKy2YQOAioYikCg0OEMDyhRSy4DyxS24KhAAMjyi6gS8AAwjh5OD0iBFHAkJoEOksC1mnkMJq8gUQKDNttKPlnfrwYp3J5XfBHXqoKpfYkAOI4ansTxaeDADmoRSCCBYAbxhC6TDx6rwYHIRX5bScjA4bLJwoDmDwDkfbA9JMrVMVdM1TN69LgkTgwgkchUahqIA)
```ts
declare function uniqueId(): number;
const ID = Symbol('ID');
interface Person {
[ID]: number;
name: string;
age: number;
}
// Allows changing the person data as long as the property key is of string type.
function changePersonData<
Obj extends Person,
Key extends Extract<keyof Person, string>,
Value extends Obj[Key]
> (obj: Obj, key: Key, value: Value): void {
obj[key] = value;
}
// Tiny Andrew was born.
const andrew = {
[ID]: uniqueId(),
name: 'Andrew',
age: 0,
};
// Cool, we're fine with that.
changePersonData(andrew, 'name', 'Pony');
// Goverment didn't like the fact that you wanted to change your identity.
changePersonData(andrew, ID, uniqueId());
```
</details>
- [`NonNullable<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1446-L1449) - Exclude `null` and `undefined` from `T`.
<details>
<summary>
Example
</summary>
Works with <code>strictNullChecks</code> set to <code>true</code>. (Read more <a href="https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html">here</a>)
[Playground](https://typescript-play.js.org/?target=6#code/C4TwDgpgBACg9gJ2AOQK4FsBGEFQLxQDOwCAlgHYDmUAPlORtrnQwDasDcAUFwPQBU-WAEMkUOADMowqAGNWwwoSgATCBIqlgpOOSjAAFsOBRSy1IQgr9cKJlSlW1mZYQA3HFH68u8xcoBlHA8EACEHJ08Aby4oKDBUTFZSWXjEFEYcAEIALihkXTR2YSSIAB54JDQsHAA+blj4xOTUsHSACkMzPKD3HHDHNQQAGjSkPMqMmoQASh7g-oihqBi4uNIpdraxPAI2VhmVxrX9AzMAOm2ppnwoAA4ABifuE4BfKAhWSyOTuK7CS7pao3AhXF5rV48E4ICDAVAIPT-cGQyG+XTEIgLMJLTx7CAAdygvRCA0iCHaMwarhJOIQjUBSHaACJHk8mYdeLwxtdcVAAOSsh58+lXdr7Dlcq7A3n3J4PEUdADMcspUE53OluAIUGVTx46oAKuAIAFZGQwCYAKIIBCILjUxaDHAMnla+iodjcIA)
```ts
type PortNumber = string | number | null;
/** Part of a class definition that is used to build a server */
class ServerBuilder {
portNumber!: NonNullable<PortNumber>;
port(this: ServerBuilder, port: PortNumber): ServerBuilder {
if (port == null) {
this.portNumber = 8000;
} else {
this.portNumber = port;
}
return this;
}
}
const serverBuilder = new ServerBuilder();
serverBuilder
.port('8000') // portNumber = '8000'
.port(null) // portNumber = 8000
.port(3000); // portNumber = 3000
// TypeScript error
serverBuilder.portNumber = null;
```
</details>
- [`Parameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1451-L1454) - Obtain the parameters of a function type in a tuple.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/GYVwdgxgLglg9mABAZwBYmMANgUwBQxgAOIUAXIgIZgCeA2gLoCUFAbnDACaIDeAUIkQB6IYgCypSlBxUATrMo1ECsJzgBbLEoipqAc0J7EMKMgDkiHLnU4wp46pwAPHMgB0fAL58+oSLARECEosLAA5ABUYG2QAHgAxJGdpVWREPDdMylk9ZApqemZEAF4APipacrw-CApEgBogkKwAYThwckQwEHUAIxxZJl4BYVEImiIZKF0oZRwiWVdbeygJmThgOYgcGFYcbhqApCJsyhtpWXcR1cnEePBoeDAABVPzgbTixFeFd8uEsClADcIxGiygIFkSEOT3SmTc2VydQeRx+ZxwF2QQ34gkEwDgsnSuFmMBKiAADEDjIhYk1Qm0OlSYABqZnYka4xA1DJZHJYkGc7yCbyeRA+CAIZCzNAYbA4CIAdxg2zJwVCkWirjwMswuEaACYmCCgA)
```ts
function shuffle(input: any[]): void {
// Mutate array randomly changing its' elements indexes.
}
function callNTimes<Fn extends (...args: any[]) => any> (func: Fn, callCount: number) {
// Type that represents the type of the received function parameters.
type FunctionParameters = Parameters<Fn>;
return function (...args: FunctionParameters) {
for (let i = 0; i < callCount; i++) {
func(...args);
}
}
}
const shuffleTwice = callNTimes(shuffle, 2);
```
</details>
- [`ConstructorParameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1456-L1459) - Obtain the parameters of a constructor function type in a tuple.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECCBOAXAlqApgWQPYBM0mgG8AoaaFRENALmgkXmQDsBzAblOmCycTV4D8teo1YdO3JiICuwRFngAKClWENmLAJRFOZRAAtkEAHQq00ALzlklNBzIBfYk+KhIMAJJTEYJsDQAwmDA+mgAPAAq0GgAHnxMODCKTGgA7tCKxllg8CwQtL4AngDaALraFgB80EWa1SRkAA6MAG5gfNAB4FABPDJyCrQR9tDNyG0dwMGhtBhgjWEiGgA00F70vv4RhY3hEZXVVinpc42KmuJkkv3y8Bly8EPaDWTkhiZd7r3e8LK3llwGCMXGQWGhEOsfH5zJlsrl8p0+gw-goAAo5MAAW3BaHgEEilU0tEhmzQ212BJ0ry4SOg+kg+gBBiMximIGA0nAfAQLGk2N4EAAEgzYcYcnkLsRdDTvNEYkYUKwSdCme9WdM0MYwYhFPSIPpJdTkAAzDKxBUaZX+aAAQgsVmkCTQxuYaBw2ng4Ok8CYcotSu8pMur09iG9vuObxZnx6SN+AyUWTF8MN0CcZE4Ywm5jZHK5aB5fP4iCFIqT4oRRTKRLo6lYVNeAHpG50wOzOe1zHr9NLQ+HoABybsD4HOKXXRA1JCoKhBELmI5pNaB6Fz0KKBAodDYPAgSUTmqYsAALx4m5nC6nW9nGq14KtaEUA9gR9PvuNCjQ9BgACNvcwNBtAcLiAA)
```ts
class ArticleModel {
title: string;
content?: string;
constructor(title: string) {
this.title = title;
}
}
class InstanceCache<T extends (new (...args: any[]) => any)> {
private ClassConstructor: T;
private cache: Map<string, InstanceType<T>> = new Map();
constructor (ctr: T) {
this.ClassConstructor = ctr;
}
getInstance (...args: ConstructorParameters<T>): InstanceType<T> {
const hash = this.calculateArgumentsHash(...args);
const existingInstance = this.cache.get(hash);
if (existingInstance !== undefined) {
return existingInstance;
}
return new this.ClassConstructor(...args);
}
private calculateArgumentsHash(...args: any[]): string {
// Calculate hash.
return 'hash';
}
}
const articleCache = new InstanceCache(ArticleModel);
const amazonArticle = articleCache.getInstance('Amazon forests burining!');
```
</details>
- [`ReturnType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1461-L1464) – Obtain the return type of a function type.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECSAmICmBlJAnAbgS2E6A3gFDTTwD2AcuQC4AW2AdgOYAUAlAFzSbnbyEAvkWFFQkGJSQB3GMVI1sNZNwg10TZgG4S0YOUY0kh1es07d+xmvQBXYDXLpWi5UlMaWAGj0GjJ6BtNdkJdBQYIADpXZGgAXmgYpB1ScOwoq38aeN9DYxoU6GFRKzVoJjUwRjwAYXJbPPRuAFkwAAcAHgAxBodsAx9GWwBbACMMAD4cxhloVraOCyYjdAAzMDxoOut1e0d0UNIZ6WhWSPOwdGYIbiqATwBtAF0uaHudUQB6ACpv6ABpJBINqJdAbADW0Do5BOw3u5R2VTwMHIq2gAANtjZ0bkbHsnFCwJh8ONjHp0EgwEZ4JFoN9PkRVr1FAZoMwkDRYIjqkgOrosepoEgAB7+eAwAV2BxOLy6ACCVxgIrFEoMeOl6AACpcwMMORgIB1JRMiBNWKVdhruJKfOdIpdrtwFddXlzKjyACp3Nq842HaDIbL6BrZBIVGhIpB1EMYSLsmjmtWW-YhAA+qegAAYLKQLQj3ZsEsdccmnGcLor2Dn8xGedHGpEIBzEzspfsfMHDNAANTQACMVaIljV5GQkRA5DYmIpVKQAgAJARO9le33BDXIyi0YuLW2nJFGLqkOvxFB0YPdBSaLZ0IwNzyPkO8-xkGgsLh8Al427a3hWAhXwwHA8EHT5PmgAB1bAQBAANJ24adKWpft72RaBUTgRBUCAj89HAM8xCTaBjggABRQx0DuHJv25P9dCkWRZVIAAiBjoFImpmjlFBgA0NpsjadByDacgIDAEAIAAQmYpjoGYgAZSBsmGPw6DtZiiFA8CoJguDmAQmoZ2QvtUKQLdoAYmBTwgdEiCAA)
```ts
/** Provides every element of the iterable `iter` into the `callback` function and stores the results in an array. */
function mapIter<
Elem,
Func extends (elem: Elem) => any,
Ret extends ReturnType<Func>
>(iter: Iterable<Elem>, callback: Func): Ret[] {
const mapped: Ret[] = [];
for (const elem of iter) {
mapped.push(callback(elem));
}
return mapped;
}
const setObject: Set<string> = new Set();
const mapObject: Map<number, string> = new Map();
mapIter(setObject, (value: string) => value.indexOf('Foo')); // number[]
mapIter(mapObject, ([key, value]: [number, string]) => {
return key % 2 === 0 ? value : 'Odd';
}); // string[]
```
</details>
- [`InstanceType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1466-L1469) – Obtain the instance type of a constructor function type.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECSAmICmBlJAnAbgS2E6A3gFDTTwD2AcuQC4AW2AdgOYAUAlAFzSbnbyEAvkWFFQkGJSQB3GMVI1sNZNwg10TZgG4S0YOUY0kh1es07d+xmvQBXYDXLpWi5UlMaWAGj0GjJ6BtNdkJdBQYIADpXZGgAXmgYpB1ScOwoq38aeN9DYxoU6GFRKzVoJjUwRjwAYXJbPPRuAFkwAAcAHgAxBodsAx9GWwBbACMMAD4cxhloVraOCyYjdAAzMDxoOut1e0d0UNIZ6WhWSPOwdGYIbiqATwBtAF0uaHudUQB6ACpv6ABpJBINqJdAbADW0Do5BOw3u5R2VTwMHIq2gAANtjZ0bkbHsnFCwJh8ONjHp0EgwEZ4JFoN9PkRVr1FAZoMwkDRYIjqkgOrosepoEgAB7+eAwAV2BxOLy6ACCVxgIrFEoMeOl6AACpcwMMORgIB1JRMiBNWKVdhruJKfOdIpdrtwFddXlzKjyACp3Nq842HaDIbL6BrZBIVGhIpB1EMYSLsmjmtWW-YhAA+qegAAYLKQLQj3ZsEsdccmnGcLor2Dn8xGedHGpEIBzEzspfsfMHDNAANTQACMVaIljV5GQkRA5DYmIpVKQAgAJARO9le33BDXIyi0YuLW2nJFGLqkOvxFB0YPdBSaLZ0IwNzyPkO8-xkGgsLh8Al427a3hWAhXwwHA8EHT5PmgAB1bAQBAANJ24adKWpft72RaBUTgRBUCAj89HAM8xCTaBjggABRQx0DuHJv25P9dCkWRZVIAAiBjoFImpmjlFBgA0NpsjadByDacgIDAEAIAAQmYpjoGYgAZSBsmGPw6DtZiiFA8CoJguDmAQmoZ2QvtUKQLdoAYmBTwgdEiCAA)
```ts
class IdleService {
doNothing (): void {}
}
class News {
title: string;
content: string;
constructor(title: string, content: string) {
this.title = title;
this.content = content;
}
}
const instanceCounter: Map<Function, number> = new Map();
interface Constructor {
new(...args: any[]): any;
}
// Keep track how many instances of `Constr` constructor have been created.
function getInstance<
Constr extends Constructor,
Args extends ConstructorParameters<Constr>
>(constructor: Constr, ...args: Args): InstanceType<Constr> {
let count = instanceCounter.get(constructor) || 0;
const instance = new constructor(...args);
instanceCounter.set(constructor, count + 1);
console.log(`Created ${count + 1} instances of ${Constr.name} class`);
return instance;
}
const idleService = getInstance(IdleService);
// Will log: `Created 1 instances of IdleService class`
const newsEntry = getInstance(News, 'New ECMAScript proposals!', 'Last month...');
// Will log: `Created 1 instances of News class`
```
</details>
- [`Omit<T, K>`](https://github.com/microsoft/TypeScript/blob/71af02f7459dc812e85ac31365bfe23daf14b4e4/src/lib/es5.d.ts#L1446) – Constructs a type by picking all properties from T and then removing K.
<details>
<summary>
Example
</summary>
[Playground](https://typescript-play.js.org/?target=6#code/JYOwLgpgTgZghgYwgAgIImAWzgG2QbwChlks4BzCAVShwC5kBnMKUcgbmKYAcIFgIjBs1YgOXMpSFMWbANoBdTiW5woFddwAW0kfKWEAvoUIB6U8gDCUCHEiNkICAHdkYAJ69kz4GC3JcPG4oAHteKDABBxCYNAxsPFBIWEQUCAAPJG4wZABySUFcgJAAEzMLXNV1ck0dIuCw6EjBADpy5AB1FAQ4EGQAV0YUP2AHDy8wEOQbUugmBLwtEIA3OcmQnEjuZBgQqE7gAGtgZAhwKHdkHFGwNvGUdDIcAGUliIBJEF3kAF5kAHlML4ADyPBIAGjyBUYRQAPnkqho4NoYQA+TiEGD9EAISIhPozErQMG4AASK2gn2+AApek9pCSXm8wFSQooAJQMUkAFQAsgAZACiOAgmDOOSIJAQ+OYyGl4DgoDmf2QJRCCH6YvALQQNjsEGFovF1NyJWAy1y7OUyHMyE+yRAuFImG4Iq1YDswHxbRINjA-SgfXlHqVUE4xiAA)
```ts
interface Animal {
imageUrl: string;
species: string;
images: string[];
paragraphs: string[];
}
// Creates new type with all properties of the `Animal` interface
// except 'images' and 'paragraphs' properties. We can use this
// type to render small hover tooltip for a wiki entry list.
type AnimalShortInfo = Omit<Animal, 'images' | 'paragraphs'>;
function renderAnimalHoverInfo (animals: AnimalShortInfo[]): HTMLElement {
const container = document.createElement('div');
// Internal implementation.
return container;
}
```
</details>
You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#predefined-conditional-types).
## Maintainers
- [Sindre Sorhus](https://github.com/sindresorhus)
- [Jarek Radosz](https://github.com/CvX)
- [Dimitri Benin](https://github.com/BendingBender)
## License
(MIT OR CC0-1.0)
---
<div align="center">
<b>
<a href="https://tidelift.com/subscription/pkg/npm-type-fest?utm_source=npm-type-fest&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
</b>
<br>
<sub>
Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
</sub>
</div>

View File

@ -0,0 +1,67 @@
/// <reference lib="esnext"/>
// TODO: This can just be `export type Primitive = not object` when the `not` keyword is out.
/**
Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
*/
export type Primitive =
| null
| undefined
| string
| number
| boolean
| symbol
| bigint;
// TODO: Remove the `= unknown` sometime in the future when most users are on TS 3.5 as it's now the default
/**
Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
*/
export type Class<T = unknown, Arguments extends any[] = any[]> = new(...arguments_: Arguments) => T;
/**
Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
*/
export type TypedArray =
| Int8Array
| Uint8Array
| Uint8ClampedArray
| Int16Array
| Uint16Array
| Int32Array
| Uint32Array
| Float32Array
| Float64Array
| BigInt64Array
| BigUint64Array;
/**
Matches a JSON object.
This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
*/
export type JsonObject = {[key: string]: JsonValue};
/**
Matches a JSON array.
*/
export interface JsonArray extends Array<JsonValue> {}
/**
Matches any valid JSON value.
*/
export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
declare global {
interface SymbolConstructor {
readonly observable: symbol;
}
}
/**
Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
*/
export interface ObservableLike {
subscribe(observer: (value: unknown) => void): void;
[Symbol.observable](): ObservableLike;
}

View File

@ -0,0 +1,22 @@
/**
Create a type from an object type without certain keys.
This type is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type). The `Omit` type does not restrict the omitted keys to be keys present on the given type, while `Except` does. The benefits of a stricter type are avoiding typos and allowing the compiler to pick up on rename refactors automatically.
Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/30825) if you want to have the stricter version as a built-in in TypeScript.
@example
```
import {Except} from 'type-fest';
type Foo = {
a: number;
b: string;
c: boolean;
};
type FooWithoutA = Except<Foo, 'a' | 'c'>;
//=> {b: string};
```
*/
export type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;

View File

@ -0,0 +1,33 @@
import {Primitive} from './basic';
/**
Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
@example
```
import {LiteralUnion} from 'type-fest';
// Before
type Pet = 'dog' | 'cat' | string;
const pet: Pet = '';
// Start typing in your TypeScript-enabled IDE.
// You **will not** get auto-completion for `dog` and `cat` literals.
// After
type Pet2 = LiteralUnion<'dog' | 'cat', string>;
const pet: Pet2 = '';
// You **will** get auto-completion for `dog` and `cat` literals.
```
*/
export type LiteralUnion<
LiteralType extends BaseType,
BaseType extends Primitive
> = LiteralType | (BaseType & {_?: never});

View File

@ -0,0 +1,39 @@
// Helper type. Not useful on its own.
type Without<FirstType, SecondType> = {[KeyType in Exclude<keyof FirstType, keyof SecondType>]?: never};
/**
Create a type that has mutually exclusive keys.
This type was inspired by [this comment](https://github.com/Microsoft/TypeScript/issues/14094#issuecomment-373782604).
This type works with a helper type, called `Without`. `Without<FirstType, SecondType>` produces a type that has only keys from `FirstType` which are not present on `SecondType` and sets the value type for these keys to `never`. This helper type is then used in `MergeExclusive` to remove keys from either `FirstType` or `SecondType`.
@example
```
import {MergeExclusive} from 'type-fest';
interface ExclusiveVariation1 {
exclusive1: boolean;
}
interface ExclusiveVariation2 {
exclusive2: string;
}
type ExclusiveOptions = MergeExclusive<ExclusiveVariation1, ExclusiveVariation2>;
let exclusiveOptions: ExclusiveOptions;
exclusiveOptions = {exclusive1: true};
//=> Works
exclusiveOptions = {exclusive2: 'hi'};
//=> Works
exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
//=> Error
```
*/
export type MergeExclusive<FirstType, SecondType> =
(FirstType | SecondType) extends object ?
(Without<FirstType, SecondType> & SecondType) | (Without<SecondType, FirstType> & FirstType) :
FirstType | SecondType;

View File

@ -0,0 +1,22 @@
import {Except} from './except';
/**
Merge two types into a new type. Keys of the second type overrides keys of the first type.
@example
```
import {Merge} from 'type-fest';
type Foo = {
a: number;
b: string;
};
type Bar = {
b: number;
};
const ab: Merge<Foo, Bar> = {a: 1, b: 2};
```
*/
export type Merge<FirstType, SecondType> = Except<FirstType, Extract<keyof FirstType, keyof SecondType>> & SecondType;

View File

@ -0,0 +1,22 @@
/**
Convert an object with `readonly` keys into a mutable object. Inverse of `Readonly<T>`.
This can be used to [store and mutate options within a class](https://github.com/sindresorhus/pageres/blob/4a5d05fca19a5fbd2f53842cbf3eb7b1b63bddd2/source/index.ts#L72), [edit `readonly` objects within tests](https://stackoverflow.com/questions/50703834), and [construct a `readonly` object within a function](https://github.com/Microsoft/TypeScript/issues/24509).
@example
```
import {Mutable} from 'type-fest';
type Foo = {
readonly a: number;
readonly b: string;
};
const mutableFoo: Mutable<Foo> = {a: 1, b: '2'};
mutableFoo.a = 3;
```
*/
export type Mutable<ObjectType> = {
// For each `Key` in the keys of `ObjectType`, make a mapped type by removing the `readonly` modifier from the key.
-readonly [KeyType in keyof ObjectType]: ObjectType[KeyType];
};

View File

@ -0,0 +1,40 @@
/**
Create an opaque type, which hides its internal details from the public, and can only be created by being used explicitly.
The generic type parameter can be anything. It doesn't have to be an object.
[Read more about opaque types.](https://codemix.com/opaque-types-in-javascript/)
There have been several discussions about adding this feature to TypeScript via the `opaque type` operator, similar to how Flow does it. Unfortunately, nothing has (yet) moved forward:
- [Microsoft/TypeScript#15408](https://github.com/Microsoft/TypeScript/issues/15408)
- [Microsoft/TypeScript#15807](https://github.com/Microsoft/TypeScript/issues/15807)
@example
```
import {Opaque} from 'type-fest';
type AccountNumber = Opaque<number>;
type AccountBalance = Opaque<number>;
function createAccountNumber(): AccountNumber {
return 2 as AccountNumber;
}
function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance {
return 4 as AccountBalance;
}
// This will compile successfully.
getMoneyForAccount(createAccountNumber());
// But this won't, because it has to be explicitly passed as an `AccountNumber` type.
getMoneyForAccount(2);
// You can use opaque values like they aren't opaque too.
const accountNumber = createAccountNumber();
// This will compile successfully.
accountNumber + 2;
```
*/
export type Opaque<Type> = Type & {readonly __opaque__: unique symbol};

View File

@ -0,0 +1,501 @@
import {LiteralUnion} from '..';
declare namespace PackageJson {
/**
A person who has been involved in creating or maintaining the package.
*/
export type Person =
| string
| {
name: string;
url?: string;
email?: string;
};
export type BugsLocation =
| string
| {
/**
The URL to the package's issue tracker.
*/
url?: string;
/**
The email address to which issues should be reported.
*/
email?: string;
};
export interface DirectoryLocations {
/**
Location for executable scripts. Sugar to generate entries in the `bin` property by walking the folder.
*/
bin?: string;
/**
Location for Markdown files.
*/
doc?: string;
/**
Location for example scripts.
*/
example?: string;
/**
Location for the bulk of the library.
*/
lib?: string;
/**
Location for man pages. Sugar to generate a `man` array by walking the folder.
*/
man?: string;
/**
Location for test files.
*/
test?: string;
[directoryType: string]: unknown;
}
export type Scripts = {
/**
Run **before** the package is published (Also run on local `npm install` without any arguments).
*/
prepublish?: string;
/**
Run both **before** the package is packed and published, and on local `npm install` without any arguments. This is run **after** `prepublish`, but **before** `prepublishOnly`.
*/
prepare?: string;
/**
Run **before** the package is prepared and packed, **only** on `npm publish`.
*/
prepublishOnly?: string;
/**
Run **before** a tarball is packed (on `npm pack`, `npm publish`, and when installing git dependencies).
*/
prepack?: string;
/**
Run **after** the tarball has been generated and moved to its final destination.
*/
postpack?: string;
/**
Run **after** the package is published.
*/
publish?: string;
/**
Run **after** the package is published.
*/
postpublish?: string;
/**
Run **before** the package is installed.
*/
preinstall?: string;
/**
Run **after** the package is installed.
*/
install?: string;
/**
Run **after** the package is installed and after `install`.
*/
postinstall?: string;
/**
Run **before** the package is uninstalled and before `uninstall`.
*/
preuninstall?: string;
/**
Run **before** the package is uninstalled.
*/
uninstall?: string;
/**
Run **after** the package is uninstalled.
*/
postuninstall?: string;
/**
Run **before** bump the package version and before `version`.
*/
preversion?: string;
/**
Run **before** bump the package version.
*/
version?: string;
/**
Run **after** bump the package version.
*/
postversion?: string;
/**
Run with the `npm test` command, before `test`.
*/
pretest?: string;
/**
Run with the `npm test` command.
*/
test?: string;
/**
Run with the `npm test` command, after `test`.
*/
posttest?: string;
/**
Run with the `npm stop` command, before `stop`.
*/
prestop?: string;
/**
Run with the `npm stop` command.
*/
stop?: string;
/**
Run with the `npm stop` command, after `stop`.
*/
poststop?: string;
/**
Run with the `npm start` command, before `start`.
*/
prestart?: string;
/**
Run with the `npm start` command.
*/
start?: string;
/**
Run with the `npm start` command, after `start`.
*/
poststart?: string;
/**
Run with the `npm restart` command, before `restart`. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
*/
prerestart?: string;
/**
Run with the `npm restart` command. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
*/
restart?: string;
/**
Run with the `npm restart` command, after `restart`. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
*/
postrestart?: string;
} & {
[scriptName: string]: string;
};
/**
Dependencies of the package. The version range is a string which has one or more space-separated descriptors. Dependencies can also be identified with a tarball or Git URL.
*/
export interface Dependency {
[packageName: string]: string;
}
export interface NonStandardEntryPoints {
/**
An ECMAScript module ID that is the primary entry point to the program.
*/
module?: string;
/**
A module ID with untranspiled code that is the primary entry point to the program.
*/
esnext?:
| string
| {
main?: string;
browser?: string;
[moduleName: string]: string | undefined;
};
/**
A hint to JavaScript bundlers or component tools when packaging modules for client side use.
*/
browser?:
| string
| {
[moduleName: string]: string | false;
};
}
export interface TypeScriptConfiguration {
/**
Location of the bundled TypeScript declaration file.
*/
types?: string;
/**
Location of the bundled TypeScript declaration file. Alias of `types`.
*/
typings?: string;
}
export interface YarnConfiguration {
/**
If your package only allows one version of a given dependency, and you’d like to enforce the same behavior as `yarn install --flat` on the command line, set this to `true`.
Note that if your `package.json` contains `"flat": true` and other packages depend on yours (e.g. you are building a library rather than an application), those other packages will also need `"flat": true` in their `package.json` or be installed with `yarn install --flat` on the command-line.
*/
flat?: boolean;
/**
Selective version resolutions. Allows the definition of custom package versions inside dependencies without manual edits in the `yarn.lock` file.
*/
resolutions?: Dependency;
}
export interface JSPMConfiguration {
/**
JSPM configuration.
*/
jspm?: PackageJson;
}
}
/**
Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
*/
export type PackageJson = {
/**
The name of the package.
*/
name?: string;
/**
Package version, parseable by [`node-semver`](https://github.com/npm/node-semver).
*/
version?: string;
/**
Package description, listed in `npm search`.
*/
description?: string;
/**
Keywords associated with package, listed in `npm search`.
*/
keywords?: string[];
/**
The URL to the package's homepage.
*/
homepage?: LiteralUnion<'.', string>;
/**
The URL to the package's issue tracker and/or the email address to which issues should be reported.
*/
bugs?: PackageJson.BugsLocation;
/**
The license for the package.
*/
license?: string;
/**
The licenses for the package.
*/
licenses?: Array<{
type?: string;
url?: string;
}>;
author?: PackageJson.Person;
/**
A list of people who contributed to the package.
*/
contributors?: PackageJson.Person[];
/**
A list of people who maintain the package.
*/
maintainers?: PackageJson.Person[];
/**
The files included in the package.
*/
files?: string[];
/**
The module ID that is the primary entry point to the program.
*/
main?: string;
/**
The executable files that should be installed into the `PATH`.
*/
bin?:
| string
| {
[binary: string]: string;
};
/**
Filenames to put in place for the `man` program to find.
*/
man?: string | string[];
/**
Indicates the structure of the package.
*/
directories?: PackageJson.DirectoryLocations;
/**
Location for the code repository.
*/
repository?:
| string
| {
type: string;
url: string;
};
/**
Script commands that are run at various times in the lifecycle of the package. The key is the lifecycle event, and the value is the command to run at that point.
*/
scripts?: PackageJson.Scripts;
/**
Is used to set configuration parameters used in package scripts that persist across upgrades.
*/
config?: {
[configKey: string]: unknown;
};
/**
The dependencies of the package.
*/
dependencies?: PackageJson.Dependency;
/**
Additional tooling dependencies that are not required for the package to work. Usually test, build, or documentation tooling.
*/
devDependencies?: PackageJson.Dependency;
/**
Dependencies that are skipped if they fail to install.
*/
optionalDependencies?: PackageJson.Dependency;
/**
Dependencies that will usually be required by the package user directly or via another dependency.
*/
peerDependencies?: PackageJson.Dependency;
/**
Package names that are bundled when the package is published.
*/
bundledDependencies?: string[];
/**
Alias of `bundledDependencies`.
*/
bundleDependencies?: string[];
/**
Engines that this package runs on.
*/
engines?: {
[EngineName in 'npm' | 'node' | string]: string;
};
/**
@deprecated
*/
engineStrict?: boolean;
/**
Operating systems the module runs on.
*/
os?: Array<LiteralUnion<
| 'aix'
| 'darwin'
| 'freebsd'
| 'linux'
| 'openbsd'
| 'sunos'
| 'win32'
| '!aix'
| '!darwin'
| '!freebsd'
| '!linux'
| '!openbsd'
| '!sunos'
| '!win32',
string
>>;
/**
CPU architectures the module runs on.
*/
cpu?: Array<LiteralUnion<
| 'arm'
| 'arm64'
| 'ia32'
| 'mips'
| 'mipsel'
| 'ppc'
| 'ppc64'
| 's390'
| 's390x'
| 'x32'
| 'x64'
| '!arm'
| '!arm64'
| '!ia32'
| '!mips'
| '!mipsel'
| '!ppc'
| '!ppc64'
| '!s390'
| '!s390x'
| '!x32'
| '!x64',
string
>>;
/**
If set to `true`, a warning will be shown if package is installed locally. Useful if the package is primarily a command-line application that should be installed globally.
@deprecated
*/
preferGlobal?: boolean;
/**
If set to `true`, then npm will refuse to publish it.
*/
private?: boolean;
/**
* A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default.
*/
publishConfig?: {
[config: string]: unknown;
};
} &
PackageJson.NonStandardEntryPoints &
PackageJson.TypeScriptConfiguration &
PackageJson.YarnConfiguration &
PackageJson.JSPMConfiguration & {
[key: string]: unknown;
};

View File

@ -0,0 +1,72 @@
import {Primitive} from './basic';
/**
Create a type from another type with all keys and nested keys set to optional.
Use-cases:
- Merging a default settings/config object with another object, the second object would be a deep partial of the default object.
- Mocking and testing complex entities, where populating an entire object with its keys would be redundant in terms of the mock or test.
@example
```
import {PartialDeep} from 'type-fest';
const settings: Settings = {
textEditor: {
fontSize: 14;
fontColor: '#000000';
fontWeight: 400;
}
autocomplete: false;
autosave: true;
};
const applySavedSettings = (savedSettings: PartialDeep<Settings>) => {
return {...settings, ...savedSettings};
}
settings = applySavedSettings({textEditor: {fontWeight: 500}});
```
*/
export type PartialDeep<T> = T extends Primitive
? Partial<T>
: T extends Map<infer KeyType, infer ValueType>
? PartialMapDeep<KeyType, ValueType>
: T extends Set<infer ItemType>
? PartialSetDeep<ItemType>
: T extends ReadonlyMap<infer KeyType, infer ValueType>
? PartialReadonlyMapDeep<KeyType, ValueType>
: T extends ReadonlySet<infer ItemType>
? PartialReadonlySetDeep<ItemType>
: T extends ((...arguments: any[]) => unknown)
? T | undefined
: T extends object
? PartialObjectDeep<T>
: unknown;
/**
Same as `PartialDeep`, but accepts only `Map`s and as inputs. Internal helper for `PartialDeep`.
*/
interface PartialMapDeep<KeyType, ValueType> extends Map<PartialDeep<KeyType>, PartialDeep<ValueType>> {}
/**
Same as `PartialDeep`, but accepts only `Set`s as inputs. Internal helper for `PartialDeep`.
*/
interface PartialSetDeep<T> extends Set<PartialDeep<T>> {}
/**
Same as `PartialDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `PartialDeep`.
*/
interface PartialReadonlyMapDeep<KeyType, ValueType> extends ReadonlyMap<PartialDeep<KeyType>, PartialDeep<ValueType>> {}
/**
Same as `PartialDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `PartialDeep`.
*/
interface PartialReadonlySetDeep<T> extends ReadonlySet<PartialDeep<T>> {}
/**
Same as `PartialDeep`, but accepts only `object`s as inputs. Internal helper for `PartialDeep`.
*/
type PartialObjectDeep<ObjectType extends object> = {
[KeyType in keyof ObjectType]?: PartialDeep<ObjectType[KeyType]>
};

View File

@ -0,0 +1,23 @@
/**
Create a type that represents either the value or the value wrapped in `PromiseLike`.
Use-cases:
- A function accepts a callback that may either return a value synchronously or may return a promised value.
- This type could be the return type of `Promise#then()`, `Promise#catch()`, and `Promise#finally()` callbacks.
Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31394) if you want to have this type as a built-in in TypeScript.
@example
```
import {Promisable} from 'type-fest';
async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
const entry = await getLogEntry();
console.log(entry);
}
logger(() => 'foo');
logger(() => Promise.resolve('bar'));
```
*/
export type Promisable<T> = T | PromiseLike<T>;

View File

@ -0,0 +1,59 @@
import {Primitive} from './basic';
/**
Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their keys/elements into immutable structures recursively.
This is useful when a deeply nested structure needs to be exposed as completely immutable, for example, an imported JSON module or when receiving an API response that is passed around.
Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/13923) if you want to have this type as a built-in in TypeScript.
@example
```
// data.json
{
"foo": ["bar"]
}
// main.ts
import {ReadonlyDeep} from 'type-fest';
import dataJson = require('./data.json');
const data: ReadonlyDeep<typeof dataJson> = dataJson;
export default data;
// test.ts
import data from './main';
data.foo.push('bar');
//=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
```
*/
export type ReadonlyDeep<T> = T extends Primitive | ((...arguments: any[]) => unknown)
? T
: T extends ReadonlyMap<infer KeyType, infer ValueType>
? ReadonlyMapDeep<KeyType, ValueType>
: T extends ReadonlySet<infer ItemType>
? ReadonlySetDeep<ItemType>
: T extends object
? ReadonlyObjectDeep<T>
: unknown;
/**
Same as `ReadonlyDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `ReadonlyDeep`.
*/
interface ReadonlyMapDeep<KeyType, ValueType>
extends ReadonlyMap<ReadonlyDeep<KeyType>, ReadonlyDeep<ValueType>> {}
/**
Same as `ReadonlyDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `ReadonlyDeep`.
*/
interface ReadonlySetDeep<ItemType>
extends ReadonlySet<ReadonlyDeep<ItemType>> {}
/**
Same as `ReadonlyDeep`, but accepts only `object`s as inputs. Internal helper for `ReadonlyDeep`.
*/
type ReadonlyObjectDeep<ObjectType extends object> = {
readonly [KeyType in keyof ObjectType]: ReadonlyDeep<ObjectType[KeyType]>
};

View File

@ -0,0 +1,32 @@
import {Except} from './except';
/**
Create a type that requires at least one of the given keys. The remaining keys are kept as is.
@example
```
import {RequireAtLeastOne} from 'type-fest';
type Responder = {
text?: () => string;
json?: () => string;
secure?: boolean;
};
const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
json: () => '{"message": "ok"}',
secure: true
};
```
*/
export type RequireAtLeastOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
{
// For each Key in KeysType make a mapped type
[Key in KeysType]: (
// …by picking that Key's type and making it required
Required<Pick<ObjectType, Key>>
)
}[KeysType]
// …then, make intersection types by adding the remaining keys to each mapped type.
& Except<ObjectType, KeysType>;

View File

@ -0,0 +1,36 @@
// TODO: Remove this when we target TypeScript >=3.5.
// eslint-disable-next-line @typescript-eslint/generic-type-naming
type _Omit<T, K extends keyof any> = Pick<T, Exclude<keyof T, K>>;
/**
Create a type that requires exactly one of the given keys and disallows more. The remaining keys are kept as is.
Use-cases:
- Creating interfaces for components that only need one of the keys to display properly.
- Declaring generic keys in a single place for a single use-case that gets narrowed down via `RequireExactlyOne`.
The caveat with `RequireExactlyOne` is that TypeScript doesn't always know at compile time every key that will exist at runtime. Therefore `RequireExactlyOne` can't do anything to prevent extra keys it doesn't know about.
@example
```
import {RequireExactlyOne} from 'type-fest';
type Responder = {
text: () => string;
json: () => string;
secure: boolean;
};
const responder: RequireExactlyOne<Responder, 'text' | 'json'> = {
// Adding a `text` key here would cause a compile error.
json: () => '{"message": "ok"}',
secure: true
};
```
*/
export type RequireExactlyOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
{[Key in KeysType]: (
Required<Pick<ObjectType, Key>> &
Partial<Record<Exclude<KeysType, Key>, never>>
)}[KeysType] & _Omit<ObjectType, KeysType>;

View File

@ -0,0 +1,32 @@
/**
Create a type that makes the given keys optional. The remaining keys are kept as is. The sister of the `SetRequired` type.
Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are optional.
@example
```
import {SetOptional} from 'type-fest';
type Foo = {
a: number;
b?: string;
c: boolean;
}
type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
// type SomeOptional = {
// a: number;
// b?: string; // Was already optional and still is.
// c?: boolean; // Is now optional.
// }
```
*/
export type SetOptional<BaseType, Keys extends keyof BaseType = keyof BaseType> =
// Pick just the keys that are not optional from the base type.
Pick<BaseType, Exclude<keyof BaseType, Keys>> &
// Pick the keys that should be optional from the base type and make them optional.
Partial<Pick<BaseType, Keys>> extends
// If `InferredType` extends the previous, then for each key, use the inferred type key.
infer InferredType
? {[KeyType in keyof InferredType]: InferredType[KeyType]}
: never;

View File

@ -0,0 +1,32 @@
/**
Create a type that makes the given keys required. The remaining keys are kept as is. The sister of the `SetOptional` type.
Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are required.
@example
```
import {SetRequired} from 'type-fest';
type Foo = {
a?: number;
b: string;
c?: boolean;
}
type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
// type SomeRequired = {
// a?: number;
// b: string; // Was already required and still is.
// c: boolean; // Is now required.
// }
```
*/
export type SetRequired<BaseType, Keys extends keyof BaseType = keyof BaseType> =
// Pick just the keys that are not required from the base type.
Pick<BaseType, Exclude<keyof BaseType, Keys>> &
// Pick the keys that should be required from the base type and make them required.
Required<Pick<BaseType, Keys>> extends
// If `InferredType` extends the previous, then for each key, use the inferred type key.
infer InferredType
? {[KeyType in keyof InferredType]: InferredType[KeyType]}
: never;

View File

@ -0,0 +1,63 @@
{
"name": "read-pkg-up",
"version": "7.0.1",
"description": "Read the closest package.json file",
"license": "MIT",
"repository": "sindresorhus/read-pkg-up",
"funding": "https://github.com/sponsors/sindresorhus",
"author": {
"name": "Sindre Sorhus",
"email": "sindresorhus@gmail.com",
"url": "sindresorhus.com"
},
"engines": {
"node": ">=8"
},
"scripts": {
"test": "xo && ava && tsd"
},
"files": [
"index.js",
"index.d.ts"
],
"keywords": [
"json",
"read",
"parse",
"file",
"fs",
"graceful",
"load",
"package",
"find",
"up",
"find-up",
"findup",
"look-up",
"look",
"search",
"match",
"resolve",
"parent",
"parents",
"folder",
"directory",
"walk",
"walking",
"path"
],
"dependencies": {
"find-up": "^4.1.0",
"read-pkg": "^5.2.0",
"type-fest": "^0.8.1"
},
"devDependencies": {
"ava": "^2.4.0",
"tsd": "^0.9.0",
"xo": "^0.25.3"
}
,"_resolved": "https://registry.npmjs.org/read-pkg-up/-/read-pkg-up-7.0.1.tgz"
,"_integrity": "sha512-zK0TB7Xd6JpCLmlLmufqykGE+/TlOePD6qKClNW7hHDKFh/J7/7gCWGR7joEQEW1bKq3a3yUZSObOoWLFQ4ohg=="
,"_from": "read-pkg-up@7.0.1"
}

View File

@ -0,0 +1,77 @@
# read-pkg-up [![Build Status](https://travis-ci.org/sindresorhus/read-pkg-up.svg?branch=master)](https://travis-ci.org/sindresorhus/read-pkg-up)
> Read the closest package.json file
## Why
- [Finds the closest package.json](https://github.com/sindresorhus/find-up)
- [Gracefully handles filesystem issues](https://github.com/isaacs/node-graceful-fs)
- [Throws more helpful JSON errors](https://github.com/sindresorhus/parse-json)
- [Normalizes the data](https://github.com/npm/normalize-package-data#what-normalization-currently-entails)
## Install
```
$ npm install read-pkg-up
```
## Usage
```js
const readPkgUp = require('read-pkg-up');
(async () => {
console.log(await readPkgUp());
/*
{
packageJson: {
name: 'awesome-package',
version: '1.0.0',
…
},
path: '/Users/sindresorhus/dev/awesome-package/package.json'
}
*/
})();
```
## API
### readPkgUp(options?)
Returns a `Promise<object>` or `Promise<undefined>` if no `package.json` was found.
### readPkgUp.sync(options?)
Returns the result object or `undefined` if no `package.json` was found.
#### options
Type: `object`
##### cwd
Type: `string`\
Default: `process.cwd()`
Directory to start looking for a package.json file.
##### normalize
Type: `boolean`\
Default: `true`
[Normalize](https://github.com/npm/normalize-package-data#what-normalization-currently-entails) the package data.
## read-pkg-up for enterprise
Available as part of the Tidelift Subscription.
The maintainers of read-pkg-up and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-read-pkg-up?utm_source=npm-read-pkg-up&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
## Related
- [read-pkg](https://github.com/sindresorhus/read-pkg) - Read a package.json file
- [pkg-up](https://github.com/sindresorhus/pkg-up) - Find the closest package.json file
- [find-up](https://github.com/sindresorhus/find-up) - Find a file by walking up parent directories
- [pkg-conf](https://github.com/sindresorhus/pkg-conf) - Get namespaced config from the closest package.json

View File

@ -0,0 +1,67 @@
import * as typeFest from 'type-fest';
import normalize = require('normalize-package-data');
declare namespace readPkg {
interface Options {
/**
[Normalize](https://github.com/npm/normalize-package-data#what-normalization-currently-entails) the package data.
@default true
*/
readonly normalize?: boolean;
/**
Current working directory.
@default process.cwd()
*/
readonly cwd?: string;
}
interface NormalizeOptions extends Options {
readonly normalize?: true;
}
type NormalizedPackageJson = PackageJson & normalize.Package;
type PackageJson = typeFest.PackageJson;
}
declare const readPkg: {
/**
@returns The parsed JSON.
@example
```
import readPkg = require('read-pkg');
(async () => {
console.log(await readPkg());
//=> {name: 'read-pkg', …}
console.log(await readPkg({cwd: 'some-other-directory'});
//=> {name: 'unicorn', …}
})();
```
*/
(options?: readPkg.NormalizeOptions): Promise<readPkg.NormalizedPackageJson>;
(options: readPkg.Options): Promise<readPkg.PackageJson>;
/**
@returns The parsed JSON.
@example
```
import readPkg = require('read-pkg');
console.log(readPkg.sync());
//=> {name: 'read-pkg', …}
console.log(readPkg.sync({cwd: 'some-other-directory'});
//=> {name: 'unicorn', …}
```
*/
sync(options?: readPkg.NormalizeOptions): readPkg.NormalizedPackageJson;
sync(options: readPkg.Options): readPkg.PackageJson;
};
export = readPkg;

View File

@ -0,0 +1,41 @@
'use strict';
const {promisify} = require('util');
const fs = require('fs');
const path = require('path');
const parseJson = require('parse-json');
const readFileAsync = promisify(fs.readFile);
module.exports = async options => {
options = {
cwd: process.cwd(),
normalize: true,
...options
};
const filePath = path.resolve(options.cwd, 'package.json');
const json = parseJson(await readFileAsync(filePath, 'utf8'));
if (options.normalize) {
require('normalize-package-data')(json);
}
return json;
};
module.exports.sync = options => {
options = {
cwd: process.cwd(),
normalize: true,
...options
};
const filePath = path.resolve(options.cwd, 'package.json');
const json = parseJson(fs.readFileSync(filePath, 'utf8'));
if (options.normalize) {
require('normalize-package-data')(json);
}
return json;
};

View File

@ -0,0 +1,9 @@
MIT License
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
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.

View File

@ -0,0 +1,4 @@
# Names sorted by how much code was originally theirs.
Isaac Z. Schlueter <i@izs.me>
Meryn Stol <merynstol@gmail.com>
Robert Kowalski <rok@kowalski.gd>

View File

@ -0,0 +1,30 @@
This package contains code originally written by Isaac Z. Schlueter.
Used with permission.
Copyright (c) Meryn Stol ("Author")
All rights reserved.
The BSD License
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

View File

@ -0,0 +1,106 @@
# normalize-package-data [![Build Status](https://travis-ci.org/npm/normalize-package-data.png?branch=master)](https://travis-ci.org/npm/normalize-package-data)
normalize-package-data exports a function that normalizes package metadata. This data is typically found in a package.json file, but in principle could come from any source - for example the npm registry.
normalize-package-data is used by [read-package-json](https://npmjs.org/package/read-package-json) to normalize the data it reads from a package.json file. In turn, read-package-json is used by [npm](https://npmjs.org/package/npm) and various npm-related tools.
## Installation
```
npm install normalize-package-data
```
## Usage
Basic usage is really simple. You call the function that normalize-package-data exports. Let's call it `normalizeData`.
```javascript
normalizeData = require('normalize-package-data')
packageData = require("./package.json")
normalizeData(packageData)
// packageData is now normalized
```
#### Strict mode
You may activate strict validation by passing true as the second argument.
```javascript
normalizeData = require('normalize-package-data')
packageData = require("./package.json")
normalizeData(packageData, true)
// packageData is now normalized
```
If strict mode is activated, only Semver 2.0 version strings are accepted. Otherwise, Semver 1.0 strings are accepted as well. Packages must have a name, and the name field must not have contain leading or trailing whitespace.
#### Warnings
Optionally, you may pass a "warning" function. It gets called whenever the `normalizeData` function encounters something that doesn't look right. It indicates less than perfect input data.
```javascript
normalizeData = require('normalize-package-data')
packageData = require("./package.json")
warnFn = function(msg) { console.error(msg) }
normalizeData(packageData, warnFn)
// packageData is now normalized. Any number of warnings may have been logged.
```
You may combine strict validation with warnings by passing `true` as the second argument, and `warnFn` as third.
When `private` field is set to `true`, warnings will be suppressed.
### Potential exceptions
If the supplied data has an invalid name or version vield, `normalizeData` will throw an error. Depending on where you call `normalizeData`, you may want to catch these errors so can pass them to a callback.
## What normalization (currently) entails
* The value of `name` field gets trimmed (unless in strict mode).
* The value of the `version` field gets cleaned by `semver.clean`. See [documentation for the semver module](https://github.com/isaacs/node-semver).
* If `name` and/or `version` fields are missing, they are set to empty strings.
* If `files` field is not an array, it will be removed.
* If `bin` field is a string, then `bin` field will become an object with `name` set to the value of the `name` field, and `bin` set to the original string value.
* If `man` field is a string, it will become an array with the original string as its sole member.
* If `keywords` field is string, it is considered to be a list of keywords separated by one or more white-space characters. It gets converted to an array by splitting on `\s+`.
* All people fields (`author`, `maintainers`, `contributors`) get converted into objects with name, email and url properties.
* If `bundledDependencies` field (a typo) exists and `bundleDependencies` field does not, `bundledDependencies` will get renamed to `bundleDependencies`.
* If the value of any of the dependencies fields (`dependencies`, `devDependencies`, `optionalDependencies`) is a string, it gets converted into an object with familiar `name=>value` pairs.
* The values in `optionalDependencies` get added to `dependencies`. The `optionalDependencies` array is left untouched.
* As of v2: Dependencies that point at known hosted git providers (currently: github, bitbucket, gitlab) will have their URLs canonicalized, but protocols will be preserved.
* As of v2: Dependencies that use shortcuts for hosted git providers (`org/proj`, `github:org/proj`, `bitbucket:org/proj`, `gitlab:org/proj`, `gist:docid`) will have the shortcut left in place. (In the case of github, the `org/proj` form will be expanded to `github:org/proj`.) THIS MARKS A BREAKING CHANGE FROM V1, where the shorcut was previously expanded to a URL.
* If `description` field does not exist, but `readme` field does, then (more or less) the first paragraph of text that's found in the readme is taken as value for `description`.
* If `repository` field is a string, it will become an object with `url` set to the original string value, and `type` set to `"git"`.
* If `repository.url` is not a valid url, but in the style of "[owner-name]/[repo-name]", `repository.url` will be set to git+https://github.com/[owner-name]/[repo-name].git
* If `bugs` field is a string, the value of `bugs` field is changed into an object with `url` set to the original string value.
* If `bugs` field does not exist, but `repository` field points to a repository hosted on GitHub, the value of the `bugs` field gets set to an url in the form of https://github.com/[owner-name]/[repo-name]/issues . If the repository field points to a GitHub Gist repo url, the associated http url is chosen.
* If `bugs` field is an object, the resulting value only has email and url properties. If email and url properties are not strings, they are ignored. If no valid values for either email or url is found, bugs field will be removed.
* If `homepage` field is not a string, it will be removed.
* If the url in the `homepage` field does not specify a protocol, then http is assumed. For example, `myproject.org` will be changed to `http://myproject.org`.
* If `homepage` field does not exist, but `repository` field points to a repository hosted on GitHub, the value of the `homepage` field gets set to an url in the form of https://github.com/[owner-name]/[repo-name]#readme . If the repository field points to a GitHub Gist repo url, the associated http url is chosen.
### Rules for name field
If `name` field is given, the value of the name field must be a string. The string may not:
* start with a period.
* contain the following characters: `/@\s+%`
* contain any characters that would need to be encoded for use in urls.
* resemble the word `node_modules` or `favicon.ico` (case doesn't matter).
### Rules for version field
If `version` field is given, the value of the version field must be a valid *semver* string, as determined by the `semver.valid` method. See [documentation for the semver module](https://github.com/isaacs/node-semver).
### Rules for license field
The `license` field should be a valid *SPDX license expression* or one of the special values allowed by [validate-npm-package-license](https://npmjs.com/package/validate-npm-package-license). See [documentation for the license field in package.json](https://docs.npmjs.com/files/package.json#license).
## Credits
This package contains code based on read-package-json written by Isaac Z. Schlueter. Used with permisson.
## License
normalize-package-data is released under the [BSD 2-Clause License](http://opensource.org/licenses/MIT).
Copyright (c) 2013 Meryn Stol

View File

@ -0,0 +1,14 @@
module.exports = extractDescription
// Extracts description from contents of a readme file in markdown format
function extractDescription (d) {
if (!d) return;
if (d === "ERROR: No README data found!") return;
// the first block of text before the first heading
// that isn't the first line heading
d = d.trim().split('\n')
for (var s = 0; d[s] && d[s].trim().match(/^(#|$)/); s ++);
var l = d.length
for (var e = s + 1; e < l && d[e].trim(); e ++);
return d.slice(s, e).join(' ').trim()
}

View File

@ -0,0 +1,418 @@
var semver = require("semver")
var validateLicense = require('validate-npm-package-license');
var hostedGitInfo = require("hosted-git-info")
var isBuiltinModule = require("resolve").isCore
var depTypes = ["dependencies","devDependencies","optionalDependencies"]
var extractDescription = require("./extract_description")
var url = require("url")
var typos = require("./typos.json")
var fixer = module.exports = {
// default warning function
warn: function() {},
fixRepositoryField: function(data) {
if (data.repositories) {
this.warn("repositories");
data.repository = data.repositories[0]
}
if (!data.repository) return this.warn("missingRepository")
if (typeof data.repository === "string") {
data.repository = {
type: "git",
url: data.repository
}
}
var r = data.repository.url || ""
if (r) {
var hosted = hostedGitInfo.fromUrl(r)
if (hosted) {
r = data.repository.url
= hosted.getDefaultRepresentation() == "shortcut" ? hosted.https() : hosted.toString()
}
}
if (r.match(/github.com\/[^\/]+\/[^\/]+\.git\.git$/)) {
this.warn("brokenGitUrl", r)
}
}
, fixTypos: function(data) {
Object.keys(typos.topLevel).forEach(function (d) {
if (data.hasOwnProperty(d)) {
this.warn("typo", d, typos.topLevel[d])
}
}, this)
}
, fixScriptsField: function(data) {
if (!data.scripts) return
if (typeof data.scripts !== "object") {
this.warn("nonObjectScripts")
delete data.scripts
return
}
Object.keys(data.scripts).forEach(function (k) {
if (typeof data.scripts[k] !== "string") {
this.warn("nonStringScript")
delete data.scripts[k]
} else if (typos.script[k] && !data.scripts[typos.script[k]]) {
this.warn("typo", k, typos.script[k], "scripts")
}
}, this)
}
, fixFilesField: function(data) {
var files = data.files
if (files && !Array.isArray(files)) {
this.warn("nonArrayFiles")
delete data.files
} else if (data.files) {
data.files = data.files.filter(function(file) {
if (!file || typeof file !== "string") {
this.warn("invalidFilename", file)
return false
} else {
return true
}
}, this)
}
}
, fixBinField: function(data) {
if (!data.bin) return;
if (typeof data.bin === "string") {
var b = {}
var match
if (match = data.name.match(/^@[^/]+[/](.*)$/)) {
b[match[1]] = data.bin
} else {
b[data.name] = data.bin
}
data.bin = b
}
}
, fixManField: function(data) {
if (!data.man) return;
if (typeof data.man === "string") {
data.man = [ data.man ]
}
}
, fixBundleDependenciesField: function(data) {
var bdd = "bundledDependencies"
var bd = "bundleDependencies"
if (data[bdd] && !data[bd]) {
data[bd] = data[bdd]
delete data[bdd]
}
if (data[bd] && !Array.isArray(data[bd])) {
this.warn("nonArrayBundleDependencies")
delete data[bd]
} else if (data[bd]) {
data[bd] = data[bd].filter(function(bd) {
if (!bd || typeof bd !== 'string') {
this.warn("nonStringBundleDependency", bd)
return false
} else {
if (!data.dependencies) {
data.dependencies = {}
}
if (!data.dependencies.hasOwnProperty(bd)) {
this.warn("nonDependencyBundleDependency", bd)
data.dependencies[bd] = "*"
}
return true
}
}, this)
}
}
, fixDependencies: function(data, strict) {
var loose = !strict
objectifyDeps(data, this.warn)
addOptionalDepsToDeps(data, this.warn)
this.fixBundleDependenciesField(data)
;['dependencies','devDependencies'].forEach(function(deps) {
if (!(deps in data)) return
if (!data[deps] || typeof data[deps] !== "object") {
this.warn("nonObjectDependencies", deps)
delete data[deps]
return
}
Object.keys(data[deps]).forEach(function (d) {
var r = data[deps][d]
if (typeof r !== 'string') {
this.warn("nonStringDependency", d, JSON.stringify(r))
delete data[deps][d]
}
var hosted = hostedGitInfo.fromUrl(data[deps][d])
if (hosted) data[deps][d] = hosted.toString()
}, this)
}, this)
}
, fixModulesField: function (data) {
if (data.modules) {
this.warn("deprecatedModules")
delete data.modules
}
}
, fixKeywordsField: function (data) {
if (typeof data.keywords === "string") {
data.keywords = data.keywords.split(/,\s+/)
}
if (data.keywords && !Array.isArray(data.keywords)) {
delete data.keywords
this.warn("nonArrayKeywords")
} else if (data.keywords) {
data.keywords = data.keywords.filter(function(kw) {
if (typeof kw !== "string" || !kw) {
this.warn("nonStringKeyword");
return false
} else {
return true
}
}, this)
}
}
, fixVersionField: function(data, strict) {
// allow "loose" semver 1.0 versions in non-strict mode
// enforce strict semver 2.0 compliance in strict mode
var loose = !strict
if (!data.version) {
data.version = ""
return true
}
if (!semver.valid(data.version, loose)) {
throw new Error('Invalid version: "'+ data.version + '"')
}
data.version = semver.clean(data.version, loose)
return true
}
, fixPeople: function(data) {
modifyPeople(data, unParsePerson)
modifyPeople(data, parsePerson)
}
, fixNameField: function(data, options) {
if (typeof options === "boolean") options = {strict: options}
else if (typeof options === "undefined") options = {}
var strict = options.strict
if (!data.name && !strict) {
data.name = ""
return
}
if (typeof data.name !== "string") {
throw new Error("name field must be a string.")
}
if (!strict)
data.name = data.name.trim()
ensureValidName(data.name, strict, options.allowLegacyCase)
if (isBuiltinModule(data.name))
this.warn("conflictingName", data.name)
}
, fixDescriptionField: function (data) {
if (data.description && typeof data.description !== 'string') {
this.warn("nonStringDescription")
delete data.description
}
if (data.readme && !data.description)
data.description = extractDescription(data.readme)
if(data.description === undefined) delete data.description;
if (!data.description) this.warn("missingDescription")
}
, fixReadmeField: function (data) {
if (!data.readme) {
this.warn("missingReadme")
data.readme = "ERROR: No README data found!"
}
}
, fixBugsField: function(data) {
if (!data.bugs && data.repository && data.repository.url) {
var hosted = hostedGitInfo.fromUrl(data.repository.url)
if(hosted && hosted.bugs()) {
data.bugs = {url: hosted.bugs()}
}
}
else if(data.bugs) {
var emailRe = /^.+@.*\..+$/
if(typeof data.bugs == "string") {
if(emailRe.test(data.bugs))
data.bugs = {email:data.bugs}
else if(url.parse(data.bugs).protocol)
data.bugs = {url: data.bugs}
else
this.warn("nonEmailUrlBugsString")
}
else {
bugsTypos(data.bugs, this.warn)
var oldBugs = data.bugs
data.bugs = {}
if(oldBugs.url) {
if(typeof(oldBugs.url) == "string" && url.parse(oldBugs.url).protocol)
data.bugs.url = oldBugs.url
else
this.warn("nonUrlBugsUrlField")
}
if(oldBugs.email) {
if(typeof(oldBugs.email) == "string" && emailRe.test(oldBugs.email))
data.bugs.email = oldBugs.email
else
this.warn("nonEmailBugsEmailField")
}
}
if(!data.bugs.email && !data.bugs.url) {
delete data.bugs
this.warn("emptyNormalizedBugs")
}
}
}
, fixHomepageField: function(data) {
if (!data.homepage && data.repository && data.repository.url) {
var hosted = hostedGitInfo.fromUrl(data.repository.url)
if (hosted && hosted.docs()) data.homepage = hosted.docs()
}
if (!data.homepage) return
if(typeof data.homepage !== "string") {
this.warn("nonUrlHomepage")
return delete data.homepage
}
if(!url.parse(data.homepage).protocol) {
data.homepage = "http://" + data.homepage
}
}
, fixLicenseField: function(data) {
if (!data.license) {
return this.warn("missingLicense")
} else{
if (
typeof(data.license) !== 'string' ||
data.license.length < 1 ||
data.license.trim() === ''
) {
this.warn("invalidLicense")
} else {
if (!validateLicense(data.license).validForNewPackages)
this.warn("invalidLicense")
}
}
}
}
function isValidScopedPackageName(spec) {
if (spec.charAt(0) !== '@') return false
var rest = spec.slice(1).split('/')
if (rest.length !== 2) return false
return rest[0] && rest[1] &&
rest[0] === encodeURIComponent(rest[0]) &&
rest[1] === encodeURIComponent(rest[1])
}
function isCorrectlyEncodedName(spec) {
return !spec.match(/[\/@\s\+%:]/) &&
spec === encodeURIComponent(spec)
}
function ensureValidName (name, strict, allowLegacyCase) {
if (name.charAt(0) === "." ||
!(isValidScopedPackageName(name) || isCorrectlyEncodedName(name)) ||
(strict && (!allowLegacyCase) && name !== name.toLowerCase()) ||
name.toLowerCase() === "node_modules" ||
name.toLowerCase() === "favicon.ico") {
throw new Error("Invalid name: " + JSON.stringify(name))
}
}
function modifyPeople (data, fn) {
if (data.author) data.author = fn(data.author)
;["maintainers", "contributors"].forEach(function (set) {
if (!Array.isArray(data[set])) return;
data[set] = data[set].map(fn)
})
return data
}
function unParsePerson (person) {
if (typeof person === "string") return person
var name = person.name || ""
var u = person.url || person.web
var url = u ? (" ("+u+")") : ""
var e = person.email || person.mail
var email = e ? (" <"+e+">") : ""
return name+email+url
}
function parsePerson (person) {
if (typeof person !== "string") return person
var name = person.match(/^([^\(<]+)/)
var url = person.match(/\(([^\)]+)\)/)
var email = person.match(/<([^>]+)>/)
var obj = {}
if (name && name[0].trim()) obj.name = name[0].trim()
if (email) obj.email = email[1];
if (url) obj.url = url[1];
return obj
}
function addOptionalDepsToDeps (data, warn) {
var o = data.optionalDependencies
if (!o) return;
var d = data.dependencies || {}
Object.keys(o).forEach(function (k) {
d[k] = o[k]
})
data.dependencies = d
}
function depObjectify (deps, type, warn) {
if (!deps) return {}
if (typeof deps === "string") {
deps = deps.trim().split(/[\n\r\s\t ,]+/)
}
if (!Array.isArray(deps)) return deps
warn("deprecatedArrayDependencies", type)
var o = {}
deps.filter(function (d) {
return typeof d === "string"
}).forEach(function(d) {
d = d.trim().split(/(:?[@\s><=])/)
var dn = d.shift()
var dv = d.join("")
dv = dv.trim()
dv = dv.replace(/^@/, "")
o[dn] = dv
})
return o
}
function objectifyDeps (data, warn) {
depTypes.forEach(function (type) {
if (!data[type]) return;
data[type] = depObjectify(data[type], type, warn)
})
}
function bugsTypos(bugs, warn) {
if (!bugs) return
Object.keys(bugs).forEach(function (k) {
if (typos.bugs[k]) {
warn("typo", k, typos.bugs[k], "bugs")
bugs[typos.bugs[k]] = bugs[k]
delete bugs[k]
}
})
}

View File

@ -0,0 +1,23 @@
var util = require("util")
var messages = require("./warning_messages.json")
module.exports = function() {
var args = Array.prototype.slice.call(arguments, 0)
var warningName = args.shift()
if (warningName == "typo") {
return makeTypoWarning.apply(null,args)
}
else {
var msgTemplate = messages[warningName] ? messages[warningName] : warningName + ": '%s'"
args.unshift(msgTemplate)
return util.format.apply(null, args)
}
}
function makeTypoWarning (providedName, probableName, field) {
if (field) {
providedName = field + "['" + providedName + "']"
probableName = field + "['" + probableName + "']"
}
return util.format(messages.typo, providedName, probableName)
}

View File

@ -0,0 +1,39 @@
module.exports = normalize
var fixer = require("./fixer")
normalize.fixer = fixer
var makeWarning = require("./make_warning")
var fieldsToFix = ['name','version','description','repository','modules','scripts'
,'files','bin','man','bugs','keywords','readme','homepage','license']
var otherThingsToFix = ['dependencies','people', 'typos']
var thingsToFix = fieldsToFix.map(function(fieldName) {
return ucFirst(fieldName) + "Field"
})
// two ways to do this in CoffeeScript on only one line, sub-70 chars:
// thingsToFix = fieldsToFix.map (name) -> ucFirst(name) + "Field"
// thingsToFix = (ucFirst(name) + "Field" for name in fieldsToFix)
thingsToFix = thingsToFix.concat(otherThingsToFix)
function normalize (data, warn, strict) {
if(warn === true) warn = null, strict = true
if(!strict) strict = false
if(!warn || data.private) warn = function(msg) { /* noop */ }
if (data.scripts &&
data.scripts.install === "node-gyp rebuild" &&
!data.scripts.preinstall) {
data.gypfile = true
}
fixer.warn = function() { warn(makeWarning.apply(null, arguments)) }
thingsToFix.forEach(function(thingName) {
fixer["fix" + ucFirst(thingName)](data, strict)
})
data._id = data.name + "@" + data.version
}
function ucFirst (string) {
return string.charAt(0).toUpperCase() + string.slice(1);
}

View File

@ -0,0 +1,9 @@
var util = require('util')
module.exports = function() {
var args = Array.prototype.slice.call(arguments, 0)
args.forEach(function(arg) {
if (!arg) throw new TypeError('Bad arguments.')
})
return util.format.apply(null, arguments)
}

View File

@ -0,0 +1,25 @@
{
"topLevel": {
"dependancies": "dependencies"
,"dependecies": "dependencies"
,"depdenencies": "dependencies"
,"devEependencies": "devDependencies"
,"depends": "dependencies"
,"dev-dependencies": "devDependencies"
,"devDependences": "devDependencies"
,"devDepenencies": "devDependencies"
,"devdependencies": "devDependencies"
,"repostitory": "repository"
,"repo": "repository"
,"prefereGlobal": "preferGlobal"
,"hompage": "homepage"
,"hampage": "homepage"
,"autohr": "author"
,"autor": "author"
,"contributers": "contributors"
,"publicationConfig": "publishConfig"
,"script": "scripts"
},
"bugs": { "web": "url", "name": "url" },
"script": { "server": "start", "tests": "test" }
}

View File

@ -0,0 +1,30 @@
{
"repositories": "'repositories' (plural) Not supported. Please pick one as the 'repository' field"
,"missingRepository": "No repository field."
,"brokenGitUrl": "Probably broken git url: %s"
,"nonObjectScripts": "scripts must be an object"
,"nonStringScript": "script values must be string commands"
,"nonArrayFiles": "Invalid 'files' member"
,"invalidFilename": "Invalid filename in 'files' list: %s"
,"nonArrayBundleDependencies": "Invalid 'bundleDependencies' list. Must be array of package names"
,"nonStringBundleDependency": "Invalid bundleDependencies member: %s"
,"nonDependencyBundleDependency": "Non-dependency in bundleDependencies: %s"
,"nonObjectDependencies": "%s field must be an object"
,"nonStringDependency": "Invalid dependency: %s %s"
,"deprecatedArrayDependencies": "specifying %s as array is deprecated"
,"deprecatedModules": "modules field is deprecated"
,"nonArrayKeywords": "keywords should be an array of strings"
,"nonStringKeyword": "keywords should be an array of strings"
,"conflictingName": "%s is also the name of a node core module."
,"nonStringDescription": "'description' field should be a string"
,"missingDescription": "No description"
,"missingReadme": "No README data"
,"missingLicense": "No license field."
,"nonEmailUrlBugsString": "Bug string field must be url, email, or {email,url}"
,"nonUrlBugsUrlField": "bugs.url field must be a string url. Deleted."
,"nonEmailBugsEmailField": "bugs.email field must be a string email. Deleted."
,"emptyNormalizedBugs": "Normalized value of bugs field is an empty object. Deleted."
,"nonUrlHomepage": "homepage field must be a string url. Deleted."
,"invalidLicense": "license should be a valid SPDX license expression"
,"typo": "%s should probably be %s."
}

View File

@ -0,0 +1,35 @@
{
"name": "normalize-package-data",
"version": "2.5.0",
"author": "Meryn Stol <merynstol@gmail.com>",
"description": "Normalizes data that can be found in package.json files.",
"license": "BSD-2-Clause",
"repository": {
"type": "git",
"url": "git://github.com/npm/normalize-package-data.git"
},
"main": "lib/normalize.js",
"scripts": {
"test": "tap test/*.js"
},
"dependencies": {
"hosted-git-info": "^2.1.4",
"resolve": "^1.10.0",
"semver": "2 || 3 || 4 || 5",
"validate-npm-package-license": "^3.0.1"
},
"devDependencies": {
"async": "^2.6.1",
"tap": "^12.4.0",
"underscore": "^1.8.3"
},
"files": [
"lib/*.js",
"lib/*.json",
"AUTHORS"
]
,"_resolved": "https://registry.npmjs.org/normalize-package-data/-/normalize-package-data-2.5.0.tgz"
,"_integrity": "sha512-/5CMN3T0R4XTj4DcGaexo+roZSdSFW/0AOOTROrjxzCG1wrWXEsGbRKevjlIL+ZDE4sZlJr5ED4YW0yqmkK+eA=="
,"_from": "normalize-package-data@2.5.0"
}

View File

@ -0,0 +1,15 @@
// Basic
export * from './source/basic';
// Utilities
export {Except} from './source/except';
export {Mutable} from './source/mutable';
export {Merge} from './source/merge';
export {MergeExclusive} from './source/merge-exclusive';
export {RequireAtLeastOne} from './source/require-at-least-one';
export {ReadonlyDeep} from './source/readonly-deep';
export {LiteralUnion} from './source/literal-union';
export {Promisable} from './source/promisable';
// Miscellaneous
export {PackageJson} from './source/package-json';

View File

@ -0,0 +1,9 @@
MIT License
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
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.

View File

@ -0,0 +1,55 @@
{
"name": "type-fest",
"version": "0.6.0",
"description": "A collection of essential TypeScript types",
"license": "(MIT OR CC0-1.0)",
"repository": "sindresorhus/type-fest",
"author": {
"name": "Sindre Sorhus",
"email": "sindresorhus@gmail.com",
"url": "sindresorhus.com"
},
"engines": {
"node": ">=8"
},
"scripts": {
"test": "xo && tsd"
},
"files": [
"index.d.ts",
"source"
],
"keywords": [
"typescript",
"ts",
"types",
"utility",
"util",
"utilities",
"omit",
"merge",
"json"
],
"devDependencies": {
"@sindresorhus/tsconfig": "^0.4.0",
"@typescript-eslint/eslint-plugin": "^1.9.0",
"@typescript-eslint/parser": "^1.10.2",
"eslint-config-xo-typescript": "^0.14.0",
"tsd": "^0.7.3",
"xo": "^0.24.0"
},
"xo": {
"extends": "xo-typescript",
"extensions": [
"ts"
],
"rules": {
"import/no-unresolved": "off",
"@typescript-eslint/indent": "off"
}
}
,"_resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.6.0.tgz"
,"_integrity": "sha512-q+MB8nYR1KDLrgr4G5yemftpMC7/QLqVndBmEEdqzmNj5dcFOO4Oo8qlwZE3ULT3+Zim1F8Kq4cBnikNhlCMlg=="
,"_from": "type-fest@0.6.0"
}

View File

@ -0,0 +1,119 @@
<div align="center">
<br>
<br>
<img src="media/logo.svg" alt="type-fest" height="300">
<br>
<br>
<b>A collection of essential TypeScript types</b>
<br>
<hr>
</div>
<br>
<br>
[![Build Status](https://travis-ci.com/sindresorhus/type-fest.svg?branch=master)](https://travis-ci.com/sindresorhus/type-fest)
[![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://www.youtube.com/watch?v=9auOCbH5Ns4)
<!-- Commented out until they actually show anything
[![npm dependents](https://badgen.net/npm/dependents/type-fest)](https://www.npmjs.com/package/type-fest?activeTab=dependents) [![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)
-->
Many of the types here should have been built-in. You can help by suggesting some of them to the [TypeScript project](https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md).
Either add this package as a dependency or copy-paste the needed types. No credit required. 👌
PR welcome for additional commonly needed types and docs improvements. Read the [contributing guidelines](.github/contributing.md) first.
## Install
```
$ npm install type-fest
```
*Requires TypeScript >=3.2*
## Usage
```ts
import {Except} from 'type-fest';
type Foo = {
unicorn: string;
rainbow: boolean;
};
type FooWithoutRainbow = Except<Foo, 'rainbow'>;
//=> {unicorn: string}
```
## API
Click the type names for complete docs.
### Basic
- [`Primitive`](source/basic.d.ts) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
- [`Class`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
- [`TypedArray`](source/basic.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
- [`ObservableLike`](source/basic.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
### Utilities
- [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type).
- [`Mutable`](source/mutable.d.ts) - Convert an object with `readonly` properties into a mutable object. Inverse of `Readonly<T>`.
- [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
- [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive properties.
- [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given properties.
- [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of a `object`/`Map`/`Set`/`Array` type.
- [`LiteralUnion`](source/literal-union.d.ts) - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
- [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
### Miscellaneous
- [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
## Declined types
*If we decline a type addition, we will make sure to document the better solution here.*
- [`Diff` and `Spread`](https://github.com/sindresorhus/type-fest/pull/7) - The PR author didn't provide any real-world use-cases and the PR went stale. If you think this type is useful, provide some real-world use-cases and we might reconsider.
## Tips
### Built-in types
There are many advanced types most users don't know about.
- [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) - Make all properties in `T` optional.
- [`Required<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1408-L1413) - Make all properties in `T` required.
- [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) - Make all properties in `T` readonly.
- [`Pick<T, K>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1422-L1427) - From `T`, pick a set of properties whose keys are in the union `K`.
- [`Record<K, T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434) - Construct a type with a set of properties `K` of type `T`.
- [`Exclude<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1436-L1439) - Exclude from `T` those types that are assignable to `U`.
- [`Extract<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1441-L1444) - Extract from `T` those types that are assignable to `U`.
- [`NonNullable<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1446-L1449) - Exclude `null` and `undefined` from `T`.
- [`Parameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1451-L1454) - Obtain the parameters of a function type in a tuple.
- [`ConstructorParameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1456-L1459) - Obtain the parameters of a constructor function type in a tuple.
- [`ReturnType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1461-L1464) – Obtain the return type of a function type.
- [`InstanceType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1466-L1469) – Obtain the instance type of a constructor function type.
You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#predefined-conditional-types).
## Maintainers
- [Sindre Sorhus](https://github.com/sindresorhus)
- [Jarek Radosz](https://github.com/CvX)
- [Dimitri Benin](https://github.com/BendingBender)
## License
(MIT OR CC0-1.0)

View File

@ -0,0 +1,67 @@
/// <reference lib="esnext"/>
// TODO: This can just be `export type Primitive = not object` when the `not` keyword is out.
/**
Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
*/
export type Primitive =
| null
| undefined
| string
| number
| boolean
| symbol
| bigint;
// TODO: Remove the `= unknown` sometime in the future when most users are on TS 3.5 as it's now the default
/**
Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
*/
export type Class<T = unknown> = new(...arguments_: any[]) => T;
/**
Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
*/
export type TypedArray =
| Int8Array
| Uint8Array
| Uint8ClampedArray
| Int16Array
| Uint16Array
| Int32Array
| Uint32Array
| Float32Array
| Float64Array
| BigInt64Array
| BigUint64Array;
/**
Matches a JSON object.
This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
*/
export type JsonObject = {[key: string]: JsonValue};
/**
Matches a JSON array.
*/
export interface JsonArray extends Array<JsonValue> {}
/**
Matches any valid JSON value.
*/
export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
declare global {
interface SymbolConstructor {
readonly observable: symbol;
}
}
/**
Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
*/
export interface ObservableLike {
subscribe(observer: (value: unknown) => void): void;
[Symbol.observable](): ObservableLike;
}

View File

@ -0,0 +1,22 @@
/**
Create a type from an object type without certain keys.
This type is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type). The `Omit` type does not restrict the omitted keys to be keys present on the given type, while `Except` does. The benefits of a stricter type are avoiding typos and allowing the compiler to pick up on rename refactors automatically.
Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/30825) if you want to have the stricter version as a built-in in TypeScript.
@example
```
import {Except} from 'type-fest';
type Foo = {
a: number;
b: string;
c: boolean;
};
type FooWithoutA = Except<Foo, 'a' | 'c'>;
//=> {b: string};
```
*/
export type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;

View File

@ -0,0 +1,33 @@
import {Primitive} from './basic';
/**
Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
@example
```
import {LiteralUnion} from 'type-fest';
// Before
type Pet = 'dog' | 'cat' | string;
const pet: Pet = '';
// Start typing in your TypeScript-enabled IDE.
// You **will not** get auto-completion for `dog` and `cat` literals.
// After
type Pet2 = LiteralUnion<'dog' | 'cat', string>;
const pet: Pet2 = '';
// You **will** get auto-completion for `dog` and `cat` literals.
```
*/
export type LiteralUnion<
LiteralType extends BaseType,
BaseType extends Primitive
> = LiteralType | (BaseType & {_?: never});

View File

@ -0,0 +1,39 @@
// Helper type. Not useful on its own.
type Without<FirstType, SecondType> = {[KeyType in Exclude<keyof FirstType, keyof SecondType>]?: never};
/**
Create a type that has mutually exclusive properties.
This type was inspired by [this comment](https://github.com/Microsoft/TypeScript/issues/14094#issuecomment-373782604).
This type works with a helper type, called `Without`. `Without<FirstType, SecondType>` produces a type that has only keys from `FirstType` which are not present on `SecondType` and sets the value type for these keys to `never`. This helper type is then used in `MergeExclusive` to remove keys from either `FirstType` or `SecondType`.
@example
```
import {MergeExclusive} from 'type-fest';
interface ExclusiveVariation1 {
exclusive1: boolean;
}
interface ExclusiveVariation2 {
exclusive2: string;
}
type ExclusiveOptions = MergeExclusive<ExclusiveVariation1, ExclusiveVariation2>;
let exclusiveOptions: ExclusiveOptions;
exclusiveOptions = {exclusive1: true};
//=> Works
exclusiveOptions = {exclusive2: 'hi'};
//=> Works
exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
//=> Error
```
*/
export type MergeExclusive<FirstType, SecondType> =
(FirstType | SecondType) extends object ?
(Without<FirstType, SecondType> & SecondType) | (Without<SecondType, FirstType> & FirstType) :
FirstType | SecondType;

View File

@ -0,0 +1,22 @@
import {Except} from './except';
/**
Merge two types into a new type. Keys of the second type overrides keys of the first type.
@example
```
import {Merge} from 'type-fest';
type Foo = {
a: number;
b: string;
};
type Bar = {
b: number;
};
const ab: Merge<Foo, Bar> = {a: 1, b: 2};
```
*/
export type Merge<FirstType, SecondType> = Except<FirstType, Extract<keyof FirstType, keyof SecondType>> & SecondType;

View File

@ -0,0 +1,22 @@
/**
Convert an object with `readonly` properties into a mutable object. Inverse of `Readonly<T>`.
This can be used to [store and mutate options within a class](https://github.com/sindresorhus/pageres/blob/4a5d05fca19a5fbd2f53842cbf3eb7b1b63bddd2/source/index.ts#L72), [edit `readonly` objects within tests](https://stackoverflow.com/questions/50703834), and [construct a `readonly` object within a function](https://github.com/Microsoft/TypeScript/issues/24509).
@example
```
import {Mutable} from 'type-fest';
type Foo = {
readonly a: number;
readonly b: string;
};
const mutableFoo: Mutable<Foo> = {a: 1, b: '2'};
mutableFoo.a = 3;
```
*/
export type Mutable<ObjectType> = {
// For each `Key` in the keys of `ObjectType`, make a mapped type by removing the `readonly` modifier from the property.
-readonly [KeyType in keyof ObjectType]: ObjectType[KeyType];
};

View File

@ -0,0 +1,501 @@
import {LiteralUnion} from '..';
declare namespace PackageJson {
/**
A person who has been involved in creating or maintaining the package.
*/
export type Person =
| string
| {
name: string;
url?: string;
email?: string;
};
export type BugsLocation =
| string
| {
/**
The URL to the package's issue tracker.
*/
url?: string;
/**
The email address to which issues should be reported.
*/
email?: string;
};
export interface DirectoryLocations {
/**
Location for executable scripts. Sugar to generate entries in the `bin` property by walking the folder.
*/
bin?: string;
/**
Location for Markdown files.
*/
doc?: string;
/**
Location for example scripts.
*/
example?: string;
/**
Location for the bulk of the library.
*/
lib?: string;
/**
Location for man pages. Sugar to generate a `man` array by walking the folder.
*/
man?: string;
/**
Location for test files.
*/
test?: string;
[directoryType: string]: unknown;
}
export type Scripts = {
/**
Run **before** the package is published (Also run on local `npm install` without any arguments).
*/
prepublish?: string;
/**
Run both **before** the package is packed and published, and on local `npm install` without any arguments. This is run **after** `prepublish`, but **before** `prepublishOnly`.
*/
prepare?: string;
/**
Run **before** the package is prepared and packed, **only** on `npm publish`.
*/
prepublishOnly?: string;
/**
Run **before** a tarball is packed (on `npm pack`, `npm publish`, and when installing git dependencies).
*/
prepack?: string;
/**
Run **after** the tarball has been generated and moved to its final destination.
*/
postpack?: string;
/**
Run **after** the package is published.
*/
publish?: string;
/**
Run **after** the package is published.
*/
postpublish?: string;
/**
Run **before** the package is installed.
*/
preinstall?: string;
/**
Run **after** the package is installed.
*/
install?: string;
/**
Run **after** the package is installed and after `install`.
*/
postinstall?: string;
/**
Run **before** the package is uninstalled and before `uninstall`.
*/
preuninstall?: string;
/**
Run **before** the package is uninstalled.
*/
uninstall?: string;
/**
Run **after** the package is uninstalled.
*/
postuninstall?: string;
/**
Run **before** bump the package version and before `version`.
*/
preversion?: string;
/**
Run **before** bump the package version.
*/
version?: string;
/**
Run **after** bump the package version.
*/
postversion?: string;
/**
Run with the `npm test` command, before `test`.
*/
pretest?: string;
/**
Run with the `npm test` command.
*/
test?: string;
/**
Run with the `npm test` command, after `test`.
*/
posttest?: string;
/**
Run with the `npm stop` command, before `stop`.
*/
prestop?: string;
/**
Run with the `npm stop` command.
*/
stop?: string;
/**
Run with the `npm stop` command, after `stop`.
*/
poststop?: string;
/**
Run with the `npm start` command, before `start`.
*/
prestart?: string;
/**
Run with the `npm start` command.
*/
start?: string;
/**
Run with the `npm start` command, after `start`.
*/
poststart?: string;
/**
Run with the `npm restart` command, before `restart`. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
*/
prerestart?: string;
/**
Run with the `npm restart` command. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
*/
restart?: string;
/**
Run with the `npm restart` command, after `restart`. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
*/
postrestart?: string;
} & {
[scriptName: string]: string;
};
/**
Dependencies of the package. The version range is a string which has one or more space-separated descriptors. Dependencies can also be identified with a tarball or Git URL.
*/
export interface Dependency {
[packageName: string]: string;
}
export interface NonStandardEntryPoints {
/**
An ECMAScript module ID that is the primary entry point to the program.
*/
module?: string;
/**
A module ID with untranspiled code that is the primary entry point to the program.
*/
esnext?:
| string
| {
main?: string;
browser?: string;
[moduleName: string]: string | undefined;
};
/**
A hint to JavaScript bundlers or component tools when packaging modules for client side use.
*/
browser?:
| string
| {
[moduleName: string]: string | false;
};
}
export interface TypeScriptConfiguration {
/**
Location of the bundled TypeScript declaration file.
*/
types?: string;
/**
Location of the bundled TypeScript declaration file. Alias of `types`.
*/
typings?: string;
}
export interface YarnConfiguration {
/**
If your package only allows one version of a given dependency, and you’d like to enforce the same behavior as `yarn install --flat` on the command line, set this to `true`.
Note that if your `package.json` contains `"flat": true` and other packages depend on yours (e.g. you are building a library rather than an application), those other packages will also need `"flat": true` in their `package.json` or be installed with `yarn install --flat` on the command-line.
*/
flat?: boolean;
/**
Selective version resolutions. Allows the definition of custom package versions inside dependencies without manual edits in the `yarn.lock` file.
*/
resolutions?: Dependency;
}
export interface JSPMConfiguration {
/**
JSPM configuration.
*/
jspm?: PackageJson;
}
}
/**
Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
*/
export type PackageJson = {
/**
The name of the package.
*/
name?: string;
/**
Package version, parseable by [`node-semver`](https://github.com/npm/node-semver).
*/
version?: string;
/**
Package description, listed in `npm search`.
*/
description?: string;
/**
Keywords associated with package, listed in `npm search`.
*/
keywords?: string[];
/**
The URL to the package's homepage.
*/
homepage?: LiteralUnion<'.', string>;
/**
The URL to the package's issue tracker and/or the email address to which issues should be reported.
*/
bugs?: PackageJson.BugsLocation;
/**
The license for the package.
*/
license?: string;
/**
The licenses for the package.
*/
licenses?: Array<{
type?: string;
url?: string;
}>;
author?: PackageJson.Person;
/**
A list of people who contributed to the package.
*/
contributors?: PackageJson.Person[];
/**
A list of people who maintain the package.
*/
maintainers?: PackageJson.Person[];
/**
The files included in the package.
*/
files?: string[];
/**
The module ID that is the primary entry point to the program.
*/
main?: string;
/**
The executable files that should be installed into the `PATH`.
*/
bin?:
| string
| {
[binary: string]: string;
};
/**
Filenames to put in place for the `man` program to find.
*/
man?: string | string[];
/**
Indicates the structure of the package.
*/
directories?: PackageJson.DirectoryLocations;
/**
Location for the code repository.
*/
repository?:
| string
| {
type: string;
url: string;
};
/**
Script commands that are run at various times in the lifecycle of the package. The key is the lifecycle event, and the value is the command to run at that point.
*/
scripts?: PackageJson.Scripts;
/**
Is used to set configuration parameters used in package scripts that persist across upgrades.
*/
config?: {
[configKey: string]: unknown;
};
/**
The dependencies of the package.
*/
dependencies?: PackageJson.Dependency;
/**
Additional tooling dependencies that are not required for the package to work. Usually test, build, or documentation tooling.
*/
devDependencies?: PackageJson.Dependency;
/**
Dependencies that are skipped if they fail to install.
*/
optionalDependencies?: PackageJson.Dependency;
/**
Dependencies that will usually be required by the package user directly or via another dependency.
*/
peerDependencies?: PackageJson.Dependency;
/**
Package names that are bundled when the package is published.
*/
bundledDependencies?: string[];
/**
Alias of `bundledDependencies`.
*/
bundleDependencies?: string[];
/**
Engines that this package runs on.
*/
engines?: {
[EngineName in 'npm' | 'node' | string]: string;
};
/**
@deprecated
*/
engineStrict?: boolean;
/**
Operating systems the module runs on.
*/
os?: Array<LiteralUnion<
| 'aix'
| 'darwin'
| 'freebsd'
| 'linux'
| 'openbsd'
| 'sunos'
| 'win32'
| '!aix'
| '!darwin'
| '!freebsd'
| '!linux'
| '!openbsd'
| '!sunos'
| '!win32',
string
>>;
/**
CPU architectures the module runs on.
*/
cpu?: Array<LiteralUnion<
| 'arm'
| 'arm64'
| 'ia32'
| 'mips'
| 'mipsel'
| 'ppc'
| 'ppc64'
| 's390'
| 's390x'
| 'x32'
| 'x64'
| '!arm'
| '!arm64'
| '!ia32'
| '!mips'
| '!mipsel'
| '!ppc'
| '!ppc64'
| '!s390'
| '!s390x'
| '!x32'
| '!x64',
string
>>;
/**
If set to `true`, a warning will be shown if package is installed locally. Useful if the package is primarily a command-line application that should be installed globally.
@deprecated
*/
preferGlobal?: boolean;
/**
If set to `true`, then npm will refuse to publish it.
*/
private?: boolean;
/**
* A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default.
*/
publishConfig?: {
[config: string]: unknown;
};
} &
PackageJson.NonStandardEntryPoints &
PackageJson.TypeScriptConfiguration &
PackageJson.YarnConfiguration &
PackageJson.JSPMConfiguration & {
[key: string]: unknown;
};

Some files were not shown because too many files have changed in this diff Show More