@telorun/stream 0.2.0 → 0.3.0

package/README.md

@@ -23,7 +23,7 @@ Built to be language-agnostic and infinitely extensible.
 
 ```bash
 # Reconcile your manifest into a running backend
-$ telo ./examples/hello-api.yaml
+$ telo ./examples/hello-api
 
 {"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
 ```
@@ -44,154 +44,7 @@ $ telo ./examples/hello-api.yaml
 
 ## Example manifest
 
-Here is an example Telo application that defines a simple HTTP API:
-
-```yaml
-kind: Telo.Application
-metadata:
-  name: feedback
-  version: 1.0.0
-  description: |
-    A complete feedback collection REST API — no code, pure YAML.
-    Persists entries to SQLite and serves them over HTTP.
-imports:
-  Http: std/http-server@0.6.1
-  Sql: std/sql@0.5.1
-targets:
-  - Migrations
-  - Server
----
-# SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
-kind: Sql.Connection
-metadata:
-  name: Db
-driver: sqlite
-file: ./tmp/feedback.db
----
-# Migrations: applied automatically before the server starts
-kind: Sql.Migrations
-metadata:
-  name: Migrations
-connection:
-  kind: Sql.Connection
-  name: Db
----
-kind: Sql.Migration
-metadata:
-  name: Migration_20260413_182154_CreateFeedback
-version: 20260413_182154_CreateFeedback
-sql: |
-  CREATE TABLE IF NOT EXISTS feedback (
-    id        INTEGER PRIMARY KEY AUTOINCREMENT,
-    text      TEXT    NOT NULL,
-    source    TEXT,
-    score     INTEGER NOT NULL DEFAULT 0,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-  )
----
-kind: Http.Server
-metadata:
-  name: Server
-baseUrl: http://localhost:8844
-port: 8844
-logger: true
-openapi:
-  info:
-    title: Feedback API
-    version: 1.0.0
-mounts:
-  - path: /v1
-    type: Http.Api.FeedbackRoutes
----
-kind: Http.Api
-metadata:
-  name: FeedbackRoutes
-routes:
-  # POST /v1/feedback — insert a new entry, score derived from body length heuristic
-  - request:
-      path: /feedback
-      method: POST
-      schema:
-        body:
-          type: object
-          properties:
-            text:
-              type: string
-              minLength: 1
-            source:
-              type: string
-          required: [ text ]
-    handler:
-      kind: Sql.Exec
-      connection:
-        kind: Sql.Connection
-        name: Db
-    inputs:
-      sql: "INSERT INTO feedback (text, source, score) VALUES (?, ?, ?)"
-      bindings:
-        - "${{ request.body.text }}"
-        - "${{ request.body.source }}"
-        - "${{ size(request.body.text) }}"
-    response:
-      - status: 201
-        headers:
-          Content-Type: application/json
-        body:
-          ok: true
-          message: Feedback received
-
-  # GET /v1/feedback — list all entries, newest first
-  - request:
-      path: /feedback
-      method: GET
-    handler:
-      kind: Sql.Select
-      connection:
-        kind: Sql.Connection
-        name: Db
-      from: feedback
-      columns: [ id, text, source, score, created_at ]
-      orderBy:
-        - { column: created_at, direction: desc }
-    response:
-      - status: 200
-        headers:
-          Content-Type: application/json
-        body: "${{ result.rows }}"
-
-  # GET /v1/feedback/{id} — fetch a single entry
-  - request:
-      path: /feedback/{id}
-      method: GET
-      schema:
-        params:
-          type: object
-          properties:
-            id:
-              type: integer
-          required: [ id ]
-    handler:
-      kind: Sql.Select
-      connection:
-        kind: Sql.Connection
-        name: Db
-      from: feedback
-      columns: [ id, text, source, score, created_at ]
-      where:
-        - { column: id, op: "=", value: "${{ request.params.id }}" }
-    response:
-      - status: 200
-        when: "size(result.rows) > 0"
-        headers:
-          Content-Type: application/json
-        body: "${{ result.rows[0] }}"
-      - status: 404
-        headers:
-          Content-Type: application/json
-        body:
-          ok: false
-          message: Not found
-```
+See [examples/](./examples/) for a list of working applications.
 
 ## Status
 

package/dist/collect-controller.d.ts

