npm package: @flexzap/pipes
Description: All the pipes that makes part of the flexzap library
Author: flexzap
Latest version: 1.0.3

# @flexzap/pipes

Comprehensive collection of transformation pipes for Angular applications, providing advanced numeric formatting capabilities. Part of the FlexZap Library ecosystem.

## Installation

```bash
npm install @flexzap/pipes
```

### Peer Dependencies

This library requires the following peer dependencies:

```bash
npm install @angular/common@^21.0.0 @angular/core@^21.0.0
```

## Usage

### Basic Setup

```typescript
import { Component } from '@angular/core';
import { ZapNumeric } from '@flexzap/pipes';

@Component({
  imports: [ZapNumeric],
  template: `
    <!-- Basic integer formatting -->
    <p>{{ 123456.789 | ZapNumeric }}</p>
    <!-- Output: 123456 -->

    <!-- Decimal formatting -->
    <p>{{ 123456.789 | ZapNumeric: { style: 'decimal', lang: 'en-US', fraction: 2 } }}</p>
    <!-- Output: 123,456.79 -->

    <!-- Currency formatting -->
    <p>{{ 123456.789 | ZapNumeric: { style: 'currency', lang: 'en-US', fraction: 2, currency: 'USD' } }}</p>
    <!-- Output: 123,456.79 USD -->
  `
})
export class MyComponent {}
```

### Advanced Usage Examples

```typescript
import { Component } from '@angular/core';
import { ZapNumeric } from '@flexzap/pipes';
import type { ZapNumericInterface } from '@flexzap/pipes';

@Component({
  imports: [ZapNumeric],
  template: `
    <div class="numeric-examples">
      <!-- Integer formatting -->
      <p>Integer: {{ 123456.789 | ZapNumeric }}</p>
      <!-- Output: 123456 -->

      <!-- Decimal with custom precision -->
      <p>Decimal: {{ 123456.789 | ZapNumeric: decimalConfig }}</p>
      <!-- Output: 123,456.7890 -->

      <!-- Currency formatting -->
      <p>Currency: {{ 123456.789 | ZapNumeric: currencyConfig }}</p>
      <!-- Output: 123,456.79 USD -->

      <!-- Percentage formatting -->
      <p>Percentage: {{ 60.7777 | ZapNumeric: percentConfig }}</p>
      <!-- Output: 60% -->

      <!-- Unit formatting -->
      <p>Unit: {{ 123456.789 | ZapNumeric: unitConfig }}</p>
      <!-- Output: 123,456.789 kg -->

      <!-- Different locales -->
      <p>German Format: {{ 123456.789 | ZapNumeric: germanConfig }}</p>
      <!-- Output: 123.456,79 EUR -->
    </div>
  `
})
export class NumericExamplesComponent {
  decimalConfig: Partial<ZapNumericInterface> = {
    style: 'decimal',
    lang: 'en-US',
    fraction: 4
  };

  currencyConfig: Partial<ZapNumericInterface> = {
    style: 'currency',
    lang: 'en-US',
    fraction: 2,
    currency: 'USD'
  };

  percentConfig: Partial<ZapNumericInterface> = {
    style: 'percent',
    lang: 'en-US'
  };

  unitConfig: Partial<ZapNumericInterface> = {
    style: 'unit',
    lang: 'en-US',
    fraction: 3,
    unit: 'kilogram'
  };

  germanConfig: Partial<ZapNumericInterface> = {
    style: 'currency',
    lang: 'de-DE',
    fraction: 2,
    currency: 'EUR'
  };
}
```

## API Reference

### ZapNumeric Pipe

Advanced numeric transformation pipe with internationalization support and multiple formatting styles.

#### Usage Syntax

```typescript
{{ value | ZapNumeric: config }}
```

#### Configuration Object

The pipe accepts a configuration object of type `Partial<ZapNumericInterface>`:

| Property   | Type     | Default                         | Description                                                           |
| ---------- | -------- | ------------------------------- | --------------------------------------------------------------------- |
| `style`    | `string` | `'integer'`                     | Formatting style: 'integer', 'decimal', 'currency', 'percent', 'unit' |
| `lang`     | `string` | `document.documentElement.lang` | Language/locale code (e.g., 'en-US', 'de-DE')                         |
| `fraction` | `number` | `2`                             | Number of decimal places (0 = none)                                   |
| `currency` | `string` | `''`                            | Currency code for currency style (e.g., 'USD', 'EUR')                 |
| `unit`     | `string` | `''`                            | Unit for unit style (e.g., 'kilogram', 'meter')                       |

#### Formatting Styles

##### Integer Style

Formats numbers as integers (truncates decimal places):

```typescript
{{ 123456.789 | ZapNumeric }}
// Output: 123456

{{ 123456.789 | ZapNumeric: { style: 'integer' } }}
// Output: 123456
```

##### Decimal Style

Formats numbers with decimal places and locale-specific separators:

```typescript
{{ 123456.789 | ZapNumeric: { style: 'decimal', lang: 'en-US', fraction: 2 } }}
// Output: 123,456.79

{{ 123456.789 | ZapNumeric: { style: 'decimal', lang: 'de-DE', fraction: 3 } }}
// Output: 123.456,789
```

##### Currency Style

Formats numbers as currency with proper locale formatting:

```typescript
{{ 123456.789 | ZapNumeric: { style: 'currency', lang: 'en-US', fraction: 2, currency: 'USD' } }}
// Output: 123,456.79 USD

{{ 123456.789 | ZapNumeric: { style: 'currency', lang: 'de-DE', fraction: 2, currency: 'EUR' } }}
// Output: 123.456,79 EUR
```

##### Percent Style

Formats numbers as percentages:

