ContextJS

Overview

A modular, test-driven TypeScript ecosystem built on object-oriented design and zero-runtime dependencies.

Getting Started

Install the CLI and Templates globally:

npm i -g @contextjs/context @contextjs/templates

Create a new project:

ctx new api my-app
cd my-app
ctx build

Core Packages

Package	Description
@contextjs/system	Foundation utilities: Console, Exception, Throw, VersionService, argument parsing, and string/object extensions
@contextjs/di	Dependency injection container with interface-based registration, constructor metadata via AST transformers, and scoped lifetimes
@contextjs/compiler	TypeScript build engine with transformer merging, diagnostic reporting, and extension-ready build() and watch() flows
@contextjs/context	Official CLI tool (ctx) supports full TypeScript flag passthrough and custom extensions
@contextjs/templates	Project templates for rapid scaffolding and development
@contextjs/commands	Command-line utilities for managing ContextJS projects

Collections & IO

Package	Description
@contextjs/collections	Generic, high-performance data structures: List, Queue, Stack, Dictionary, HashSet
@contextjs/io	Filesystem abstraction with File, Directory, async read/write, and path utilities

Text

Package	Description
@contextjs/text	String manipulation utilities, including a segment-based StringBuilder with fluent chaining, formatting, and cloning support

Configuration

Package	Description
@contextjs/configuration	Configuration abstraction layer with a unified provider interface
@contextjs/configuration-json	JSON configuration provider that loads environment-aware settings with fallback support

Routing

Package	Description
@contextjs/routing	Advanced router supporting literal, parameter, optional, and wildcard segments with a scoring-based matcher

Web Server

Package	Description
@contextjs/webserver	High-performance, TypeScript-first HTTP/HTTPS server built directly on raw TCP sockets for maximum throughput, and zero runtime dependencies. Supports HTTP/2 with automatic HTTP/1.1 fallback, pooled contexts for minimal GC, and a robust middleware pipeline.
@contextjs/webserver-middleware-static	Static files middleware for the ContextJS WebServer
@contextjs/webserver-middleware-cookies	Middleware for ContextJS WebServer that transparently handles HTTP cookies in requests and responses.
@contextjs/webserver-middleware-controllers	Controllers middleware for the ContextJS webserver.

Ecosystem Principles

• Modular structure: All packages expose public APIs via api/index.ts
• Test coverage: 100% unit test coverage enforced across all packages (node:test)
• Test design: Structured by class/method using context.assert
• Documentation: All modules include clean README files with badges, usage, and API references
• Extensibility: Compiler and CLI support transformers and extensions (internal and external)
• Transformers: Auto-discovered from .transformers/ folders and injected at compile time

All packages follow MIT licensing and are actively maintained under the ContextJS GitHub organization.

WebServer Benchmarks

Below are the results of our WebServer benchmark suite, which compares throughput and latency across four different Node.js–based HTTP servers. Each test is run on GitHub Actions' provided "ubuntu-latest" runner. The benchmarks target a minimal server that responds with a 200 OK status and a short body of "OK" They use 500 concurrent connections, a pipelining factor of 1, and run for 10 seconds, with a warmup phase, and results averaged over three runs.

Summary

Server	Req/sec	Latency (ms)	Throughput (MB/s)	Errors
ContextJS	15492.53	31.97	2.76	0.00
Node.js Raw HTTP	14793.33	33.51	2.64	0.00
Fastify	13884.27	35.80	2.48	0.00
Express	8942.94	55.93	2.14	0.00

Column descriptions:

• Req/sec — Average number of HTTP requests served per second.
• Latency (ms) — Median (50th percentile) response time in milliseconds.
• Throughput (MB/s) — Average data transferred per second.
• Errors — Total connection-level failures (e.g. resets, refusals).

Extended Metrics

Server	Connections	Pipelining	Duration (s)	Latency Stdev (ms)	Requests Stdev	Throughput Stdev (MB/s)	Total Requests
ContextJS	500	1	10.07	102.32	258.50	0.05	464750
Node.js Raw HTTP	500	1	10.08	109.54	198.34	0.04	443750
Fastify	500	1	10.10	121.67	174.27	0.03	416500
Express	500	1	10.15	237.23	191.14	0.05	268250

Extended column descriptions:

• Connections — Number of simultaneous TCP connections opened.
• Pipelining — Number of requests pipelined per connection.
• Duration (s) — Total benchmark runtime in seconds.
• Latency Stdev (ms) — Standard deviation of response latency.
• Requests Stdev — Standard deviation of the requests/sec across samples.
• Throughput Stdev (MB/s) — Standard deviation of throughput.
• Total Requests — Sum of all successful 2xx responses across all iterations.