@@ -0,0 +1,29 @@
+import type { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+interface CollectResource {
+    metadata: {
+        name: string;
+        module?: string;
+    };
+}
+interface CollectInputs {
+    input: AsyncIterable<unknown>;
+}
+interface CollectOutputs {
+    items: unknown[];
+}
+/**
+ * Terminal stream sink — the inverse of Stream.Of. Consumes `input` fully and
+ * returns every item as `items`, in order. Draining drives the producer's side
+ * effects (so it "runs" an upstream agent / pipeline); the result materializes the
+ * finite stream for inspection, assertion, or aggregation in CEL. Value-agnostic and
+ * buffered — bounded by the stream's length.
+ */
+declare class StreamCollect implements ResourceInstance<CollectInputs, CollectOutputs> {
+    private readonly resource;
+    constructor(resource: CollectResource);
+    invoke(inputs: CollectInputs): Promise<CollectOutputs>;
+    snapshot(): Record<string, unknown>;
+}
+export declare function register(_ctx: ControllerContext): void;
+export declare function create(resource: CollectResource, _ctx: ResourceContext): Promise<StreamCollect>;
+export {};

package/dist/collect-controller.js

@@ -0,0 +1,33 @@
+import { InvokeError } from "@telorun/sdk";
+/**
+ * Terminal stream sink — the inverse of Stream.Of. Consumes `input` fully and
+ * returns every item as `items`, in order. Draining drives the producer's side
+ * effects (so it "runs" an upstream agent / pipeline); the result materializes the
+ * finite stream for inspection, assertion, or aggregation in CEL. Value-agnostic and
+ * buffered — bounded by the stream's length.
+ */
+class StreamCollect {
+    resource;
+    constructor(resource) {
+        this.resource = resource;
+    }
+    async invoke(inputs) {
+        const name = this.resource.metadata.name;
+        const input = inputs?.input;
+        if (!input ||
+            typeof input[Symbol.asyncIterator] !== "function") {
+            throw new InvokeError("ERR_INVALID_INPUT", `Stream.Collect "${name}": 'input' must be an AsyncIterable.`);
+        }
+        const items = [];
+        for await (const item of input)
+            items.push(item);
+        return { items };
+    }
+    snapshot() {
+        return {};
+    }
+}
+export function register(_ctx) { }
+export async function create(resource, _ctx) {
+    return new StreamCollect(resource);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/stream",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Generic stream substrate — value-agnostic stream construction (Stream.Of).",
   "keywords": [
     "telo",
@@ -32,6 +32,11 @@
       "types": "./dist/of-controller.d.ts",
       "bun": "./src/of-controller.ts",
       "import": "./dist/of-controller.js"
+    },
+    "./collect": {
+      "types": "./dist/collect-controller.d.ts",
+      "bun": "./src/collect-controller.ts",
+      "import": "./dist/collect-controller.js"
     }
   },
   "files": [
@@ -41,7 +46,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.18.0"
+    "@telorun/sdk": "0.38.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/collect-controller.ts

@@ -0,0 +1,55 @@
+import type { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { InvokeError } from "@telorun/sdk";
+
+interface CollectResource {
+  metadata: { name: string; module?: string };
+}
+
+interface CollectInputs {
+  input: AsyncIterable<unknown>;
+}
+
+interface CollectOutputs {
+  items: unknown[];
+}
+
+/**
+ * Terminal stream sink — the inverse of Stream.Of. Consumes `input` fully and
+ * returns every item as `items`, in order. Draining drives the producer's side
+ * effects (so it "runs" an upstream agent / pipeline); the result materializes the
+ * finite stream for inspection, assertion, or aggregation in CEL. Value-agnostic and
+ * buffered — bounded by the stream's length.
+ */
+class StreamCollect implements ResourceInstance<CollectInputs, CollectOutputs> {
+  constructor(private readonly resource: CollectResource) {}
+
+  async invoke(inputs: CollectInputs): Promise<CollectOutputs> {
+    const name = this.resource.metadata.name;
+    const input = inputs?.input;
+    if (
+      !input ||
+      typeof (input as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] !== "function"
+    ) {
+      throw new InvokeError(
+        "ERR_INVALID_INPUT",
+        `Stream.Collect "${name}": 'input' must be an AsyncIterable.`,
+      );
+    }
+    const items: unknown[] = [];
+    for await (const item of input) items.push(item);
+    return { items };
+  }
+
+  snapshot(): Record<string, unknown> {
+    return {};
+  }
+}
+
+export function register(_ctx: ControllerContext): void {}
+
+export async function create(
+  resource: CollectResource,
+  _ctx: ResourceContext,
+): Promise<StreamCollect> {
+  return new StreamCollect(resource);
+}