Environment

The Environment class is the top-level container for your Sigil configuration. It manages a collection of entities and orchestrates their lifecycle.

Import

import { Environment } from "sigil";

Constructor

new Environment(name: string)

Parameter	Type	Description
name	string	A name for this environment (used in logs and state tracking)

Properties

name

env.name: string

The environment’s name, as passed to the constructor.

entities

env.entities: Entity[]

All registered entities, in registration order.

Methods

add(entity)

env.add<T extends Entity>(entity: T): T

Register an entity in the environment. Returns the entity (useful for chaining or capturing a reference).

const db = env.add(new Postgres("db", { ... }));
// db is typed as Postgres, not Entity

Entities are started in the order they are added, so add dependencies first.

get(name)

env.get(name: string): Entity | undefined

Retrieve a registered entity by name.

const db = env.get("db");

up()

env.up(): Promise<void>

Start all entities sequentially in registration order. Each entity’s start() must complete before the next one begins.

Throws if any entity fails to start.

down()

env.down(): Promise<void>

Stop all entities in reverse registration order. If stopping one entity throws, it logs the error and continues stopping the remaining entities.

status()

env.status(): Array<{ name: string; status: EntityStatus }>

Returns the current status of all entities.

const statuses = env.status();
// [
//   { name: "db", status: "running" },
//   { name: "backend", status: "running" },
// ]

Full Example

import { Environment, Postgres, Service, APIInterface } from "sigil";

const env = new Environment("my-app");

const db = env.add(
  new Postgres("db", {
    database: "myapp",
    initSql: "./schema.sql",
  })
);

env.add(
  new Service(
    "api",
    {
      command: ["node", "server.js"],
      env: { DATABASE_URL: db.connectionString },
      readyCheck: { url: "http://localhost:3000/health" },
    },
    [new APIInterface(3000)]
  )
);

export default env;