@devbro/neko-helper

A comprehensive collection of utility functions and classes for common programming tasks in Node.js and TypeScript applications. Includes array manipulation, number formatting, cryptographic operations, event handling, async utilities, and more.


Table of Contents

- Installation
- Features
- Quick Start
- Modules
- Array Utilities
- Number Utilities
- Encoding & Cryptography
- Time Utilities
- Event Management
- Pattern Enforcers
- Types
- API Reference
- Real-World Examples
- Best Practices
- TypeScript Support
- Contributing
- Related Packages

Installation

``bash
npm install @devbro/neko-helper
`

Features

- Array Operations: Intersperse, flatten, cross join, chunking, grouping, and more
- Number Formatting: Currency, file sizes, abbreviations, ordinals, Roman numerals
- Cryptography: Hashing (MD5, SHA-1/256/512, SHA3), JWT, bcrypt, Ed25519 signatures
- Time Utilities: Sleep/delay functions for async operations
- Event Management: Type-safe event emitters with async support
- Pattern Enforcers: Singleton pattern, repeaters, function chaining
- Environment: Safe environment variable access with defaults
- Type Definitions: JSON types, utility types for TypeScript
- Zero Config: Import and use immediately
- Fully Typed: Complete TypeScript support with generics
- Tree Shakeable: Use only what you need

Quick Start

`typescript
import { Arr, Num, Enc, sleep, getEnv } from '@devbro/neko-helper';

// Array operations
const chunks = Arr.chunk([1, 2, 3, 4, 5], 2);
// [[1, 2], [3, 4], [5]]

// Number formatting
const formatted = Num.abbreviate(1500000);
// "1.5M"

const currency = Num.currencyFormat(1234.56, 'USD');
// "$1,234.56"

// Hashing
const hash = Enc.hash.sha256('password');
// "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"

// JWT
const token = await Enc.jwt.sign({ userId: 123 }, 'secret');
const payload = await Enc.jwt.verify(token, 'secret');

// Async delay
await sleep(1000); // Wait 1 second

// Environment variables
const apiKey = getEnv('API_KEY', 'default-key');
`

Modules

$3

Import: import { Arr } from '@devbro/neko-helper';

#### Arr.intersperse(arr: T[], sep: S): (T | S)[]

Insert a separator between array elements.

`typescript
Arr.intersperse([1, 2, 3], 0);
// [1, 0, 2, 0, 3]

Arr.intersperse(['a', 'b', 'c'], '-');
// ['a', '-', 'b', '-', 'c']
`

#### Arr.flatten(arr: T[][]): T[]

Flatten a nested array by one level.

`typescript
Arr.flatten([[1, 2], [3, 4], [5]]);
// [1, 2, 3, 4, 5]
`

#### Arr.crossJoin(arr1: T[], arr2: U[]): [T, U][]

Create all combinations of two arrays (Cartesian product).

`typescript
Arr.crossJoin([1, 2], ['a', 'b']);
// [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
`

#### Arr.chunk(arr: T[], size: number): T[][]

Split array into chunks of specified size.

`typescript
Arr.chunk([1, 2, 3, 4, 5], 2);
// [[1, 2], [3, 4], [5]]
`

#### Arr.unique(arr: T[]): T[]

Remove duplicate values from array.

`typescript
Arr.unique([1, 2, 2, 3, 3, 3]);
// [1, 2, 3]
`

#### Arr.groupBy(arr: T[], key: keyof T | ((item: T) => string)): Record

Group array elements by key or function result.

`typescript
const users = [
{ name: 'John', role: 'admin' },
{ name: 'Jane', role: 'user' },
{ name: 'Bob', role: 'admin' },
];

