Skip to content

Commit 06c5cfb

Browse files
ljharbljharb
committed
fund: support multiple funding sources
See npm/rfcs#68
1 parent f533d61 commit 06c5cfb

File tree

6 files changed

+290
-127
lines changed

6 files changed

+290
-127
lines changed

Diff for: ‎docs/content/configuring-npm/package-json.md

+19-2
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,8 @@ npm also sets a top-level "maintainers" field with your npm user info.
197197
### funding
198198

199199
You can specify an object containing an URL that provides up-to-date
200-
information about ways to help fund development of your package:
200+
information about ways to help fund development of your package, or
201+
a string URL, or an array of these:
201202

202203
"funding": {
203204
"type" : "individual",
@@ -209,10 +210,26 @@ information about ways to help fund development of your package:
209210
"url" : "https://www.patreon.com/my-account"
210211
}
211212

213+
"funding": "http://example.com/donate"
214+
215+
"funding": [
216+
{
217+
"type" : "individual",
218+
"url" : "http://example.com/donate"
219+
},
220+
"http://example.com/donateAlso",
221+
{
222+
"type" : "patreon",
223+
"url" : "https://www.patreon.com/my-account"
224+
}
225+
]
226+
227+
212228
Users can use the `npm fund` subcommand to list the `funding` URLs of all
213229
dependencies of their project, direct and indirect. A shortcut to visit each
214230
funding url is also available when providing the project name such as:
215-
`npm fund <projectname>`.
231+
`npm fund <projectname>` (when there are multiple URLs, the first one will be
232+
visited)
216233

217234
### files
218235

Diff for: ‎lib/fund.js

+47-81
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,14 @@ const readShrinkwrap = require('./install/read-shrinkwrap.js')
1414
const mutateIntoLogicalTree = require('./install/mutate-into-logical-tree.js')
1515
const output = require('./utils/output.js')
1616
const openUrl = require('./utils/open-url.js')
17-
const { getFundingInfo, retrieveFunding, validFundingUrl } = require('./utils/funding.js')
17+
const { getFundingInfo, retrieveFunding, validFundingField, flatCacheSymbol } = require('./utils/funding.js')
1818

1919
const FundConfig = figgyPudding({
2020
browser: {}, // used by ./utils/open-url
2121
global: {},
2222
json: {},
23-
unicode: {}
23+
unicode: {},
24+
which: {}
2425
})
2526

2627
module.exports = fundCmd
@@ -29,7 +30,7 @@ const usage = require('./utils/usage')
2930
fundCmd.usage = usage(
3031
'fund',
3132
'npm fund [--json]',
32-
'npm fund [--browser] [[<@scope>/]<pkg>'
33+
'npm fund [--browser] [[<@scope>/]<pkg> [--which=<fundingSourceNumber>]'
3334
)
3435

