@darthcav/ts-utils

A collection of utility functions for TypeScript applications and modules.

API Documentation

Features

• Native TypeScript execution (Node.js type stripping, no transpiler needed at runtime)
• Strict TypeScript configuration with isolated declarations
• Biome for linting and formatting
• Built-in Node.js test runner
• TypeDoc for API documentation
• GitHub Actions CI/CD workflows

Installation

npm install @darthcav/ts-utils

Usage

getConsoleLogger

Configures logging and returns a Logger for the given category name. Records at or above lowestLevel are written to the console using an ANSI color formatter with RFC 3339 timestamps. The internal logtape/meta logger is silenced.

import { getConsoleLogger, main } from "@darthcav/ts-utils"

const logger = await getConsoleLogger("my-app")

main("my-app", logger, () => {
    logger.info(`Application is running`)
    // start servers, connect to databases, etc.
})

Pass a second argument to change the minimum log level (defaults to "info"):

const logger = await getConsoleLogger("my-app", "debug")

monitorMemory

Starts a periodic interval that logs process uptime and memory usage (in bytes). The interval defaults to every 24 hours.

import { getConsoleLogger, main, monitorMemory } from "@darthcav/ts-utils"

const logger = await getConsoleLogger("my-app")

main("my-app", logger, () => {
    monitorMemory(logger)      // every 24 hours
    monitorMemory(logger, 1)   // every hour
})

millisecondsToString

Converts a duration in milliseconds to a human-readable string. Sub-second values are rounded to the nearest second. Leading zero components are omitted except for seconds, which are always included.

import { millisecondsToString } from "@darthcav/ts-utils"

millisecondsToString(3_661_000) // "1h 1m 1s"
millisecondsToString(90_000)    // "1m 30s"
millisecondsToString(5_000)     // "5s"

noop

A no-op function that does nothing and returns void. Useful as a placeholder callback or default handler.

import { noop } from "@darthcav/ts-utils"

setTimeout(noop, 1000)
element.addEventListener("click", noop)

getDummyLogger

Returns a no-op Logger useful as a placeholder in tests. All logging methods are no-ops and isEnabledFor always returns false. getChild and with return the same dummy logger instance.

import { getDummyLogger } from "@darthcav/ts-utils"

const logger = getDummyLogger()
// use logger in tests without any console output

main

Bootstraps an application process: logs startup information, optionally registers handlers for SIGINT and SIGTERM (controlled by defaultInterruptionHandler, defaults to true), always registers handlers for uncaughtException and unhandledRejection, then delegates to an optional launcher function.

The three optional parameters — launcher (function), monitorMemoryHours (number, defaults to 0), and defaultInterruptionHandler (boolean, defaults to true) — have distinct types. Any subset can be passed in order and the function resolves each by type, so middle parameters can be omitted:

import { getLogger } from "@logtape/logtape"
import { main } from "@darthcav/ts-utils"

const logger = getLogger(["my-app"])

main("my-app", logger)                            // all defaults
main("my-app", logger, () => startServer())       // launcher only
main("my-app", logger, 2)                         // monitor every 2h
main("my-app", logger, false)                     // disable SIGINT/SIGTERM handler
main("my-app", logger, () => startServer(), 2)    // launcher + monitor
main("my-app", logger, () => startServer(), false)// launcher + no handler
main("my-app", logger, 2, false)                  // monitor + no handler
main("my-app", logger, () => startServer(), 2, false) // all three

For the full API reference see the API Documentation.

Development

# Install dependencies
npm install

# Type-check
npm run typecheck

# Build (compile to JavaScript)
npm run build

# Run tests
npm test

# Lint and format
npm run lint
npm run lint:fix

# Generate documentation
npm run doc

Project Structure

src/
  index.ts          # Public API entry point
  main.ts           # Main module
  noop.ts           # No-op function
  loggers/          # Logger utilities
  __tests__/        # Test files
dist/               # Compiled output (generated)
public/             # Documentation output (generated)

License

Apache-2.0