@winkjs/composer 0.4.0 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -28
- package/package.json +11 -3
package/README.md
CHANGED
|
@@ -1,62 +1,148 @@
|
|
|
1
1
|
# winkComposer
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@winkjs/composer)
|
|
3
4
|
[](https://opensource.org/licenses/MIT)
|
|
4
5
|
|
|
5
6
|
## Composable Streaming Intelligence
|
|
6
7
|
[<img align="right" src="https://decisively.github.io/wink-logos/logo-title.png" width="100px" >](https://winkjs.org/)
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
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.
|
|
9
10
|
|
|
10
|
-
winkComposer turns live data streams into clear, actionable insights by composing small, focused building blocks — signal conditioning, anomaly detection, and health assessment — into pipelines underpinned by neural-network intelligence.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
## See It in Action
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
> [!NOTE]
|
|
17
|
-
> The [documentation site](https://composer.winkjs.org) is live and growing — interactive demos run real winkComposer nodes in your browser, no installation or sign-up required. The full source now lives in this repository, MIT-licensed. MCP integration for AI-driven queries over pre-computed insights is in active development.
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
## Explore Possibilities
|
|
21
|
-
|
|
22
|
-
Real data. Real insight. Each demo runs the same winkComposer core that powers edge-to-cloud deployments — right here in your browser.
|
|
14
|
+
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.
|
|
23
15
|
|
|
24
16
|
| [](https://composer.winkjs.org/docs/use-cases/bearing-health) | [](https://composer.winkjs.org/docs/use-cases/server-health) | [](https://composer.winkjs.org/docs/use-cases/process-quality) |
|
|
25
17
|
|:---:|:---:|:---:|
|
|
26
18
|
| [**Detecting Bearing Failure**](https://composer.winkjs.org/docs/use-cases/bearing-health) | [**Detecting Server Latency Degradation**](https://composer.winkjs.org/docs/use-cases/server-health) | [**Catching Process Drift**](https://composer.winkjs.org/docs/use-cases/process-quality) |
|
|
27
19
|
| Predictive Maintenance | AIOps | Process Control |
|
|
28
20
|
|
|
21
|
+
Other end-to-end examples include [diagnosing Wi-Fi access-point health](https://composer.winkjs.org/docs/use-cases/wifi-ap-health), [classifying driving conditions](https://composer.winkjs.org/docs/use-cases/driving-modes) from OBD-II telematics, and [tracking wash-cycle quality](https://composer.winkjs.org/docs/use-cases/wash-cycle-quality).
|
|
29
22
|
|
|
30
|
-
|
|
23
|
+
Prefer to start with a failure mode instead of an industry? [Recipes](https://composer.winkjs.org/docs/playground/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.
|
|
31
24
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
25
|
+
|
|
26
|
+
## How It Works
|
|
27
|
+
|
|
28
|
+
A flow is a [pipeline](docs/handbook/understanding-composer.md) of small, single-purpose [nodes](docs/handbook/nodes/index.md). 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.
|
|
29
|
+
|
|
30
|
+
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](docs/handbook/nodes/intelligence.md). The filter estimates what sensors cannot directly measure. The network weighs many weak signals into one confident verdict.
|
|
31
|
+
|
|
32
|
+
You define such a pipeline in code — a [linear flow](docs/handbook/flow-language.md) 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](docs/handbook/understanding-composer.md) — one flow, thousands of assets.
|
|
33
|
+
|
|
34
|
+
Results leave through emitters and storage: alerts to an MQTT broker like Mosquitto or the terminal, insights to QuestDB. [Grafana dashboards](docs/handbook/visualization.md) read from there. The stack is open source end to end.
|
|
35
|
+
|
|
36
|
+
The Quick Start below builds one such pipeline end to end.
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
Requires Node.js 22 or newer.
|
|
42
|
+
|
|
43
|
+
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:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm create @winkjs/composer
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
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](https://composer.winkjs.org/docs/playground/hello-flow) in the browser playground. The same project also lives in the repository, in [`examples/hello-flow`](examples/hello-flow).
|
|
50
|
+
|
|
51
|
+
Here is the whole program, [`hello-flow.js`](examples/hello-flow/hello-flow.js):
|
|
52
|
+
|
|
53
|
+
```javascript
|
|
54
|
+
import { flow, csv, terminal } from '@winkjs/composer';
|
|
55
|
+
|
|
56
|
+
const handle = await flow( 'hello-flow' )
|
|
57
|
+
|
|
58
|
+
// Replay the CSV like a live feed: one reading every 200 ms.
|
|
59
|
+
.source( csv, { path: 'data/pump-temps.csv', delayMs: 200 } )
|
|
60
|
+
|
|
61
|
+
// Alerts print to the terminal here. A production flow points this
|
|
62
|
+
// at an MQTT broker instead, with QuestDB for storage.
|
|
63
|
+
.emitter( terminal, { verbose: true, prefix: '[pump]' } )
|
|
64
|
+
|
|
65
|
+
// One isolated pipeline per pump, and alerts name the pump in
|
|
66
|
+
// their topic. This feed has a single pump; a fleet needs no
|
|
67
|
+
// code change.
|
|
68
|
+
.assetId( 'id' )
|
|
69
|
+
|
|
70
|
+
// 1. clean — reject readings outside a sane range
|
|
71
|
+
.sanitize( 'clean', 'motor_t',
|
|
72
|
+
{ failureReason: 'reject_reason' },
|
|
73
|
+
{ ranges: { min: 0, max: 120 } } )
|
|
74
|
+
|
|
75
|
+
// 2. detect — flag when the motor runs hot
|
|
76
|
+
.threshold( 'tooHot', 'motor_t',
|
|
77
|
+
{ active: 'is_hot' },
|
|
78
|
+
{ mode: 'above', threshold: 80, hysteresis: 3 } )
|
|
79
|
+
|
|
80
|
+
// 3. confirm — hot across several readings, not one spike
|
|
81
|
+
.persistenceCheck( 'confirmHot',
|
|
82
|
+
( msg ) => msg.is_hot,
|
|
83
|
+
{ persistenceConfirmed: 'hot_confirmed' },
|
|
84
|
+
{ minVotes: 3, outOfTotal: 5 } )
|
|
85
|
+
|
|
86
|
+
// 4. broadcast — print an alert once confirmed
|
|
87
|
+
.emitIf( 'alert',
|
|
88
|
+
( msg ) => msg.hot_confirmed,
|
|
89
|
+
{ target: 'terminal', insightType: 'overheat' } )
|
|
90
|
+
|
|
91
|
+
.run();
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
To use winkComposer in your own project:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npm install @winkjs/composer
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
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`).
|
|
101
|
+
|
|
102
|
+
The example above replays a CSV file. A live deployment reads from an MQTT broker instead — or runs [headless](docs/handbook/headless-flow.md), where your own code feeds the flow. Headless takes any source you already run: an OPC-UA client, a Kafka consumer.
|
|
42
103
|
|
|
43
104
|
|
|
44
105
|
## Performance
|
|
45
106
|
|
|
46
|
-
|
|
107
|
+
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.
|
|
47
108
|
|
|
48
109
|
| Configuration | Throughput |
|
|
49
110
|
|----------------------|-------------------------|
|
|
50
111
|
| Raspberry Pi 5 | ~100K messages/second |
|
|
51
112
|
| Modern server | ~1.2M messages/second |
|
|
52
|
-
| Tracking
|
|
113
|
+
| Tracking 10K assets | ~500K messages/second |
|
|
53
114
|
|
|
54
|
-
The same pipeline [runs in your browser](https://composer.winkjs.org/docs/benchmark) — browser
|
|
115
|
+
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](https://composer.winkjs.org/docs/benchmark) — browser performance varies from native Node.js due to JIT differences.
|
|
55
116
|
|
|
56
117
|
|
|
57
118
|
## Built for the Real World
|
|
58
119
|
|
|
59
|
-
|
|
120
|
+
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](docs/handbook/resilience.md) 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.
|
|
121
|
+
|
|
122
|
+
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.
|
|
123
|
+
|
|
124
|
+
The documentation also relates winkComposer's concepts to two industrial standards: [ISO 13374](https://composer.winkjs.org/docs/reference/iso-13374-mapping) for condition monitoring, the [NIST AI RMF](https://composer.winkjs.org/docs/reference/nist-ai-rmf-mapping) for AI risk management.
|
|
125
|
+
|
|
126
|
+
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.
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
## Documentation
|
|
130
|
+
|
|
131
|
+
The documentation lives in two places: the [documentation site](https://composer.winkjs.org) for interactive learning, and the in-repo handbook for version-matched reference.
|
|
132
|
+
|
|
133
|
+
| Resource | What it covers |
|
|
134
|
+
|---|---|
|
|
135
|
+
| [**Hello Flow!**](https://composer.winkjs.org/docs/playground/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. |
|
|
136
|
+
| [**Recipes**](https://composer.winkjs.org/docs/playground/recipes) | Short, runnable patterns for recurring failure modes — each names the nodes it uses and runs in the browser. |
|
|
137
|
+
| [**Explore Nodes**](https://composer.winkjs.org/docs/playground/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. |
|
|
138
|
+
| [**Under the Hood**](https://composer.winkjs.org/docs/concepts/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. |
|
|
139
|
+
| [**Flow Language**](https://composer.winkjs.org/docs/concepts/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. |
|
|
140
|
+
| [**Composition Patterns**](https://composer.winkjs.org/docs/concepts/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. |
|
|
141
|
+
| [**Semantics**](https://composer.winkjs.org/docs/concepts/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. |
|
|
142
|
+
| [**Node Index**](https://composer.winkjs.org/docs/reference/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. |
|
|
143
|
+
| [**Handbook**](docs/handbook/index.md) | The complete reference, right here in the repo and version-matched: the handbook at any release tag describes exactly that release's code. |
|
|
144
|
+
| [**Changelog**](CHANGELOG.md) | Release notes for every published version — what changed, what broke, and what to do about it. |
|
|
145
|
+
| [**Roadmap**](ROADMAP.md) | What is planned next, item by item, with complexity and status. |
|
|
60
146
|
|
|
61
147
|
|
|
62
148
|
## Get Involved
|
|
@@ -65,7 +151,16 @@ Each asset runs in its own isolated state — a fault in one never affects anoth
|
|
|
65
151
|
|:---:|:---:|:---:|
|
|
66
152
|
| Support open-source streaming intelligence. | Stay updated on releases and ecosystem developments. | Questions, ideas, or feedback — all welcome. |
|
|
67
153
|
|
|
154
|
+
Want to contribute code or docs? Start with the [contributing guide](CONTRIBUTING.md). The project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
|
|
155
|
+
|
|
68
156
|
|
|
69
157
|
## About winkJS
|
|
70
158
|
|
|
71
|
-
[winkJS](https://winkjs.org) is the open-source home of
|
|
159
|
+
[winkJS](https://winkjs.org) 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.
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
## License
|
|
163
|
+
|
|
164
|
+
winkComposer is released under the [MIT License](LICENSE).
|
|
165
|
+
|
|
166
|
+
Copyright (c) 2024-26 GRAYPE Systems Private Limited.
|
package/package.json
CHANGED
|
@@ -1,18 +1,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@winkjs/composer",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "Composable Streaming Intelligence — turn streaming data into actionable insights, from edge to cloud",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"streaming",
|
|
7
7
|
"streaming-intelligence",
|
|
8
|
+
"streaming-analytics",
|
|
8
9
|
"real-time",
|
|
9
|
-
"edge",
|
|
10
|
+
"edge-computing",
|
|
10
11
|
"iot",
|
|
12
|
+
"iiot",
|
|
13
|
+
"industrial-iot",
|
|
11
14
|
"time-series",
|
|
12
15
|
"signal-processing",
|
|
16
|
+
"anomaly-detection",
|
|
17
|
+
"predictive-maintenance",
|
|
13
18
|
"mqtt",
|
|
14
19
|
"questdb",
|
|
15
|
-
"wink-composer",
|
|
16
20
|
"winkjs",
|
|
17
21
|
"wink"
|
|
18
22
|
],
|
|
@@ -71,5 +75,9 @@
|
|
|
71
75
|
"mqtt": "^5.15.1",
|
|
72
76
|
"msgpackr": "^1.11.10",
|
|
73
77
|
"pg": "^8.20.0"
|
|
78
|
+
},
|
|
79
|
+
"overrides": {
|
|
80
|
+
"serialize-javascript": "^7.1.0",
|
|
81
|
+
"diff": "^8.0.3"
|
|
74
82
|
}
|
|
75
83
|
}
|