context

At a Glance

Why

Modern development requires running code across different environments (Node.js, browsers, Deno, etc.). Managing execution boundaries manually is error-prone and creates tight coupling.

Benefit

Provides a unified abstraction layer that handles runtime differences automatically, enabling truly portable code that works across environments without modification.

For

Library authors, tool builders, and teams building portable systems that need to work across multiple JavaScript/TypeScript runtimes without environment-specific code.

Use

Import the context layer in your code, write against its unified API, and deploy to any supported runtime. The layer handles adaptation and compatibility concerns.

Architecture

Context Diagram

How context interacts with the surrounding environment:

┌─────────────────────────────────────────────────────────────┐
│                        Developer                            │
│                    (writes portable code)                   │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ uses unified API
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                       context                               │
│                  (execution boundary)                       │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Adapters   │  │   Runtime    │  │  Capability  │     │
│  │              │  │   Detection  │  │   Registry   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└───┬──────────────┬──────────────┬──────────────┬───────────┘
    │              │              │              │
    ▼              ▼              ▼              ▼
┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
│ Node.js│    │Browser │    │  Deno  │    │  Bun   │
└────────┘    └────────┘    └────────┘    └────────┘

Internal Architecture

Key modules inside context:

┌─────────────────────────────────────────────────────────────┐
│                       context Core                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌───────────────────────────────────────────────────┐     │
│  │             Runtime Detection                     │     │
│  │  • Identifies current environment                 │     │
│  │  • Feature capability checks                      │     │
│  │  • Version compatibility matrix                   │     │
│  └───────────────┬───────────────────────────────────┘     │
│                  │                                          │
│                  ▼                                          │
│  ┌───────────────────────────────────────────────────┐     │
│  │             Adapter Layer                         │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐        │     │
│  │  │   I/O    │  │   FS     │  │   HTTP   │        │     │
│  │  │ Adapter  │  │ Adapter  │  │ Adapter  │  ...   │     │
│  │  └──────────┘  └──────────┘  └──────────┘        │     │
│  └───────────────┬───────────────────────────────────┘     │
│                  │                                          │
│                  ▼                                          │
│  ┌───────────────────────────────────────────────────┐     │
│  │          Unified API Interface                    │     │
│  │  • Consistent method signatures                   │     │
│  │  • Standardized error handling                    │     │
│  │  • Promise-based async operations                 │     │
│  └───────────────────────────────────────────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

How to Use

1. Install the package Add context to your project using your preferred package manager: npm install @gitbrainlab/context
2. Import the context layer Import the unified API in your code: import { context } from '@gitbrainlab/context';
3. Write portable code Use the context API instead of runtime-specific APIs. For example, use context.fs.readFile() instead of Node's fs.readFile or Deno's Deno.readTextFile.
4. Deploy anywhere Your code now works across Node.js, browsers, Deno, and other supported runtimes without modification.
5. Extend with adapters Add custom adapters for specialized functionality or new runtime environments as needed.

Related Projects