stof 0.8.39

A smart, declarative runtime for data workflows.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231

<p align="center"><img src="./content/stof.png" height="150"></p>
<p align="center">
    <a href="https://docs.stof.dev"><img src="https://img.shields.io/badge/docs-docs.stof.dev-purple?logo=gitbook&logoColor=white"></a><span style="margin: 0px 4px;"></span>
    <a href="https://github.com/dev-formata-io/stof"><img src="https://img.shields.io/github/stars/dev-formata-io/stof"></a>
</p>
<p align="center">
    <a href="https://github.com/dev-formata-io/stof/actions"><img src="https://img.shields.io/github/actions/workflow/status/dev-formata-io/stof/rust.yml"></a>
    <a href="https://crates.io/crates/stof"><img src="https://img.shields.io/crates/d/stof?label=Stof%20downloads&color=aqua"></a>
    <a href="https://crates.io/crates/stof-cli"><img src="https://img.shields.io/crates/d/stof-cli?label=CLI%20downloads&color=darkgray"></a>
    <a href="https://crates.io/crates/stof"><img src="https://img.shields.io/crates/l/stof?color=maroon"></a>
    <a href="https://github.com/dev-formata-io/stof/commits"><img src="https://img.shields.io/github/commit-activity/m/dev-formata-io/stof"></a>
</p>

----

<br/>

