### Basic Custom Addon Example

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/addons.md

A basic example demonstrating how to create a custom addon with postprocess and beforeWrite hooks. It shows how to integrate a custom addon into the CheckPackages function.

```typescript
import { CheckPackages } from 'taze'

const customAddon = {
  postprocess(pkg, options) {
    console.log(`Processing ${pkg.name}`)
  },
  beforeWrite(pkg, options) {
    console.log(`Writing ${pkg.name}`)
  }
}

await CheckPackages(
  {
    cwd: process.cwd(),
    addons: [customAddon],
  }
)
```

--------------------------------

### Example Usage of Version Filtering

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/resolves.md

Demonstrates how to use `getFilteredVersions` to get an array of available versions and `getVersionOfRange` to find the latest minor update. Ensure you have the necessary imports and a resolved dependency object.

```typescript
import { getVersionOfRange, getFilteredVersions } from 'taze'

const dep = // ... resolved dependency
const filtered = getFilteredVersions(dep, options)
console.log(`Available versions: ${filtered.length}`)

const minorUpdate = getVersionOfRange(dep, 'minor', options)
if (minorUpdate) {
  console.log(`Latest minor: ${minorUpdate}`)
}
```

--------------------------------

### Run Taze CLI

Source: https://github.com/antfu-collective/taze/blob/main/README.md

Execute Taze to check for dependency updates. No installation is required.

```bash
npx taze
```

--------------------------------

### beforeWrite Hook Example

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/addons.md

Implement the beforeWrite hook to perform actions immediately before resolved dependencies are written to a file. This example shows how to validate package data.

```typescript
const addon = {
  beforeWrite(pkg, options) {
    // Ensure specific field formatting
    if (pkg.raw.name && !pkg.raw.version) {
      throw new Error(`${pkg.name} missing version field`)
    }
    
    console.log(`Writing ${pkg.name}...`)
  }
}
```

--------------------------------

### Usage Example for CheckPackages

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/CheckPackages.md

Demonstrates how to use the CheckPackages function with various options and callbacks to check and log dependency updates. It shows how to access the results and iterate through resolved package changes.

```typescript
import { CheckPackages } from 'taze'

const result = await CheckPackages(
  {
    cwd: process.cwd(),
    recursive: true,
    mode: 'minor',
    concurrency: 10,
    write: false,
  },
  {
    afterPackagesLoaded(pkgs) {
      console.log(`Found ${pkgs.length} packages`)
    },
    beforePackageStart(pkg) {
      console.log(`Checking: ${pkg.name}`)
    },
    onDependencyResolved(pkgName, depName, progress, total) {
      console.log(`[${progress}/${total}] ${depName}`)
    },
    beforePackageWrite(pkg) {
      // Prevent automatic write, inspect changes first
      return false
    },
    afterPackageEnd(pkg) {
      const updates = pkg.resolved.filter(d => d.update)
      console.log(`${pkg.name}: ${updates.length} updates available`)
    },
  }
)

// Access resolved packages
for (const pkg of result.packages) {
  for (const dep of pkg.resolved) {
    if (dep.update) {
      console.log(
        `${pkg.name}: ${dep.name} ${dep.currentVersion} → ${dep.targetVersion} (${dep.diff})`
      )
    }
  }
}
```

--------------------------------

### Load Package Metadata Example

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/package-io.md

Demonstrates how to use the loadPackage function to load metadata from 'pnpm-workspace.yaml' and filter dependencies. It then iterates over the loaded package metadata and logs their types and names.

```typescript
import { loadPackage } from 'taze'

const pkgs = await loadPackage(
  'pnpm-workspace.yaml',
  { cwd: process.cwd() },
  (name) => !name.startsWith('@internal/')
)

pkgs.forEach(pkg => {
  console.log(`${pkg.type}: ${pkg.name}`)
})
```

--------------------------------

### Postprocess Hook Example

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/addons.md

Demonstrates using the `postprocess` hook to conditionally skip dependency updates and log update information.

```typescript
const addon = {
  postprocess(pkg, options) {
    // Skip updating specific dependency for this package
    const dep = pkg.resolved.find(d => d.name === 'custom-lib')
    if (dep) {
      dep.update = false
    }
    
    // Log all updates
    pkg.resolved.forEach(dep => {
      if (dep.update) {
        console.log(`${pkg.name}: ${dep.name} → ${dep.targetVersion}`)
      }
    })
  }
}
```

--------------------------------

### Example Usage of getPackageData

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/resolves.md

Demonstrates how to import and use the `getPackageData` function to retrieve the latest version and all available versions of a package.

```typescript
import { getPackageData } from 'taze'

const data = await getPackageData('react', 'npm', process.cwd())
console.log(data.tags.latest) // '18.2.0'
console.log(data.versions)    // ['0.1.0', '0.2.0', ..., '18.2.0']
```

--------------------------------

### Example Usage of resolveDependencies

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/resolves.md

Demonstrates how to use the resolveDependencies function to resolve dependencies for a package. It includes loading the package, setting concurrency options, filtering dependencies, and logging update information.

```typescript
import { resolveDependencies, loadPackage } from 'taze'

const packages = await loadPackage('package.json', { cwd: process.cwd() }, () => true)
const pkg = packages[0]

await resolveDependencies(
  pkg,
  { mode: 'minor', cwd: process.cwd(), concurrency: 5 },
  (dep) => !dep.name.includes('internal'),
  (pkgName, depName, progress, total) => {
    console.log(`[${progress}/${total}] ${depName}`)
  }
)

pkg.resolved.forEach(dep => {
  if (dep.update) {
    console.log(`${dep.name}@${dep.currentVersion} → ${dep.targetVersion}`)
  }
})
```

