https://github.com/myprototypewhat/npx-scope-finder
A specialized tool for finding executable (npx-compatible) packages within a specific npm scope. This tool helps you discover all packages in a scope that can be run using npx.
https://github.com/myprototypewhat/npx-scope-finder
Last synced: 5 months ago
JSON representation
A specialized tool for finding executable (npx-compatible) packages within a specific npm scope. This tool helps you discover all packages in a scope that can be run using npx.
- Host: GitHub
- URL: https://github.com/myprototypewhat/npx-scope-finder
- Owner: MyPrototypeWhat
- License: mit
- Created: 2025-03-15T08:54:50.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-18T10:13:41.000Z (over 1 year ago)
- Last Synced: 2025-10-19T00:53:48.719Z (9 months ago)
- Language: TypeScript
- Homepage:
- Size: 60.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# npx-scope-finder
A specialized tool for finding executable (npx-compatible) packages within a specific npm scope. This tool helps you discover all packages in a scope that can be run using `npx`.
✨ **Cross-Platform Support**: Works in both Node.js and browser environments!
## Features
- 🌐 **Universal Compatibility**: Works in both Node.js and browser environments
- 🔄 **Robust Error Handling**: Built-in retry mechanism for network issues
- 🎯 **Scope-Focused**: Easily find all executable packages within your organization's scope
- 📦 **Zero Dependencies**: Uses native fetch API, no external dependencies
- ⚡ **High Performance**: Uses concurrent requests for faster results
- 🛡️ **Fault Tolerant**: Uses `Promise.allSettled` to handle partial failures gracefully
- 🔍 **Complete Data**: Includes full package metadata in the `original` property
- 💪 **Type Safety**: Full TypeScript support with detailed type definitions
- 🔻 **Optimized Size**: Code is minified for smaller package size
## Changelog
A detailed changelog is available in the [CHANGELOG.md](./CHANGELOG.md) file.
### 1.3.0 (2024-03-18)
- 🔧 Improved project structure with separate type definitions
- 🗑️ Removed code comments for smaller bundle size
- 🔻 Added code minification for optimized package size
- ⬆️ Updated TypeScript target to ES2020
- 🧩 Exported all TypeScript interfaces and types for better developer experience
- 📝 Enhanced type definitions based on official npm Registry API documentation
- 🔄 Added links to official npm documentation for better TypeScript integration
- 🧹 Removed unused type definitions to reduce bundle size and improve code clarity
### 1.2.0 (2024-03-15)
- ⚡ Added concurrent requests for improved performance
- 🛡️ Implemented `Promise.allSettled` for fault-tolerant package fetching
- 🔍 Added original package data in the `original` property
- 🗑️ Removed format utilities for a more streamlined API
### 1.1.0 (2024-03-15)
- ✨ Added browser support
- 🔄 Replaced npm-registry-fetch with native fetch API
- ⚡️ Improved retry mechanism with better error handling
- 🧪 Added comprehensive retry tests
- 📦 Reduced package size by removing external dependencies
## Installation
```bash
npm install npx-scope-finder
# or
pnpm add npx-scope-finder
# or
yarn add npx-scope-finder
```
## Usage
```typescript
import { npxFinder } from 'npx-scope-finder';
// Basic usage - get raw package data
const packages = await npxFinder('@your-scope', {
timeout: 10000, // Request timeout in milliseconds (default: 10000)
retries: 3, // Number of retries for failed requests (default: 3)
retryDelay: 1000 // Delay between retries in milliseconds (default: 1000)
});
console.log(`Found ${packages.length} executable packages`);
// Access package data
packages.forEach(pkg => {
console.log(`Package: ${pkg.name}@${pkg.version}`);
console.log(`Description: ${pkg.description || 'No description'}`);
console.log('Executable commands:', Object.keys(pkg.bin || {}));
// Access full original npm registry data
console.log('Full package data:', pkg.original);
// Access other metadata
if (pkg.links?.repository) {
console.log(`Repository: ${pkg.links.repository}`);
}
if (pkg.dependencies) {
console.log('Dependencies:', Object.keys(pkg.dependencies).length);
}
});
// Custom formatting example
packages.forEach(pkg => {
const customFormat = `
📦 ${pkg.name}@${pkg.version}
${pkg.description || 'No description'}
Commands: ${Object.keys(pkg.bin || {}).join(', ')}
Run with: npx ${pkg.name}
`;
console.log(customFormat);
});
```
## API
### `npxFinder(scope: string, options?: NpxFinderOptions): Promise`
The main function for finding executable packages in a scope.
#### Parameters
- `scope`: The npm scope to search in (e.g., '@your-scope')
- `options`: Optional configuration
- `timeout`: Request timeout in milliseconds (default: 10000)
- `retries`: Number of retries for failed requests (default: 3)
- `retryDelay`: Delay between retries in milliseconds (default: 1000)
#### Returns
Array of `NPMPackage` objects with the following structure:
```typescript
interface NPMPackage {
name: string; // Package name
description?: string; // Package description
version: string; // Latest version
bin?: Record; // Executable commands
dependencies?: Record; // Dependencies
scripts?: Record; // npm scripts
keywords?: string[]; // Package keywords
links?: { // Related links
npm?: string; // npm package page
repository?: string; // Code repository
homepage?: string; // Homepage
};
original?: PackageInfo; // Complete original package data from npm registry
}
```
> **Type Definitions**: The `NPMPackage` interface and all other type definitions are derived from the [official npm Registry API documentation](https://github.com/npm/registry/blob/master/docs/responses/package-metadata.md).
### Exported Types
The library exports all types for maximum flexibility:
```typescript
import {
NPMPackage, // Main package result type
NpxFinderOptions, // Options for the npxFinder function
SearchResponse, // Raw response from npm registry search
PackageInfo // Detailed package information from npm registry
} from 'npx-scope-finder';
```
This allows developers to easily extend the library or implement custom type-safe handling of the returned data.
> **Note**: The type definitions in this library are based on the official npm Registry API documentation:
> - [Package Metadata Documentation](https://github.com/npm/registry/blob/master/docs/responses/package-metadata.md)
> - [Registry API Documentation](https://github.com/npm/registry/blob/master/docs/REGISTRY-API.md)
## Example Output
Example package object:
```javascript
{
name: '@your-scope/cli-tool',
version: '1.0.0',
description: 'A command line tool',
bin: {
'your-tool': './bin/cli.js'
},
dependencies: {
'commander': '^9.0.0',
'chalk': '^5.0.0'
},
keywords: ['cli', 'tool', 'automation'],
links: {
npm: 'https://www.npmjs.com/package/@your-scope/cli-tool',
repository: 'https://github.com/your-org/cli-tool',
homepage: 'https://your-org.github.io/cli-tool'
},
original: {
// Complete package data from npm registry
// ...
}
}
```
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/MyPrototypeWhat/npx-scope-finder.git
cd npx-scope-finder
# Install dependencies
pnpm install
# Build the project
pnpm build
```
### Testing
```bash
# Run all tests
pnpm test
# Run specific test suites
pnpm test:functional # Run functional tests
pnpm test:retry # Run retry mechanisms tests
```
### Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT