README
¶
🌀 Nexss Flow
Nexss Flow is a Go runtime and language for composing .nflow programs from registered actions. The nflow CLI runs flows and inspects the active compiler surface.
Install
Requires Go 1.26 or later. Install the CLI from the current main branch:
go install github.com/nexssp/flow/cmd/nflow@main 🌀
nflow version
Make sure Go's binary directory ($(go env GOBIN), or $(go env GOPATH)/bin when GOBIN is unset) is on your PATH.
Quick start
nflow help
nflow lint examples/00_flow_basics/04_data_transformation.nflow
nflow lint ./examples/...
nflow run examples/00_flow_basics/04_data_transformation.nflow
The example projects a nested value into a new shape and prints:
{
"id": 101,
"name": "Maksymilian",
"status": "active",
"summary": "Maksymilian (ID: 101) is active"
}
Examples
The introductory flows are checked by CI: each one must pass nflow lint and run successfully from the repository root.
- Logging and debug
- Timeout and fallback
- Dynamic dispatch
- Data transformation
- Error fallback
- Parallel actions
Run the complete set locally with task examples or run an individual flow with nflow run <file.nflow>.
Verify without running a flow 🌀
Use nflow lint <file.nflow> for a static check, or pass a directory or Go-style recursive target such as nflow lint ./examples/... to discover sources automatically. It preprocesses each file, parses its pipeline, and checks referenced atoms and modifiers against that file's active registry; it does not execute flows. Recursive discovery sorts paths, skips .git, .hg, .svn, vendor, and node_modules, and does not follow symlinks. Lint is not a substitute for exercising runtime behavior, and it does not prove every expression or input will succeed. The broader nflow lint ./... also discovers internal developer sources and extension fixtures, some of which currently produce context-specific diagnostics; CI intentionally scopes its lint gate to ./examples/....
The similarly named build commands do different jobs:
nflow build -o ./bin/my-flow examples/00_flow_basics/04_data_transformation.nflowcreates a standalone executable with the flow embedded. It is a packaging/build command, not a check-only validator; the flow runs when you launch the generated executable. Put-obefore the input path with the current CLI parser.nflow help buildcurrently advertises--target, but this checkout's implementation does not parse that flag; the command above uses the supported-ooption.go build ./...compiles the repository's Go packages. It does not validate or execute.nflowfiles.go test ./...runs the repository's Go tests, including tests that may exercise Flow features. For a no-runtime-execution check of a particular flow, usenflow lint; for repository code verification, usego test ./....
Documentation
- Language syntax and directives
- CLI and runtime
- Extension bundles
- Practical secure-pipeline examples
- Editor setup for VS Code and Zed
Microkernel and extensions
Nexss Flow uses a microkernel-style design: core.Bundle is the contract through which bundles contribute action libraries and compiler extensions. The CLI assembles its built-in bundles, while @require can load a bundle for a flow; a package's presence under extensions/ alone does not enable it. See the extension guide for the current bundle model.
Directories
¶
| Path | Synopsis |
|---|---|
|
selftest
Package selftest runs the Nexss Flow self-test suite: a feature-by- feature check of every registered bundle, run in-process against the binary's own compiler and runtime.
|
Package selftest runs the Nexss Flow self-test suite: a feature-by- feature check of every registered bundle, run in-process against the binary's own compiler and runtime. |
|
cmd
|
|
|
nflow
command
|
|
|
Plik: flow/core/resolver.go
|
Plik: flow/core/resolver.go |
|
extensions
|
|
|
assert
Package assert provides the `assert(cond, msg)` keyword and the `@assert: expr` directive.
|
Package assert provides the `assert(cond, msg)` keyword and the `@assert: expr` directive. |
|
config
Package config provides the @config and @config.load directives that populate meta["config"], which OnPreprocess forwards to the compiler as a compile-time key-value map.
|
Package config provides the @config and @config.load directives that populate meta["config"], which OnPreprocess forwards to the compiler as a compile-time key-value map. |
|
config_yaml
Package config_yaml registers a YAML decoder with extensions/config.
|
Package config_yaml registers a YAML decoder with extensions/config. |
|
decide
Package decide provides the `decide` action: it evaluates a state against a registered decision backend and returns structured answers.
|
Package decide provides the `decide` action: it evaluates a state against a registered decision backend and returns structured answers. |
|
description
Package description provides the `@description "..."` directive, which records a human-readable summary of a .nflow file into meta["description"].
|
Package description provides the `@description "..."` directive, which records a human-readable summary of a .nflow file into meta["description"]. |
|
external
Package external provides three actions for calling code that lives outside the Flow process: exec (shell), http.request (HTTP client), and wasm (Wazero WASI modules).
|
Package external provides three actions for calling code that lives outside the Flow process: exec (shell), http.request (HTTP client), and wasm (Wazero WASI modules). |
|
flow_version
Package flow_version provides the @flow_version directive, which rejects a .nflow file at compile time when the running compiler does not satisfy the declared version constraint.
|
Package flow_version provides the @flow_version directive, which rejects a .nflow file at compile time when the running compiler does not satisfy the declared version constraint. |
|
fs
Package fs ships the file-system stream source and operators: fs.walk as a source; fs.filter, fs.read, fs.sort, fs.write, and the terminal sinks out.stdout and out.file as stream operators.
|
Package fs ships the file-system stream source and operators: fs.walk as a source; fs.filter, fs.read, fs.sort, fs.write, and the terminal sinks out.stdout and out.file as stream operators. |
|
hook
Package hook provides the `@hook:name` directive, which attaches every named hook from the kernel registry to the compiled pipeline, and the hook.probe action that reads HookProbeKey from the context to prove a hook fired.
|
Package hook provides the `@hook:name` directive, which attaches every named hook from the kernel registry to the compiled pipeline, and the hook.probe action that reads HookProbeKey from the context to prove a hook fired. |
|
include
Package include provides the `@include "file.nflow"` directive.
|
Package include provides the `@include "file.nflow"` directive. |
|
io
Package io ships process-stdio stream primitives: io.stdin reads newline-delimited items from standard input; io.stdout and io.stderr write each item as a line and pass it through.
|
Package io ships process-stdio stream primitives: io.stdin reads newline-delimited items from standard input; io.stdout and io.stderr write each item as a line and pass it through. |
|
loop
Package loop provides the `loop(body) until(cond)` keyword.
|
Package loop provides the `loop(body) until(cond)` keyword. |
|
macros
Package macros extends the compiler with a @macro engine.
|
Package macros extends the compiler with a @macro engine. |
|
modifiers_auth
Package modifiers_auth ships the identity guards :auth, :role=, :perm=, and :feature=.
|
Package modifiers_auth ships the identity guards :auth, :role=, :perm=, and :feature=. |
|
modifiers_core
Package modifiers_core ships the execution modifiers :timeout=, :retry=, :concurrency=, :cache=, :coalesce, :dedup, :idempotent, and :rate_limit=.
|
Package modifiers_core ships the execution modifiers :timeout=, :retry=, :concurrency=, :cache=, :coalesce, :dedup, :idempotent, and :rate_limit=. |
|
modifiers_meta
Package modifiers_meta ships the metadata modifiers :name=, :desc=, :description=, :status=, :tag=, :scope=, and the flags :read_only, :audit, :debug, :deprecated, :strict, :lenient.
|
Package modifiers_meta ships the metadata modifiers :name=, :desc=, :description=, :status=, :tag=, :scope=, and the flags :read_only, :audit, :debug, :deprecated, :strict, :lenient. |
|
nodes_bench
Package nodes_bench provides bench.run (measure latency distribution of an action), bench.save (write results to a file), and bench.compare (diff against a stored baseline).
|
Package nodes_bench provides bench.run (measure latency distribution of an action), bench.save (write results to a file), and bench.compare (diff against a stored baseline). |
|
nodes_dispatch
Package nodes_dispatch provides the `dispatch.run` action, which tries explicitly listed actions in order and returns the first successful result.
|
Package nodes_dispatch provides the `dispatch.run` action, which tries explicitly listed actions in order and returns the first successful result. |
|
nodes_distribute
Package nodes_distribute provides distribute.map (bounded-concurrency fan-out over a slice) and distribute.reduce (fold the map output into a single value).
|
Package nodes_distribute provides distribute.map (bounded-concurrency fan-out over a slice) and distribute.reduce (fold the map output into a single value). |
|
nodes_log
Package nodes_log provides log.info, log.warn, and log.error as pass-through nodes.
|
Package nodes_log provides log.info, log.warn, and log.error as pass-through nodes. |
|
nodes_supervisor
Package nodes_supervisor provides the supervisor action: it compiles and runs a set of named child pipelines concurrently, isolating each child's panic, error, and timeout.
|
Package nodes_supervisor provides the supervisor action: it compiles and runs a set of named child pipelines concurrently, isolating each child's panic, error, and timeout. |
|
on
Package on provides the `@on event "protocol:target"` directive, which records an EventTrigger into meta["on_event"].
|
Package on provides the `@on event "protocol:target"` directive, which records an EventTrigger into meta["on_event"]. |
|
on_error
Package on_error provides the `@on_error { when ...
|
Package on_error provides the `@on_error { when ... |
|
pipeline
Package pipeline provides the `@pipeline NAME ...
|
Package pipeline provides the `@pipeline NAME ... |
|
pool
Package pool provides the `@pool NAME [member1, member2] { strategy: "round_robin" }` directive.
|
Package pool provides the `@pool NAME [member1, member2] { strategy: "round_robin" }` directive. |
|
progress
Package progress ships a TTY progress reporter and two actions that publish progress events through kernel/xctx.
|
Package progress ships a TTY progress reporter and two actions that publish progress events through kernel/xctx. |
|
projection
Package projection adds the `{ ...
|
Package projection adds the `{ ... |
|
render
Package render provides the render.markdown stream operator, which reformats FileContent into a single Markdown document.
|
Package render provides the render.markdown stream operator, which reformats FileContent into a single Markdown document. |
|
retry
Package retry adds retry resilience to individual Flow atoms through the AtomAdvise contract.
|
Package retry adds retry resilience to individual Flow atoms through the AtomAdvise contract. |
|
runtime
Package runtime ships the primitive actions every .nflow pipeline starts from: runtime.const, runtime.noop, runtime.debug, runtime.fail, runtime.pick, runtime.wrap, runtime.with, runtime.env, runtime.uuid, runtime.call, runtime.dispatch_by_prefix, json.clean, runtime.sleep.
|
Package runtime ships the primitive actions every .nflow pipeline starts from: runtime.const, runtime.noop, runtime.debug, runtime.fail, runtime.pick, runtime.wrap, runtime.with, runtime.env, runtime.uuid, runtime.call, runtime.dispatch_by_prefix, json.clean, runtime.sleep. |
|
schema
Package schema provides the `@schema NAME { Field Type `json:"..." validate:"..."` ...
|
Package schema provides the `@schema NAME { Field Type `json:"..." validate:"..."` ... |
|
scope
Package scope provides the `@scope :mods { ...
|
Package scope provides the `@scope :mods { ... |
|
selftestkit
Package selftestkit ships the coverage fixtures the self-test suite references as `cov.*`.
|
Package selftestkit ships the coverage fixtures the self-test suite references as `cov.*`. |
|
syntax
Package syntax ships the four binary operators every .nflow file relies on: ->, |, &, ||.
|
Package syntax ships the four binary operators every .nflow file relies on: ->, |, &, ||. |
|
template
Package template provides a reusable Go text-template renderer and exposes it to Flow as the template.render action.
|
Package template provides a reusable Go text-template renderer and exposes it to Flow as the template.render action. |
|
Package native is the single source of truth for the bundle set the shipped nflow CLI loads.
|
Package native is the single source of truth for the bundle set the shipped nflow CLI loads. |
|
Package redact masks well-known credential-shaped field names before a value is handed to a logger.
|
Package redact masks well-known credential-shaped field names before a value is handed to a logger. |
|
Plik: flow/runner/config.go
|
Plik: flow/runner/config.go |
|
Package spec osadza oficjalne pliki specyfikacji .nflow.
|
Package spec osadza oficjalne pliki specyfikacji .nflow. |
|
Package template provides package-agnostic text template rendering.
|
Package template provides package-agnostic text template rendering. |
Click to show internal directories.
Click to hide internal directories.