purify-objects/README.md

A powerful TypeScript library for cleaning objects by removing empty values, with support for YAML and CSV formats

# purify-objects

[![npm version](https://img.shields.io/npm/v/purify-objects.svg)](https://www.npmjs.com/package/purify-objects)
[![npm downloads](https://img.shields.io/npm/dm/purify-objects.svg)](https://www.npmjs.com/package/purify-objects)
[![npm bundle size](https://img.shields.io/bundlephobia/minzip/purify-objects)](https://bundlephobia.com/package/purify-objects)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/ml7s/purify-objects/pulls)

A powerful TypeScript library for cleaning objects by removing empty values, with support for YAML and CSV formats.

## Features

- Clean objects by removing empty values (null, undefined, empty strings, empty arrays, empty objects)
- Support for JSON, YAML, and CSV formats
- Format conversion between JSON, YAML, and CSV
- Command-line interface (CLI) for file processing
- Safe mode to prevent accidental modifications
- Compare mode to preview changes
- Custom cleaning options
- Automatic format detection based on file extension

## Installation

```bash
npm install purify-objects
```

## Usage

### As a Library

```typescript
import { cleanObject, parseContent, stringifyContent } from 'purify-objects';

const obj = {
  id: 1,
  name: "Turki",
  meta: {
    age: null,
    location: {
      city: "Riyadh",
      coords: undefined,
      district: "",
    },
    preferences: {},
  },
  roles: [],
  lastLogin: "2024-01-15",
  status: 0
};

const cleaned = cleanObject(obj);

const yaml = `
version: 2
config:
  user: Turki
  env: prod
  paths:
    root: /app
    temp: null
    logs:
  plugins: []
`;

const parsed = parseContent(yaml, 'yaml');
const result = cleanObject(parsed);
const output = stringifyContent(result, 'yaml');

const csv = `
id,name,department,salary,active
1,Turki,IT,15000,true
2,Ahmad,HR,,false
3,Mohammed,IT,12000,
4,,Finance,,true
`;

const data = parseContent(csv, 'csv', { headers: true });
const processed = data.map(row => cleanObject(row));
const final = stringifyContent(processed, 'csv', { headers: true });
```

### Command Line Interface (CLI)

Basic usage:
```bash
npx purify-objects input.json
npx purify-objects input.yaml
npx purify-objects input.csv
```

Save output to a file:
```bash
npx purify-objects input.json --output cleaned.json
```

### Format Conversion

Convert between formats:
```bash
# Convert JSON to YAML
npx purify-objects input.json --convert-to yaml

# Convert YAML to CSV
npx purify-objects input.yaml --convert-to csv

# Convert CSV to JSON
npx purify-objects input.csv --convert-to json
```

Convert without cleaning:
```bash
npx purify-objects input.yaml --convert-to json --noclean
```

### CSV Options

```bash
# Use custom delimiter
npx purify-objects input.csv --delimiter ";"

# Disable headers
npx purify-objects input.csv --no-headers
```

### Additional Options

```bash
# Preview changes without modifying the file
npx purify-objects input.json --compare

# Safe mode (creates new file instead of modifying)
npx purify-objects input.json --safe

# Remove zero values
npx purify-objects input.json --remove-zero-values
```

## CLI Options

- `--output <file>`: Save output to a file
- `--format <format>`: Specify input format (json, yaml, csv)
- `--convert-to <format>`: Convert to specified format
- `--noclean`: Convert without cleaning data
- `--compare`: Preview changes without modifying
- `--safe`: Create new file instead of modifying
- `--delimiter <char>`: CSV delimiter (default: ",")
- `--no-headers`: Process CSV without headers
- `--remove-zero-values`: Remove fields with zero values

## API

```typescript
function cleanObject<T extends object>(
  obj: T,
  customCleaner?: (key: string, value: any) => boolean,
  keepFields?: string[],
  options?: CleanerOptions
): T;

function parseContent(
  content: string,
  format: 'json' | 'yaml' | 'csv',
  options?: ParserOptions
): object | object[];

function stringifyContent(
  data: object | object[],
  format: 'json' | 'yaml' | 'csv',
  options?: ParserOptions
): string;

interface CleanerOptions {
  recursive?: boolean;
  safe?: boolean;
}

interface ParserOptions {
  delimiter?: string;
  headers?: boolean;
}
```

## License

MIT