/walkeros-understanding-sources

name: walkeros-understanding-sources
description:
  Use when working with walkerOS sources, understanding event capture, or
  learning about the push interface. Covers browser, dataLayer, and server
  source patterns.

Understanding walkerOS Sources

Overview

Sources capture events from the external world (browser DOM, dataLayer, HTTP requests, cloud functions) and feed them to the collector.

**Core principle:** Sources capture. They don't process or deliver—that's collector and destinations.

Source Interface

See [packages/core/src/types/source.ts](../../packages/core/src/types/source.ts) for canonical interface.

Init Function (Context Pattern)

Sources use a context-based initialization pattern:

import type { Source } from '@walkeros/core';

export const sourceMySource: Source.Init<Types> = async (context) => {
  const { config = {}, env, logger, id } = context;
  // ...
};

**Context contains:**

| Property | Type | Purpose | | ----------- | -------------------------------------- | ------------------------------------------------------------------------------------------- | | `config` | `Source.Config<T>` | Settings, mapping, options | | `env` | `Types['env']` | Environment (push, logger) | | `logger` | `Logger` | Logging functions | | `id` | `string` | Source identifier | | `collector` | `Collector.Instance` | Reference to collector | | `withScope` | `(scope, respond, body) => Promise<R>` | Bind ingest + respond to a single scope (server sources). Takes a normalized `Source.Scope` |

Push Method

| Method | Purpose | | ------------- | ----------------------------------- | | `push(input)` | Receive external input, emit events |

Init Method

`init?: () => void | Promise<void>` — Optional eager-startup hook on the returned `Source.Instance`. The factory must be **side-effect-free**: build the instance and return it. The collector calls `init()` on every source eagerly after all factories register, regardless of `config.require`. Use `init` for work that previously sat in the factory body: adopting a pre-init window queue (e.g., `window.elbLayer`), attaching DOM listeners, opening sockets, intercepting `window.dataLayer`. After `init` runs the collector flips `Source.Config.init` to `true`.

queueOn Buffer

`queueOn?: Array<{ type: On.Types; data: unknown }>` — Optional buffer on the `Source.Instance` for lifecycle events delivered before the source is **started** (started ≡ `config.init === true && !config.require?.length`). The collector pushes `{ type, data }` here when it would otherwise call `source.on(type, data)`. Once the source becomes started, the collector replays each entry via `source.on(...)` and clears the queue.

Destroy Method

`destroy?: DestroyFn` — Optional cleanup method. Called during `command('shutdown')`. Use to close HTTP servers, timers, or connections. Receives `{ id, config, env, logger }`.

Source Lifecycle

The collector and every source agree on three lifecycle markers, all on `Source.Config`:

| Field | Purpose | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `init?: boolean` | Set by the collector to `true` after `Instance.init()` resolves. Authors do not write to it. Reflects "init has run", not "is started". | | `require?: string[]` | Author-supplied **timing hint**. Lists collector state a source needs before its first `on()` delivery. Satisfied by the collector's **current recorded state** (level), not only by a future event — so order does not matter: the gate clears whether the required state was recorded before or after this source registered. It is not a correctness dependency: a source reacts to state correctly whether or not it declares `require`. | | `disabled?: boolean` | Hard skip — no factory invocation, no init, no event capture. |

The flow is:

1. **Register** — c