3536
fundCmd.completion = function (opts, cb) {
@@ -52,96 +53,52 @@ function printJSON (fundingInfo) {
5253
// level possible, in that process they also carry their dependencies along
5354
// with them, moving those up in the visual tree
5455
function printHuman (fundingInfo, opts) {
55-
// mapping logic that keeps track of seen items in order to be able
56-
// to push all other items from the same type/url in the same place
57-
const seen = new Map()
56+
const flatCache = fundingInfo[flatCacheSymbol]
5857

59-
function seenKey ({ type, url } = {}) {
60-
return url ? String(type) + String(url) : null
61-
}
62-
63-
function setStackedItem (funding, result) {
64-
const key = seenKey(funding)
65-
if (key && !seen.has(key)) seen.set(key, result)
66-
}
58+
const { name, version } = fundingInfo
59+
const printableVersion = version ? `@${version}` : ''
6760

68-
function retrieveStackedItem (funding) {
69-
const key = seenKey(funding)
70-
if (key && seen.has(key)) return seen.get(key)
71-
}
61+
const items = Object.keys(flatCache).map((url) => {
62+
const deps = flatCache[url]
7263

73-
// ---
74-
75-
const getFundingItems = (fundingItems) =>
76-
Object.keys(fundingItems || {}).map((fundingItemName) => {
77-
// first-level loop, prepare the pretty-printed formatted data
78-
const fundingItem = fundingItems[fundingItemName]
79-
const { version, funding } = fundingItem
80-
const { type, url } = funding || {}
64+
const packages = deps.map((dep) => {
65+
const { name, version } = dep
8166

8267
const printableVersion = version ? `@${version}` : ''
83-
const printableType = type && { label: `type: ${funding.type}` }
84-
const printableUrl = url && { label: `url: ${funding.url}` }
85-
const result = {
86-
fundingItem,
87-
label: fundingItemName + printableVersion,
88-
nodes: []
89-
}
90-
91-
if (printableType) {
92-
result.nodes.push(printableType)
93-
}
94-
95-
if (printableUrl) {
96-
result.nodes.push(printableUrl)
97-
}
98-
99-
setStackedItem(funding, result)
100-
101-
return result
102-
}).reduce((res, result) => {
103-
// recurse and exclude nodes that are going to be stacked together
104-
const { fundingItem } = result
105-
const { dependencies, funding } = fundingItem
106-
const items = getFundingItems(dependencies)
107-
const stackedResult = retrieveStackedItem(funding)
108-
items.forEach(i => result.nodes.push(i))
109-
110-
if (stackedResult && stackedResult !== result) {
111-
stackedResult.label += `, ${result.label}`
112-
items.forEach(i => stackedResult.nodes.push(i))
113-
return res
114-
}
115-
116-
res.push(result)
117-
118-
return res
119-
}, [])
120-
121-
const [ result ] = getFundingItems({
122-
[fundingInfo.name]: {
123-
dependencies: fundingInfo.dependencies,
124-
funding: fundingInfo.funding,
125-
version: fundingInfo.version
68+
return `${name}${printableVersion}`
69+
})
70+
71+
return {
72+
label: url,
73+
nodes: [packages.join(', ')]
12674
}
12775
})
12876

129-
return archy(result, '', { unicode: opts.unicode })
77+
return archy({ label: `${name}${printableVersion}`, nodes: items }, '', { unicode: opts.unicode })
13078
}
13179

132-
function openFundingUrl (packageName, cb) {
80+
function openFundingUrl (packageName, fundingSourceNumber, cb) {
13381
function getUrlAndOpen (packageMetadata) {
13482
const { funding } = packageMetadata
135-
const { type, url } = retrieveFunding(funding) || {}
136-
const noFundingError =
137-
new Error(`No funding method available for: ${packageName}`)
138-
noFundingError.code = 'ENOFUND'
139-
const typePrefix = type ? `${type} funding` : 'Funding'
140-
const msg = `${typePrefix} available at the following URL`
141-
142-
if (validFundingUrl(funding)) {
83+
const validSources = [].concat(retrieveFunding(funding)).filter(validFundingField)
84+
85+
if (validSources.length === 1 || (fundingSourceNumber > 0 && fundingSourceNumber <= validSources.length)) {
86+
const { type, url } = validSources[fundingSourceNumber ? fundingSourceNumber - 1 : 0]
87+
const typePrefix = type ? `${type} funding` : 'Funding'
88+
const msg = `${typePrefix} available at the following URL`
14389
openUrl(url, msg, cb)
90+
} else if (!(fundingSourceNumber >= 1)) {
91+
validSources.forEach(({ type, url }, i) => {
92+
const typePrefix = type ? `${type} funding` : 'Funding'
93+
const msg = `${typePrefix} available at the following URL`
94+
console.log(`${i + 1}: ${msg}: ${url}`)
95+
})
96+
console.log('Run `npm fund [<@scope>/]<pkg> --which=1`, for example, to open the first funding URL listed in that package')
97+
cb()
14498
} else {
99+
const noFundingError = new Error(`No valid funding method available for: ${packageName}`)
100+
noFundingError.code = 'ENOFUND'
101+
145102
throw noFundingError
146103
}
147104
}
@@ -161,15 +118,24 @@ function fundCmd (args, cb) {
161118
const opts = FundConfig(npmConfig())
162119
const dir = path.resolve(npm.dir, '..')
163120
const packageName = args[0]
121+
const numberArg = opts.which
122+
123+
const fundingSourceNumber = numberArg && parseInt(numberArg, 10)
124+
125+
if (numberArg !== undefined && (String(fundingSourceNumber) !== numberArg || fundingSourceNumber < 1)) {
126+
const err = new Error('`npm fund [<@scope>/]<pkg> [--which=fundingSourceNumber]` must be given a positive integer')
127+
err.code = 'EFUNDNUMBER'
128+
throw err
129+
}
164130

165131
if (opts.global) {
166-
const err = new Error('`npm fund` does not support globals')
132+
const err = new Error('`npm fund` does not support global packages')
167133
err.code = 'EFUNDGLOBAL'
168134
throw err
169135
}
170136

171137
if (packageName) {
172-
openFundingUrl(packageName, cb)
138+
openFundingUrl(packageName, fundingSourceNumber, cb)
173139
return
174140
}
175141

Diff for: ‎lib/utils/funding.js

+62-32
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,31 @@ const URL = require('url').URL
44

55
exports.getFundingInfo = getFundingInfo
66
exports.retrieveFunding = retrieveFunding
7-
exports.validFundingUrl = validFundingUrl
7+
exports.validFundingField = validFundingField
88

9-
// supports both object funding and string shorthand
9+
const flatCacheSymbol = Symbol('npm flat cache')
10+
exports.flatCacheSymbol = flatCacheSymbol
11+
12+
// supports object funding and string shorthand, or an array of these
13+
// if original was an array, returns an array; else returns the lone item
1014
function retrieveFunding (funding) {
11-
return typeof funding === 'string'
12-
? {
13-
url: funding
14-
}
15-
: funding
15+
const sources = [].concat(funding || []).map(item => (
16+
typeof item === 'string'
17+
? { url: item }
18+
: item
19+
))
20+
return Array.isArray(funding) ? sources : sources[0]
1621
}
1722

1823
// Is the value of a `funding` property of a `package.json`
1924
// a valid type+url for `npm fund` to display?
20-
function validFundingUrl (funding) {
25+
function validFundingField (funding) {
2126
if (!funding) return false
2227

28+
if (Array.isArray(funding)) {
29+
return funding.every(f => !Array.isArray(f) && validFundingField(f))
30+
}
31+
2332
try {
2433
var parsed = new URL(funding.url || funding)
2534
} catch (error) {
@@ -34,11 +43,13 @@ function validFundingUrl (funding) {
3443
return Boolean(parsed.host)
3544
}
3645

46+
const empty = () => Object.create(null)
47+
3748
function getFundingInfo (idealTree, opts) {
38-
let length = 0
49+
let packageWithFundingCount = 0
50+
const flat = empty()
3951
const seen = new Set()
4052
const { countOnly } = opts || {}
41-
const empty = () => Object.create(null)
4253
const _trailingDependencies = Symbol('trailingDependencies')
4354

4455
function tracked (name, version) {
@@ -70,52 +81,70 @@ function getFundingInfo (idealTree, opts) {
7081
)
7182
}
7283

84+
function addToFlatCache (funding, dep) {
85+
[].concat(funding || []).forEach((f) => {
86+
const key = f.url
87+
if (!Array.isArray(flat[key])) {
88+
flat[key] = []
89+
}
90+
flat[key].push(dep)
91+
})
92+
}
93+
94+
function attachFundingInfo (target, funding, dep) {
95+
if (funding && validFundingField(funding)) {
96+
target.funding = retrieveFunding(funding)
97+
if (!countOnly) {
98+
addToFlatCache(target.funding, dep)
99+
}
100+
101+
packageWithFundingCount++
102+
}
103+
}
104+
73105
function getFundingDependencies (tree) {
74106
const deps = tree && tree.dependencies
75107
if (!deps) return empty()
76108

77-
// broken into two steps to make sure items appearance
78-
// within top levels takes precedence over nested ones
79-
return (Object.keys(deps)).map((key) => {
109+
const directDepsWithFunding = Object.keys(deps).map((key) => {
80110
const dep = deps[key]
81111
const { name, funding, version } = dep
82112

83-
const fundingItem = {}
84-
85113
// avoids duplicated items within the funding tree
86114
if (tracked(name, version)) return empty()
87115

116+
const fundingItem = {}
117+
88118
if (version) {
89119
fundingItem.version = version
90120
}
91121

92-
if (funding && validFundingUrl(funding)) {
93-
fundingItem.funding = retrieveFunding(funding)
94-
length++
95-
}
122+
attachFundingInfo(fundingItem, funding, dep)
96123

97124
return {
98125
dep,
99126
fundingItem
100127
}
101-
}).reduce((res, { dep, fundingItem }, i) => {
102-
if (!fundingItem) return res
128+
})
129+
130+
return directDepsWithFunding.reduce((res, { dep: directDep, fundingItem }, i) => {
131+
if (!fundingItem || fundingItem.length === 0) return res
103132

104133
// recurse
105-
const dependencies = dep.dependencies &&
106-
Object.keys(dep.dependencies).length > 0 &&
107-
getFundingDependencies(dep)
134+
const transitiveDependencies = directDep.dependencies &&
135+
Object.keys(directDep.dependencies).length > 0 &&
136+
getFundingDependencies(directDep)
108137

109138
// if we're only counting items there's no need
110139
// to add all the data to the resulting object
111140
if (countOnly) return null
112141

113-
if (hasDependencies(dependencies)) {
114-
fundingItem.dependencies = retrieveDependencies(dependencies)
142+
if (hasDependencies(transitiveDependencies)) {
143+
fundingItem.dependencies = retrieveDependencies(transitiveDependencies)
115144
}
116145

117-
if (fundingItem.funding) {
118-
res[dep.name] = fundingItem
146+
if (fundingItem.funding && fundingItem.funding.length !== 0) {
147+
res[directDep.name] = fundingItem
119148
} else if (fundingItem.dependencies) {
120149
res[_trailingDependencies] =
121150
Object.assign(
@@ -126,12 +155,12 @@ function getFundingInfo (idealTree, opts) {
126155
}
127156

128157
return res
129-
}, empty())
158+
}, countOnly ? null : empty())
130159
}
131160

132161
const idealTreeDependencies = getFundingDependencies(idealTree)
133162
const result = {
134-
length
163+
length: packageWithFundingCount
135164
}
136165

137166
if (!countOnly) {
@@ -145,8 +174,9 @@ function getFundingInfo (idealTree, opts) {
145174
result.funding = retrieveFunding(idealTree.funding)
146175
}
147176

148-
result.dependencies =
149-
retrieveDependencies(idealTreeDependencies)
177+
result.dependencies = retrieveDependencies(idealTreeDependencies)
178+
179+
result[flatCacheSymbol] = flat
150180
}
151181

152182
return result

0 commit comments

Comments
 (0)