@telorun/record-stream 0.5.0 → 0.6.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,161 +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.
-targets:
-  - Migrations
-  - Server
----
-kind: Telo.Import
-metadata:
-  name: Http
-source: std/http-server@0.5.0
----
-kind: Telo.Import
-metadata:
-  name: Sql
-source: std/sql@0.3.0
----
-# 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/on-complete-controller.d.ts

@@ -0,0 +1,47 @@
+import type { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { Stream } from "@telorun/sdk";
+/**
+ * RecordStream.OnComplete — a stream passthrough that fires a side effect once the
+ * input has been fully consumed. Every item forwards to `output` in order as it
+ * arrives (the downstream consumer streams live); the items are also retained, and
+ * when the input completes normally the injected `handler` Invocable is called once
+ * with `{ records, context }` — `records` is the full list observed, `context` is the
+ * opaque caller data passed through the `context` input.
+ *
+ * The canonical use is persist-while-streaming: an HTTP handler streams an AI/agent
+ * response to the client via `output` and, at end-of-stream, `handler` writes the turn
+ * to a store. The primitive stays domain-neutral — it does no CEL and knows nothing of
+ * SQL; the projection from `records` to whatever the store needs lives in `handler`
+ * (typically a Run.Sequence).
+ *
+ * `handler` is NOT called if the input errors (a thrown iterator error propagates) or
+ * the consumer cancels early (`break` / aborted response) — completion means the input
+ * ran to its end. Records are buffered in memory, bounded by the input stream's length
+ * (same envelope as RecordStream.Tee).
+ */
+interface OnCompleteResource {
+    metadata: {
+        name: string;
+        module?: string;
+    };
+    /** Live Invocable instance after Phase 5 ref injection. */
+    handler: {
+        invoke(inputs: unknown): Promise<unknown>;
+    };
+}
+interface OnCompleteInputs {
+    input: AsyncIterable<unknown>;
+    context?: unknown;
+}
+interface OnCompleteOutputs {
+    output: Stream<unknown>;
+}
+declare class OnComplete implements ResourceInstance<OnCompleteInputs, OnCompleteOutputs> {
+    private readonly resource;
+    constructor(resource: OnCompleteResource);
+    invoke(inputs: OnCompleteInputs): Promise<OnCompleteOutputs>;
+    snapshot(): Record<string, unknown>;
+}
+export declare function register(_ctx: ControllerContext): void;
+export declare function create(resource: OnCompleteResource, _ctx: ResourceContext): Promise<OnComplete>;
+export {};

package/dist/on-complete-controller.js

@@ -0,0 +1,37 @@
+import { InvokeError, Stream } from "@telorun/sdk";
+class OnComplete {
+    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", `RecordStream.OnComplete "${name}": 'input' must be an AsyncIterable.`);
+        }
+        const handler = this.resource.handler;
+        if (!handler || typeof handler.invoke !== "function") {
+            throw new InvokeError("ERR_INVALID_REFERENCE", `RecordStream.OnComplete "${name}": 'handler' is not a live Invocable instance — check that Phase 5 injection ran.`);
+        }
+        const context = inputs.context;
+        async function* passthrough() {
+            const records = [];
+            for await (const item of input) {
+                records.push(item);
+                yield item;
+            }
+            // Input ran to its end — fire the completion handler once, then close. An error
+            // from the handler propagates (the stream ends by throwing); it is not swallowed.
+            await handler.invoke({ records, context });
+        }
+        return { output: new Stream(passthrough()) };
+    }
+    snapshot() {
+        return {};
+    }
+}
+export function register(_ctx) { }
+export async function create(resource, _ctx) {
+    return new OnComplete(resource);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/record-stream",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Stream operations on structured records — generic, format-neutral transformers.",
   "keywords": [
     "telo",
@@ -34,6 +34,11 @@
       "bun": "./src/extract-text-controller.ts",
       "import": "./dist/extract-text-controller.js"
     },
+    "./on-complete": {
+      "types": "./dist/on-complete-controller.d.ts",
+      "bun": "./src/on-complete-controller.ts",
+      "import": "./dist/on-complete-controller.js"
+    },
     "./tee": {
       "types": "./dist/tee-controller.d.ts",
       "bun": "./src/tee-controller.ts",
@@ -46,10 +51,11 @@
   ],
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@telorun/sdk": "0.38.0"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.13.0"
+    "@telorun/sdk": "*"
   },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json"

package/src/on-complete-controller.ts

@@ -0,0 +1,85 @@
+import type { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { InvokeError, Stream } from "@telorun/sdk";
+
+/**
+ * RecordStream.OnComplete — a stream passthrough that fires a side effect once the
+ * input has been fully consumed. Every item forwards to `output` in order as it
+ * arrives (the downstream consumer streams live); the items are also retained, and
+ * when the input completes normally the injected `handler` Invocable is called once
+ * with `{ records, context }` — `records` is the full list observed, `context` is the
+ * opaque caller data passed through the `context` input.
+ *
+ * The canonical use is persist-while-streaming: an HTTP handler streams an AI/agent
+ * response to the client via `output` and, at end-of-stream, `handler` writes the turn
+ * to a store. The primitive stays domain-neutral — it does no CEL and knows nothing of
+ * SQL; the projection from `records` to whatever the store needs lives in `handler`
+ * (typically a Run.Sequence).
+ *
+ * `handler` is NOT called if the input errors (a thrown iterator error propagates) or
+ * the consumer cancels early (`break` / aborted response) — completion means the input
+ * ran to its end. Records are buffered in memory, bounded by the input stream's length
+ * (same envelope as RecordStream.Tee).
+ */
+interface OnCompleteResource {
+  metadata: { name: string; module?: string };
+  /** Live Invocable instance after Phase 5 ref injection. */
+  handler: { invoke(inputs: unknown): Promise<unknown> };
+}
+
+interface OnCompleteInputs {
+  input: AsyncIterable<unknown>;
+  context?: unknown;
+}
+
+interface OnCompleteOutputs {
+  output: Stream<unknown>;
+}
+
+class OnComplete implements ResourceInstance<OnCompleteInputs, OnCompleteOutputs> {
+  constructor(private readonly resource: OnCompleteResource) {}
+
+  async invoke(inputs: OnCompleteInputs): Promise<OnCompleteOutputs> {
+    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",
+        `RecordStream.OnComplete "${name}": 'input' must be an AsyncIterable.`,
+      );
+    }
+    const handler = this.resource.handler;
+    if (!handler || typeof handler.invoke !== "function") {
+      throw new InvokeError(
+        "ERR_INVALID_REFERENCE",
+        `RecordStream.OnComplete "${name}": 'handler' is not a live Invocable instance — check that Phase 5 injection ran.`,
+      );
+    }
+    const context = inputs.context;
+
+    async function* passthrough(): AsyncGenerator<unknown> {
+      const records: unknown[] = [];
+      for await (const item of input) {
+        records.push(item);
+        yield item;
+      }
+      // Input ran to its end — fire the completion handler once, then close. An error
+      // from the handler propagates (the stream ends by throwing); it is not swallowed.
+      await handler.invoke({ records, context });
+    }
+
+    return { output: new Stream(passthrough()) };
+  }
+
+  snapshot(): Record<string, unknown> {
+    return {};
+  }
+}
+
+export function register(_ctx: ControllerContext): void {}
+
+export async function create(
+  resource: OnCompleteResource,
+  _ctx: ResourceContext,
+): Promise<OnComplete> {
+  return new OnComplete(resource);
+}