--------------------------------

### getMaxSatisfying Usage Examples

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/versions.md

Demonstrates how to use the getMaxSatisfying function with different modes to select versions from a list.

```typescript
import { getMaxSatisfying } from 'taze'

const versions = ['1.0.0', '1.1.0', '1.2.0', '2.0.0', '2.1.0']
const tags = { latest: '2.1.0', next: '3.0.0-beta' }

console.log(getMaxSatisfying(versions, '^1.2.0', 'major', tags))
// '2.1.0'

console.log(getMaxSatisfying(versions, '^1.2.0', 'minor', tags))
// '1.2.0'

console.log(getMaxSatisfying(versions, '^1.2.0', 'patch', tags))
// '1.2.0'

console.log(getMaxSatisfying(versions, '^1.2.0', 'latest', tags))
// '2.1.0' (from tags.latest)

console.log(getMaxSatisfying(versions, '^1.2.0', 'newest', tags))
// '3.0.0-beta' (last version)
```

--------------------------------

### Define Taze Configuration

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/configuration.md

Use `defineConfig` in your `taze.config.js` or `taze.config.ts` file for type-safe configuration and IDE autocompletion. This example shows how to configure package bumping, caching, installation, and monorepo specific options.

```typescript
import { defineConfig } from 'taze'

export default defineConfig({
  // ignore packages from bumping
  exclude: ['webpack'],
  // fetch latest package info from registry without cache
  force: true,
  // write to package.json
  write: true,
  // run package manager install after bumping
  install: true,
  // ignore paths for looking for package.json in monorepo
  ignorePaths: ['**/node_modules/**', '**/test/**'],
  // ignore package.json in other workspaces
  ignoreOtherWorkspaces: true,
  // override bumping mode for each package
  packageMode: {
    'typescript': 'major',
    'unocss': 'ignore',
    '/vue/': 'latest'
  },
  // exclude from maturity period filter
  maturityPeriodExclude: ['react', '@myorg/*'],
  // disable checking specific fields
  depFields: {
    overrides: false
  }
})
```

--------------------------------

### JSON Configuration for Taze

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/configuration.md

An example of Taze configuration using a JSON file, specifying exclusions, update modes, and dependency field overrides.

```json
{
  ".tazerc": {
    "exclude": ["webpack"],
    "force": true,
    "write": true,
    "recursive": true,
    "maturityPeriod": 7,
    "maturityPeriodExclude": ["react"],
    "packageMode": {
      "typescript": "major",
      "jest": "ignore"
    },
    "depFields": {
      "overrides": false
    }
  }
}
```

--------------------------------

### Basic Taze Configuration

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/configuration.md

A basic Taze configuration file to force updates, write changes, and install dependencies.

```typescript
// taze.config.ts
import { defineConfig } from 'taze'

export default defineConfig({
  force: true,
  write: true,
  install: true,
})
```

--------------------------------

### getVersionOfRange

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Gets the version that satisfies a given version range. Returns the version string or undefined.

```APIDOC
## getVersionOfRange

### Description
Get version matching range.

### Returns
`string | undefined`
```

--------------------------------

### Apply Updates and Write Changes

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/README.md

Applies detected package updates and writes the changes to the package.json files. It also installs the updated dependencies. Requires 'taze' to be imported.

```typescript
const result = await CheckPackages({
  cwd: process.cwd(),
  write: true,
  install: true,
})
```

--------------------------------

### Get and Set Nested Dependencies by Path

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/dependencies.md

Use `getByPath` to retrieve nested dependency data and `setByPath` to add or update properties using dot notation. Ensure the path is a string, and for `setByPath`, provide the value to be set.

```typescript
import { getByPath, setByPath } from 'taze'

const pkg = {
  dependencies: { react: '^18.0.0' },
  devDependencies: { typescript: '^5.0.0' }
}

const deps = getByPath(pkg, 'dependencies')
console.log(deps) // { react: { version: '^18.0.0', parents: [] } }

setByPath(pkg, 'pnpm.overrides', { webpack: '^5.0.0' })
// pkg.pnpm.overrides = { webpack: '^5.0.0' }
```

--------------------------------

### Load Packages with Discovery Options

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/package-io.md

Loads packages from the filesystem using specified discovery options. Configure recursive search, ignore paths, and include/exclude package names.

```typescript
import { loadPackages } from 'taze'

const pkgs = await loadPackages({
  cwd: '/my/project',
  recursive: true,
  ignorePaths: ['**/node_modules/**', '**/test/**'],
  include: ['react', 'typescript'],
  exclude: ['webpack'],
})

for (const pkg of pkgs) {
  console.log(`${pkg.name} at ${pkg.relative}`)
  console.log(`  Dependencies: ${pkg.deps.length}`)
}
```

--------------------------------

### getVersionOfTag

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Gets the version associated with a specific distribution tag. Returns the version string or undefined.

```APIDOC
## getVersionOfTag

### Description
Get version for dist-tag.

### Returns
`string | undefined`
```

--------------------------------

### Include Peer Dependencies

Source: https://github.com/antfu-collective/taze/blob/main/README.md

Enable the update process for peer dependencies by passing the --peer option.

```bash
taze --peer
```

--------------------------------

