Web Helpers

A collection of utility functions for web development, including currency conversion, Base64 encoding/decoding, and file handling.

Installation

npm install @accitdg/web-helpers

Usage

Import the package

import webHelpers from "@accitdg/web-helpers";
// or
import {
  convertNumberToCurrency,
  arrayBufferToBase64 /* ... */,
} from "@accitdg/web-helpers";

Functions

convertNumberToCurrency(numberValue: number): string

Converts a number to Philippine Peso (PHP) currency format.

Parameters:

• numberValue (number): The number to convert

Returns: Formatted currency string

Example:

webHelpers.convertNumberToCurrency(1000);
// Output: "₱1,000.00"

arrayBufferToBase64(buffer: ArrayBuffer): string

Converts an ArrayBuffer to a Base64-encoded string.

Parameters:

• buffer (ArrayBuffer): The buffer to encode

Returns: Base64 encoded string

Example:

const buffer = new ArrayBuffer(8);
const base64 = webHelpers.arrayBufferToBase64(buffer);

cleanBase64(base64: string): string

Removes the data URL prefix from a Base64 string, leaving only the encoded data.

Parameters:

• base64 (string): The Base64 string with or without prefix

Returns: Cleaned Base64 string without prefix

Example:

const cleaned = webHelpers.cleanBase64("data:image/png;base64,iVBORw0KG...");
// Output: "iVBORw0KG..."

## Supported File Types

The `cleanBase64` function supports:

- Images: png, jpg, jpeg, gif, webp, etc.
- PDF documents
- Word documents (.docx, .dotx)
- Excel spreadsheets (.xlsx)

restoreBase64(cleanedBase64: string, imageType?: string): string

Restores a clean Base64 string to a complete data URL format.

Parameters:

• cleanedBase64 (string): The Base64 string without prefix
• imageType (string, optional): Image type (default: "png")

Returns: Complete data URL string

Example:

const dataUrl = webHelpers.restoreBase64("iVBORw0KG...", "jpeg");
// Output: "data:image/jpeg;base64,iVBORw0KG..."

downloadBase64File(base64Data: string, filename: string): void

Triggers a download of a file from Base64-encoded data.

Parameters:

• base64Data (string): The Base64 encoded file data
• filename (string): The name of the file to download

Example:

webHelpers.downloadBase64File(
  "data:image/png;base64,iVBORw0KG...",
  "image.png"
);

getFileExtensionFromBase64(base64String: string): string | null

Extracts the file extension from a Base64 data URL.

Parameters:

• base64String (string): The Base64 data URL

Returns: File extension (e.g., "png", "pdf") or null if parsing fails

Example:

const ext = webHelpers.getFileExtensionFromBase64(
  "data:image/png;base64,iVBORw0KG..."
);
// Output: "png"

Configuration

createPayload and createPayload2 read applicationId and notificationId from a global config object. Call configureHelpers once during app initialization to set global defaults:

configureHelpers({
  applicationId: "app-123",
  notificationId: "notif-abc",
});

• These global values are stored on globalThis.__WEB_HELPERS_CONFIG.
• Individual calls to createPayload / createPayload2 can override these values by passing notifId / applicationId in the arguments.

Payload factories

createPayload(args?)

Returns a full, readable payload shape suitable for APIs that expect verbose keys.

Signature (TypeScript):

createPayload(args?: {
  pagination?: { count: number; page: number };
  payload?: Record<string, any>;
  notifId?: string | null;
})

Returns:

{
  isLazyLoading: boolean;
  notificationId: string | null;
  applicationId: string | null;
  geoLocation: {
    latitude: string;
    longitude: string;
    dateTime: string;
  }
  pagination: {
    count: number;
    page: number;
  }
  payload: Record<string, any>;
}

Example:

const result = createPayload({ payload: { foo: "bar" } });
// uses configured notificationId/applicationId unless notifId is provided

createPayload2(options?)

Returns a compact payload shape (short keys) for services that use abbreviated keys.

Signature (TypeScript):

createPayload2({
  pagination?: { c: number; p: number },
  payload?: Record<string, any>,
  notifId?: string | null,
  applicationId?: string | null,
} = {})

Returns:

{
  isLl: boolean;
  nId: string | null;
  aId: string | null;
  gL: {
    lt: string;
    long: string;
    date: string;
  }
  pg: {
    c: number;
    p: number;
  }
  p: Record<string, any>;
}

Example:

const short = createPayload2({ payload: { x: 1 } });
// uses configured applicationId/notificationId unless overridden in the call

formatNumberWithCommas(number: number): string

Formats a number with comma separators for thousands, preserving decimal places.

Parameters:

number (number): The number to format Returns: Formatted number string with commas as thousand separators

Example:

webHelpers.formatNumberWithCommas(1000);
// Output: "1,000"

webHelpers.formatNumberWithCommas(1234567.89);
// Output: "1,234,567.89"

webHelpers.formatNumberWithCommas(500);
// Output: "500"

titleCase(str: string): string

Converts a string to title case, capitalizing the first letter of each word and converting the rest to lowercase.

Parameters:

• str (string): The string to convert to title case

Returns: Title case formatted string, or the original input if not a string

Example:

webHelpers.titleCase("hello world");
// Output: "Hello World"

webHelpers.titleCase("tHIS IS A TEST");
// Output: "This Is A Test"

webHelpers.titleCase("javascript  typescript");
// Output: "Javascript Typescript"

webHelpers.titleCase("single");
// Output: "Single"

webHelpers.titleCase(123);
// Output: 123 (returns original value if not a string)

maskFormatPhilippineNumber(number: string): string

Formats a Philippine phone number string into a standardized mask format (+63 XXXX XXXX XXX). Accepts numbers with various input formats and cleans them before formatting.

Parameters:

• number (string): The phone number string to format (can include non-numeric characters)

Returns: Formatted Philippine phone number in the format "+63 XXXX XXXX XXX", or the original input if invalid

Example:

webHelpers.maskFormatPhilippineNumber("09171234567");
// Output: "+63 9171 2345 67"

webHelpers.maskFormatPhilippineNumber("+639171234567");
// Output: "+63 9171 2345 67"

webHelpers.maskFormatPhilippineNumber("63 917 123 4567");
// Output: "+63 9171 2345 67"

webHelpers.maskFormatPhilippineNumber("09171234");
// Output: "09171234" (returns original - invalid length)

webHelpers.maskFormatPhilippineNumber("(0917) 123-4567");
// Output: "+63 9171 2345 67"

License

@allcardtech2025