API Usage

/**
 * Check packages for dependency updates with optional callbacks
 * @param options - Configuration options for the check operation
 * @param callbacks - Optional event callbacks for lifecycle hooks
 * @returns Promise resolving to results with package metadata
 */
function CheckPackages(
  options: CheckOptions,
  callbacks?: CheckEventCallbacks
): Promise<{ packages: PackageMeta[] }>;

interface CheckEventCallbacks {
  /** Called after all packages are loaded but before processing */
  afterPackagesLoaded?: (pkgs: PackageMeta[]) => void;
  /** Called before processing each individual package */
  beforePackageStart?: (pkg: PackageMeta) => void;
  /** Called after processing each individual package */
  afterPackageEnd?: (pkg: PackageMeta) => void;
  /** Called before writing changes to a package (return false to skip) */
  beforePackageWrite?: (pkg: PackageMeta) => boolean | Promise<boolean>;
  /** Called after all packages are processed */
  afterPackagesEnd?: (pkgs: PackageMeta[]) => void;
  /** Called after writing changes to a package */
  afterPackageWrite?: (pkg: PackageMeta) => void;
  /** Called during dependency resolution for progress tracking */
  onDependencyResolved?: (packageName: string | null, depName: string, progress: number, total: number) => void;
}

import { CheckPackages } from "taze";

// Basic usage
const result = await CheckPackages({
  cwd: process.cwd(),
  mode: "minor"
});

// With callbacks for progress tracking
const result = await CheckPackages({
  mode: "patch",
  write: true
}, {
  afterPackagesLoaded: (packages) => {
    console.log(`Processing ${packages.length} packages`);
  },
  onDependencyResolved: (pkg, dep, progress, total) => {
    console.log(`Resolved ${dep} (${progress}/${total})`);
  },
  beforePackageWrite: (pkg) => {
    console.log(`Writing updates to ${pkg.filepath}`);
    return true; // Allow write
  }
});

/**
 * Load all packages from the current directory structure
 * @param options - Common options for package discovery
 * @returns Promise resolving to array of package metadata
 */
function loadPackages(options: CommonOptions): Promise<PackageMeta[]>;

/**
 * Load a single package file (package.json or pnpm-workspace.yaml)
 * @param relative - Relative path to the package file
 * @param options - Common options for loading
 * @param shouldUpdate - Function to determine if a dependency should be updated
 * @returns Promise resolving to array of package metadata
 */
function loadPackage(
  relative: string,
  options: CommonOptions,
  shouldUpdate: (name: string) => boolean
): Promise<PackageMeta[]>;

/**
 * Write updated package data back to disk
 * @param pkg - Package metadata with resolved changes
 * @param options - Common options for writing
 * @returns Promise that resolves when write is complete
 */
function writePackage(pkg: PackageMeta, options: CommonOptions): Promise<void>;

/**
 * Resolve dependencies for a single package
 * @param pkg - Package metadata to resolve dependencies for
 * @param options - Check options for resolution configuration
 * @param filter - Optional filter function for dependency inclusion
 * @param onProgress - Optional progress callback
 * @returns Promise that resolves when resolution is complete
 */
function resolvePackage(
  pkg: PackageMeta,
  options: CheckOptions,
  filter?: DependencyFilter,
  onProgress?: DependencyResolvedCallback
): Promise<void>;

/**
 * Resolve a single dependency to its target version
 * @param dep - Raw dependency to resolve
 * @param options - Check options for resolution configuration
 * @param filter - Optional filter function for dependency inclusion
 * @returns Promise resolving to resolved dependency change
 */
function resolveDependency(
  dep: RawDep,
  options: CheckOptions,
  filter?: DependencyFilter
): Promise<ResolvedDepChange>;

/**
 * Resolve dependencies for multiple packages
 * @param deps - Array of raw dependencies to resolve
 * @param options - Check options for resolution configuration
 * @param filter - Optional filter function for dependency inclusion
 * @param progressCallback - Optional progress callback
 * @returns Promise that resolves when all resolutions are complete
 */
function resolveDependencies(
  deps: RawDep[],
  options: CheckOptions,
  filter?: DependencyFilter,
  progressCallback?: (name: string, counter: number, total: number) => void
): Promise<void>;

