@flexzap/pipes

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

Installation

npm install @flexzap/pipes

Peer Dependencies

This library requires the following peer dependencies:

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

Usage

Basic Setup

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

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

{{ 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):

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

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

Decimal Style

Formats numbers with decimal places and locale-specific separators:

{{ 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:

{{ 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:

{{ 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:

{{ 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

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:

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

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:

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

Custom Locale Examples

// 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

# 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

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

# From the monorepo root
npm run pipes:build      # Build with version bump
ng build @flexzap/pipes  # Build directly

Code Scaffolding

To generate new pipes within this library:

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

Publishing

Build for Publication

# From the monorepo root
npm run pipes:build

Publish to NPM

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

Contributing

This library is part of the FlexZap Library monorepo. Please refer to the main repository 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 file for details.

Links

• Homepage: https://www.flexzap.dev
• Repository: https://github.com/vitorazevedo/flexzap-library
• Monorepo Documentation: Main README