@flexzap/utilities

Essential utility services and helpers for Angular applications. Part of the FlexZap Library ecosystem.

Installation

npm install @flexzap/utilities

Peer Dependencies

This library requires the following peer dependencies:

npm install @angular/common@^21.2.10 @angular/core@^21.2.10 @angular/platform-browser@^21.2.10

Usage

ZapNavigation

The ZapNavigation service provides safe, platform-agnostic navigation methods.

import { Component, inject } from '@angular/core';
import { ZapNavigation } from '@flexzap/utilities';

@Component({
  template: `
    <button (click)="goToExternal()">Go to Google</button>
    <button (click)="sendEmail()">Contact Us</button>
    <button (click)="callSupport()">Call Support</button>
  `
})
export class MyComponent {
  private navigation = inject(ZapNavigation);

  goToExternal() {
    // Safely navigates to URL (sanitized and browser-check included)
    this.navigation.goToUrl('https://google.com', '_blank');
  }

  sendEmail() {
    this.navigation.mailTo('[email protected]', 'Help', 'I need assistance');
  }

  callSupport() {
    this.navigation.callTo('+1234567890');
  }
}

ZapCookieUtil

The ZapCookieUtil service provides methods for managing browser cookies.

import { Component, inject } from '@angular/core';
import { ZapCookieUtil } from '@flexzap/utilities';

@Component({
  template: `
    <button (click)="setPreference()">Set Preference</button>
    <p>Current Preference: {{ preference }}</p>
  `
})
export class CookieComponent {
  private cookieUtil = inject(ZapCookieUtil);
  preference: string | null = null;

  constructor() {
    this.preference = this.cookieUtil.getCookie('user_pref');
  }

  setPreference() {
    this.cookieUtil.setCookie('user_pref', 'dark_mode', 365);
    this.preference = 'dark_mode';
  }
}

API Reference

ZapNavigation Service

Service for handling navigation and URL opening in a safe, platform-agnostic way.

Methods

| Method | Parameters | Description | | -------------- | -------------------------------------------------------------------- | -------------------------------------------------------------- | | goToUrl | url: string, target?: '_self' \| '_blank' \| '_parent' \| '_top' | Navigates to the specified URL. Default target is _self. | | mailTo | email: string, subject?: string, body?: string | Opens the default email client with optional subject and body. | | callTo | tel: string | Initiates a phone call to the specified number. | | smsTo | tel: string | Initiates an SMS to the specified number. | | linkTo | id: string | Smoothly scrolls to the element with the specified ID. | | downloadFile | url: string, filename?: string | Downloads a file from the specified URL. |

Features

• Platform Agnostic: Safe to call in SSR environments (checks PLATFORM_ID).
• Security: Automatically sanitizes URLs to prevent XSS.
• SSR Safe: Prevents window access on the server.

ZapCookieUtil Service

Utility service for managing browser cookies.

Methods

| Method | Parameters | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | getCookie | name: string | Retrieves a cookie value by name. | | setCookie | name: string, value: string, days?: number, path?: string, domain?: string, secure?: boolean, sameSite?: 'Lax' \| 'Strict' \| 'None' | Sets a cookie with the specified parameters. |

Features

• SSR Safe: Checks for DOCUMENT availability before accessing document.cookie.
• Typesafe: Provides typed arguments for cookie options.

Testing

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

Running Tests

# From the monorepo root
npm run utilities:test            # Run all unit tests with coverage
npm run utilities: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/utilities/

Development

Building the Library

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

Publishing

Build for Publication

# From the monorepo root
npm run utilities:build

Publish to NPM

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

Contributing

This library is part of the FlexZap Library monorepo. Please refer to the main repository for contribution guidelines.

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