Arr.groupBy(users, 'role');
// {
// admin: [{ name: 'John', role: 'admin' }, { name: 'Bob', role: 'admin' }],
// user: [{ name: 'Jane', role: 'user' }]
// }
`

$3

Import: import { Num } from '@devbro/neko-helper';

#### Num.abbreviate(num: number): string

Abbreviate large numbers with K, M, B, T suffixes.

`typescript
Num.abbreviate(1000); // "1K"
Num.abbreviate(1500); // "1.5K"
Num.abbreviate(1000000); // "1M"
Num.abbreviate(2500000); // "2.5M"
Num.abbreviate(1000000000); // "1B"
`

#### Num.clamp(num: number, min: number, max: number): number

Clamp number between min and max values.

`typescript
Num.clamp(5, 1, 10); // 5
Num.clamp(-5, 1, 10); // 1
Num.clamp(15, 1, 10); // 10
`

#### Num.currencyFormat(num: number, currency?: string): string

Format number as currency.

`typescript
Num.currencyFormat(1234.56); // "$1,234.56"
Num.currencyFormat(1234.56, 'EUR'); // "€1,234.56"
Num.currencyFormat(1234.56, 'GBP'); // "£1,234.56"
`

#### Num.fileSize(bytes: number): string

Format bytes to human-readable file size.

`typescript
Num.fileSize(1024); // "1 KB"
Num.fileSize(1048576); // "1 MB"
Num.fileSize(1073741824); // "1 GB"
Num.fileSize(1536); // "1.5 KB"
`

#### Num.ordinal(num: number): string

Convert number to ordinal string.

`typescript
Num.ordinal(1); // "1st"
Num.ordinal(2); // "2nd"
Num.ordinal(3); // "3rd"
Num.ordinal(4); // "4th"
Num.ordinal(21); // "21st"
`

#### Num.toWords(num: number): string

Convert number to words.

`typescript
Num.toWords(42); // "forty-two"
Num.toWords(1234); // "one thousand, two hundred thirty-four"
`

#### Num.toRoman(num: number): string

Convert number to Roman numerals.

`typescript
Num.toRoman(9); // "IX"
Num.toRoman(42); // "XLII"
Num.toRoman(1994); // "MCMXCIV"
`

#### Num.percentage(value: number, total: number, decimals?: number): string

Calculate percentage.

`typescript
Num.percentage(25, 100); // "25%"
Num.percentage(33, 100, 2); // "33.00%"
Num.percentage(1, 3, 2); // "33.33%"
`

$3

Import: import { Enc } from '@devbro/neko-helper';

#### Hash Functions

`typescript
// MD5
Enc.hash.md5('hello world');
// "5eb63bbbe01eeed093cb22bb8f5acdc3"

// SHA-1
Enc.hash.sha1('hello world');
// "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"

// SHA-256
Enc.hash.sha256('hello world');
// "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"

// SHA-512
Enc.hash.sha512('hello world');
// "309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee..."

// SHA3-256
Enc.hash.sha3_256('hello world');
// "644bcc7e564373040999aac89e7622f3ca71fba1..."

// SHA3-512
Enc.hash.sha3_512('hello world');
// "840006653e9ac9e95117a15c915caab81662918e..."
`

#### JWT Operations

`typescript
// Sign JWT
const token = await Enc.jwt.sign({ userId: 123, role: 'admin' }, 'secret-key', { expiresIn: '1h' });

// Verify JWT
const payload = await Enc.jwt.verify(token, 'secret-key');
// { userId: 123, role: 'admin', iat: ..., exp: ... }

// Decode JWT (without verification)
const decoded = Enc.jwt.decode(token);
`

#### Bcrypt Password Hashing

`typescript
// Hash password
const hash = await Enc.bcrypt.encrypt('password123');
// "$2a$10$..."

// Verify password
const isValid = await Enc.bcrypt.compare('password123', hash);
// true

// Check if string is bcrypt hash
Enc.bcrypt.isHash(hash);
// true
`

#### Ed25519 Signatures

`typescript
// Generate key pair
const privateKey = Enc.ed25519.generatePrivateKey();
const publicKey = await Enc.ed25519.getPublicKey(privateKey);

