# @isdk/util

> a set of utility functions

Latest version **0.3.13** (published 2026-10-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install @isdk/util
pnpm add @isdk/util
yarn add @isdk/util
bun add @isdk/util
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.13 |
| Published | 2026-10-09 |
| First published | 2025-03-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 7 |
| Unpacked size | 796.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Riceball LEE @snowyu |
| Maintainers | isdk |

## Links

- npm: https://www.npmjs.com/package/@isdk/util
- Repository: isdk/util.js
- Homepage: https://github.com/isdk/util.js
- Issues: https://github.com/isdk/util.js/issues
- npm.io page: https://npm.io/package/@isdk/util

## Dependencies (7)

- [yaml](https://npm.io/package/yaml.md) ^2.9.0
- [util-ex](https://npm.io/package/util-ex.md) ^2.7.1
- [events-ex](https://npm.io/package/events-ex.md) ^2.4.3
- [lodash-es](https://npm.io/package/lodash-es.md) ^4.18.1
- [@isdk/glob](https://npm.io/package/@isdk/glob.md) ^0.1.2
- [load-config-file](https://npm.io/package/load-config-file.md) ^2.1.0
- [@isdk/common-error](https://npm.io/package/@isdk/common-error.md) ^0.2.2

## Recent versions

- 0.3.13 (latest) — 2026-10-09
- 0.3.12 — 2026-09-09
- 0.3.11 — 2026-07-08
- 0.3.10 — 2026-06-26
- 0.3.9 — 2026-03-08
- 0.3.8 — 2026-03-05
- 0.3.7 — 2026-02-16
- 0.3.6 — 2026-02-13
- 0.3.5 — 2026-02-13
- 0.3.4 — 2026-01-29
- 0.3.3 — 2025-11-09
- 0.3.2 — 2025-08-02
- 0.3.1 — 2025-05-13
- 0.3.0 — 2025-03-31
- 0.2.0 — 2025-03-31
- … 6 more at https://npm.io/package/@isdk/util/versions

## README

# Utility Functions

This package provides a set of utility functions.

[![Version](https://img.shields.io/npm/v/@isdk/util.svg)](https://npmjs.org/package/@isdk/util)
[![Downloads/week](https://img.shields.io/npm/dw/@isdk/util.svg)](https://npmjs.org/package/@isdk/util)

## Browser Support

This package works in both Node.js and browser environments. All 23 modules are available in browsers via native implementations or lightweight shims.

### Import Patterns

**1. Automatic bundler resolution (recommended):**

```ts
import { sleep, Deque, ConfigFile, findPort } from '@isdk/util'
```

When your bundler (webpack, Vite, Rollup, esbuild, etc.) targets a browser environment, it automatically picks the browser build via the `browser` field in `package.json`. No special configuration needed.

**2. Explicit browser entry:**

```ts
import { sleep, Deque, ConfigFile, findPort } from '@isdk/util/browser'
```

Use this when you want to explicitly import the browser build, or when using a runtime that doesn't respect the `browser` field.

**3. Direct ESM import (CDN):**

```ts
import { sleep } from 'https://cdn.jsdelivr.net/npm/@isdk/util@latest/dist/browser.mjs'
```
> **Note:** CDN imports are for quick prototyping. For production, pin a specific version (e.g., `@0.3.10`).

### Usage Examples

#### Basic utilities

```ts
import { sleep, Deque, IntSet } from '@isdk/util'

// Sleep
await sleep(1000)

// Double-ended queue
const queue = new Deque<number>([1, 2, 3])
queue.push(4)
const item = queue.shift() // 1

// Integer bit-field set
const set = new IntSet()
set.add(0).add(2).add(4)
set.has(2) // true
```

#### String utilities

```ts
import { toCamelCase, toPascalCase, toCapitalCase } from '@isdk/util'

toCamelCase('hello-world')    // 'helloWorld'
toPascalCase('hello-world')   // 'HelloWorld'
toCapitalCase('hello_world')  // 'Hello World'
```

#### In-memory configuration file (ConfigFile)

```ts
import { ConfigFile } from '@isdk/util'

// Save a config to in-memory storage
ConfigFile.saveSync('app.config.yaml', { name: 'my-app', version: 2 })

// Check if it exists
ConfigFile.existsSync('app.config.yaml') // true

// Load it back
const config = ConfigFile.loadSync('app.config.yaml')
console.log(config.name) // 'my-app'
```

#### Virtual folder traversal

```ts
import {
  VirtualFileSystem,
  traverseFolder,
  type BrowserDirent,
} from '@isdk/util'

// Set up a virtual directory structure
VirtualFileSystem.register('/project', [
  { name: 'src', isFile: () => false, isDirectory: () => true },
  { name: 'package.json', isFile: () => true, isDirectory: () => false },
])
VirtualFileSystem.register('/project/src', [
  { name: 'index.ts', isFile: () => true, isDirectory: () => false },
  { name: 'utils.ts', isFile: () => true, isDirectory: () => false },
])

// Traverse it
await traverseFolder('/project', (filePath, entry) => {
  console.log(entry.isDirectory() ? '[DIR]' : '[FILE]', filePath)
})
// Output:
// [DIR]  /project/src
// [FILE] /project/package.json
// [FILE] /project/src/index.ts
// [FILE] /project/src/utils.ts
```

#### Port validation

```ts
import { findPort } from '@isdk/util'

// Validate a specific port
await findPort(3000)     // 3000
await findPort(70000)   // throws 'Port out of range: 70000'

// Get a random port
await findPort(0)        // e.g., 42153
await findPort()         // e.g., 18734
```

### Module Availability

All modules work in both environments. Some use browser-compatible shims where Node.js APIs don't exist:

| Module | Browser Notes |
|--------|---------------|
| `array-has-all` | — |
| `async-semaphore` | Uses `events-ex` (browser-friendly) |
| `async-signal-gate` | — |
| `config-file` | Uses in-memory `Map` storage instead of filesystem |
| `deque` | — |
| `extract-code-block` | — |
| `filename` | Native path operations; no `path` dependency |
| `find-port` | Validates port number, no actual TCP |
| `front-matter` | — |
| `get-multi-level-extname` | Native path operations; no `path` dependency |
| `glob` | Native path operations; no `path` dependency |
| `include-files` | — |
| `intset` | — |
| `is-string-in` | — |
| `omit-deep-by` | — |
| `omit-empty-deep` | — |
| `remove-leading-empty-lines` | — |
| `sleep` | `yieldExec` uses `setImmediate` fallback |
| `to-camel-case` | — |
| `to-pascal-case` | — |
| `to-capital-case` | — |
| `traverse-folder` | Uses in-memory `VirtualFileSystem` |
| `yaml` | — |

### Browser-Specific Behavior

- **`ConfigFile`**: Uses an in-memory `Map` as the backing store instead of the filesystem. Data is not persisted between page reloads. Supports `.yml`, `.yaml`, and `.json` formats by default.

- **`findPort`**: Validates the port number and returns it. Since there is no TCP stack in the browser, `port: 0` returns a random port number, and options like `host` and `retryCount` are accepted but ignored.

- **`traverseFolder` / `traverseFolderSync`**: Uses `VirtualFileSystem` to simulate directory traversal. Register directories and files with `VirtualFileSystem.register()` before traversing.

- **`yieldExec`**: Uses `setImmediate` when available (Node.js) and falls back to `setTimeout(fn, 0)` in browsers.

- **`filename`**: All path operations are implemented natively without relying on Node's `path` module. Both Unix (`/`) and Windows (`\\`) path separators are detected and handled automatically.

- **`getMultiLevelExtname` and `glob`**: Path operations (`extname`, `basename`, `relative`) are implemented inline without the `path` module dependency.

---
_Source: https://npm.io/package/@isdk/util · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._