or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-npm-keyword

Get a list of npm packages with keywords using the npm registry API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/npm-keyword@8.0.x

To install, run

npx @tessl/cli install tessl/npm-npm-keyword@8.0.0

index.mddocs/

npm-keyword

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.

Package Information

  • Package Name: npm-keyword
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install npm-keyword

Core Imports

import { npmKeyword, npmKeywordNames, npmKeywordCount } from "npm-keyword";

For CommonJS:

const { npmKeyword, npmKeywordNames, npmKeywordCount } = require("npm-keyword");

For default import:

import npmKeyword from "npm-keyword";

To import types:

import { type Options, type PackageDescriptor } from "npm-keyword";

Basic Usage

import { npmKeyword, npmKeywordNames, npmKeywordCount } from "npm-keyword";

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

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

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

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

// Limit results
const limitedResults = await npmKeyword('testing', { size: 50 });

Capabilities

Package Search with Descriptions

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

/**
 * Get a list of npm packages with certain keywords
 * @param keyword - One or more keywords. Only matches packages that have *all* the given keywords
 * @param options - Configuration options
 * @returns Promise resolving to array of package descriptors
 */
function npmKeyword(
  keyword: string | readonly string[], 
  options?: Options
): Promise<PackageDescriptor[]>;

Usage Examples:

// Single keyword
const packages = await npmKeyword('testing');

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

// With size limit
const packages = await npmKeyword('gulp', { size: 100 });

Package Names Only

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

/**
 * Get a list of npm package names with certain keywords
 * @param keyword - One or more keywords. Only matches packages that have *all* the given keywords
 * @param options - Configuration options
 * @returns Promise resolving to array of package names
 */
function npmKeywordNames(
  keyword: string | readonly string[], 
  options?: Options
): Promise<string[]>;

Usage Examples:

// Single keyword
const names = await npmKeywordNames('vue');

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

// With size limit
const names = await npmKeywordNames('react', { size: 50 });

Package Count

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

/**
 * Get the count of npm packages with certain keywords
 * @param keyword - One or more keywords. Only matches packages that have *all* the given keywords
 * @returns Promise resolving to number of matching packages
 */
function npmKeywordCount(
  keyword: string | readonly string[]
): Promise<number>;

Usage Examples:

// Single keyword count
const count = await npmKeywordCount('express');

// Multiple keywords count
const count = await npmKeywordCount(['express', 'middleware']);

Types

interface Options {
  /** Limits the amount of results (range: 1-250) */
  readonly size?: number;
}

interface PackageDescriptor {
  /** Package name */
  readonly name: string;
  /** Package description */
  readonly description: string;
}

Error Handling

The library throws TypeError in the following cases:

  • Invalid keyword parameter: When keyword is not a string or array of strings
  • Invalid size option: When size is 0 or greater than 250
// These will throw TypeError
try {
  await npmKeyword(42 as any); // Invalid keyword type
  await npmKeyword('test', { size: 0 }); // Invalid size (too small)
  await npmKeyword('test', { size: 300 }); // Invalid size (too large)
} catch (error) {
  console.error(error.message);
}

Constraints and Limitations

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

API Dependencies

The library uses:

  • ky: Modern HTTP client for making requests to the npm registry
  • registry-url: Gets the appropriate npm registry URL

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