@winkjs/composer

v0.4.2

Published

a day ago

Composable Streaming Intelligence — turn streaming data into actionable insights, from edge to cloud

Downloads

324

winkComposer

Composable Streaming Intelligence

winkComposer is a JavaScript framework that turns streaming data into real-time insights and decisions. The streams can come from anywhere: IoT and IIoT sensors, vehicle telematics, server metrics. There is no batch job to wait for. In real-time operations like a plant floor, a delayed insight is a lost opportunity. It is open source, purpose-built for SMBs and MSMEs.

See It in Action

The fastest way to understand winkComposer is to watch it work. The demos below run in your browser — real nodes, live data, no install, nothing to sign up for. Each one uses the same core that runs from edge to cloud.

Other end-to-end examples include diagnosing Wi-Fi access-point health, classifying driving conditions from OBD-II telematics, and tracking wash-cycle quality.

Prefer to start with a failure mode instead of an industry? Recipes are short, runnable patterns for recurring problems. They cover gradual drift, directional trends, sudden shifts, hidden parasitic drain, PID-loop hunting, frozen sensors, and subtle process shifts — plus adaptive compression for storage.

How It Works

A flow is a pipeline of small, single-purpose nodes. Each node reads fields from the message, computes its result, and adds the result onto the same message for the nodes downstream. The message that leaves the pipeline carries its whole history. A message can also stop early — a failed check drops it, and nothing downstream fires.

The intelligence emerges from composition. Together the nodes cover the whole path from raw signal to decision: clean signals, extract features, detect change, fuse evidence, and act. The repertoire runs from a simple threshold, through a Kalman filter, to a two-layer spiking neural network. The filter estimates what sensors cannot directly measure. The network weighs many weak signals into one confident verdict.

You define such a pipeline in code — a linear flow that reads top to bottom, not a drag-and-drop graph. Explicit control signals handle orchestration, so a flow stays readable as it grows. And when many machines share one flow, each gets its own isolated state — one flow, thousands of assets.

Results leave through emitters and storage: alerts to an MQTT broker like Mosquitto or the terminal, insights to QuestDB. Grafana dashboards read from there. The stack is open source end to end.

The Quick Start below builds one such pipeline end to end.

Quick Start

Requires Node.js 22 or newer.

The Quick Start flow replays a CSV feed of pump motor temperatures. It cleans each reading, flags a hot motor, confirms the heat is not a blip, and prints an alert. One command scaffolds it as a runnable project:

npm create @winkjs/composer

Accept the directory prompt, then run the three printed steps. A run takes about eight seconds. Watch for the overheat alert. Prefer zero install? Build this flow interactively in the browser playground. The same project also lives in the repository, in examples/hello-flow.

Here is the whole program, hello-flow.js:

import { flow, csv, terminal } from '@winkjs/composer';

const handle = await flow( 'hello-flow' )

    // Replay the CSV like a live feed: one reading every 200 ms.
    .source( csv, { path: 'data/pump-temps.csv', delayMs: 200 } )

    // Alerts print to the terminal here. A production flow points this
    // at an MQTT broker instead, with QuestDB for storage.
    .emitter( terminal, { verbose: true, prefix: '[pump]' } )

    // One isolated pipeline per pump, and alerts name the pump in
    // their topic. This feed has a single pump; a fleet needs no
    // code change.
    .assetId( 'id' )

    // 1. clean — reject readings outside a sane range
    .sanitize( 'clean', 'motor_t',
        { failureReason: 'reject_reason' },
        { ranges: { min: 0, max: 120 } } )

    // 2. detect — flag when the motor runs hot
    .threshold( 'tooHot', 'motor_t',
        { active: 'is_hot' },
        { mode: 'above', threshold: 80, hysteresis: 3 } )

    // 3. confirm — hot across several readings, not one spike
    .persistenceCheck( 'confirmHot',
        ( msg ) => msg.is_hot,
        { persistenceConfirmed: 'hot_confirmed' },
        { minVotes: 3, outOfTotal: 5 } )

    // 4. broadcast — print an alert once confirmed
    .emitIf( 'alert',
        ( msg ) => msg.hot_confirmed,
        { target: 'terminal', insightType: 'overheat' } )

    .run();

To use winkComposer in your own project:

npm install @winkjs/composer