### getMaxSatisfying

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Gets the maximum version that satisfies a given version range. Returns the version string or undefined.

```APIDOC
## getMaxSatisfying

### Description
Get max version matching mode.

### Returns
`string | undefined`
```

--------------------------------

### Fetch Package with Error Handling

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/packument.md

Demonstrates how to use the `fetchPackage` function and handle potential errors, including network issues and cases where the package does not exist or returns an error.

```typescript
import { fetchPackage } from 'taze'

try {
  const data = await fetchPackage('non-existent-package-xyz')
  if (data.error) {
    console.error('Package fetch error:', data.error)
    // data.versions will be empty []
    // data.tags will be {}
  } else {
    console.log('Success:', data.versions.length, 'versions')
  }
} catch (error) {
  // Network error or other exception
  console.error('Unexpected error:', error)
}
```

--------------------------------

### loadBunWorkspace

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads Bun workspace configuration. Returns a promise that resolves with workspace metadata.

```APIDOC
## loadBunWorkspace

### Description
Load bun workspace.

### Returns
`Promise<BunWorkspaceMeta[]>`
```

--------------------------------

### Parse Dependencies from Package

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/dependencies.md

Parses dependencies from a package object for a specific dependency type and filters them for updates. Ensure 'taze' is installed and imported.

```typescript
import { parseDependencies, readJSON } from 'taze'

const pkg = await readJSON('/path/to/package.json')
const deps = parseDependencies(
  pkg,
  'dependencies',
  (name) => !name.startsWith('@internal/')
)

deps.forEach(dep => {
  console.log(`${dep.name}@${dep.currentVersion} (update: ${dep.update})`)
})
```

--------------------------------

### Use Taze Addons in Code

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/addons.md

Demonstrates how to integrate custom addons when using Taze programmatically.

```typescript
import { CheckPackages } from 'taze'

const addon1 = { /* ... */ }
const addon2 = { /* ... */ }

const result = await CheckPackages(
  { cwd: process.cwd() },
  { /* callbacks */ }
)
```

--------------------------------

### Load Bun Workspace Catalogs

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/workspace-support.md

Loads Bun workspace catalogs from package.json. It processes configurations in workspaces.catalog and workspaces.catalogs, and requires a bun.lockb or bun.lock file to exist.

```typescript
export async function loadBunWorkspace(
  relative: string,
  options: CommonOptions,
  shouldUpdate: (name: string) => boolean,
  existingRaw?: Record<string, unknown>
): Promise<BunWorkspaceMeta[]>
```

```typescript
import { loadBunWorkspace } from 'taze'

const workspaces = await loadBunWorkspace(
  'package.json',
  { cwd: process.cwd() },
  () => true
)

workspaces.forEach(ws => {
  console.log(`Bun workspace: ${ws.type}`)
})
```

--------------------------------

### Taze Project File Structure

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/MANIFEST.md

Illustrates the directory layout of the Taze project, showing the purpose of each file and subdirectory within the output folder.

```tree
/output/
├── README.md                          # Overview and getting started
├── INDEX.md                           # Complete function/type index
├── types.md                           # All type definitions
├── configuration.md                   # Config file format and options
├── errors.md                          # Error catalog and handling
├── MANIFEST.md                        # This file
└── api-reference/
    ├── CheckPackages.md               # Main API function
    ├── package-io.md                  # Package file I/O
    ├── dependencies.md                # Dependency parsing
    ├── resolves.md                    # Registry resolution
    ├── versions.md                    # Version utilities
    ├── packument.md                   # Registry fetching
    ├── workspace-support.md           # Monorepo support
    └── addons.md                      # Extension system
```

--------------------------------

### Fetch npm Package Metadata

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/packument.md

Fetches npm package metadata with timeout protection. Use this to get information about a package, including its versions, tags, and deprecation status.

```typescript
export async function fetchPackage(
  spec: string,
  force?: boolean,
  cwd?: string
): Promise<PackageData>
```

```typescript
interface PackageData {
  tags: Record<string, string>      // { latest: '1.2.3', next: '2.0.0-beta' }
  versions: string[]                // All available versions
  time?: Record<string, string>     // ISO timestamps of releases
  nodeSemver?: Record<string, string> // Node.js engine requirements
  error?: Error | string            // Network or fetch error
  provenance?: Record<string, boolean | 'trustedPublisher'>
  deprecated?: Record<string, string | boolean>
  integrity?: Record<string, string> // SRI hashes for packageManager field
}
```

```typescript
import { fetchPackage } from 'taze'

const data = await fetchPackage('react', false, process.cwd())
console.log(data.tags.latest)      // '18.2.0'
console.log(data.versions.length)  // ~500
console.log(data.deprecated)       // { '0.1.0': 'Very old version' }
```

--------------------------------

### loadPackages

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/package-io.md

Loads all packages from the filesystem based on discovery options. It discovers package.json files (and variants like package.yaml), searches subdirectories recursively if specified, and applies include/exclude filters.

```APIDOC
## loadPackages

### Description
Loads all packages from the filesystem based on discovery options. It discovers package.json files (and variants like package.yaml), searches subdirectories recursively if specified, and applies include/exclude filters.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
`export async function loadPackages(options: CommonOptions): Promise<PackageMeta[]>`

### Parameters
- **options** (`CommonOptions`) - Required - Options controlling discovery: `cwd`, `recursive`, `ignorePaths`, `ignoreOtherWorkspaces`, `include`, `exclude`

### Return Type
`PackageMeta[]` — Array of packages discovered on disk. Each entry includes type-specific metadata (package.json content, pnpm workspace context, etc.)

### Behavior
- Discovers package.json files (and variants like package.yaml)
- If `recursive: true`, searches all subdirectories matching ignore patterns
- Returns both root package and workspace packages
- Applies include/exclude filters to package names
- Automatically detects workspace types (pnpm, bun, yarn)

### Example
```typescript
import { loadPackages } from 'taze'

