@telorun/run 0.1.1 → 0.1.3

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/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # @telorun/run
2
2
 
3
+ ## 0.1.3
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies
8
+ - @telorun/sdk@0.2.8
9
+
10
+ ## 0.1.2
11
+
12
+ ### Patch Changes
13
+
14
+ - Updated dependencies
15
+ - @telorun/sdk@0.2.7
16
+
3
17
  ## 0.1.1
4
18
 
5
19
  ### Patch Changes
package/README.md ADDED
@@ -0,0 +1,233 @@
1
+ # ⚡ Telo
2
+
3
+ Runtime for declarative backends.
4
+
5
+ Telo is an execution engine (Micro-Kernel) that runs logic defined entirely in YAML manifests. Instead of writing imperative backend code, you define your routes, databases, schemas, and AI workflows as atomic, interconnected YAML documents. Telo takes those manifests and runs them.
6
+
7
+ Built to be language-agnostic and infinitely extensible.
8
+
9
+ ```bash
10
+ # Reconcile your manifest into a running backend
11
+ $ telo ./examples/hello-api.yaml
12
+
13
+ {"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
14
+ ```
15
+
16
+ ## Why use Telo?
17
+
18
+ - **Open Standards:** Built on YAML, JSON Schema, and CEL — no proprietary DSL.
19
+ - **Static Analysis:** CEL type checking, reference validation, and IDE diagnostics catch errors before runtime.
20
+ - **Micro-Kernel Architecture:** Telo itself knows nothing about HTTP or SQL. Everything is a module you import, scope, and compose with typed variable and secret contracts.
21
+ - **Language Agnostic:** Available as a Node.js runtime today, with a shared YAML runtime contract that allows for future Rust or Go implementations without changing your manifests.
22
+
23
+ ## What It Does
24
+
25
+ - **Loads** YAML resources and compiles CEL expressions (`${{ }}`) into an in-memory registry.
26
+ - **Resolves** resource dependencies via a multi-pass init loop, handling ordering automatically.
27
+ - **Indexes** resources by Kind and Name for constant-time lookup.
28
+ - **Dispatches** execution to the controller that owns each Kind.
29
+
30
+ Manifests also support directives for dynamic generation: `$let`, `$if`, `$for`, `$eval`, and `$include`. See [CEL-YAML Templating](./yaml-cel-templating/README.md) for documentation.
31
+
32
+ ## Example manifest
33
+
34
+ Here is an example Telo application that defines a simple HTTP API:
35
+
36
+ ```yaml
37
+ kind: Kernel.Module
38
+ metadata:
39
+ name: feedback
40
+ version: 1.0.0
41
+ description: |
42
+ A complete feedback collection REST API — no code, pure YAML.
43
+ Persists entries to SQLite and serves them over HTTP.
44
+ targets:
45
+ - Migrations
46
+ - Server
47
+ ---
48
+ kind: Kernel.Import
49
+ metadata:
50
+ name: Http
51
+ source: ../modules/http-server
52
+ ---
53
+ kind: Kernel.Import
54
+ metadata:
55
+ name: Sql
56
+ source: ../modules/sql
57
+ ---
58
+ # SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
59
+ kind: Sql.Connection
60
+ metadata:
61
+ name: Db
62
+ driver: sqlite
63
+ file: ./tmp/feedback.db
64
+ ---
65
+ # Migrations: applied automatically before the server starts
66
+ kind: Sql.Migrations
67
+ metadata:
68
+ name: Migrations
69
+ connection:
70
+ kind: Sql.Connection
71
+ name: Db
72
+ ---
73
+ kind: Sql.Migration
74
+ metadata:
75
+ name: Migration_20260413_182154_CreateFeedback
76
+ sql: |
77
+ CREATE TABLE IF NOT EXISTS feedback (
78
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
79
+ text TEXT NOT NULL,
80
+ source TEXT,
81
+ score INTEGER NOT NULL DEFAULT 0,
82
+ created_at DATETIME DEFAULT CURRENT_TIMESTAMP
83
+ )
84
+ ---
85
+ kind: Http.Server
86
+ metadata:
87
+ name: Server
88
+ baseUrl: http://localhost:8844
89
+ port: 8844
90
+ logger: true
91
+ openapi:
92
+ info:
93
+ title: Feedback API
94
+ version: 1.0.0
95
+ mounts:
96
+ - path: /v1
97
+ type: Http.Api.FeedbackRoutes
98
+ ---
99
+ kind: Http.Api
100
+ metadata:
101
+ name: FeedbackRoutes
102
+ routes:
103
+ # POST /v1/feedback — insert a new entry, score derived from body length heuristic
104
+ - request:
105
+ path: /feedback
106
+ method: POST
107
+ schema:
108
+ body:
109
+ type: object
110
+ properties:
111
+ text:
112
+ type: string
113
+ minLength: 1
114
+ source:
115
+ type: string
116
+ required: [text]
117
+ handler:
118
+ kind: Sql.Exec
119
+ connection:
120
+ kind: Sql.Connection
121
+ name: Db
122
+ inputs:
123
+ sql: "INSERT INTO feedback (text, source, score) VALUES (?, ?, ?)"
124
+ bindings:
125
+ - "${{ request.body.text }}"
126
+ - "${{ request.body.source }}"
127
+ - "${{ size(request.body.text) }}"
128
+ response:
129
+ - status: 201
130
+ headers:
131
+ Content-Type: application/json
132
+ body:
133
+ ok: true
134
+ message: Feedback received
135
+
136
+ # GET /v1/feedback — list all entries, newest first
137
+ - request:
138
+ path: /feedback
139
+ method: GET
140
+ handler:
141
+ kind: Sql.Select
142
+ connection:
143
+ kind: Sql.Connection
144
+ name: Db
145
+ from: feedback
146
+ columns: [id, text, source, score, created_at]
147
+ orderBy:
148
+ - { column: created_at, direction: desc }
149
+ response:
150
+ - status: 200
151
+ headers:
152
+ Content-Type: application/json
153
+ body: "${{ result.rows }}"
154
+
155
+ # GET /v1/feedback/{id} — fetch a single entry
156
+ - request:
157
+ path: /feedback/{id}
158
+ method: GET
159
+ schema:
160
+ params:
161
+ type: object
162
+ properties:
163
+ id:
164
+ type: integer
165
+ required: [id]
166
+ handler:
167
+ kind: Sql.Select
168
+ connection:
169
+ kind: Sql.Connection
170
+ name: Db
171
+ from: feedback
172
+ columns: [id, text, source, score, created_at]
173
+ where:
174
+ - { column: id, op: "=", value: "${{ request.params.id }}" }
175
+ response:
176
+ - status: 200
177
+ when: "size(result.rows) > 0"
178
+ headers:
179
+ Content-Type: application/json
180
+ body: "${{ result.rows[0] }}"
181
+ - status: 404
182
+ headers:
183
+ Content-Type: application/json
184
+ body:
185
+ ok: false
186
+ message: Not found
187
+ ```
188
+
189
+ ## Status
190
+
191
+ Telo is under **active development**. The core runtime, module system, and standard library are functional, but the API surface — including YAML shapes — may change without notice. Not yet recommended for production use.
192
+
193
+ ## The Meaning of Telo
194
+
195
+ The name Telo is derived from the Greek root Telos - meaning the "end goal", "purpose", or "final state". That is exactly the philosophy behind this runtime. In standard imperative programming, you have to write thousands of lines of code to tell a server exactly how to start. With Telo, you simply declare your desired final state.
196
+
197
+ You define the end state. Telo makes it real.
198
+
199
+ ## Philosophy
200
+
201
+ Modern platforms often spend disproportionate effort on technical mechanics-wiring frameworks, managing infrastructure, and negotiating toolchains-while the original business problem gets delayed or diluted. Telo pushes in the opposite direction: it treats kernel execution as a stable, predictable host so teams can concentrate on the **business logic and outcomes** instead of the plumbing.
202
+
203
+ By separating "what the system should do" from "how it is hosted", the runtime reduces friction for domain‑level changes. Teams can move faster on product requirements, experiment more safely, and keep conversations centered on value delivered rather than implementation trivia.
204
+
205
+ Telo also aims to **join forces across all programming language communities**, so the best ideas, patterns, and implementations can converge into a shared kernel truth without forcing everyone into a single stack.
206
+
207
+ YAML also makes the system more **AI‑friendly** than traditional programming languages: it is explicit, structured, and easier for tools to generate, review, and transform without losing intent.
208
+
209
+ ## Modularity
210
+
211
+ Telo is built around **modules** that own specific resource kinds. A module is loaded from a manifest, declares which kinds it implements, and then receives only the resources of those kinds. This keeps concerns isolated and lets teams compose systems from focused building blocks rather than monolithic services.
212
+
213
+ At kernel execution time, execution is always routed by **Kind.Name**. The kernel resolves the Kind to its owning module and hands off execution. Modules can call back into the kernel to execute other resources, enabling composition without tight coupling.
214
+
215
+ ## Architecture
216
+
217
+ The architecture is inspired by Kubernetes-style manifests: declarative resources, explicit kinds, and a control plane that routes work based on those definitions.
218
+ Those manifests were taken to the next level by allowing them to run inside a standalone runtime host.
219
+
220
+ ## See more at
221
+
222
+ - [Telo Kernel](./kernel/README.md)
223
+ - [CEL-YAML Templating](./yaml-cel-templating/README.md)
224
+ - [Telo SDK for module authors](sdk/README.md)
225
+ - [Modules](modules/README.md)
226
+
227
+ ## License
228
+
229
+ See [LICENSE](https://github.com/telorun/telo/blob/main/LICENSE).
230
+
231
+ ## Contribution Note
232
+
233
+ By contributing, you agree that code and examples in this repository may be translated or re‑implemented in other programming languages (including by AI systems) to support the project’s polyglot goals.
@@ -14,6 +14,10 @@ interface IfStep {
14
14
  name: string;
15
15
  if: string;
16
16
  then: Step[];
17
+ elseif?: Array<{
18
+ if: string;
19
+ then: Step[];
20
+ }>;
17
21
  else?: Step[];
18
22
  }
19
23
  interface WhileStep {
@@ -49,6 +53,7 @@ declare class RunSequence {
49
53
  constructor(ctx: ResourceContext, resource: RunSequenceManifest);
50
54
  init(): Promise<void>;
51
55
  private resolveInvokes;
56
+ private inlineInvokeResourceName;
52
57
  run(): Promise<void>;
53
58
  invoke(inputs: Record<string, unknown>): Promise<unknown>;
54
59
  private runScopeTargets;
package/dist/sequence.js CHANGED
@@ -23,36 +23,47 @@ class RunSequence {
23
23
  async init() {
24
24
  this.resolveInvokes(this.resource.steps);
25
25
  }
26
- resolveInvokes(stepList) {
27
- for (const step of stepList) {
26
+ resolveInvokes(stepList, path = ["steps"]) {
27
+ for (const [index, step] of stepList.entries()) {
28
+ const stepPath = [...path, String(index)];
28
29
  if (isInvokeStep(step)) {
29
30
  const raw = step.invoke;
30
31
  if (!raw || typeof raw.invoke !== "function") {
31
- step.invoke = this.ctx.resolveChildren(raw, step.name);
32
+ step.invoke = this.ctx.resolveChildren(raw, this.inlineInvokeResourceName(step.name, stepPath));
32
33
  }
33
34
  }
34
35
  if (isIfStep(step)) {
35
- this.resolveInvokes(step.then);
36
+ this.resolveInvokes(step.then, [...stepPath, "then"]);
37
+ if (step.elseif) {
38
+ for (const [elseifIndex, branch] of step.elseif.entries()) {
39
+ this.resolveInvokes(branch.then, [...stepPath, "elseif", String(elseifIndex), "then"]);
40
+ }
41
+ }
36
42
  if (step.else)
37
- this.resolveInvokes(step.else);
43
+ this.resolveInvokes(step.else, [...stepPath, "else"]);
38
44
  }
39
45
  if (isWhileStep(step))
40
- this.resolveInvokes(step.do);
46
+ this.resolveInvokes(step.do, [...stepPath, "do"]);
41
47
  if (isSwitchStep(step)) {
42
- for (const branch of Object.values(step.cases))
43
- this.resolveInvokes(branch);
48
+ for (const [caseName, branch] of Object.entries(step.cases)) {
49
+ this.resolveInvokes(branch, [...stepPath, "cases", caseName]);
50
+ }
44
51
  if (step.default)
45
- this.resolveInvokes(step.default);
52
+ this.resolveInvokes(step.default, [...stepPath, "default"]);
46
53
  }
47
54
  if (isTryStep(step)) {
48
- this.resolveInvokes(step.try);
55
+ this.resolveInvokes(step.try, [...stepPath, "try"]);
49
56
  if (step.catch)
50
- this.resolveInvokes(step.catch);
57
+ this.resolveInvokes(step.catch, [...stepPath, "catch"]);
51
58
  if (step.finally)
52
- this.resolveInvokes(step.finally);
59
+ this.resolveInvokes(step.finally, [...stepPath, "finally"]);
53
60
  }
54
61
  }
55
62
  }
63
+ inlineInvokeResourceName(stepName, stepPath) {
64
+ const safeName = stepName.replace(/[^a-zA-Z0-9_-]+/g, "_");
65
+ return `__sequence_${stepPath.join("_")}__${safeName}`;
66
+ }
56
67
  async run() {
57
68
  if (this.resource.with) {
58
69
  await this.resource.with.run(async (scope) => {
@@ -136,8 +147,17 @@ class RunSequence {
136
147
  async executeIfStep(step, steps, scope, extraCtx) {
137
148
  if (this.ctx.expandValue(step.if, { steps, ...extraCtx })) {
138
149
  await this.executeSteps(step.then, steps, scope, extraCtx);
150
+ return;
151
+ }
152
+ if (step.elseif) {
153
+ for (const branch of step.elseif) {
154
+ if (this.ctx.expandValue(branch.if, { steps, ...extraCtx })) {
155
+ await this.executeSteps(branch.then, steps, scope, extraCtx);
156
+ return;
157
+ }
158
+ }
139
159
  }
140
- else if (step.else) {
160
+ if (step.else) {
141
161
  await this.executeSteps(step.else, steps, scope, extraCtx);
142
162
  }
143
163
  }
package/package.json CHANGED
@@ -1,6 +1,24 @@
1
1
  {
2
2
  "name": "@telorun/run",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
+ "description": "Telo Run module - Sequence execution for Telo manifests.",
5
+ "keywords": [
6
+ "telo",
7
+ "run",
8
+ "sequence",
9
+ "pipeline"
10
+ ],
11
+ "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
12
+ "license": "SEE LICENSE IN LICENSE",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/telorun/telo.git",
16
+ "directory": "modules/run/nodejs"
17
+ },
18
+ "homepage": "https://github.com/telorun/telo#readme",
19
+ "bugs": {
20
+ "url": "https://github.com/telorun/telo/issues"
21
+ },
4
22
  "type": "module",
5
23
  "main": "./src/sequence.ts",
6
24
  "module": "./src/sequence.ts",
@@ -11,7 +29,7 @@
11
29
  }
12
30
  },
13
31
  "dependencies": {
14
- "@telorun/sdk": "0.2.6"
32
+ "@telorun/sdk": "0.2.8"
15
33
  },
16
34
  "devDependencies": {
17
35
  "@types/node": "^20.0.0",
package/src/sequence.ts CHANGED
@@ -17,6 +17,10 @@ interface IfStep {
17
17
  name: string;
18
18
  if: string;
19
19
  then: Step[];
20
+ elseif?: Array<{
21
+ if: string;
22
+ then: Step[];
23
+ }>;
20
24
  else?: Step[];
21
25
  }
22
26
 
@@ -84,34 +88,47 @@ class RunSequence {
84
88
  this.resolveInvokes(this.resource.steps);
85
89
  }
86
90
 
87
- private resolveInvokes(stepList: Step[]): void {
88
- for (const step of stepList) {
91
+ private resolveInvokes(stepList: Step[], path: string[] = ["steps"]): void {
92
+ for (const [index, step] of stepList.entries()) {
93
+ const stepPath = [...path, String(index)];
89
94
  if (isInvokeStep(step)) {
90
95
  const raw = step.invoke as unknown;
91
96
  if (!raw || typeof (raw as Invocable).invoke !== "function") {
92
97
  (step as InvokeStep).invoke = this.ctx.resolveChildren(
93
98
  raw as any,
94
- step.name,
99
+ this.inlineInvokeResourceName(step.name, stepPath),
95
100
  ) as KindRef<Invocable>;
96
101
  }
97
102
  }
98
103
  if (isIfStep(step)) {
99
- this.resolveInvokes(step.then);
100
- if (step.else) this.resolveInvokes(step.else);
104
+ this.resolveInvokes(step.then, [...stepPath, "then"]);
105
+ if (step.elseif) {
106
+ for (const [elseifIndex, branch] of step.elseif.entries()) {
107
+ this.resolveInvokes(branch.then, [...stepPath, "elseif", String(elseifIndex), "then"]);
108
+ }
109
+ }
110
+ if (step.else) this.resolveInvokes(step.else, [...stepPath, "else"]);
101
111
  }
102
- if (isWhileStep(step)) this.resolveInvokes(step.do);
112
+ if (isWhileStep(step)) this.resolveInvokes(step.do, [...stepPath, "do"]);
103
113
  if (isSwitchStep(step)) {
104
- for (const branch of Object.values(step.cases)) this.resolveInvokes(branch);
105
- if (step.default) this.resolveInvokes(step.default);
114
+ for (const [caseName, branch] of Object.entries(step.cases)) {
115
+ this.resolveInvokes(branch, [...stepPath, "cases", caseName]);
116
+ }
117
+ if (step.default) this.resolveInvokes(step.default, [...stepPath, "default"]);
106
118
  }
107
119
  if (isTryStep(step)) {
108
- this.resolveInvokes(step.try);
109
- if (step.catch) this.resolveInvokes(step.catch);
110
- if (step.finally) this.resolveInvokes(step.finally);
120
+ this.resolveInvokes(step.try, [...stepPath, "try"]);
121
+ if (step.catch) this.resolveInvokes(step.catch, [...stepPath, "catch"]);
122
+ if (step.finally) this.resolveInvokes(step.finally, [...stepPath, "finally"]);
111
123
  }
112
124
  }
113
125
  }
114
126
 
127
+ private inlineInvokeResourceName(stepName: string, stepPath: string[]): string {
128
+ const safeName = stepName.replace(/[^a-zA-Z0-9_-]+/g, "_");
129
+ return `__sequence_${stepPath.join("_")}__${safeName}`;
130
+ }
131
+
115
132
  async run(): Promise<void> {
116
133
  if (this.resource.with) {
117
134
  await this.resource.with.run(async (scope) => {
@@ -217,7 +234,19 @@ class RunSequence {
217
234
  ): Promise<void> {
218
235
  if (this.ctx.expandValue(step.if, { steps, ...extraCtx })) {
219
236
  await this.executeSteps(step.then, steps, scope, extraCtx);
220
- } else if (step.else) {
237
+ return;
238
+ }
239
+
240
+ if (step.elseif) {
241
+ for (const branch of step.elseif) {
242
+ if (this.ctx.expandValue(branch.if, { steps, ...extraCtx })) {
243
+ await this.executeSteps(branch.then, steps, scope, extraCtx);
244
+ return;
245
+ }
246
+ }
247
+ }
248
+
249
+ if (step.else) {
221
250
  await this.executeSteps(step.else, steps, scope, extraCtx);
222
251
  }
223
252
  }