/**
 * Parse dependencies from package.json structure into RawDep format
 * @param pkg - Package.json object or similar structure
 * @param type - Type of dependencies to parse
 * @param shouldUpdate - Function to determine if dependency should be updated
 * @returns Array of raw dependency objects
 */
function parseDependencies(
  pkg: any,
  type: DepType,
  shouldUpdate: (name: string) => boolean
): RawDep[];

/**
 * Convert resolved dependency changes back to package.json format
 * @param deps - Array of resolved dependency changes
 * @param type - Type of dependencies to dump
 * @returns Object with dependency names and versions
 */
function dumpDependencies(deps: ResolvedDepChange[], type: DepType): Record<string, any>;

/**
 * Helper for defining configuration with full type safety
 * @param config - Partial configuration object
 * @returns The same configuration object with type information
 */
function defineConfig(config: Partial<CheckOptions>): Partial<CheckOptions>;

import { defineConfig, CheckPackages } from "taze";

const config = defineConfig({
  mode: "minor",
  include: ["react", "vue"],
  exclude: ["legacy-*"],
  write: false,
  interactive: true
});

const result = await CheckPackages(config);

interface PackageMeta {
  /** Package name */
  name: string;
  /** Is private package */
  private: boolean;
  /** Package version */
  version: string;
  /** Absolute filepath */
  filepath: string;
  /** Relative filepath to the root project */
  relative: string;
  /** Dependencies */
  deps: RawDep[];
  /** Resolved dependencies */
  resolved: ResolvedDepChange[];
}

interface RawDep {
  /** Dependency name */
  name: string;
  /** Current version specification */
  currentVersion: string;
  /** Source field in package.json */
  source: DepType;
  /** Whether this dependency should be updated */
  update: boolean;
  /** Parent path for nested dependencies */
  parents?: string[];
  /** Protocol (npm, jsr) */
  protocol?: Protocol;
}

interface ResolvedDepChange extends RawDep {
  /** Latest version available */
  latestVersionAvailable?: string;
  /** Target version to update to */
  targetVersion: string;
  /** Timestamp of target version */
  targetVersionTime?: string;
  /** Timestamp of current version */
  currentVersionTime?: string;
  /** Target version provenance status */
  targetProvenance?: boolean | 'trustedPublisher';
  /** Current version provenance status */
  currentProvenance?: boolean | 'trustedPublisher';
  /** Whether provenance was downgraded */
  provenanceDowngraded: boolean;
  /** Type of version difference */
  diff: DiffType;
  /** Package metadata from registry */
  pkgData: PackageData;
  /** Error during resolution if any */
  resolveError?: Error | string | null;
  /** Alias name for aliased dependencies */
  aliasName?: string;
  /** Node.js compatibility information */
  nodeCompatibleVersion?: { semver: string; compatible: boolean };
}

type DependencyFilter = (dep: RawDep) => boolean | Promise<boolean>;

type DependencyResolvedCallback = (
  packageName: string | null,
  depName: string,
  progress: number,
  total: number
) => void;

type DepType =
  | "dependencies"
  | "devDependencies"
  | "peerDependencies"
  | "optionalDependencies"
  | "packageManager"
  | "pnpm.overrides"
  | "resolutions"
  | "overrides"
  | "pnpm-workspace";

type Protocol = "npm" | "jsr";

type DiffType = "major" | "minor" | "patch" | "error" | null;

import { CheckPackages, PackageMeta } from "taze";

await CheckPackages({
  mode: "minor",
  recursive: true
}, {
  beforePackageStart: (pkg: PackageMeta) => {
    console.log(`Processing ${pkg.name} at ${pkg.relative}`);
  },
  beforePackageWrite: (pkg: PackageMeta) => {
    // Custom validation before writing
    const hasBreakingChanges = pkg.resolved.some(dep => dep.diff === "major");
    if (hasBreakingChanges) {
      console.warn(`Skipping ${pkg.name} due to breaking changes`);
      return false; // Skip writing
    }
    return true;
  }
});

import { CheckPackages, defineConfig } from "taze";

const config = defineConfig({
  mode: "patch", // Only patch updates
  include: ["@types/*"], // Only type packages
  exclude: ["react"], // Exclude React updates
  depFields: {
    dependencies: true,
    devDependencies: true,
    peerDependencies: false // Skip peer deps
  }
});

const result = await CheckPackages(config);