const pkgs = await loadPackages({
  cwd: '/my/project',
  recursive: true,
  ignorePaths: ['**/node_modules/**', '**/test/**'],
  include: ['react', 'typescript'],
  exclude: ['webpack'],
})

for (const pkg of pkgs) {
  console.log(`${pkg.name} at ${pkg.relative}`)
  console.log(`  Dependencies: ${pkg.deps.length}`)
}
```
```

--------------------------------

### loadPackages

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads multiple packages. Details are available in './io/packages'.

```APIDOC
## loadPackages

### Description
Loads multiple packages. Details are available in './io/packages'.

### Signature
```typescript
function loadPackages(...args: any[])
```

### Usage
```typescript
import { loadPackages } from 'taze'

const pkgs = loadPackages(...)
```
```

--------------------------------

### Define Taze Addon in Configuration

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/addons.md

Shows how to import and use a custom addon within the Taze configuration file.

```typescript
import { defineConfig } from 'taze'

const myAddon = {
  postprocess(pkg) {
    // custom logic
  }
}

export default defineConfig({
  addons: [myAddon],
})
```

--------------------------------

### Get Prefixed Version

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/versions.md

Extracts the version prefix from a 'current' version string and applies it to a 'target' version string. Returns null on error. Useful for updating dependencies while maintaining their versioning strategy.

```typescript
import { getPrefixedVersion } from 'taze'

// Current has ^, apply to target
console.log(getPrefixedVersion('^1.2.0', '1.3.0'))  // '^1.3.0'

// Current has ~, apply to target
console.log(getPrefixedVersion('~1.2.0', '1.2.3'))  // '~1.2.3'

// Current is exact, apply to target
console.log(getPrefixedVersion('1.2.0', '1.2.1'))   // '1.2.1'

// Current is wildcard
console.log(getPrefixedVersion('*', '1.2.0'))       // '*'
```

--------------------------------

### loadBunWorkspace

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/workspace-support.md

Loads Bun workspace catalogs from package.json workspaces. It processes configurations only if a Bun lock file exists and returns metadata for both main package.json and workspace catalogs.

```APIDOC
## loadBunWorkspace

### Description
Loads Bun workspace catalogs from `package.json` workspaces. This function only processes configurations if a `bun.lockb` or `bun.lock` file exists. It detects Bun workspace catalogs in `workspaces.catalog` and `workspaces.catalogs` and returns metadata for both the main `package.json` and any workspace catalogs.

### Signature
```typescript
export async function loadBunWorkspace(
  relative: string,
  options: CommonOptions,
  shouldUpdate: (name: string) => boolean,
  existingRaw?: Record<string, unknown>
): Promise<BunWorkspaceMeta[]>
```

### Parameters

- **relative** (`string`): Path to the `package.json` file containing workspace definitions.
- **options** (`CommonOptions`): Common options for the operation.
- **shouldUpdate** (`(name: string) => boolean`): A predicate function to filter which workspaces to update.
- **existingRaw** (`Record<string, unknown>`, Optional): A pre-read `package.json` object to avoid re-reading the file.

### Return Type

`BunWorkspaceMeta[]` — An array of Bun workspace metadata entries.

### Example

```typescript
import { loadBunWorkspace } from 'taze'

const workspaces = await loadBunWorkspace(
  'package.json',
  { cwd: process.cwd() },
  () => true
)

workspaces.forEach(ws => {
  console.log(`Bun workspace: ${ws.type}`)
})
```
```

--------------------------------

### Stable Releases with Maturity Period

Source: https://github.com/antfu-collective/taze/blob/main/README.md

Use the 'stable' mode along with --maturity-period to ensure only stable releases are considered after the specified cooldown period.

```bash
taze stable --maturity-period 14
```

--------------------------------

### loadPackages

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Discovers and loads all packages. Returns a promise that resolves with package metadata.

```APIDOC
## loadPackages

### Description
Discover and load all packages.

### Returns
`Promise<PackageMeta[]>`
```

--------------------------------

### loadPackage

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads a single package. Details are available in './io/packages'.

```APIDOC
## loadPackage

### Description
Loads a single package. Details are available in './io/packages'.

### Signature
```typescript
function loadPackage(...args: any[])
```

### Usage
```typescript
import { loadPackage } from 'taze'

const pkg = loadPackage(...)
```
```

--------------------------------

### fetchPackage

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Fetches package metadata from the npm registry. Returns a promise that resolves with package data.

```APIDOC
## fetchPackage

### Description
Fetch npm package metadata.

### Returns
`Promise<PackageData>`
```

--------------------------------

### fetchPackage

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/packument.md

Fetches npm package metadata with timeout protection. It uses `get-npm-meta` and caches results in-memory and on disk for 30 minutes, with a 5-second timeout per request.

