Skip to main content

Create Your Own Source

A source captures events from an environment (browser, server, third-party API) and forwards them to the walkerOS collector.

The Source Interface​

Sources are async functions that receive configuration and environment, then return a source instance:

Loading...

The returned instance must implement:

Loading...

Types Bundle​

Sources use a Types interface to bundle all TypeScript types:

Loading...

The 4 type parameters:

  1. Settings: Source configuration options
  2. Mapping: Event mapping (usually never for sources)
  3. Push: External push signature (what source.push exposes)
  4. Env: Internal dependencies (what source calls via env.elb)

Environment Parameter​

The env parameter is always provided by the collector and contains:

  • elb: Required - function to send events to collector (provided automatically)
  • Custom dependencies: Optional - any APIs your source needs (you provide via config)
Loading...

The collector always provides env.elb. You provide other dependencies (like window, document, custom APIs) when configuring the source.

Minimal Example​

Loading...

Complete Example: Event API Source​

Capturing events from a third-party API with event listeners:

Loading...

Using Your Source​

Loading...

Testing Your Source​

Test Utilities​

Loading...

Test Example​

Loading...

Common Patterns​

Polling for API Readiness​

When the external API isn't immediately available:

Loading...

Source as Adapter Pattern​

Sources bridge external systems and the collector:

External System  ←→  Source (Adapter)  ←→  Collector

Two interfaces:

  1. External (source.push): Platform-specific signature

    • Browser: push(elem, data, options) → Returns Promise<PushResult>
    • Server: push(req, res) → Returns Promise<void> (writes HTTP response)
    • Your choice: Match your environment's needs

  2. Internal (env.elb): Standard collector interface

    • Always Elb.Fn - same across all sources
    • Sources translate external inputs → standard events → env.elb(event)

Example signatures:

Loading...

The Push type parameter defines what your source exposes externally. Internally, all sources use env.elb to forward to the collector.

Key Concepts​

  • env is always provided: Collector ensures env exists with elb
  • Validate custom dependencies: Only check optional env properties your source needs
  • Types bundle: Use 4-parameter pattern for full type safety
  • Adapter pattern: External push adapts to environment, internal env.elb stays standard
  • Cleanup: Implement destroy() to remove listeners
  • Stateless: Let collector manage state

Next Steps​

💡 Need Professional Support?
Need professional support with your walkerOS implementation? Check out our services.