ts-pkgx

ts-pkgx

This library includes tools to fetch and save package information from pkgx.dev.

Installation

npm install ts-pkgx
bun install ts-pkgx

Usage

CLI Tool

The library includes a comprehensive CLI tool to manage packages from pkgx.dev:

# Fetch a single package
bun run pkgx:fetch node

# Fetch multiple packages
bun run pkgx:fetch --pkg "node,python,go"

# With custom output directory
bun run pkgx:fetch node --output-dir ./data/packages

# Fetch all packages
bun run pkgx:fetch-all

# Set options for fetching
bun run pkgx:fetch-all --timeout 180000 --output-dir ./data/packages --limit 100

# Generate documentation
bun run pkgx:docs

# Update local pantry cache
bun ./bin/cli.ts update-pantry

# Generate TypeScript files from cache
bun ./bin/cli.ts generate-ts

# Generate package index
bun ./bin/cli.ts generate-index

# Generate package aliases
bun ./bin/cli.ts generate-aliases

# Generate constants file
bun ./bin/cli.ts generate-consts

# Resolve dependency files and transitive dependencies
bun ./bin/cli.ts resolve-deps deps.yaml

# Get PHP versions for CI/CD workflows
bun ./bin/cli.ts get-php-versions
bun ./bin/cli.ts get-php-versions --format yaml
bun ./bin/cli.ts get-php-versions --branches 8.4,8.3 --format csv

Dependency Resolution

ts-pkgx includes a powerful dependency resolver that can analyze dependency files and resolve all transitive dependencies:

# Resolve a single dependency file
bun ./bin/cli.ts resolve-deps deps.yaml --verbose --install-command

# Find and resolve all dependency files in a project
bun ./bin/cli.ts resolve-deps --find-files ./my-project

# Output as JSON for automation
bun ./bin/cli.ts resolve-deps deps.yaml --json

# Filter for specific OS
bun ./bin/cli.ts resolve-deps deps.yaml --target-os darwin --include-os-deps

ts-pkgx also provides comprehensive Integration APIs designed for package managers and deployment tools that need advanced dependency resolution:

import { resolveDependencies } from 'ts-pkgx'

// Resolve dependencies from a YAML file
const result = await resolveDependencies('./deps.yaml', {
  targetOs: 'darwin',
  includeOsSpecific: true
})

console.log(`Installing ${result.totalCount} packages...`)

// Install each resolved package
for (const pkg of result.packages) {
  await launchpad.install(pkg.name, pkg.version)
}

Key Features:

• 🔍 Deep transitive dependency resolution - Automatically resolves all nested dependencies
• ⚡ Version conflict resolution - Intelligently handles conflicting version constraints
• 🎯 OS-specific dependencies - Platform-aware dependency resolution
• 📄 Multiple input formats - YAML files, strings, and individual packages
• 🔧 Semantic versioning - Full semver constraint support (^, ~, >=, etc.)

For detailed integration examples and API documentation, see the Launchpad Integration Guide.

Programmatic Usage

You can also use the library programmatically in your code:

import {
  fetchAndSaveAllPackages,
  fetchPantryPackage,
  fetchPantryPackageWithMetadata,
  findDependencyFiles,
  resolveDependencies,
  resolveDependenciesFromYaml,
  resolveDependencyFile,
  resolvePackageDependencies,
  savePackageAsTypeScript,
  saveToCacheAndOutput
} from 'ts-pkgx'

// Fetch a single package using pkgx.dev
const nodePackage = await fetchPantryPackage('node')
console.log(nodePackage)

// Fetch package with metadata from pantry
const packageWithMeta = await fetchPantryPackageWithMetadata('node', {
  timeout: 30000,
  debug: false
})

// Fetch and save all packages
const savedPackages = await fetchAndSaveAllPackages({
  timeout: 120000,
  outputDir: 'src/packages',
  concurrency: 8
})
console.log(`Saved ${savedPackages.length} packages`)

// Save package as TypeScript file
if (packageWithMeta) {
  const filePath = savePackageAsTypeScript('src/packages', 'node', packageWithMeta.packageInfo)
  console.log(`Saved to ${filePath}`)
}

// Resolve dependency files and transitive dependencies
const depFiles = findDependencyFiles('./my-project')
for (const file of depFiles) {
  const result = await resolveDependencyFile(file, {
    pantryDir: 'src/pantry',
    packagesDir: 'src/packages',
    maxDepth: 10,
    verbose: true,
  })

  console.log(`${file}: Found ${result.uniquePackages.length} unique packages`)
  if (result.conflicts.length > 0) {
    console.log(`Resolved ${result.conflicts.length} version conflicts`)
  }
}

