@contextjs/system

A zero-dependency system utility library for the ContextJS ecosystem, providing application lifecycle, environment detection, console formatting, exception handling, property extraction (nameof()), and core extensions — all written with full type safety.

Features

• Application lifecycle management with onRun() hooks
• Environment detection with development/production/test/staging support
• Console formatting with ANSI styles and argument parsing
• Typed exceptions like NullReferenceException and InvalidExpressionException
• Safe property extraction via nameof() for both lambdas and keys
• Core helpers for object and string manipulation with type guards
• Type-safe utility Throw guard methods
• Fully tested, 100% coverage, no dependencies

Installation

npm i @contextjs/system

Quick Start

1. Run an application

import { Application } from '@contextjs/system';

const app = new Application();

app.onRun(async () => {
    console.log("App booted");
});

await app.runAsync();

2. nameof() Example

import { Application, nameof } from '@contextjs/system';

const app = new Application();

class User {
    name: string = 'John Doe';
    age: number = 30;
}

class Config {
    port: number = 3000;
    host: string = 'localhost';
}

const user = new User();

const property = nameof(() => user.name); // "name"
const key = nameof<Config>('port');       // "port"

app.onRun(async () => {
    console.log("App is running");
    console.log(`User name: ${user.name}`);
    console.log(`User age: ${user.age}`);
});

await app.runAsync();

Console Formatting

import { Console } from "@contextjs/system";

Console.writeLineSuccess('✔ Success');
Console.writeLineWarning('⚠ Warning');
Console.writeLineError('✖ Error');
Console.writeLineInfo('ℹ Info');

Console.writeLineFormatted({ format: ['bold', 'green'], text: 'Styled' });

Common Utilities

Guard with Throw

import { Application, StringExtensions, Throw } from "@contextjs/system";

const name = StringExtensions.empty;
const configPath = "config.json";
const obj = { key: "value" };

const app = new Application();

app.onRun(async () => {
    Throw.ifNullOrWhiteSpace(name);
    Throw.ifNullOrEmpty(configPath);
    Throw.ifNull(obj);
});

await app.runAsync();

Use string helpers

import { StringExtensions } from "@contextjs/system";

const value = "a b c ";

StringExtensions.removeWhiteSpaces(value);
console.log(StringExtensions.isNullOrWhitespace(value));

Check object null state

import { ObjectExtensions } from "@contextjs/system";

const value: string = "Hello, World!";

if (!ObjectExtensions.isNullOrUndefined(value)) {
    // TypeScript will narrow the type
    console.log(value);
}

Testing

This library is fully covered with unit tests using Node's native test module.

Test coverage includes:

• Environment parsing
• Console formatting
• String/object helpers
• Exception and guard behavior
• Version display
• Application lifecycle execution
• Property name extraction via nameof()

Philosophy

@contextjs/system is built to be the minimal core foundation for higher-level libraries in the ContextJS ecosystem. It provides safe, strongly-typed primitives that you can rely on without reflection, decorators, or external dependencies.

API Reference

For detailed API documentation, please refer to the API Reference.