npm-keyword

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

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

import npmKeyword from "npm-keyword";

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

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 });

/**
 * 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[]>;

// 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 });

/**
 * 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[]>;

// 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 });

/**
 * 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>;

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

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

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;
}

// 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);
}