// Launchpad Integration API - Resolve dependencies for package managers
const launchpadResult = await resolveDependencies('./deps.yaml', {
  targetOs: 'darwin',
  includeOsSpecific: true,
  maxDepth: 10,
  verbose: false
})

console.log(`Launchpad: Installing ${launchpadResult.totalCount} packages`)
console.log(`Direct dependencies: ${launchpadResult.directCount}`)
console.log(`Version conflicts resolved: ${launchpadResult.conflicts.length}`)

// Install commands ready for use (both use direct deps only)
console.log('Launchpad:', launchpadResult.launchpadCommand)
console.log('pkgx:', launchpadResult.pkgxCommand)

// Resolve from YAML string
const yamlContent = `
global: true
dependencies:
  bun.sh: ^1.2.16
  gnu.org/grep: ^3.12.0
`
const yamlResult = await resolveDependenciesFromYaml(yamlContent)

// Resolve single package dependencies
const grepDeps = await resolvePackageDependencies('gnu.org/grep')
console.log(`grep has ${grepDeps.length} total dependencies`)

// Get PHP versions for CI/CD workflows
const { getPhpVersionsForWorkflow } = await import('ts-pkgx')
const workflowVersions = getPhpVersionsForWorkflow()
console.log('Latest PHP versions for CI:', workflowVersions)
// Output: ['8.4.11', '8.3.24', '8.2.29', '8.1.32']

TypeScript Types

ts-pkgx provides comprehensive TypeScript types for all packages in the pkgx.dev ecosystem, enabling you to work in a fully typed environment with extensive type safety features:

import type {
  LaunchpadInstallResult, // Launchpad API result type
  LaunchpadPackage, // Individual package in Launchpad result
  LaunchpadResolverOptions, // Launchpad resolution options
  PackageFetchOptions, // Options for fetching packages
  Packages, // Type alias for Pantry
  Pantry, // Complete pantry type with all packages
  PkgxPackage // Package information interface
} from 'ts-pkgx'
import {
  aliases, // Package aliases mapping
  pantry // Access to all packages with full type safety
} from 'ts-pkgx'

// Access packages with full type safety using domain-based properties
const nodePackage = pantry.nodejs_org
const pythonPackage = pantry.python_org
const goPackage = pantry.go_dev
const bunPackage = pantry.bun_sh

// Alternative access using underscored domain names
const curlPackage = pantry.curl_se
const gitPackage = pantry.git_scm_org

// All package properties are fully typed
console.log(nodePackage.name) // string: 'nodejs.org'
console.log(nodePackage.domain) // string: 'nodejs.org'
console.log(nodePackage.description) // string: package description
console.log(nodePackage.programs) // readonly string[]: ['node', 'npm', 'npx']
console.log(nodePackage.versions) // readonly string[]: available versions
console.log(nodePackage.installCommand) // string: 'launchpad install nodejs.org'
console.log(nodePackage.companions) // readonly string[]: companion packages
console.log(nodePackage.dependencies) // readonly string[]: dependencies

// Type-safe access with aliases
const alias = aliases.node // 'nodejs.org'
const packageByAlias = pantry[aliases.node as keyof Pantry]

// Package fetching with typed options
const fetchOptions: PackageFetchOptions = {
  timeout: 30000,
  outputDir: 'src/packages',
  cacheDir: '.cache',
  debug: false,
  concurrency: 8
}

The type system includes:

• Comprehensive type safety: All package properties and operations are type-checked
• Pantry types: Full type definitions for all packages in the pkgx ecosystem
• Package interfaces: Detailed typed interfaces for package metadata
• Fetch options: Type-safe configuration for package fetching operations
• Domain mapping: Both domain names and underscored variants for flexible access
• Alias support: Type-safe alias resolution for common package names
• Auto-completion: Full IntelliSense support in your IDE for all 1600+ packages

Running Tests

bun test

Development

Running Tests

bun test

Building the Package

bun run build

Updating Packages

# Update the local pantry cache
bun ./bin/cli.ts update-pantry

# Regenerate all package TypeScript files
bun ./bin/cli.ts fetch --all

# Generate documentation
bun ./bin/cli.ts generate-docs

Changelog

Please see our releases page for information on changes.

Contributing

Please see CONTRIBUTING for details.

Community

For help or discussion:

• Discussions on GitHub
• Join the Stacks Discord Server

Postcardware

"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Credits

• Max Howell - for creating pkgx and Homebrew
• pkgm & dev - thanks for the inspiration
• Chris Breuer
• All Contributors

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