```APIDOC
## fetchPackage

### Description
Fetches npm package metadata with timeout protection.

### Method
`async`

### Parameters
#### Path Parameters
- **spec** (string) - Required - Package specifier (e.g., 'react', '@vue/core', 'typescript')
- **force** (boolean) - Optional - Bypass npm cache and fetch fresh data (default: `false`)
- **cwd** (string) - Optional - Working directory for npm config resolution

### Return Type
```typescript
interface PackageData {
  tags: Record<string, string>
  versions: string[]
  time?: Record<string, string>
  nodeSemver?: Record<string, string>
  error?: Error | string
  provenance?: Record<string, boolean | 'trustedPublisher'>
  deprecated?: Record<string, string | boolean>
  integrity?: Record<string, string>
}
```

### Behavior
- Uses `get-npm-meta` to fetch from npm registry
- Caches results in-memory and on disk for 30 minutes
- Includes timeout of 5 seconds per request
- Returns race between fetch and timeout promise

### Throws
- If fetch fails or times out, error is stored in `PackageData.error`
- Promise rejection converted to error object

### Example
```typescript
import { fetchPackage } from 'taze'

const data = await fetchPackage('react', false, process.cwd())
console.log(data.tags.latest)      // '18.2.0'
console.log(data.versions.length)  // ~500
console.log(data.deprecated)       // { '0.1.0': 'Very old version' }
```
```

--------------------------------

### Import Main Taze API

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Use this import path for the main Taze API functions.

```typescript
import { ... } from 'taze'
```

--------------------------------

### loadPackage

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads a single package file by its path. Returns a promise that resolves with package metadata.

```APIDOC
## loadPackage

### Description
Load single package file by path.

### Returns
`Promise<PackageMeta[]>`
```

--------------------------------

### writeBunWorkspace

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/workspace-support.md

Writes resolved dependencies back to the Bun workspace configuration.

```APIDOC
## writeBunWorkspace

### Description
Writes resolved dependencies back to the Bun workspace configuration.

### Signature
```typescript
export async function writeBunWorkspace(
  pkg: BunWorkspaceMeta,
  options: CommonOptions
): Promise<void>
```

### Parameters

- **pkg** (`BunWorkspaceMeta`): The Bun workspace metadata object containing the resolved dependencies to write.
- **options** (`CommonOptions`): Common options for the operation.
```

--------------------------------

### Import Core Taze API and Utilities

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/README.md

Import the main API functions, package I/O utilities, dependency parsing functions, and resolution helpers from the 'taze' package. This snippet also re-exports various types for convenience.

```typescript
import {
  // Main API
  CheckPackages,
  defineConfig,
  
  // Package I/O
  loadPackage,
  loadPackages,
  writePackage,
  
  // Dependencies
  parseDependencies,
  parseDependency,
  dumpDependencies,
  
  // Resolution
  resolveDependency,
  resolveDependencies,
  resolvePackage,
  getPackageData,
  
  // Types (re-exported)
  CheckOptions,
  CommonOptions,
  PackageMeta,
  ResolvedDepChange,
  RawDep,
  DiffType,
  RangeMode,
  DepType,
  // ... and many more
} from 'taze'
```

--------------------------------

### Implement Safe Error Handling in Addon

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/addons.md

Illustrates how to use try-catch blocks within an addon's postprocess hook to handle potential errors gracefully.

```typescript
const safeAddon = {
  async postprocess(pkg, options) {
    try {
      // Risky operation
    } catch (error) {
      console.error(`Addon error in ${pkg.name}:`, error)
      // Optionally suppress error or transform it
    }
  }
}
```

--------------------------------

### Apply Version Range Prefix

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/versions.md

Applies a specified prefix to a version string. Returns null if either the version or prefix is null. Useful for setting version constraints.

```typescript
import { applyVersionRangePrefix } from 'taze'

console.log(applyVersionRangePrefix('1.2.3', '^'))   // '^1.2.3'
console.log(applyVersionRangePrefix('1.2.3', '~'))   // '~1.2.3'
console.log(applyVersionRangePrefix('1.2.3', '>='))  // '>=1.2.3'
console.log(applyVersionRangePrefix('1.2.3', '*'))   // '*'
console.log(applyVersionRangePrefix('1.2.3', null))  // null
```

--------------------------------

### Load pnpm Workspace Catalogs and Overrides

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/workspace-support.md

Loads pnpm workspace catalogs and overrides from `pnpm-workspace.yaml`. Use this to read workspace definitions and dependencies.

```typescript
export async function loadPnpmWorkspace(
  relative: string,
  options: CommonOptions,
  shouldUpdate: (name: string) => boolean
): Promise<PnpmWorkspaceMeta[]>
```

```typescript
import { loadPnpmWorkspace } from 'taze'

const workspaces = await loadPnpmWorkspace(
  'pnpm-workspace.yaml',
  { cwd: process.cwd() },
  (name) => true
)

workspaces.forEach(ws => {
  console.log(`${ws.name}: ${ws.deps.length} packages`)
})
// Output:
// pnpm-catalog:default: 15 packages
// pnpm-catalog:web: 8 packages
// pnpm-workspace:overrides: 3 packages
```

--------------------------------

### writePackage

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Writes package information. Details are available in './io/packages'.

```APIDOC
## writePackage

### Description
Writes package information. Details are available in './io/packages'.

### Signature
```typescript
function writePackage(...args: any[])
```

### Usage
```typescript
import { writePackage } from 'taze'

writePackage(...)
```
```

--------------------------------

### Taze Configuration File

Source: https://github.com/antfu-collective/taze/blob/main/README.md

Configure Taze options using a 'taze.config.js' file for persistent settings.

