@octovel/environment

A lightweight and cross-platform Node.js library to safely interact with the system, user, and process environment through a unified, type-safe API.

Classes

• UserEnvironment – Manage user-specific environment variables.
• SystemEnvironment – Manage system-specific environment variables.
• ProcessRegistry – Track and manage active child processes.
• ProcessManager – Manage environment variables with hooks, temporary/conditional values, and hashing.
• ProcessController – Control and manage processes.

This library also provides some types to work with environment variables, and provided classes through the API.

Documentation

• UserEnvironment Guide
• SystemEnvironment Guide
• ProcessRegistry Guide
• ProcessManager Guide
• ProcessController Guide

Features

• Type-safe API for all environment operations
• Hooks for add, update, delete, and clear events
• Temporary and conditional variables
• Hashing/encryption support for sensitive values
• Cross-platform support: Windows, Linux, macOS

Getting Started

Install via your preferred package manager:

npm install @octovel/environment
# or
yarn add @octovel/environment
# or
pnpm add @octovel/environment

Examples:

Here are some usage examples of the classes.

SystemEnvironment

import { SystemEnvironment, WindowsRegistryType, Platform } from "@octovel/environment";

interface MySystemEnv {
  PATH: string;
  JAVA_HOME: string;
  NODE_ENV: string;
}

const env = new SystemEnvironment<MySystemEnv>(Platform.Windows);

// Set variable
env.set("JAVA_HOME", "C:\\Program Files\\Java", {
  type: WindowsRegistryType.REG_EXPAND_SZ,
});

// Get variable
const javaPath = env.get("JAVA_HOME", { defaultValue: "NotFound" });
console.log("JAVA_HOME =", javaPath);

// List variables
console.log("Keys:", env.listKeys());
console.log("Values:", env.listValues());

// Save backup
await env.saveToFile("./system-env.json");

// Remove variable
env.remove("JAVA_HOME");

UserEnvironment

import { UserEnvironment, Platform, WindowsRegistryType } from "@octovel/environment";

interface MyEnvironment {
  [key: string]: string;
  TEST_PATH: string;
  NODE_ENV: string;
}

const env = new UserEnvironment<MyEnvironment>(Platform.Windows);

// Set variable
env.set("TEST_PATH", "%ProgramFiles%\\MyApp", {
  type: WindowsRegistryType.REG_EXPAND_SZ,
});

// Get variable
const val = env.get("TEST_PATH");
console.log("TEST_PATH =", val);

// List variables
console.log("Keys:", env.listKeys());
console.log("Values:", env.listValues());

// Save backup
await env.saveToFile("./user-env.json");

// Remove variable
env.remove("TEST_PATH");

ProcessManager

import { ProcessManager } from "@octovel/environment";

interface EnvSchema {
  NODE_ENV: string;
  API_KEY?: string;
}

const manager = new ProcessManager<EnvSchema>();

// Set variables
manager.set("NODE_ENV", "development");
manager.setTemporary("API_KEY", "secret", { ttl: 5000 }); // 5 seconds

// Get variables
console.log(manager.get("NODE_ENV")); // "development"

// Hooks
manager.onAdd((key, value) => console.log(`Added ${key}=${value}`));

// Snapshot & restore
const snap = manager.snapshot();
manager.set("NODE_ENV", "production");
manager.restore(snap);

// Increment numeric value
manager.set("COUNTER", 1);
manager.increment("COUNTER", 2); // COUNTER = 3

ProcessController

import { ProcessController } from "@octovel/environment";
import type { ChildProcessWithoutNullStreams } from "node:child_process";

const controller = new ProcessController<ChildProcessWithoutNullStreams>();

// Start a background process
const proc = controller.start("node", ["--version"]);

proc.stdout.on("data", (chunk) => console.log("Output:", chunk.toString()));

// Check if alive
console.log("Is running:", controller.isRunning(proc));

// Restart the process
controller.restart(proc, "node", ["--version"], { cwd: process.cwd(), env: proc.env });

// Stop after delay
setTimeout(() => {
  controller.stop(proc);
  console.log("Process stopped.");
}, 2000);

ProcessRegistry

import { ProcessRegistry } from "@octovel/environment";
import { spawn } from "node:child_process";

const registry = new ProcessRegistry();
const proc = spawn("node", ["app.js"]);

registry.add({ pid: proc.pid!, command: "node", args: ["app.js"], name: "App Server" }, proc);

console.log("Registered:", registry.count());

const record = registry.get(proc.pid!);
console.log("Process info:", record);

registry.remove(proc.pid!);
console.log("Remaining:", registry.count());

License

Apache-2.0 © Octovel