• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# libnpmfund
2
3[![npm version](https://img.shields.io/npm/v/libnpmfund.svg)](https://npm.im/libnpmfund)
4[![license](https://img.shields.io/npm/l/libnpmfund.svg)](https://npm.im/libnpmfund)
5[![CI - libnpmfund](https://github.com/npm/cli/actions/workflows/ci-libnpmfund.yml/badge.svg)](https://github.com/npm/cli/actions/workflows/ci-libnpmfund.yml)
6
7[`libnpmfund`](https://github.com/npm/libnpmfund) is a Node.js library for
8retrieving **funding** information for packages installed using
9[`arborist`](https://github.com/npm/arborist).
10
11## Table of Contents
12
13* [Example](#example)
14* [Install](#install)
15* [Contributing](#contributing)
16* [API](#api)
17* [LICENSE](#license)
18
19## Example
20
21```js
22const { read } = require('libnpmfund')
23
24const fundingInfo = await read()
25console.log(
26  JSON.stringify(fundingInfo, null, 2)
27)
28// => {
29  length: 2,
30  name: 'foo',
31  version: '1.0.0',
32  funding: { url: 'https://example.com' },
33  dependencies: {
34    bar: {
35      version: '1.0.0',
36      funding: { url: 'http://collective.example.com' }
37    }
38  }
39}
40```
41
42## Install
43
44`$ npm install libnpmfund`
45
46### Contributing
47
48The npm team enthusiastically welcomes contributions and project participation!
49There's a bunch of things you can do if you want to contribute! The
50[Contributor Guide](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md)
51outlines the process for community interaction and contribution. Please don't
52hesitate to jump in if you'd like to, or even ask us questions if something
53isn't clear.
54
55All participants and maintainers in this project are expected to follow the
56[npm Code of Conduct](https://www.npmjs.com/policies/conduct), and just
57generally be excellent to each other.
58
59Please refer to the [Changelog](CHANGELOG.md) for project history details, too.
60
61Happy hacking!
62
63### API
64
65##### <a name="fund.read"></a> `> fund.read([opts]) -> Promise<Object>`
66
67Reads **funding** info from a npm install and returns a promise for a
68tree object that only contains packages in which funding info is defined.
69
70Options:
71
72- `countOnly`: Uses the tree-traversal logic from **npm fund** but skips over
73any obj definition and just returns an obj containing `{ length }` - useful for
74things such as printing a `6 packages are looking for funding` msg.
75- `workspaces`: `Array<String>` List of workspaces names to filter for,
76the result will only include a subset of the resulting tree that includes
77only the nodes that are children of the listed workspaces names.
78- `path`, `registry` and more [Arborist](https://github.com/npm/arborist/) options.
79
80##### <a name="fund.readTree"></a> `> fund.readTree(tree, [opts]) -> Promise<Object>`
81
82Reads **funding** info from a given install tree and returns a tree object
83that only contains packages in which funding info is defined.
84
85- `tree`: An [`arborist`](https://github.com/npm/arborist) tree to be used, e.g:
86
87```js
88const Arborist = require('@npmcli/arborist')
89const { readTree } = require('libnpmfund')
90
91const arb = new Arborist({ path: process.cwd() })
92const tree = await arb.loadActual()
93
94return readTree(tree, { countOnly: false })
95```
96
97Options:
98
99- `countOnly`: Uses the tree-traversal logic from **npm fund** but skips over
100any obj definition and just returns an obj containing `{ length }` - useful for
101things such as printing a `6 packages are looking for funding` msg.
102
103##### <a name="fund.normalizeFunding"></a> `> fund.normalizeFunding(funding) -> Object`
104
105From a `funding` `<object|string|array>`, retrieves normalized funding objects
106containing a `url` property.
107
108e.g:
109
110```js
111normalizeFunding('http://example.com')
112// => {
113  url: 'http://example.com'
114}
115```
116
117##### <a name="fund.isValidFunding"></a> `> fund.isValidFunding(funding) -> Boolean`
118
119Returns `<true>` if `funding` is a valid funding object, e.g:
120
121```js
122isValidFunding({ foo: 'not a valid funding obj' })
123// => false
124
125isValidFunding('http://example.com')
126// => true
127```
128
129## LICENSE
130
131[ISC](./LICENSE)
132