Utilities

/**
 * Recursively removes directory and all contents
 * @param dir - Directory path to remove
 * @returns Promise that resolves when removal is complete
 */
function remove(dir: string): Promise<void>;

/**
 * Copies files or directories recursively with options
 * @param from - Source path
 * @param to - Destination path  
 * @param opts - Copy options (including filter function)
 * @returns Promise that resolves when copying is complete
 */
function copy(from: string, to: string, opts?: object): Promise<void>;

import { copy, remove } from 'clean-publish/utils.js';

// Copy directory with filtering
await copy('src', 'dist/src', {
  filter: (source, dest) => !source.includes('.test.js')
});

// Copy single file
await copy('README.md', 'dist/README.md');

// Remove directory completely
await remove('temp-build');

/**
 * Reads and parses JSON file
 * @param file - Path to JSON file
 * @returns Promise resolving to parsed JSON object
 * @throws Error if file cannot be read or parsed
 */
function readJSON(file: string): Promise<object>;

/**
 * Writes object to JSON file with formatting
 * @param file - Output file path
 * @param json - Object to serialize to JSON
 * @returns Promise that resolves when file is written
 */
function writeJSON(file: string, json: object): Promise<void>;

/**
 * Reads and parses JSON from stdin
 * @returns Promise resolving to parsed JSON object
 * @throws Error if stdin content cannot be parsed
 */
function readJSONFromStdin(): Promise<object>;

import { readJSON, writeJSON, readJSONFromStdin } from 'clean-publish/utils.js';

// Read package.json
const pkg = await readJSON('package.json');

// Write formatted JSON
await writeJSON('output.json', { 
  name: pkg.name,
  version: pkg.version 
});

// Read from stdin (useful for pipes)
const stdinData = await readJSONFromStdin();

/**
 * Parses comma-separated string into array
 * @param arg - Comma-separated string
 * @returns Array of trimmed strings
 */
function parseListArg(arg: string): string[];

import { parseListArg } from 'clean-publish/utils.js';

// Parse CLI list arguments
const files = parseListArg('*.test.js, coverage/, docs/internal/');
console.log(files); // ['*.test.js', 'coverage/', 'docs/internal/']

// Handle whitespace variations
const fields = parseListArg('devDependencies,scripts.test, husky');
console.log(fields); // ['devDependencies', 'scripts.test', 'husky']

/**
 * Checks if value is a non-null object
 * @param object - Value to check
 * @returns Boolean indicating if value is an object
 */
function isObject(object: any): boolean;

/**
 * Filters object properties by key predicate function
 * @param object - Object to filter
 * @param filterByKey - Predicate function for keys (defaults to include all)
 * @param deep - Whether to apply filtering recursively to nested objects
 * @returns New object with filtered properties, or original if unchanged
 */
function filterObjectByKey(object: object, filterByKey?: Function, deep?: boolean): object;

/**
 * Converts dot-notation path to array of keys
 * @param path - Dot-separated property path (supports escaped dots)
 * @returns Array of property keys
 */
function pathToKeys(path: string): string[];

/**
 * Deletes nested property from object using key path
 * @param object - Object to modify
 * @param keys - Array of keys representing path to property
 * @returns Boolean indicating if property was successfully deleted
 */
function deleteProperty(object: object, keys: string[]): boolean;

import { 
  isObject, 
  filterObjectByKey, 
  pathToKeys, 
  deleteProperty 
} from 'clean-publish/utils.js';

// Type checking
console.log(isObject({}));        // true
console.log(isObject(null));      // false
console.log(isObject([]));        // true
console.log(isObject('string'));  // false

// Filter object properties
const scripts = {
  test: 'jest',
  build: 'webpack',
  dev: 'webpack-dev-server',
  start: 'node server.js'
};

const buildScripts = filterObjectByKey(scripts, key => 
  ['build', 'start'].includes(key)
);
console.log(buildScripts); // { build: 'webpack', start: 'node server.js' }

// Deep filtering
const config = {
  build: {
    input: 'src/index.js',
    output: 'dist/bundle.js',
    sourcemap: true
  },
  dev: {
    port: 3000,
    hot: true
  }
};

const filtered = filterObjectByKey(config, key => key !== 'sourcemap', true);
// Result: build.sourcemap property removed recursively

// Path manipulation
const path = 'scripts.test';
const keys = pathToKeys(path);
console.log(keys); // ['scripts', 'test']

// Handle escaped dots
const escapedPath = 'publishConfig.@types/node';
const escapedKeys = pathToKeys(escapedPath);
// Properly handles escaped dots in property names

// Delete nested properties
const packageJson = {
  scripts: {
    test: 'jest',
    build: 'webpack'
  },
  devDependencies: {
    jest: '^27.0.0'
  }
};

const deleted = deleteProperty(packageJson, ['scripts', 'test']);
console.log(deleted); // true
console.log(packageJson.scripts); // { build: 'webpack' }

const pkg = {
  name: 'my-package',
  version: '1.0.0', 
  devDependencies: { jest: '^27.0.0' },
  dependencies: { lodash: '^4.17.0' }
};

// Keep only production fields
const prod = filterObjectByKey(pkg, key => 
  !['devDependencies', 'scripts'].includes(key)
);

const config = {
  build: {
    minify: true,
    sourcemap: true,
    dev: {
      watch: true
    }
  }
};

// Remove all 'dev' keys recursively
const production = filterObjectByKey(config, key => key !== 'dev', true);

const scripts = {
  'test:unit': 'jest',
  'test:e2e': 'cypress',
  'build:prod': 'webpack --mode=production',
  'build:dev': 'webpack --mode=development'
};

// Keep only production scripts
const prodScripts = filterObjectByKey(scripts, key => 
  key.includes('prod') || !key.includes('test')
);