@isdk/util

Utility Functions

This package provides a set of utility functions.

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):

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:

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):

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

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

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)

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

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

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.