tessl/npm-utility

A collection of useful TypeScript/JavaScript utilities for crypto, date, string, number, JSON operations and more.

—

Pending

Overview

Eval results

Files

Number Operations

Name: tessl/npm-utility
Author: tessl

Safe number operations with precision handling, random number generation, and validation for JavaScript's safe integer limits to prevent precision loss and overflow issues.

Capabilities

Safe Integer Constants

JavaScript safe integer limits and string representations for precision validation.

const MAX_SAFE_INTEGER: number;      // 9007199254740991 or 2^53 - 1
const MIN_SAFE_INTEGER: number;      // -9007199254740991
const MAX_SAFE_INTEGER_STR: string;  // "9007199254740991"

Usage Examples:

import { MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, MAX_SAFE_INTEGER_STR, isSafeNumberString, toSafeNumber } from "utility";

// Using constants for validation
const userInput = "9007199254740991";
if (parseInt(userInput) <= MAX_SAFE_INTEGER) {
  console.log("Safe to convert to number");
}

// Compare against limits
console.log(MAX_SAFE_INTEGER);     // 9007199254740991
console.log(MIN_SAFE_INTEGER);     // -9007199254740991
console.log(MAX_SAFE_INTEGER_STR); // "9007199254740991"

// Validation using string constant
const isMaxSafe = isSafeNumberString(MAX_SAFE_INTEGER_STR);
// Result: true

// Beyond safe limits
const tooLarge = (MAX_SAFE_INTEGER + 1).toString();
const isUnsafe = isSafeNumberString(tooLarge);
// Result: false

// Practical usage with API input validation
function processNumericInput(value: string): number | string {
  if (value.length > MAX_SAFE_INTEGER_STR.length) {
    return value; // Too long, keep as string
  }
  return toSafeNumber(value);
}

Safe Number String Validation

Validate if a number string can be safely converted to JavaScript Number.

/**
 * Detect if a number string can safely convert to JavaScript Number
 * @param s - Number format string
 * @returns True if string represents a safe number
 */
function isSafeNumberString(s: string): boolean;

Usage Examples:

import { isSafeNumberString, MAX_SAFE_INTEGER } from "utility";

// Safe numbers
const safe1 = isSafeNumberString("123456789");
// Result: true

const safe2 = isSafeNumberString("-1000");
// Result: true

const safeMax = isSafeNumberString("9007199254740991");
// Result: true

// Unsafe numbers (too large)
const unsafe1 = isSafeNumberString("9007199254740992");
// Result: false

const unsafe2 = isSafeNumberString("123456789012345678901234567890");
// Result: false

// Negative numbers
const safeNeg = isSafeNumberString("-9007199254740991");
// Result: true

Safe Number Conversion

Convert string to Number only if within safe integer range.

/**
 * Convert string to Number if string is in safe Number scope
 * @param s - Number format string or existing number
 * @returns Number if safe conversion possible, otherwise returns original string
 */
function toSafeNumber(s: string | number): number | string;

Usage Examples:

import { toSafeNumber } from "utility";

// Safe conversions
const num1 = toSafeNumber("12345");
// Result: 12345 (number)

const num2 = toSafeNumber("-9007199254740991");
// Result: -9007199254740991 (number)

// Already a number
const num3 = toSafeNumber(42);
// Result: 42 (number)

// Unsafe conversions (returns original string)
const str1 = toSafeNumber("9007199254740992");
// Result: "9007199254740992" (string)

const str2 = toSafeNumber("123456789012345678901234567890");
// Result: "123456789012345678901234567890" (string)

// Floating point numbers
const float1 = toSafeNumber("123.456");
// Result: 123.456 (number)

Random Number Generation

Generate random integers within specified bounds with automatic bound swapping.

/**
 * Produces a random integer between inclusive bounds
 * @param lower - Lower bound (or upper bound if upper not provided)
 * @param upper - Upper bound (optional)
 * @returns Random integer within bounds
 */
function random(lower?: number, upper?: number): number;

Usage Examples:

import { random } from "utility";

// No parameters - returns 0
const zero = random();
// Result: 0

// Single parameter - random between 0 and parameter
const dice = random(6);
// Result: 0, 1, 2, 3, 4, or 5

// Two parameters - random between bounds (inclusive)
const percentage = random(1, 100);
// Result: integer between 1 and 100

// Automatic bound swapping
const swapped = random(10, 1);
// Result: integer between 1 and 10 (bounds automatically swapped)

// Negative numbers
const negative = random(-10, -1);
// Result: integer between -10 and -1

// Mixed bounds
const mixed = random(-5, 5);
// Result: integer between -5 and 5

Install with Tessl CLI