Getting started

This guide walks through Station from first install to a production-ready setup with persistence, recurring jobs, multi-step pipelines, and lifecycle observers.

Prerequisites

• Node.js 18 or later
• A package manager (pnpm, npm, or yarn)
• A TypeScript project configured for ES modules ("type": "module" in your package.json)

1. Install

pnpm add station-signal

2. Define a signal

A signal is a named, type-safe background job definition. It declares an input schema, execution constraints, and a handler function using a builder pattern. Signals are defined in their own files so the runner can auto-discover them.

// signals/send-email.tsimport { signal, z } from "station-signal"; export const sendEmail = signal("sendEmail")  .input(z.object({    to: z.string(),    subject: z.string(),    body: z.string(),  }))  .timeout(30_000)  .retries(2)  .run(async (input) => {    console.log(`Sending email to ${input.to}`);    // Your email sending logic here  });

Builder methods

3. Create the runner

The runner is the process that polls for due jobs and spawns child processes to execute them. Point it at a directory of signal files and call start().

// runner.tsimport path from "node:path";import { SignalRunner } from "station-signal"; const runner = new SignalRunner({  signalsDir: path.join(import.meta.dirname, "signals"),}); runner.start();

4. Trigger a signal

import { sendEmail } from "./signals/send-email.js"; const runId = await sendEmail.trigger({  to: "user@example.com",  subject: "Welcome",  body: "Thanks for signing up.",}); console.log(`Enqueued run: ${runId}`);

5. Add persistence (SQLite)

The default in-memory adapter loses all jobs on process restart. For anything beyond local development, use the SQLite adapter.

pnpm add station-adapter-sqlite

// runner.tsimport path from "node:path";import { SignalRunner } from "station-signal";import { SqliteAdapter } from "station-adapter-sqlite"; const runner = new SignalRunner({  signalsDir: path.join(import.meta.dirname, "signals"),  adapter: new SqliteAdapter({    dbPath: path.join(import.meta.dirname, "jobs.db"),  }),}); runner.start();

Shared adapter for separate processes

When triggers happen in a different process than the runner (common in web servers), both processes need access to the same adapter instance. Use the configure() function to set a global default.

// config.tsimport { configure } from "station-signal";import { SqliteAdapter } from "station-adapter-sqlite"; configure({  adapter: new SqliteAdapter({ dbPath: "./jobs.db" }),});

Import the config module before any signal imports in your trigger process:

// In your web server or trigger processimport "./config.js"; // Run configure() firstimport { sendEmail } from "./signals/send-email.js"; await sendEmail.trigger({  to: "user@example.com",  subject: "Order confirmation",  body: "Your order has been placed.",});

6. Recurring signals

Signals can run on a fixed interval. The runner handles scheduling, re-enqueuing, and retry logic automatically.

// signals/health-check.tsimport { signal } from "station-signal"; export const healthCheck = signal("healthCheck")  .every("5m")  .run(async () => {    const res = await fetch("https://api.example.com/health");    if (!res.ok) throw new Error(`Health check failed: ${res.status}`);  });

7. Multi-step signals

For pipelines where each stage transforms data for the next, use steps instead of a single handler.

// signals/process-order.tsimport { signal, z } from "station-signal"; export const processOrder = signal("processOrder")  .input(z.object({ orderId: z.string(), amount: z.number() }))  .step("validate", async (input) => {    if (input.amount <= 0) throw new Error("Invalid amount");    return { ...input, validated: true };  })  .step("charge", async (prev) => {    const chargeId = await payments.charge(prev.amount);    return { orderId: prev.orderId, chargeId };  })  .step("notify", async (prev) => {    await notify(`Order ${prev.orderId} charged: ${prev.chargeId}`);  })  .build();

8. Subscribers

Subscribers observe the signal lifecycle. Use them for logging, metrics, alerting, or any side effect that should not live inside a handler.

import { SignalRunner, ConsoleSubscriber } from "station-signal"; const runner = new SignalRunner({  signalsDir: "./signals",  subscribers: [    new ConsoleSubscriber(), // Built-in: logs all events to stdout    {      onRunStarted({ run }) {        metrics.increment("signal.started", { name: run.signalName });      },      onRunCompleted({ run }) {        metrics.increment("signal.completed", { name: run.signalName });      },      onRunFailed({ run, error }) {        alerting.send(`Signal ${run.signalName} failed: ${error}`);      },    },  ],});

Next steps