@dxkit-org/node-js-kit/README.md

Modern TypeScript utility library for Node.js - Network and JWT utilities for server-side JavaScript and TypeScript projects

# DXKit Node.js Kit

> **Modern TypeScript utility library for Node.js** - Specialized collection of network and JWT utilities for Node.js projects.

[![npm version](https://badge.fury.io/js/@dxkit-org/node-js-kit.svg)](https://www.npmjs.com/package/@dxkit-org/node-js-kit)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Tree Shakable](https://img.shields.io/badge/Tree--Shakable-✓-brightgreen.svg)](https://webpack.js.org/guides/tree-shaking/)

A collection of advanced Node.js-specific JavaScript/TypeScript utility functions for server-side development.

## 🌐 Node.js Focused

This library is designed specifically for **Node.js environments** and provides specialized server-side utilities:

- **� `@dxkit-org/node-js-kit`** - Core Node.js utilities (network, JWT)
- **📦 Individual imports** - `@dxkit-org/node-js-kit/module/function` for maximum tree-shaking

> **Note**: This is a Node.js-focused package. For universal utilities that work across Node.js, Browser, and Web Workers, check out `@dxkit-org/js-kit`.

## 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
- 🖥️ **Node.js Optimized** - Specialized for server-side development

## Installation

```bash
npm install @dxkit-org/node-js-kit
```

**Alternative package managers:**

```bash
# Yarn
yarn add @dxkit-org/node-js-kit

# pnpm
pnpm add @dxkit-org/node-js-kit

# Bun
bun add @dxkit-org/node-js-kit
```

## Usage

### Node.js Network and JWT Utilities

This package provides specialized Node.js utilities for network operations and JWT handling:

```typescript
import {
  isPortInUse,
  findAvailablePort,
  jwtSign,
  jwtVerify,
} from "@dxkit-org/node-js-kit"

// Network utilities
const portInUse = await isPortInUse(3000)
const availablePort = await findAvailablePort({ startPort: 8000 })

// JWT utilities
const token = jwtSign({ userId: "123" }, "your-secret-key")
const payload = jwtVerify(token, "your-secret-key")
```

### Individual Module Imports

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

```typescript
// Network utilities - individual imports
import { isPortInUse, findAvailablePort } from "@dxkit-org/node-js-kit/network"

// JWT utilities - individual imports
import { jwtSign, jwtVerify } from "@dxkit-org/node-js-kit/jwt"
```

## 📋 Available Modules

### 🟡 Node.js Modules

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

## 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
  }
}
```

## API Reference

### 📚 Package Documentation

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

- **[🌐 Network Utilities](./src/network/network.md)** - Port management and connectivity testing
- **[ JWT Utilities](./src/jwt/jwt.md)** - JSON Web Token operations

### Quick Reference

#### Network Utilities

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

#### JWT Utilities

- `jwtSign<T>(payload: T, secret: string, options?): Promise<string>` - Sign JWT token
- `jwtVerify<T>(token: string, secret: string, options?): Promise<T | null>` - Verify JWT token
- `jwtDecode<T>(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