Utilities Overview

io-oidis-commons provides a comprehensive set of utility classes that handle common programming tasks with null-safety, consistent APIs, and edge-case handling. These utilities are available on both frontend and backend unless noted otherwise.

Package: io-oidis-commons

Quick Selection Guide

Task	Use	Not
Check for null/empty/undefined	ObjectValidator.IsEmptyOrNull()	=== null, typeof x
Convert string ↔ number ↔ boolean	Convert	parseInt(), Number()
Format, split, search strings	StringUtils	Manual regex or .split()
Deep merge or clone objects	JsonUtils.Extend(), JsonUtils.Clone()	Object.assign(), spread
Log for development/debugging	LogIt	console.log()
Log for audit trail (persisted)	SystemLog	LogIt (not persisted)
Run child processes	Terminal.Execute()	child_process.exec()
Read/write files	FileSystemHandler	fs.readFileSync()
Measure execution time	Stopwatch	Date.now()
Yield to the event loop in a long loop	TimeoutManager.YieldToIO(), .Map(), .ForEach()	tight for / for await over big data
Validate JSON schemas	SchemaValidator	Manual checks

Core Utilities

Utility	Purpose	Page
LogIt & SystemLog	Development logging (LogIt) and persistent audit trail (SystemLog)	Logging
ObjectValidator	Null-safe type checking — IsEmptyOrNull, IsSet, IsString, IsDigit, IsArray, and more	ObjectValidator
StringUtils	String manipulation — search, replace, split, format, hash, case conversion, version comparison	StringUtils
JsonUtils	Object operations — deep merge, clone, JSONP generation, binary serialization	JsonUtils
Convert	Type conversion — string/number/boolean parsing, date boundaries, time formatting, encoding, math	Convert
Echo	Screen output — formatted printing to HTML elements or custom handlers, stream capture	Echo
Stopwatch	Performance timing — start/stop/restart, elapsed time measurement, block timing	Stopwatch
Reflection	Runtime OOP metadata — class discovery, hierarchy inspection, type checking, dynamic instantiation, @Partial resolution	Reflection
PersistenceHandler	Cross-environment persistent key-value storage — auto-selects localStorage or cookies, CRC integrity, complex object serialization	PersistenceHandler
Property	Combined getter/setter helpers — null-safe, auto-coercing, range-validating. The standard pattern for all model and args properties	Property
TimeoutManager	Timing and event-loop cooperation — Sleep, YieldToIO, and the yielding ForEach/Map helpers that keep long in-memory loops from starving the event loop	TimeoutManager

Backend Utilities

These utilities are available only on the backend (Node.js) and provide infrastructure-level functionality.

Utility	Purpose	Page
Terminal	Cross-platform child process execution — Execute, Spawn, Elevate, Open, Kill, and async variants. Never use child_process directly.	Terminal
CSVHandler	CSV import/export with encoding support — wraps the csv npm package with Windows-1250 defaults	CSVHandler
FileSystemHandler	Cross-platform file I/O, directory operations, glob matching, HTTP downloads, and archive management (ZIP/TAR)	FileSystemHandler
LogProcessor	Server-side logging with pluggable adapters — Std, File, JSON, and Sentry — plus automatic path anonymization	LogProcessor
CertsManager	TLS certificate management with ACME (Let's Encrypt) integration and automatic renewal	CertsManager
Cron	Task scheduling using cron expressions with node-cron — recurring tasks, master stop, remote control	Cron
Firewall	Windows firewall rule management — registers inbound service rules via netsh.exe	Firewall
Metrics	Server metrics collection and APM reporting via Elastic APM — HTTP/WebSocket traffic statistics	Metrics
SchemaValidator	JSON schema validation for configuration files and runtime data — backed by z-schema	SchemaValidator
StringReplace	Token replacement engine for HTML, JS, and CSS — variable interpolation, file imports, and iteration	StringReplace
Events	Server-side event infrastructure — EventsManager for HTTP request wiring and lifecycle events	Events

Supporting Utilities

These smaller utilities serve specific infrastructure needs. They are used internally by the framework and occasionally by application code.

TraceBack

Captures and parses JavaScript stack traces into structured call-site objects. Used internally by LogIt and SystemLog for caller identification.

import { TraceBack } from "@io-oidis-commons/.../Utils/TraceBack.js";

// Capture the current call site (who called this method?)
const entry = TraceBack.CaptureEntry();
// entry.at   → "Io.Oidis.MyProject.MyClass.MyMethod"
// entry.from → "Io.Oidis.MyProject.OtherClass.Caller"

// Parse an Error stack trace into structured objects
const sites = TraceBack.Parse(new Error());
sites.forEach(($site) => {
    LogIt.Info($site.getFileName(), $site.getLineNumber());
});

Key methods: CaptureEntry($offset?, $infinityTrace?), getTrace(), Parse($error)

Counters

Global named counter registry for generating sequential IDs or tracking invocation counts.

import { Counters } from "@io-oidis-commons/.../Utils/Counters.js";

const id1 = Counters.getNext("Invoice");  // → 1
const id2 = Counters.getNext("Invoice");  // → 2
const id3 = Counters.getNext("Order");    // → 1 (separate counter)

Counters.Clear("Invoice");  // Reset "Invoice" counter
Counters.Clear();           // Reset all counters

Key methods: getNext($owner), Clear($owner?)

EnvironmentHelper

Re-exports global runtime environment variables from globalThis for centralized access.

import { isBrowser, buildTime } from "@io-oidis-commons/.../Utils/EnvironmentHelper.js";

if (isBrowser) {
    // Running in browser — safe to access DOM
} else {
    // Running in Node.js — safe to access fs, process, etc.
}

LogIt.Info("Build:", buildTime);

Exports: isBrowser : boolean, buildTime : string, appExceptionHandler

FileSystemFilter

Enumeration utility for composing file system filter strings. Used with Oidis file system operations to specify which items to include.

import { FileSystemFilter } from "@io-oidis-commons/.../Utils/FileSystemFilter.js";

// Pre-defined filters
FileSystemFilter.ALL              // "*"
FileSystemFilter.DIRECTORIES      // Directories only
FileSystemFilter.HIDDEN_ALL       // Including hidden items

// Compose custom filters
const filter = FileSystemFilter.Create("*.ts", "*.js");

Key methods: Create(...$options) — concatenates filter options with | delimiter

ReflectionEmitter

Provides dynamic class/module registration into the global namespace tree. Used by Loader.ts and ForceCompile.ts to register classes at runtime.

import { ReflectionEmitter } from "@io-oidis-commons/.../Utils/ReflectionEmitter.js";

// Synchronous registration
ReflectionEmitter.RegisterSync("Io.Oidis.MyProject.MyClass", MyClass);

// Async registration (dynamic import)
await ReflectionEmitter.Register("Io.Oidis.MyProject.LazyClass");

Key methods: Register($namespace, $class?) (async), RegisterSync($namespace, $class) (sync)

tip

ReflectionEmitter populates the global namespace tree that Reflection then queries. In most projects, you interact with this indirectly through Loader.ts and ForceCompile.ts — direct use is rare.

---

See also: Architecture Overview | Vanilla vs Framework