sync-npm-packages/dist/index.d.mts

Sync released npm packages to mirror registries automatically.

//#region src/types.d.ts
interface DetectOptions {
  /**
   * Current working directory for glob
   *
   * @default process.cwd()
   */
  cwd?: string;
  /**
   * Use built-in default ignore patterns
   *
   * @default true
   */
  defaultIgnore?: boolean;
  /**
   * Exclude packages from being synced
   *
   * @default []
   */
  exclude?: string | string[];
  /**
   * Ignore package.json glob pattern
   *
   * @default []
   */
  ignore?: string | string[];
  /**
   * Additional packages to sync
   *
   * @default []
   */
  include?: string | string[];
  /**
   * With `optionalDependencies` in `package.json`
   *
   * @default false
   */
  withOptional?: boolean;
}
interface SyncOptions {
  /**
   * Target mirror site to sync
   *
   * @requires
   */
  target: 'npmmirror' | 'custom';
  /**
   * Enable caching of synced packages to avoid duplicate syncs
   *
   * @default false
   */
  cache?: boolean;
  /**
   * Directory to store cache files
   * Only used when cache is enabled
   *
   * @default '.sync-cache'
   */
  cacheDir?: string;
  /**
   * Maximum number of concurrent sync requests
   *
   * @default 5
   */
  concurrency?: number;
  /**
   * Enable debug mode
   *
   * @default false
   */
  debug?: boolean;
  /**
   * Custom registry host or HTTPS URL for syncing
   * When specified, overrides the default npmmirror registry
   * Host must be public and must not include path, query, or credentials
   *
   * @example 'registry.example.com'
   */
  registry?: string;
  /**
   * HTTP method used for sync requests
   *
   * @default 'PUT'
   */
  syncMethod?: 'PUT' | 'POST' | 'PATCH';
  /**
   * Path template used when target is `custom`
   * Use `{packageName}` placeholder for URL-encoded package name
   *
   * @example '/-/package/{packageName}/syncs'
   */
  syncPathTemplate?: string;
  /**
   * Number of retry attempts on failure
   *
   * @default 3
   */
  retry?: number;
  /**
   * Delay between retries in milliseconds
   *
   * @default 1000
   */
  retryDelay?: number;
  /**
   * Silent mode, suppress all output
   *
   * @default false
   */
  silent?: boolean;
  /**
   * Request timeout in milliseconds
   *
   * @default 10000
   */
  timeout?: number;
  /**
   * Enable verbose output
   *
   * @default false
   */
  verbose?: boolean;
  /**
   * Callback function executed after each package sync attempt
   * Can be used for logging, metrics collection, or cleanup
   *
   * @param packageName - Name of the package that was synced
   * @param error - Error if sync failed, undefined if successful
   * @returns Promise that resolves after completion
   *
   * @example
   * afterSync: async (pkg, error) => {
   *   if (error) {
   *     console.log(`Failed to sync ${pkg}: ${error.message}`)
   *   } else {
   *     console.log(`Successfully synced ${pkg}`)
   *   }
   * }
   */
  afterSync?: (packageName: string, error?: Error) => Promise<void> | void;
  /**
   * Callback function executed before each package sync
   * Can be used for logging, validation, or custom logic
   *
   * @param packageName - Name of the package being synced
   * @returns Promise that resolves before sync proceeds, or rejects to skip sync
   *
   * @example
   * beforeSync: async (pkg) => {
   *   console.log(`About to sync ${pkg}`)
   * }
   */
  beforeSync?: (packageName: string) => Promise<void> | void;
}
/**
 * options
 */
type Options = DetectOptions & SyncOptions & {
  /**
   * Dry run
   *
   * @default false
   */
  dry?: boolean;
};
/**
 * All property is optional
 */
type OptionalOptions = Partial<Options>;
/**
 * partial of package.json type
 */
interface PackageJson {
  name: string;
  version: string;
  optionalDependencies?: Record<string, string>;
  private?: boolean;
}
//#endregion
//#region src/core.d.ts
/**
 * Sync npm packages release to a mirror site
 *
 * @param input - package names
 * @param options - sync options {@link SyncOptions}
 * @returns a Promise that resolves when syncing is complete
 *
 * @example
 *
 * ```ts
 * import { syncNpmPackages } from 'sync-npm-packages'
 *
 * // single package
 * await syncNpmPackages('package-foobar', { target: 'npmmirror' })
 *
 * // multiple packages
 * await syncNpmPackages(['package-foo', 'package-bar'], { target: 'npmmirror' })
 * ```
 */
declare function syncNpmPackages(input: string | string[], options: SyncOptions): Promise<void>;
/**
 * Get valid package names from all package.json files
 *
 * @param options - detect options {@link DetectOptions}
 * @returns a promise resolves valid package names
 */
declare function getValidPackageNames(options?: DetectOptions): Promise<string[]>;
/**
 * Auto detect and sync npm packages release to a mirror site
 * @param options - detect options {@link DetectOptions} and sync options {@link SyncOptions }
 *
 * @example
 *
 * ```ts
 * import { syncNpmPackagesAuto } from 'sync-npm-packages'
 *
 * await syncNpmPackagesAuto({ target: 'npmmirror' })
 * ```
 */
declare function syncNpmPackagesAuto(options: DetectOptions & SyncOptions): Promise<void>;
//#endregion
//#region src/config.d.ts
/**
 * Define config for cli and NodeJS api
 *
 * @param config - user defined config
 * @returns config
 */
declare function defineConfig(config?: OptionalOptions): OptionalOptions;
/**
 * Resolve user definedConfig based on cli config and config file
 *
 * @param cliConfig - cli config
 * @returns merged config
 */
declare function resolveConfig<T extends OptionalOptions = {}>(cliConfig?: Partial<T>): Promise<Partial<T>>;
//#endregion
export { DetectOptions, OptionalOptions, Options, PackageJson, SyncOptions, defineConfig, getValidPackageNames, resolveConfig, syncNpmPackages, syncNpmPackagesAuto };