0
# npm-keyword
1

2
npm-keyword is a lightweight Node.js library that provides a simple and efficient way to search for npm packages by keywords using the npm registry API. It offers three main functions for different search result formats: full package information, package names only, and result counts.
3

4
## Package Information
5

6
- **Package Name**: npm-keyword
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install npm-keyword`
10

11
## Core Imports
12

13
```typescript
14
import { npmKeyword, npmKeywordNames, npmKeywordCount } from "npm-keyword";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { npmKeyword, npmKeywordNames, npmKeywordCount } = require("npm-keyword");
21
```
22

23
For default import:
24

25
```typescript
26
import npmKeyword from "npm-keyword";
27
```
28

29
To import types:
30

31
```typescript
32
import { type Options, type PackageDescriptor } from "npm-keyword";
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { npmKeyword, npmKeywordNames, npmKeywordCount } from "npm-keyword";
39

40
// Get full package information
41
const packages = await npmKeyword('gulpplugin');
42
console.log(packages);
43
//=> [{name: 'gulp-autoprefixer', description: 'PostCSS plugin to parse CSS and add vendor prefixes to CSS rules'}, ...]
44

45
// Get package names only (faster)
46
const packageNames = await npmKeywordNames('gulpplugin');
47
console.log(packageNames);
48
//=> ['gulp-autoprefixer', 'gulp-sass', 'gulp-concat', ...]
49

50
// Get count of matching packages
51
const count = await npmKeywordCount('gulpplugin');
52
console.log(count);
53
//=> 3457
54

55
// Search with multiple keywords (AND logic)
56
const reactPackages = await npmKeyword(['react', 'component']);
57
// Returns packages that have BOTH 'react' AND 'component' keywords
58

59
// Limit results
60
const limitedResults = await npmKeyword('testing', { size: 50 });
61
```
62

63
## Capabilities
64

65
### Package Search with Descriptions
66

67
Get a list of npm packages with certain keywords, including package names and descriptions.
68

69
```typescript { .api }
70
/**
71
 * Get a list of npm packages with certain keywords
72
 * @param keyword - One or more keywords. Only matches packages that have *all* the given keywords
73
 * @param options - Configuration options
74
 * @returns Promise resolving to array of package descriptors
75
 */
76
function npmKeyword(
77
  keyword: string | readonly string[], 
78
  options?: Options
79
): Promise<PackageDescriptor[]>;
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
// Single keyword
86
const packages = await npmKeyword('testing');
87

88
// Multiple keywords (AND logic)
89
const packages = await npmKeyword(['testing', 'mocha']);
90

91
// With size limit
92
const packages = await npmKeyword('gulp', { size: 100 });
93
```
94

95
### Package Names Only
96

97
Get a list of npm package names with certain keywords. This is faster than `npmKeyword()` as it doesn't include descriptions.
98

99
```typescript { .api }
100
/**
101
 * Get a list of npm package names with certain keywords
102
 * @param keyword - One or more keywords. Only matches packages that have *all* the given keywords
103
 * @param options - Configuration options
104
 * @returns Promise resolving to array of package names
105
 */
106
function npmKeywordNames(
107
  keyword: string | readonly string[], 
108
  options?: Options
109
): Promise<string[]>;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
// Single keyword
116
const names = await npmKeywordNames('vue');
117

118
// Multiple keywords
119
const names = await npmKeywordNames(['vue', 'component']);
120

121
// With size limit
122
const names = await npmKeywordNames('react', { size: 50 });
123
```
124

125
### Package Count
126

127
Get the count of npm packages with certain keywords without retrieving the actual package data.
128

129
```typescript { .api }
130
/**
131
 * Get the count of npm packages with certain keywords
132
 * @param keyword - One or more keywords. Only matches packages that have *all* the given keywords
133
 * @returns Promise resolving to number of matching packages
134
 */
135
function npmKeywordCount(
136
  keyword: string | readonly string[]
137
): Promise<number>;
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
// Single keyword count
144
const count = await npmKeywordCount('express');
145

146
// Multiple keywords count
147
const count = await npmKeywordCount(['express', 'middleware']);
148
```
149

150
## Types
151

152
```typescript { .api }
153
interface Options {
154
  /** Limits the amount of results (range: 1-250) */
155
  readonly size?: number;
156
}
157

158
interface PackageDescriptor {
159
  /** Package name */
160
  readonly name: string;
161
  /** Package description */
162
  readonly description: string;
163
}
164
```
165

166
## Error Handling
167

168
The library throws `TypeError` in the following cases:
169

170
- **Invalid keyword parameter**: When keyword is not a string or array of strings
171
- **Invalid size option**: When size is 0 or greater than 250
172

173
```typescript
174
// These will throw TypeError
175
try {
176
  await npmKeyword(42 as any); // Invalid keyword type
177
  await npmKeyword('test', { size: 0 }); // Invalid size (too small)
178
  await npmKeyword('test', { size: 300 }); // Invalid size (too large)
179
} catch (error) {
180
  console.error(error.message);
181
}
182
```
183

184
## Constraints and Limitations
185

186
- **Maximum results**: 250 packages per search (npm registry API limitation)
187
- **Size range**: The `size` option must be between 1 and 250
188
- **Keyword logic**: Multiple keywords use AND logic (all keywords must match)
189
- **Node.js requirement**: Requires Node.js >= 18
190

191
## API Dependencies
192

193
The library uses:
194
- `ky`: Modern HTTP client for making requests to the npm registry
195
- `registry-url`: Gets the appropriate npm registry URL
196

197
The default npm registry endpoint used is: `https://registry.npmjs.org/-/v1/search`