// Sign message
const message = 'Hello, World!';
const signature = await Enc.ed25519.sign(message, privateKey);

// Verify signature
const isValid = await Enc.ed25519.verify(signature, message, publicKey);
// true
`

#### Random Generation

`typescript
// Random bytes
const bytes = Enc.random.bytes(32);
//

// Random hex string
const hex = Enc.random.hex(16);
// "a1b2c3d4e5f6..."

// Random UUID v4
const uuid = Enc.random.uuid();
// "550e8400-e29b-41d4-a716-446655440000"
`

#### Base64 Encoding

`typescript
// Encode to base64
const encoded = Enc.base64.encode('Hello, World!');
// "SGVsbG8sIFdvcmxkIQ=="

// Decode from base64
const decoded = Enc.base64.decode(encoded);
// "Hello, World!"

// URL-safe base64
const urlSafe = Enc.base64.encodeUrl('Hello, World!');
const urlDecoded = Enc.base64.decodeUrl(urlSafe);
`

$3

#### sleep(ms: number): Promise

Async delay function.

`typescript
import { sleep } from '@devbro/neko-helper';

console.log('Starting...');
await sleep(1000); // Wait 1 second
console.log('Done!');

// Use in async loops
for (const item of items) {
await processItem(item);
await sleep(100); // 100ms delay between items
}
`

$3

Type-safe event emitters with async support.

#### EventManager

`typescript
import { EventManager } from '@devbro/neko-helper';

type Events = ['userCreated', 'userDeleted', 'userUpdated'];

const events = new EventManager();

// Register event listeners
events.on('userCreated', (user) => {
console.log('User created:', user);
});

events.on('userCreated', async (user) => {
await sendWelcomeEmail(user);
});

// Emit events
await events.emit('userCreated', { id: 1, name: 'John' });

// Remove listener
const handler = (user) => console.log(user);
events.on('userCreated', handler);
events.off('userCreated', handler);
`

#### EventEmittorBase

Base class for creating event-driven classes.

`typescript
import { EventEmittorBase } from '@devbro/neko-helper';

type UserEvents = ['login', 'logout', 'register'];

class UserService extends EventEmittorBase {
async login(email: string, password: string) {
// Authentication logic
const user = { id: 1, email };

await this.emit('login', user);
return user;
}

async logout(userId: number) {
await this.emit('logout', userId);
}
}

const userService = new UserService();

userService.on('login', (user) => {
console.log('User logged in:', user.email);
});

await userService.login('user@example.com', 'password');
`

$3

#### Singleton Pattern

`typescript
import { createSingleton } from '@devbro/neko-helper';

class Database {
constructor(public connectionString: string) {
console.log('Database connected:', connectionString);
}
}

const getDatabase = createSingleton((label: string, connStr: string) => {
return new Database(connStr);
});

// Get singleton instance
const db1 = getDatabase('default', 'postgres://...');
const db2 = getDatabase('default', 'postgres://...');
console.log(db1 === db2); // true (same instance)

// Different label, different instance
const db3 = getDatabase('cache', 'redis://...');
console.log(db1 === db3); // false (different label)
`

#### Repeater Pattern

`typescript
import { createRepeater } from '@devbro/neko-helper';

const repeater = createRepeater(() => {
console.log('Running task...');
// Your periodic task
}, 5000); // Run every 5 seconds

repeater.start(); // Start repeating
// ... task runs every 5 seconds ...
repeater.stop(); // Stop repeating
`

#### Function Chaining

`typescript
import { chainer } from '@devbro/neko-helper';

const add = (x: number, y: number, z: number) => x + y + z;
const multiply = (x: number, y: number) => x * y;
const divide = (x: number, y: number) => x / y;

const result = await chainer(10)
.step(add, 5, 3) // 10 + 5 + 3 = 18
.step(multiply, 2) // 18 * 2 = 36
.step(divide, 4); // 36 / 4 = 9