```javascript
import { defineConfig } from 'taze'

export default defineConfig({
  // ignore packages from bumping
  exclude: [
    'webpack'
  ],
  // fetch latest package info from registry without cache
  force: true,
  // write to package.json
  write: true,
  // run `npm install` or `yarn install` right after bumping
  install: true,
  // ignore paths for looking for package.json in monorepo
  ignorePaths: [
    '**/node_modules/**',
    '**/test/**',
  ],
  // ignore package.json that in other workspaces (with their own .git,pnpm-workspace.yaml,etc.)
  ignoreOtherWorkspaces: true,
  // override with different bumping mode for each package
  packageMode: {
    'typescript': 'major',
    'unocss': 'ignore',
    // regex starts and ends with '/' 
    '/vue/': 'latest'
  },
  // exclude packages from the maturity period filter
  maturityPeriodExclude: [
    'react',
    '@myorg/*',
  ],
  // disable checking for "overrides" package.json field
  depFields: {
    overrides: false
  }
})
```

--------------------------------

### defineConfig

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Helper function for creating typed configurations. It returns a partial configuration object.

```APIDOC
## defineConfig

### Description
Helper for typed configuration.

### Returns
`Partial<CheckOptions>`
```

--------------------------------

### Fetch Package Data from Registry

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/resolves.md

Fetches package metadata from npm or JSR registries with in-memory caching for 30 minutes. Results are also cached to a file at `~/.taze/cache.json` unless disabled. Pass `force: true` in options to bypass the cache.

```typescript
export async function getPackageData(
  name: string,
  protocol?: Protocol,
  cwd?: string
): Promise<PackageData>
```

--------------------------------

### Configure Cache TTL and Path

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/packument.md

Defines the cache time-to-live (TTL) as 30 minutes and specifies the temporary directory path for storing cache files.

```typescript
const cacheTTL = 30 * 60_000 // 30 minutes
const cachePath = os.tmpdir()/taze/cache.json
```

--------------------------------

### loadPackage

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/package-io.md

Loads a single package file by its relative path, returning an array of package metadata. It handles different package file types and respects provided options and update predicates.

```APIDOC
## loadPackage

### Description
Loads a single package file by relative path. It detects the package type, handles workspace configurations, and respects dependency field and update predicate options.

### Method
`export async function loadPackage(...)`

### Parameters
#### Path Parameters
- **relative** (`string`) - Yes - Relative path to package file (e.g., 'package.json' or 'packages/ui/package.json')
- **options** (`CommonOptions`) - Yes - Common options including cwd, depFields, peer settings
- **shouldUpdate** (`(name: string) => boolean`) - Yes - Predicate function to determine if a dependency should be included in updates

### Return Type
`PackageMeta[]` — Array of metadata objects. For most files returns single entry, but workspace files (pnpm-workspace.yaml) may return multiple entries for catalogs.

### Behavior
- Detects package type by file extension/name
- For pnpm-workspace.yaml: creates entries for each catalog and overrides
- For package.json: checks for Bun workspace catalogs, returns both Bun and package.json metadata
- For package.yaml: loads YAML format with preserved formatting
- Respects `depFields` option to include/exclude specific dependency types
- Applies `shouldUpdate` predicate to populate `deps[].update` field

### Example
```typescript
import { loadPackage } from 'taze'

const pkgs = await loadPackage(
  'pnpm-workspace.yaml',
  { cwd: process.cwd() },
  (name) => !name.startsWith('@internal/')
)

pkgs.forEach(pkg => {
  console.log(`${pkg.type}: ${pkg.name}`)
})
```
```

--------------------------------

### loadCache

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads the cache from disk. Returns a promise that resolves when the cache is loaded.

```APIDOC
## loadCache

### Description
Load cache from disk.

### Returns
`Promise<void>`
```

--------------------------------

### Write Bun Workspace Configuration

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/workspace-support.md

Writes resolved dependencies back to the Bun workspace configuration.

```typescript
export async function writeBunWorkspace(
  pkg: BunWorkspaceMeta,
  options: CommonOptions
): Promise<void>
```

--------------------------------

### CheckPackages

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Main API for discovering and resolving packages. It returns a promise that resolves with package metadata.

```APIDOC
## CheckPackages

### Description
Main API for discovering and resolving packages.

### Returns
`Promise<{ packages: PackageMeta[] }>`
```

--------------------------------

### Bun Workspaces Catalog Configuration

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/workspace-support.md

Specify shared package versions using the `catalog` field within the `workspaces` object in `package.json` for Bun projects.

```json
{
  "workspaces": ["packages/*"],
  "catalog": {
    "react": "^18.0.0"
  }
}
```

--------------------------------

### applyVersionRangePrefix

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/versions.md

Applies a specified range prefix to a given version string. It handles null inputs gracefully, returning null if either the version or prefix is null.

```APIDOC
## applyVersionRangePrefix

### Description
Applies a range prefix to a version number.

### Method
Not applicable (function signature provided)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Function Signature
```typescript
export function applyVersionRangePrefix(version: string | null, prefix: string | null): string | null
```

### Parameters
- **version** (`string | null`) - Required - Version to prefix (e.g., '1.2.3')
- **prefix** (`string | null`) - Required - Prefix to apply (e.g., '^', '~', '>=')

### Return Type
`string | null` — Prefixed version, or null if either input is null.

### Example
```typescript
import { applyVersionRangePrefix } from 'taze'

