@joe-sh/pj

TypeScript API and binary installer for pj - a fast project finder.

Features

• Dual-purpose package: Works as both a global CLI tool and a TypeScript library
• Automatic binary management: Downloads and manages the pj binary automatically
• Smart binary resolution: Prefers globally installed pj, falls back to managed binary
• Full TypeScript support: Complete type definitions for all APIs
• Cross-platform: Works on macOS, Linux, and Windows

Installation

As a global CLI tool

npm install -g @joe-sh/pj

Then use pj directly:

pj --icons

As a library

npm install @joe-sh/pj

Usage

Library API

import { Pj, discover } from '@joe-sh/pj';

// Using the class-based API
const pj = new Pj();
const projects = await pj.discover();
console.log(projects);

// Using standalone functions
const allProjects = await discover();

// Find a specific project
const myProject = await pj.findProject('my-app');

// Search for projects by pattern
const reactProjects = await pj.findProjects(/react/i);

// Get projects grouped by marker type
const byMarker = await pj.discoverByMarker();
console.log(byMarker.get('package.json')); // All Node.js projects

Discovery Options

const projects = await pj.discover({
  // Search paths
  paths: ['~/projects', '~/code'],

  // Project markers to detect
  markers: ['.git', 'package.json', 'go.mod'],

  // Patterns to exclude
  excludes: ['node_modules', 'vendor'],

  // Maximum search depth
  maxDepth: 3,

  // Include icons in output
  icons: true,

  // Bypass cache
  noCache: true,
});

Configuration Management

import { Pj, loadConfig, saveConfig } from '@joe-sh/pj';

// Load existing configuration
const config = await loadConfig();

// Create instance with custom config
const pj = new Pj({
  paths: ['~/my-projects'],
  maxDepth: 5,
});

// Save configuration
await pj.saveConfig();

Binary Management

import { Pj, getBinaryManager } from '@joe-sh/pj';

const pj = new Pj();

// Check binary status
const status = await pj.getBinaryStatus();
console.log(status);
// { available: true, path: '/usr/local/bin/pj', version: '1.4.1', source: 'global' }

// Ensure binary is available (downloads if needed)
const binaryPath = await pj.ensureBinary();

// Update to latest version
await pj.updateBinary();

// Get version
const version = await pj.getBinaryVersion();

Cache Management

const pj = new Pj();

// Clear the project cache
await pj.clearCache();

// Get cache info
const info = await pj.getCacheInfo();
console.log(info);
// { exists: true, path: '~/.cache/pj', fileCount: 3, totalSize: 4096 }

API Reference

Pj Class

The main class for interacting with pj.

Constructor

new Pj(config?: Partial<PjConfig>)

Methods

| Method | Description | |--------|-------------| | discover(options?) | Discover all projects | | discoverFromPaths(paths, options?) | Discover projects from specific paths | | findProject(name, options?) | Find a project by name | | findProjects(pattern, options?) | Find projects matching a pattern | | discoverByMarker(options?) | Get projects grouped by marker type | | countByMarker(options?) | Count projects by marker type | | clearCache() | Clear the pj project cache | | getCacheInfo() | Get information about the pj cache | | loadConfig(path?) | Load configuration from file | | saveConfig(config?, path?) | Save configuration to file | | getConfig() | Get current configuration | | setConfig(config) | Update configuration | | ensureBinary(options?) | Ensure the pj binary is available | | getBinaryStatus() | Get the status of the pj binary | | updateBinary(options?) | Update the pj binary | | getBinaryVersion() | Get the version of the pj binary |

Standalone Functions

| Function | Description | |----------|-------------| | discover(options?) | Discover all projects | | discoverFromPaths(paths, options?) | Discover from specific paths | | findProject(name, options?) | Find a project by name | | findProjects(pattern, options?) | Find projects by pattern | | discoverByMarker(options?) | Group projects by marker | | countByMarker(options?) | Count projects by marker | | loadConfig(path?) | Load configuration | | saveConfig(config, path?) | Save configuration | | clearCache() | Clear the project cache | | getCacheInfo() | Get cache information | | getBinaryManager() | Get the binary manager instance |

Types

interface Project {
  path: string;      // Absolute path to the project
  name: string;      // Project name (directory name)
  marker: string;    // Marker that identified this project
  icon?: string;     // Optional Nerd Font icon
  priority?: number; // Marker priority
}

interface DiscoverOptions {
  paths?: string[];
  markers?: string[];
  excludes?: string[];
  maxDepth?: number;
  noIgnore?: boolean;
  nested?: boolean;
  noCache?: boolean;
  icons?: boolean;
  configPath?: string;
  verbose?: boolean;
}

interface PjConfig {
  paths: string[];
  markers: string[];
  exclude: string[];
  maxDepth: number;
  cacheTTL: number;
  noIgnore: boolean;
  noNested: boolean;
  icons: Record<string, string>;
}

interface BinaryStatus {
  available: boolean;
  path: string | null;
  version: string | null;
  source: 'global' | 'cache' | 'env' | null;
}

Environment Variables

| Variable | Description | |----------|-------------| | PJ_BINARY_PATH | Override the pj binary path | | PJ_SKIP_INSTALL | Skip binary download during npm install | | PJ_INSTALL_BINARY | Force binary download in CI environments |

Version Compatibility

This package tracks the pj CLI version using a major.minor pinning strategy:

| This package | Compatible pj versions | |--------------|------------------------| | 1.4.x | 1.4.0, 1.4.1, 1.4.2, ... | | 1.5.x | 1.5.0, 1.5.1, 1.5.2, ... |

How it works:

• This package stays in sync with pj's major.minor version
• Patch versions (the third number) are independent — patches to this package are for TypeScript wrapper bug fixes, not pj CLI changes
• When you install or update, the package automatically downloads the latest compatible pj patch within your major.minor range

What this means for you:

• @joe-sh/[email protected] will install the latest pj 1.4.x (e.g., 1.4.5 if available)
• When pj 1.5.0 is released, upgrade to @joe-sh/[email protected] to get the new features

Binary Resolution Order

The package looks for the pj binary in this order:

1. PJ_BINARY_PATH environment variable
2. Globally installed pj in PATH (if version-compatible)
3. Cached binary in ~/.cache/pj-node/ (if version-compatible)
4. Downloads from GitHub releases (highest compatible version)

Requirements

• Node.js 20.0.0 or higher

Related Projects

• pj - The pj CLI tool
• pj.nvim - Neovim integration

License

MIT