console.log(result); // 9

// Works with async functions
const fetchUser = async (id: number) => ({ id, name: 'John' });
const sendEmail = async (user: any) => ({ sent: true, to: user.name });

const emailResult = await chainer(123).step(fetchUser).step(sendEmail);

console.log(emailResult); // { sent: true, to: 'John' }
`

#### Class Detection

`typescript
import { isClass } from '@devbro/neko-helper';

class MyClass {}
function myFunction() {}
const myArrow = () => {};

isClass(MyClass); // true
isClass(myFunction); // false
isClass(myArrow); // false
isClass({}); // false
`

$3

Factory pattern for dynamic object creation.

`typescript
import { FlexibleFactory } from '@devbro/neko-helper';

interface Animal {
speak(): string;
}

const animalFactory = new FlexibleFactory();

// Register constructors
animalFactory.register('dog', (name: string) => ({
speak: () => ${name} says Woof!,
}));

animalFactory.register('cat', (name: string) => ({
speak: () => ${name} says Meow!,
}));

// Create instances
const dog = animalFactory.create('dog', 'Buddy');
console.log(dog.speak()); // "Buddy says Woof!"

const cat = animalFactory.create('cat', 'Whiskers');
console.log(cat.speak()); // "Whiskers says Meow!"
`

$3

#### getEnv(key: string, defaultValue?: any): string

Safely access environment variables with optional defaults.

`typescript
import { getEnv } from '@devbro/neko-helper';

// With default value
const apiKey = getEnv('API_KEY', 'default-api-key');

// Without default (throws if not set)
const dbUrl = getEnv('DATABASE_URL');
// Throws: "process.env.DATABASE_URL is not defined"

// Usage in configuration
const config = {
port: parseInt(getEnv('PORT', '3000')),
host: getEnv('HOST', '0.0.0.0'),
nodeEnv: getEnv('NODE_ENV', 'development'),
apiKey: getEnv('API_KEY'),
};
`

$3

Utility types for TypeScript.

`typescript
import type { JSONValue, JSONObject, JSONArray } from '@devbro/neko-helper';

// JSON-compatible types
const data: JSONObject = {
name: 'John',
age: 30,
active: true,
tags: ['user', 'admin'],
metadata: {
created: '2026-01-31',
updated: null,
},
};

const items: JSONArray = [1, 'two', true, null, { key: 'value' }];

const value: JSONValue = 'can be any JSON-compatible value';
`

API Reference

$3

- intersperse(arr: T[], sep: S): (T | S)[]
- flatten(arr: T[][]): T[]
- crossJoin(arr1: T[], arr2: U[]): [T, U][]
- chunk(arr: T[], size: number): T[][]
- unique(arr: T[]): T[]
- groupBy(arr: T[], key: keyof T | Function): Record
- difference(arr1: T[], arr2: T[]): T[]
- intersection(arr1: T[], arr2: T[]): T[]
- shuffle(arr: T[]): T[]
- sample(arr: T[]): T
- sum(arr: number[]): number
- average(arr: number[]): number

$3

- abbreviate(num: number): string
- clamp(num: number, min: number, max: number): number
- currencyFormat(num: number, currency?: string): string
- fileSize(bytes: number): string
- ordinal(num: number): string
- toWords(num: number): string
- toRoman(num: number): string
- percentage(value: number, total: number, decimals?: number): string
- random(min: number, max: number): number
- round(num: number, decimals: number): number

$3

#### Hash

- hash.md5(data: string): string
- hash.sha1(data: string): string
- hash.sha256(data: string): string
- hash.sha512(data: string): string
- hash.sha3_256(data: string): string
- hash.sha3_512(data: string): string

#### JWT

- jwt.sign(payload: object, secret: string, options?: SignOptions): Promise
- jwt.verify(token: string, secret: string, options?: VerifyOptions): Promise