console.log(applyVersionRangePrefix('1.2.3', '^'))   // '^1.2.3'
console.log(applyVersionRangePrefix('1.2.3', '~'))   // '~1.2.3'
console.log(applyVersionRangePrefix('1.2.3', '>='))  // '>=1.2.3'
console.log(applyVersionRangePrefix('1.2.3', '*'))   // '*'
console.log(applyVersionRangePrefix('1.2.3', null))  // null
```
```

--------------------------------

### Import Taze CLI API

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Use this import path to access Taze's command-line interface functionalities.

```typescript
import { ... } from 'taze/cli'
```

--------------------------------

### Taze Package Root Exports

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Lists the main exports available from the Taze package root. These are the primary entry points for using Taze programmatically.

```typescript
// src/index.ts exports:
export { CheckPackages } from './api/check'
export { dumpDependencies, parseDependencies } from './io/dependencies'
export { loadPackage, loadPackages, writePackage } from './io/packages'
export { resolveDependencies, resolveDependency, resolvePackage } from './io/resolves'
export * from './types'
export function defineConfig(config: Partial<CheckOptions>)
```

--------------------------------

### getPrefixedVersion

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/versions.md

Extracts the prefix from a current version string and applies it to a target version string. Returns the prefixed target version or null if an error occurs.

```APIDOC
## getPrefixedVersion

### Description
Extracts prefix from current version and applies it to target version.

### Method
Not applicable (function signature provided)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Function Signature
```typescript
export function getPrefixedVersion(current: string, target: string): string | null
```

### Parameters
- **current** (`string`) - Required - Current version (e.g., '^1.2.0')
- **target** (`string`) - Required - Target version to apply prefix to (e.g., '1.3.0')

### Return Type
`string | null` — Target version with current's prefix applied, or null on error.

### Behavior
1. Extracts prefix from current version
2. Applies prefix to target version
3. Returns prefixed target

### Example
```typescript
import { getPrefixedVersion } from 'taze'

// Current has ^, apply to target
console.log(getPrefixedVersion('^1.2.0', '1.3.0'))  // '^1.3.0'

// Current has ~, apply to target
console.log(getPrefixedVersion('~1.2.0', '1.2.3'))  // '~1.2.3'

// Current is exact, apply to target
console.log(getPrefixedVersion('1.2.0', '1.2.1'))   // '1.2.1'

// Current is wildcard
console.log(getPrefixedVersion('*', '1.2.0'))       // '*'
```
```

--------------------------------

### loadPnpmWorkspace

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads pnpm-workspace.yaml. Returns a promise that resolves with workspace metadata.

```APIDOC
## loadPnpmWorkspace

### Description
Load pnpm-workspace.yaml.

### Returns
`Promise<PnpmWorkspaceMeta[]>`
```

--------------------------------

### loadPackageYAML

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads package.yaml. Returns a promise that resolves with package metadata.

```APIDOC
## loadPackageYAML

### Description
Load package.yaml.

### Returns
`Promise<PackageMeta[]>`
```

--------------------------------

### loadPnpmWorkspace

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/workspace-support.md

Loads pnpm workspace catalogs and overrides from `pnpm-workspace.yaml`. It parses the YAML file and creates metadata entries for different sections like 'catalog', 'catalogs', and 'overrides'.

```APIDOC
## loadPnpmWorkspace

### Description
Loads pnpm workspace catalogs and overrides from `pnpm-workspace.yaml`.

### Method
`loadPnpmWorkspace(relative: string, options: CommonOptions, shouldUpdate: (name: string) => boolean): Promise<PnpmWorkspaceMeta[]>`

### Parameters
#### Path Parameters
- **relative** (string) - Required - Path to pnpm-workspace.yaml
#### Query Parameters
- **options** (CommonOptions) - Required - Common options including cwd
- **shouldUpdate** ((name: string) => boolean) - Required - Filter predicate for versions

### Return Type
`PnpmWorkspaceMeta[]` — Array of workspace metadata entries, one per catalog, one per overrides section.

### Behavior
- Parses YAML using `pnpm-workspace-yaml` library
- Creates entry for `catalog` section if present
- Creates entry for each named catalog in `catalogs` section
- Creates entry for `overrides` section if present
- All entries are marked as private

### Example
```typescript
import { loadPnpmWorkspace } from 'taze'

const workspaces = await loadPnpmWorkspace(
  'pnpm-workspace.yaml',
  { cwd: process.cwd() },
  (name) => true
)

workspaces.forEach(ws => {
  console.log(`${ws.name}: ${ws.deps.length} packages`)
})
// Output:
// pnpm-catalog:default: 15 packages
// pnpm-catalog:web: 8 packages
// pnpm-workspace:overrides: 3 packages
```
```

--------------------------------

### getLatestVersionAvailable

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Checks if a newer version is available and returns it. Returns the latest version string or undefined.

```APIDOC
## getLatestVersionAvailable

### Description
Get latest if newer.

### Returns
`string | undefined`
```

--------------------------------

### Protocol Type Definition

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/types.md

Defines the supported package registry protocols. Use 'npm' for the npm registry and 'jsr' for the JSR registry.

```typescript
type Protocol = 'npm' | 'jsr'
```

--------------------------------

### writeBunWorkspace

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Writes to Bun workspace configuration. Returns a promise that resolves when the operation is complete.

```APIDOC
## writeBunWorkspace

### Description
Write bun workspace.

### Returns
`Promise<void>`
```

--------------------------------

### Run Taze Recursively for Monorepos

