@ludeschersoftware/utils

A lightweight utility package for JavaScript and TypeScript — starting with a unique hash generator and growing into your go-to toolbox.

Built with clarity and modularity in mind, this package is perfect for developers who want clean, reusable functions without the clutter.

✨ Features

• 🔑 CreateUniqHash(length) — Generate readable, structured random hashes
• 🌀 HashValue(value) — Create a fast, deterministic 32-bit integer hash from strings
• 📦 EmptyBox() — Get a type-safe, initialized Box object with zeroed dimensions
• 🔁 ResolveAsync(promise) — Wrap any promise in a Result<T, E> for safe async handling
• ⏱️ Sleep(delayMs) — Pause execution for a given number of milliseconds
• 🎲 Uses randomInt from @ludeschersoftware/math for consistent randomness
• 🧠 Type-safe and framework-agnostic
• 🪶 Zero dependencies, fully tree-shakable
• 🧱 Designed for expansion: string utilities, state wrappers, and more

📦 Installation

npm install @ludeschersoftware/utils
# or
yarn add @ludeschersoftware/utils

🔧 Usage

import {
  CreateUniqHash,
  HashValue,
  EmptyBox,
  ResolveAsync,
  Sleep
} from '@ludeschersoftware/utils';

// Unique random hash
const hash = CreateUniqHash(24);
console.log(hash); // → e.g., "A9cF7gH2kL"

// Deterministic string hash
const code = HashValue("Hello World");
console.log(code); // → e.g., 1794106052

// Empty Box object
const box = EmptyBox();
console.log(box); // → { x: 0, y: 0, width: 0, height: 0 }

// Safe async resolution
const result = await ResolveAsync(fetchUser());
if (result.isOk()) {
  console.log("User:", result.unwrap());
} else {
  console.error("Error:", result.unwrapErr());
}

// Sleep for 500ms
await Sleep(500);
console.log("Woke up after 500ms");

📐 Function Reference

CreateUniqHash(length: number): string

Generates a pseudo-random string of the specified length using a mix of:

• Uppercase letters (A–Z) → when i % 4 === 0
• Digits (0–9) → when i % 3 === 0
• Lowercase letters (a–z) → otherwise

Internally uses randomInt(min, max) from @ludeschersoftware/math for consistent, inclusive random number generation.

Example:

CreateUniqHash(12); // → "A9cF7gH2kLz"
CreateUniqHash(20); // → "A1b2C3d4E5f6G7h8I9"

HashValue(value: string): number

Computes a deterministic 32-bit integer hash for a given string.

• Useful for creating stable IDs, cache keys, or simple hash maps.
• Always returns the same integer for the same string input.
• Operates quickly with bitwise math.

⚠️ Note: This is not cryptographically secure. Do not use for passwords or security-sensitive applications.

Example:

HashValue("Hello"); // → 69609650
HashValue("Hello"); // → 69609650 (deterministic)
HashValue("World"); // → 83766130

EmptyBox(): Box

Creates and returns a new Box object with zeroed dimensions. The Box type is imported from @ludeschersoftware/types.

Shape of Box:

interface Box {
  x: number;
  y: number;
  width: number;
  height: number;
}

Example:

const b = EmptyBox();
// → { x: 0, y: 0, width: 0, height: 0 }

ResolveAsync<T, E = unknown>(promise: Promise<T>): Result<T, E>

Wraps any promise in a Result<T, E> object from @ludeschersoftware/result, allowing safe and expressive async handling without try/catch.

• Returns Result.Ok(data) if resolved
• Returns Result.Err(error) if rejected
• You can optionally specify a custom error type E
• Fully type-safe and composable

Example:

// Default error type (unknown)
const result = await ResolveAsync(fetchData());

// Custom error type
const result = await ResolveAsync<User, FetchError>(fetchUser());

if (result.isOk()) {
  const data = result.unwrap();
  console.log("Success:", data);
} else {
  console.error("Failure:", result.unwrapErr());
}

Sleep(delayMs: number = 300): Promise<void>

Pauses execution for the specified number of milliseconds.

• Useful for throttling, testing, or simulating delays
• Defaults to 300ms if no value is provided
• Returns a promise that resolves after the delay

Example:

await Sleep();       // Waits 300ms
await Sleep(1000);   // Waits 1 second

🧱 Roadmap

Planned additions include:

• debounce, throttle, memoize
• String utilities: slugify, camelCase, truncate
• Object helpers: deepClone, merge, omit
• Geometry: intersects(boxA, boxB), expandBox(box, padding)

🧼 License

MIT © Johannes Ludescher

💬 Feedback & Contributions

This package is just getting started. If you’ve got ideas, improvements, or want to help shape the future of @ludeschersoftware/utils, your input is more than welcome.