```typescript
{{ 0.607777 | ZapNumeric: { style: 'percent', lang: 'en-US' } }}
// Output: 60%

{{ 60.7777 | ZapNumeric: { style: 'percent', lang: 'en-US' } }}
// Output: 60% (automatically converts from whole numbers)
```

##### Unit Style

Formats numbers with units using Intl.NumberFormat unit support:

```typescript
{{ 123456.789 | ZapNumeric: { style: 'unit', lang: 'en-US', fraction: 2, unit: 'kilogram' } }}
// Output: 123,456.79 kg

{{ 1500 | ZapNumeric: { style: 'unit', lang: 'en-US', fraction: 1, unit: 'meter' } }}
// Output: 1,500.0 m
```

### Type Definitions

#### ZapNumericInterface

```typescript
interface ZapNumericInterface {
  style: string; // Formatting style
  value: number; // Numeric value to format
  fraction: number; // Decimal places
  lang: string; // Language/locale code
  currency: string; // Currency code
  unit: string; // Unit identifier
}
```

#### Specialized Types

The library exports specialized types for different formatting contexts:

```typescript
type ZapInteger = Pick<ZapNumericInterface, 'value'>;
type ZapDecimal = Pick<ZapNumericInterface, 'value' | 'lang' | 'fraction'>;
type ZapCurrency = Pick<ZapNumericInterface, 'value' | 'lang' | 'fraction' | 'currency'>;
type ZapPercent = Pick<ZapNumericInterface, 'value' | 'lang'>;
type ZapUnit = Pick<ZapNumericInterface, 'value' | 'lang' | 'fraction' | 'unit'>;
```

### PipesUtils Service

Injectable utility service providing helper functions for pipe operations.

#### Methods

| Method       | Parameters                        | Return Type | Description                                    |
| ------------ | --------------------------------- | ----------- | ---------------------------------------------- |
| `truncate()` | `value: number, decimals: number` | `number`    | Truncates a number to specified decimal places |

#### Usage

```typescript
import { inject } from '@angular/core';
import { PipesUtils } from '@flexzap/pipes';

// In a component or service
const pipesUtils = inject(PipesUtils);
const truncated = PipesUtils.truncate(123.456789, 2); // Returns: 123.45
```

## Internationalization Support

The library fully supports internationalization through the `Intl.NumberFormat` API:

### Supported Locales

Any valid BCP 47 language tag is supported, including:

- `'en-US'` - US English
- `'de-DE'` - German
- `'fr-FR'` - French
- `'ja-JP'` - Japanese
- `'pt-BR'` - Brazilian Portuguese
- And many more...

### Automatic Locale Detection

If no language is specified, the pipe automatically detects the document's language:

```typescript
// Uses document.documentElement.lang
{{ 123456.789 | ZapNumeric: { style: 'currency', currency: 'USD' } }}
```

### Custom Locale Examples

```typescript
// US format
{{ 123456.789 | ZapNumeric: { style: 'currency', lang: 'en-US', currency: 'USD' } }}
// Output: 123,456.79 USD

// German format
{{ 123456.789 | ZapNumeric: { style: 'currency', lang: 'de-DE', currency: 'EUR' } }}
// Output: 123.456,79 EUR

// Japanese format
{{ 123456.789 | ZapNumeric: { style: 'currency', lang: 'ja-JP', currency: 'JPY' } }}
// Output: 123,457 JPY
```

## Testing

This library uses Jest for unit testing with zoneless Angular configuration.

### Running Tests

```bash
# From the monorepo root
npm run pipes:test           # Run all unit tests with coverage
npm run pipes:test:watch     # Run tests in watch mode (no coverage)
```

### Test Configuration

- **Framework**: Jest with jest-preset-angular
- **Environment**: jsdom
- **Configuration**: Zoneless Angular (mandatory)
- **Coverage**: Reports generated at `coverage/flexzap/pipes/`

### Testing with ZapNumeric

```typescript
import { TestBed } from '@angular/core/testing';
import { provideZonelessChangeDetection } from '@angular/core';
import { ZapNumeric } from '@flexzap/pipes';

describe('ZapNumeric', () => {
  let pipe: ZapNumeric;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [provideZonelessChangeDetection()]
    });
    pipe = new ZapNumeric();
  });

  it('should format currency correctly', () => {
    const result = pipe.transform(123456.789, {
      style: 'currency',
      lang: 'en-US',
      fraction: 2,
      currency: 'USD'
    });
    expect(result).toBe('123,456.79 USD');
  });
});
```

## Development

### Building the Library

```bash
# From the monorepo root
npm run pipes:build      # Build directly
ng build @flexzap/pipes  # Build using Angular CLI
```

### Code Scaffolding

To generate new pipes within this library:

```bash
ng generate pipe [pipe-name] --project @flexzap/pipes
```

## Publishing

### Build for Publication

```bash
# From the monorepo root
npm run pipes:build
```

### Publish to NPM

```bash
cd dist/flexzap/pipes
npm publish --access public
```

## Contributing

This library is part of the FlexZap Library monorepo. Please refer to the [main repository](../../../README.md) for contribution guidelines.

### Development Guidelines

- Use standalone pipes (default behavior)
- Support internationalization through Intl APIs
- Write comprehensive tests with Jest (zoneless configuration)
- Follow semantic versioning for releases
- Use TypeScript strict mode
- Provide clear type definitions for all public APIs

## License

MIT License - see the [LICENSE](../../../LICENSE) file for details.

## Links

- **Homepage**: [https://www.flexzap.dev](https://www.flexzap.dev)
- **Repository**: [https://github.com/vitorazevedo/flexzap-library](https://github.com/vitorazevedo/flexzap-library)
- **Monorepo Documentation**: [Main README](../../../README.md)