Source: https://github.com/antfu-collective/taze/blob/main/README.md

Use the -r flag to enable recursive scanning for monorepos, updating dependencies across subdirectories.

```bash
npx taze -r
```

--------------------------------

### Import Internal Taze Modules (Not Recommended)

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Avoid importing from 'taze/src/...' as these are internal modules and not part of the public API, subject to change without notice.

```typescript
import { ... } from 'taze/src/...'  // Not part of public API
```

--------------------------------

### Accessing Dependency Errors in Taze

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/errors.md

Demonstrates how to iterate through resolved packages and their dependencies to check for and log various types of errors, including registry errors, resolution errors, and version diff calculation failures.

```typescript
import { CheckPackages } from 'taze'

const result = await CheckPackages({ cwd: process.cwd() })

for (const pkg of result.packages) {
  for (const dep of pkg.resolved) {
    // Check package metadata errors
    if (dep.pkgData.error) {
      console.error(`${dep.name}: Registry error: ${dep.pkgData.error}`)
    }
    
    // Check resolution errors
    if (dep.resolveError) {
      console.error(`${dep.name}: Resolution error: ${dep.resolveError}`)
    }
    
    // Check calculation errors
    if (dep.diff === 'error') {
      console.error(`${dep.name}: Version diff calculation failed`)
    }
  }
}
```

--------------------------------

### resolveConfig

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads and merges configuration files with provided options. Returns a promise that resolves with the merged configuration.

```APIDOC
## resolveConfig

### Description
Load and merge config file + options.

### Returns
`Promise<CommonOptions>`
```

--------------------------------

### Check Packages for Updates

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Use `CheckPackages` to find available updates for your project's dependencies. Configure options like `cwd`, `mode`, and `recursive`. Inspect the `packages` array for detailed update information.

```typescript
import { CheckPackages } from 'taze'

// Check for updates
const { packages } = await CheckPackages({
  cwd: process.cwd(),
  mode: 'minor',
  recursive: true,
})

// Inspect results
packages.forEach(pkg => {
  pkg.resolved.forEach(dep => {
    if (dep.update) {
      console.log(`${dep.name}: ${dep.currentVersion} → ${dep.targetVersion}`)
    }
  })
})
```

--------------------------------

### CheckPackages

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Represents a class for checking packages. The specific methods and usage are detailed in './api/check'.

```APIDOC
## CheckPackages

### Description
Represents a class for checking packages. The specific methods and usage are detailed in './api/check'.

### Usage
```typescript
import { CheckPackages } from 'taze'

// Instantiate and use CheckPackages as needed
const checker = new CheckPackages(...)
```
```

--------------------------------

### resolveDependencies

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Resolves dependencies. Details are available in './io/resolves'.

```APIDOC
## resolveDependencies

### Description
Resolves dependencies. Details are available in './io/resolves'.

### Signature
```typescript
function resolveDependencies(...args: any[])
```

### Usage
```typescript
import { resolveDependencies } from 'taze'

const resolved = resolveDependencies(...)
```
```

--------------------------------

### Define PnpmWorkspaceMeta Interface

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/types.md

Interface for pnpm workspace metadata from 'pnpm-workspace.yaml'. Includes raw content and context.

```typescript
interface PnpmWorkspaceMeta extends BasePackageMeta {
  type: 'pnpm-workspace.yaml'
  raw: Record<string, any>
  context: PnpmWorkspaceYaml
}
```

--------------------------------

### Monorepo Package Discovery with Glob

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/workspace-support.md

Use glob patterns to discover package files in a monorepo when recursive mode is enabled. This helps in finding all potential package directories.

```typescript
const yamlPackages = await glob('**/package.yaml', { ...globOptions })
const jsonPackages = await glob('**/package.json', { ...globOptions })
```

--------------------------------

### loadPackageJSON

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Loads package.json specifically. Returns a promise that resolves with package metadata.

```APIDOC
## loadPackageJSON

### Description
Load package.json specifically.

### Returns
`Promise<PackageMeta[]>`
```

--------------------------------

### Taze Dependency Type Shortcuts

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Maps common dependency type names to their short aliases used within Taze configurations.

```typescript
DependenciesTypeShortMap = {
  'packageManager': 'package-manager',
  'dependencies': '',
  'devDependencies': 'dev',
  'peerDependencies': 'peer',
  'optionalDependencies': 'optional',
  'resolutions': 'resolutions',
  'overrides': 'overrides',
  'pnpm.overrides': 'pnpm-overrides',
  'pnpm-workspace': 'pnpm-workspace',
  'bun-workspace': 'bun-workspace',
  'yarn-workspace': 'yarn-workspace',
}
```

--------------------------------

### loadCache

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/api-reference/resolves.md

Loads cached package data from disk. This function is called automatically if the cache is not forced.

```APIDOC
## loadCache

### Description
Loads cached package data from disk. This function is called automatically if the cache is not forced.

### Signature

```typescript
export async function loadCache(): Promise<void>
```
```

--------------------------------

### defineConfig

Source: https://github.com/antfu-collective/taze/blob/main/_autodocs/INDEX.md

Defines the configuration for Taze. Accepts partial CheckOptions to override defaults.

```APIDOC
## defineConfig

### Description
Defines the configuration for Taze. Accepts partial CheckOptions to override defaults.

### Signature
```typescript
function defineConfig(config: Partial<CheckOptions>)
```

### Parameters
* **config** (Partial<CheckOptions>) - An object containing partial configuration options to override the defaults.
```