Your project needs "type": "module" in its package.json. Then copy the flow above and point path at your own data. The replayed file has two columns: a pump id and a motor temperature (id, motor_t).

The example above replays a CSV file. A live deployment reads from an MQTT broker instead — or runs headless, where your own code feeds the flow. Headless takes any source you already run: an OPC-UA client, a Kafka consumer.

Performance

The numbers below come from a pure compute benchmark — every step a live message takes through an 8-node flow, from arrival to final output. Storage and MQTT I/O are excluded — these are compute ceilings, not full-deployment numbers.

| Configuration | Throughput | |----------------------|-------------------------| | Raspberry Pi 5 | ~100K messages/second | | Modern server | ~1.2M messages/second | | Tracking 10K assets | ~500K messages/second |

Two configurations produced these numbers. The first two rows interleave 10 asset pipelines in random order — 4.5 million messages (10 pipelines × 900 data points × 500 iterations). The third row runs the same flow with 10,000 assets — 10,000 isolated states alive at once, 9 million messages, under 140 MB of heap. Pipelines are created dynamically as each asset first appears; timing uses process.hrtime.bigint(). The same pipeline runs in your browser — browser performance varies from native Node.js due to JIT differences.

Built for the Real World

Write a flow once and run it anywhere Node.js does — an industrial-grade Raspberry Pi, a production server, a Kubernetes cluster. Each asset's state is isolated, so a fault in one stays in one. Messages queue locally when the network drops and drain cleanly on reconnect. Shutdown is ordered and deterministic: sources close first, storage last. A misconfigured flow fails when you define it, not in production — unknown options, output collisions, and bad triggers are all caught at definition time.

The test suite holds over 6,500 tests behind a 99.5% coverage gate. Integration tests run against real Mosquitto and QuestDB services, not mocks. Every npm release carries SLSA provenance — a public, verifiable link from the package back to the exact source commit and the build that produced it. npm audit signatures verifies it.

The documentation also relates winkComposer's concepts to two industrial standards: ISO 13374 for condition monitoring, the NIST AI RMF for AI risk management.

Flows can run headless inside your own application — no broker, no services. Your code feeds messages in from any source you already run. Already running a historian (the plant's time-series system of record)? winkComposer adds value beside it — it watches the live stream and acts, while the historian keeps the record.

Documentation

The documentation lives in two places: the documentation site for interactive learning, and the in-repo handbook for version-matched reference.

| Resource | What it covers | |---|---| | Hello Flow! | Build a 4-node temperature monitor from scratch — smooth, detect, confirm, broadcast — with an interactive demo running real nodes in your browser. The natural starting point. | | Recipes | Short, runnable patterns for recurring failure modes — each names the nodes it uses and runs in the browser. | | Explore Nodes | Single-node sandboxes — drag a slider, watch the node respond in real time. Covers the Kalman 1D filter and the kernel convolution node, with more to come. | | Under the Hood | How messages flow and get enriched node by node, how bad data and throwing functions are handled without crashing the pipeline, how per-asset isolation works, and timestamp requirements. | | Flow Language | The complete DSL reference — flow anatomy, node call signatures, dynamic options (tunables), single vs. multi-field processing, naming policies, and node processing types. | | Composition Patterns | Proven node combinations for recurring problems: noise-tolerant alarms, drift detection, adaptive diagnostics, layered flows, and downsampling for storage. Includes clear guidance on when to use passIf, emitIf, or controller/disable. | | Semantics | How to define what computed values mean — types, units, physical ranges, operational limits — as a single source of truth shared by storage, dashboards, and query engines. Covers the facts-vs-decisions design principle. | | Node Index | Every node grouped by category — Signal Conditioning, Detection, Feature Extraction, Intelligence, and more — with what each computes and what it adds to the message. | | Handbook | The complete reference, right here in the repo and version-matched: the handbook at any release tag describes exactly that release's code. | | Changelog | Release notes for every published version — what changed, what broke, and what to do about it. | | Roadmap | What is planned next, item by item, with complexity and status. |

Get Involved

Want to contribute code or docs? Start with the contributing guide. The project follows the Contributor Covenant.

About winkJS

winkJS is the open-source home of high-performance JavaScript tools. winkNLP covers natural language processing; winkComposer covers streaming intelligence. Both follow the same discipline: developer-friendly APIs, measured performance, and well-tested code.

License

winkComposer is released under the MIT License.