Advanced JavaScript Kit

> Modern TypeScript utility library with tree-shaking support - Comprehensive collection of array, string, number, network, sleep, and JWT utilities for JavaScript and TypeScript projects.


A collection of advanced JavaScript/TypeScript utility functions for modern development.

🌐 Environment Compatibility

This library is designed to work across multiple JavaScript environments with platform-specific exports:

- ✅ advanced-js-kit - Universal utilities that work in Node.js, Browser, and Web Workers
- 🟡 advanced-js-kit/node - Node.js-only utilities + all universal utilities
- 🟢 advanced-js-kit/browser - Browser-optimized utilities + all universal utilities
- 📦 Individual imports - advanced-js-kit/module/function for maximum tree-shaking

> Breaking Change (v1.1.0): Node.js-only modules (network, jwt) are no longer exported from the main package. Use advanced-js-kit/node instead.

Features

- 🚀 TypeScript Support - Full TypeScript support with type definitions
- 📦 Tree Shakable - Import only what you need
- 🧪 Well Tested - Comprehensive test coverage
- 📖 Well Documented - JSDoc comments for all functions
- 🔧 Modern Build - Built with tsup for optimal bundling
- 💡 Excellent IDE Support - Full auto-completion and IntelliSense support
- 🌐 Cross-Platform - Works in Node.js, browsers, and web workers

Installation

``bash
npm install advanced-js-kit
`

Alternative package managers:
`bash

Yarn

yarn add advanced-js-kit

pnpm

pnpm add advanced-js-kit

Bun

bun add advanced-js-kit
`

Usage

$3

For maximum compatibility, import universal modules that work in Node.js, Browser, and Web Workers:

`typescript
import { chunk, capitalize, clamp, sleep, convertToSeconds } from 'advanced-js-kit';

// Array utilities
const chunkedArray = chunk([1, 2, 3, 4, 5], 2);
// Result: [[1, 2], [3, 4], [5]]

// String utilities
const capitalizedString = capitalize('hello world');
// Result: "Hello world"

// Number utilities
const clampedNumber = clamp(15, 0, 10);
// Result: 10

// Sleep utilities
await sleep({ seconds: 2, milliseconds: 500 }); // Sleep for 2.5 seconds

// Time utilities
const seconds = convertToSeconds({ minutes: 5, seconds: 30 });
// Result: 330 (seconds)
`

$3

For Node.js-specific functionality (network operations, JWT handling):

`typescript
import { isPortInUse, findAvailablePort, jwtSign, jwtVerify } from 'advanced-js-kit/node';

// Network utilities (Node.js only)
const portInUse = await isPortInUse(3000);
const availablePort = await findAvailablePort({ startPort: 8000 });

// JWT utilities (Node.js only)
const token = jwtSign({ userId: '123' }, 'your-secret-key');
const payload = jwtVerify(token, 'your-secret-key');

// Note: Universal utilities are also available from /node for convenience
import { chunk, capitalize } from 'advanced-js-kit/node';
`

$3

For browser-specific optimizations (currently same as universal, but future-proof):

`typescript
import { chunk, capitalize, clamp, sleep, convertToSeconds } from 'advanced-js-kit/browser';

// Currently includes all universal utilities
// Future browser-specific features will be added here
`

$3

`typescript
import {
isNodeEnvironment,
EnvironmentError
} from 'advanced-js-kit';

// Check environment before using Node.js-only features
if (isNodeEnvironment()) {
// Use Node.js-specific imports
const { isPortInUse } = await import('advanced-js-kit/node');
const { jwtSign } = await import('advanced-js-kit/node');

const portInUse = await isPortInUse(3000);
const token = jwtSign({ userId: '123' }, 'secret');
} else {
console.log('Using browser-compatible features only');
// Use browser/universal imports
const { chunk, capitalize } = await import('advanced-js-kit/browser');
}
`

$3

`typescript
import { jwtVerify, EnvironmentError } from 'advanced-js-kit/node';

try {
const payload = jwtVerify(token, secret);
} catch (error) {
if (error instanceof EnvironmentError) {
console.log(Feature not available: ${error.message});
console.log(Required: ${error.requiredEnvironment}, Current: ${error.currentEnvironment});
}
}
`

$3

You can also import individual functions for optimal tree-shaking:

`typescript
// Universal utilities - individual imports
import { chunk } from 'advanced-js-kit/array/chunk';
import { capitalize } from 'advanced-js-kit/string/capitalize';
import { clamp } from 'advanced-js-kit/number/clamp';
import { sleep } from 'advanced-js-kit/sleep/sleep';
import { convertToSeconds } from 'advanced-js-kit/time/time';