**A smart, declarative runtime for data workflows**
- [Docs](https://docs.stof.dev)
- [GitHub](https://github.com/dev-formata-io/stof)
- [Discord](https://discord.gg/Up5kxdeXZt)
- [Install](https://docs.stof.dev/book/installation)

## What is Stof?

Stof works **with** other data formats to bridge the gap between static data and programmable documents. It is a lightweight, embeddable, and portable data logic format & platform for AI, infra-as-code, and config-heavy workflows. It's built to support:

- Data-Mesh, Integration, & Orchestration **glue-layer**
- Universal LLM & AI workflows, tools, & **intersystem data**
- Smart configs with logic, types, units, schemas, & **self-validation**
- Asynchronous **validation & transformation**

> Think of Stof as a foundation for building robust and declarative data flows, config systems, or backend models.

## When to use Stof?

Modern software (especially AI/ML, infra, cloud, CI/CD, and workflows) increasingly relies on structured data that needs to be:
- Human-readable
- Machine-validatable
- Extendable with logic
- Executable safely
- Translatable between formats
- Transported between systems
- Versioned and inspectable

But the tools we have for this are *primitive and fragmented*:
- JSON/YAML/TOML carry structure, but rely on other tools for behavior, units, schemas, or validations.
- External tools create complexity between systems and often require additional configuration & maintenence.
- Configs drift and break across environments.
- Runtime logic is scattered across codebases, devops scripts, and data definitions.

> Stof unifies **structure + validation + behavior** into one **coherent, inspectable, portable artifact**.

*Note: if you're doing simple config loading or small and static data modeling, learning Stof might feel like overkill. You can replicate most of what Stof does using JSON + code + libraries; it just takes more effort and lacks formality, organization, single-file simplicity, unification, etc. (also a big pain for cross-boundary systems, like APIs, teams, and services).*

## Example/Tour

> Located in `examples/readme` for you to try yourself.
``` rust
/*
 * True data interop!
 * Import/export any format - our goal is to work seamlessly WITH other formats.
 * Organize data, APIs, configs, connectors, pipelines, AI, etc. with objects & paths, as a graph.
 */
import "old_crusty_config.toml" as OldCrusty; // Creates a new root object named "OldCrusty"
import "norse.png" as self.NorseImage;        // Creates a child object with path "root.NorseImage"


/*
 * Define objects and fields in a JSON-like way.
 */
{
    "json-like": "json objects & fields can be parsed by Stof natively",
    str "just stof": "it's all Stof, so use types, etc."
}

field: 42              // Optionally end field declarations with a comma or semi-colon
str typed: "types!"    // Field types for consistency, readability, and reliability
const bool cool: true; // Constant fields for immutable data (with or without type)

MiB unit-types: OldCrusty.server.RAM; // Unit types for conversions on casts, operations, etc.
cm height: 6ft + 1in;                 // Expressions and a full runtime always available


/*
 * Functions & logic as data. Manipulate this document from within.
 *
 * - Sandboxed (host defines system access, if any)
 * - Portable (send and execute over a network)
 * - Simple (familiar, approachable, and intuative, without looking like a blob of JSON)
 */
fn hello_world() -> str {
    "hello, world"
}


/*
 * Use objects to organize every type of data, including logic & APIs.
 * Keyword "self" always refers to the current object.
 * Keyword "super" always refers to the parent object (if any).
 * Navigate the graph of data via dot separated paths (both down and up, including other roots).
 * Use "?" in front of function calls to return null if the function doesn't exist.
 */
Api: {
    import "api"; // default ".stof" extension if not provided
    str config-name: ?self.modular_apis(OldCrusty); // "Old Crusty"
}


/*
 * Attributes for metadata & control (both fields & functions).
 *
 * - Used for main, test, and async functions
 * - Reference objects, functions, and data (validation, access control, schemas, etc.)
 * - Always available programmatically for metadata access
 */
#[my_attribute]
#[attribute_with_val(42days)]
#[metadata_map({"config": true})]
#[metadata_obj(new { stof_object: true })]
#[validation((value: unknown): bool => true)]
metadata_field: "we have attributes"


/*
 * Foundational async behavior for modern networking and concurrency.
 * No threads by default, but host system can implement async as single or multi-threaded.
 *
 * Note: "async fn" just adds #[async] as a function attribute.
 *
 * - HTTP requests & APIs
 * - Database connections
 * - Event driven systems
 * - Declarative UI + logic
 */
async fn doing_something_concurrently() {
    // "Std" library, an extensible & complete standard library
    pln("Hello, Stof!");

    // Turn any expression into an async expression
    const handle = async 42;
    assert_eq(await handle, 42);

    // Async block expressions (and regular block expressions)
    const result = await async {
        let a = 5;
        let b = 5;
        return a + b;
    };
    assert_eq(result, 10);
}


/*
 * Prototypes for modern, complex data models & interfaces.
 * See docs for details.
 *
 * - Schemas
 * - Modular APIs applied to static data
 * - Pipelines & workflows
 * - Inheritance via #[extends(obj | str)]
 */
#[type]
Config: {
    /**

     * Example use with imported OldCrusty TOML data.
     * ```
     * const config = OldCrusty as Config;
     * assert_eq(config.description(), "Left to drift & die, but is required somehow");
     * ```
     */
    fn description() -> str {
        self.description ?? "no description"
    }
}



#[main]
/**

 * Stof CLI uses #[main] attributes by default to tell which functions to run with `stof run`.
 * Change this with the -a option, allowing you to use attributes instead of multiple scripts.
 *
 * Run with CLI via `stof run readme.stof` - you'll see `Hello, Stof!` printed to your console.
 * Run with `stof -d run readme.stof` - you'll now see YAML output in addition.
 *
 * Logging (log_debug, log_trace, log_info, log_warn, log_error) built in:
 * - `stof run readme.stof` - only log_warn & log_error
 * - `stof -d run readme.stof` - log_info in addition to warn & error
 * - `stof -dd run readme.stof` - all logs available
 * - uses "log" Rust crate for flexibility
 */
fn main() {
    self.doing_something_concurrently();

    const yaml = stringify("yaml", self);
    log_info(yaml);
}
```
``` bash
> cd examples/readme

> stof run readme.stof

Hello, Stof!

```

## Installation

Add Stof to your `Cargo.toml`:
```toml
[dependencies]
stof = "0.8.*"
```

See [installation docs](https://docs.stof.dev/book/installation) for CLI instructions and more information.

## Documentation

- [Hello, World](https://docs.stof.dev/book/hello-world)
- [Roadmap](https://docs.stof.dev/roadmap)
- [Install](https://docs.stof.dev/book/installation)
- [GitHub](https://github.com/dev-formata-io/stof)

## Status

Stof is currently in **early development**, we welcome feedback and contributions. The core is stable for experimentation, and is actively being used in production at [Formata](https://formata.io).

New features are being added weekly, so hop into the Discord and get involved!

## License

Apache 2.0. See LICENSE for details.

## Feedback & Community

- Open issues or discussions on [GitHub](https://github.com/dev-formata-io/stof)
- Chat with us on [Discord](https://discord.gg/Up5kxdeXZt)
- Star the project to support future development!

> Reach out to info@stof.dev to contact us directly