@contextjs/system NPM

@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.