// Node.js-only utilities - individual imports
import { isPortInUse, findAvailablePort } from 'advanced-js-kit/network/port';
import { jwtSign, jwtVerify } from 'advanced-js-kit/jwt/jwt';

// Platform-specific bundles (recommended)
import { chunk, capitalize, clamp } from 'advanced-js-kit'; // Universal only
import { isPortInUse, jwtSign, chunk } from 'advanced-js-kit/node'; // Node.js + Universal
import { chunk, capitalize, sleep } from 'advanced-js-kit/browser'; // Browser + Universal
`

📋 Available Modules

$3

| Module | Functions | Description |
|--------|-----------|-------------|
| array/chunk | chunk | Split arrays into chunks of specified size |
| string/capitalize | capitalize, capitalizeWords | String capitalization utilities |
| number/clamp | clamp, inRange | Number range utilities |
| sleep/sleep | sleep | Promise-based sleep with multiple time units |
| time/time | convertToSeconds | Time conversion utilities |
| utils/environment | isNodeEnvironment, isBrowserEnvironment, getEnvironment | Environment detection |

$3

| Module | Functions | Description |
|--------|-----------|-------------|
| network/port | isPortInUse, isPortAvailable, findAvailablePort | Port checking and management |
| jwt/jwt | jwtSign, jwtVerify | JSON Web Token operations |

> Note: Node.js-only modules will throw EnvironmentError when used in non-Node.js environments.

TypeScript Configuration

For optimal compatibility with this package, ensure your tsconfig.json uses modern module resolution:

`json
{
"compilerOptions": {
"moduleResolution": "bundler", // or "node16"/"nodenext"
"module": "ESNext", // or "Node16"
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"skipLibCheck": true
}
}
`

$3

If you encounter module resolution errors like:
`
Cannot find module 'advanced-js-kit/string/capitalize' or its corresponding type declarations
`

Try these solutions:

1. Update your TypeScript configuration to use modern module resolution (see above)
2. Ensure you're using a recent Node.js version (16+ recommended)
3. Copy the example configuration from example-tsconfig-for-consumers.json in this package
4. As a workaround, you can import directly from the dist folder:
`typescript
import { capitalize } from "advanced-js-kit/dist/string/capitalize.js";
`

$3

This package provides excellent IDE support with:
- Auto-completion for all functions and their parameters
- Type checking with full TypeScript support
- JSDoc documentation shown in hover tooltips
- Auto-import suggestions when typing function names

API Reference

$3

For comprehensive documentation with examples, advanced usage patterns, and best practices, see the individual package documentation:

- 🔢 Array Utilities - Array manipulation and chunking utilities
- 🌐 Network Utilities - Port management and connectivity testing
- 🔢 Number Utilities - Number clamping and range validation
- ⏰ Sleep Utilities - Advanced sleep and timing functions
- 📝 String Utilities - String manipulation and formatting
- 🔐 JWT Utilities - JSON Web Token operations

$3

#### Array Utilities
- chunk(array: T[], size: number): T[][] - Splits an array into chunks of a specified size

#### String Utilities
- capitalize(str: string): string - Capitalizes the first letter of a string
- capitalizeWords(str: string): string - Capitalizes the first letter of each word

#### Number Utilities
- clamp(number: number, lower: number, upper: number): number - Clamps a number within bounds
- inRange(number: number, lower: number, upper: number): boolean - Checks if number is in range

#### Sleep Utilities
- sleep(params: TSleepParams): Promise - Advanced sleep with flexible options
- sleepMs(ms: number): Promise - Sleep for milliseconds
- sleepSeconds(seconds: number): Promise - Sleep for seconds
- sleepMinutes(minutes: number): Promise - Sleep for minutes
- sleepUntil(unixTimestamp: number): Promise - Sleep until timestamp

#### Network Utilities
- isPortInUse(port: number, options?): Promise - Check if port is in use
- isPortAvailable(port: number, options?): Promise - Check if port is available
- findAvailablePort(options?): Promise - Find an available port
- checkMultiplePorts(ports: number[], options?): Promise> - Check multiple ports
- waitForPort(port: number, state: string, options?): Promise - Wait for port state

#### JWT Utilities
- jwtSign(payload: T, secret: string, options?): Promise - Sign JWT token
- jwtVerify(token: string, secret: string, options?): Promise - Verify JWT token
- jwtDecode(token: string, options?): T | null - Decode JWT without verification
- jwtIsExpired(token: string): boolean | null - Check if token is expired
- jwtTimeUntilExpiry(token: string): number | null - Get time until expiration

Development

`bash

Install dependencies

npm install

Build the project

npm run build

Watch mode for development

npm run dev

Type checking

npm run type-check

Run tests

npm run test
``

License

MIT