@3dsource/utils

A comprehensive collection of utility functions and helpers for 3dsource projects. This library provides common functionality used across different 3dsource applications and libraries.

Overview

The utils library offers a wide range of utility functions organized by category:

• Color manipulation and conversion
• Mathematical operations for 3D applications
• Geometry utilities
• File and image processing
• String manipulation
• RxJS operators and utilities
• Development helpers
• And more

Installation

Prerequisites

• Node.js 20+
• TypeScript 5.8+

Peer Dependencies

This library requires the following peer dependencies:

{
  "rxjs": "^7.8.2",
  "ts-md5": "^1.3.1",
  "uuid": "^11.1.0"
}

Library Installation

  npm i @3dsource/utils

Usage

Import the specific utility functions you need:

import { hexToRgb } from '@3dsource/utils/color';
import { clamp } from '@3dsource/utils/math';
import { generateUUID } from '@3dsource/utils/helpers';

Available Utilities

Color Utilities

The color module provides functions for working with colors:

import { hexToRgb, rgbToHex, darken, lighten } from '@3dsource/utils/color';

// Convert hex color to RGB
const rgb = hexToRgb('#ff0000'); // { r: 255, g: 0, b: 0 }

// Convert RGB to hex
const hex = rgbToHex(255, 0, 0); // '#ff0000'

// Darken a color by 20%
const darkRed = darken('#ff0000', 0.2);

Math Utilities

The math module provides mathematical functions:

import { clamp, lerp, degToRad } from '@3dsource/utils/math';

// Clamp a value between min and max
const clampedValue = clamp(150, 0, 100); // 100

// Linear interpolation
const interpolated = lerp(0, 100, 0.5); // 50

// Convert degrees to radians
const radians = degToRad(180); // 3.14159...

Geometry Utilities

The geom module provides geometry-related functions:

import { calculateDistance, isPointInPolygon } from '@3dsource/utils/geom';

// Calculate distance between two points
const distance = calculateDistance({ x: 0, y: 0 }, { x: 3, y: 4 }); // 5

Complete List of Utility Categories

• color - Color manipulation and conversion
• constants - Common constants used across the project
• csv - CSV parsing and generation
• dev - Development utilities
• filenaming - File naming utilities
• geom - Geometry utilities
• helpers - General helper functions
• image - Image processing utilities
• interfaces - Common TypeScript interfaces
• math - Mathematical functions
• mutex - Mutex implementation for async operations
• predicates - Type guards and predicates
• rxjs - RxJS operators and utilities
• strings - String manipulation functions

Examples

Working with UUIDs

import { generateUUID, isValidUUID } from '@3dsource/utils/helpers';

// Generate a new UUID
const id = generateUUID();

// Check if a string is a valid UUID
const isValid = isValidUUID(id); // true

Using RxJS Utilities

import { retryWithBackoff } from '@3dsource/utils/rxjs';
import { of, throwError } from 'rxjs';
import { mergeMap } from 'rxjs/operators';

// Retry an operation with exponential backoff
function getData() {
  return of(Math.random()).pipe(
    mergeMap((val) => (val < 0.5 ? throwError(() => new Error('Failed')) : of(val))),
    retryWithBackoff({
      initialInterval: 100,
      maxRetries: 3,
    }),
  );
}