@inferencesh/app 0.1.12 → 0.1.13

package/README.md

@@ -22,6 +22,7 @@ npm install @inferencesh/app
 | `StorageDir` | standard storage directory constants (`DATA`, `TEMP`, `CACHE`) |
 | `download()` | download a url to a directory with caching |
 | `textMeta`, `imageMeta`, `videoMeta`, `audioMeta`, `rawMeta` | output metadata factories for usage-based pricing |
+| `createStreamSchema`, `pcm16`, `media`, `Live` | live fields for stream functions — values that flow over the socket while the task runs |
 
 ## file handling
 
@@ -219,6 +220,42 @@ export class App {
 }
 ```
 
+## stream functions
+
+a stream function takes its input and a socket (`async talk(inputData, socket)`), runs until it returns, and its return value is the result. some input and output fields are **live**: their values travel over the socket while the task runs instead of in the request body. declare them with `createStreamSchema`; in the json schema they become `{"type": "array", "format": "stream", "items": ...}` and are never required.
+
+```javascript
+import { z } from "zod";
+import { createStreamSchema, pcm16, Live } from "@inferencesh/app";
+
+export const TalkInput = z.object({
+  effect: z.enum(["none", "robot"]).default("none"),   // ordinary: set at the start, may change live
+  audio: createStreamSchema(z, pcm16(z, 16000)),      // live media: binary frames
+});
+
+export const TalkOutput = z.object({
+  audio: createStreamSchema(z, pcm16(z, 16000)),
+  frames: z.number().default(0),
+});
+
+export class App {
+  async talk(input, socket) {
+    const live = new Live(socket, input, TalkInput, TalkOutput);
+    let n = 0;
+    for await (const { field, value } of live) {
+      if (field === "audio") {          // value is a Buffer of PCM samples
+        n++;
+        await live.send({ audio: value });
+      }
+      // an ordinary field (effect) is already set on input when it changes
+    }
+    return { frames: n };
+  }
+}
+```
+
+on the wire, a binary frame is one item of the schema's single binary live field (`pcm16(z, rate, channels)` or `media(z, contentType)`); a json text frame is a partial object keyed by field name: an item of a live field (`{"events": {"type": "interrupt"}}`) or a new value for an ordinary field (`{"effect": "robot"}`). frames that do not fit the input schema are answered with `{"error": {"field", "message"}}` and skipped. `live.send({...})` sends the output binary field as a binary frame and everything else as one json frame; unknown output fields throw.
+
 ## requirements
 
 - node.js 18.0.0 or higher

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { File } from "./file.js";
 export type { FileOptions, FileData } from "./file.js";
 export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
+export type { Socket, Frame } from "./socket.js";
+export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, BINARY_SCHEMA_MARKER, } from "./stream.js";
+export type { Update } from "./stream.js";
 export { StorageDir, ensureDir } from "./storage.js";
 export type { StorageDirValue } from "./storage.js";
 export { download } from "./download.js";

package/dist/index.js

@@ -2,6 +2,7 @@
 export { File } from "./file.js";
 // Zod schema utilities
 export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
+export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, BINARY_SCHEMA_MARKER, } from "./stream.js";
 // Storage directories
 export { StorageDir, ensureDir } from "./storage.js";
 // Download utility

package/dist/socket.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The socket a stream function talks to.
+ *
+ * An app declares a stream function by taking a `socket` parameter after its
+ * input:
+ *
+ * ```js
+ * export class App {
+ *   async stream(inputData, socket) {
+ *     for await (const frame of socket) {   // Buffer or string, in order
+ *       await socket.send(frame);           // Buffer -> binary, string -> text,
+ *     }                                     // anything else -> JSON text
+ *     return { ... };
+ *   }
+ * }
+ * ```
+ *
+ * The function runs until it returns; its return value is the result the
+ * platform records. Frames from the client arrive in order; the iterator ends
+ * (and `recv()` resolves to null) when the client closes. Returning ends the
+ * stream for the client. This is a different thing from the platform's app
+ * session (a worker leased across several calls): a stream function runs as
+ * one call, inside an app session or on its own.
+ *
+ * The object the kernel passes in implements this interface; the interface
+ * here is for typing.
+ */
+/** One frame on the wire: binary (Buffer) or text (string). */
+export type Frame = Buffer | string;
+/** One live stream between a client and a stream function. */
+export interface Socket {
+    readonly id: string;
+    metadata: Record<string, unknown>;
+    /** True once the client is gone or the app closed the socket. */
+    readonly closed: boolean;
+    /** The next frame from the client, or null once it is gone. */
+    recv(): Promise<Frame | null>;
+    [Symbol.asyncIterator](): AsyncIterator<Frame>;
+    /** Send a frame: Buffer/Uint8Array/ArrayBuffer as binary, string as text, anything else as JSON text. */
+    send(data: Buffer | Uint8Array | ArrayBuffer | string | object): Promise<void>;
+    /** Stop reading from the client; the stream ends when the function returns. */
+    close(): Promise<void>;
+}

package/dist/socket.js

@@ -0,0 +1,28 @@
+/**
+ * The socket a stream function talks to.
+ *
+ * An app declares a stream function by taking a `socket` parameter after its
+ * input:
+ *
+ * ```js
+ * export class App {
+ *   async stream(inputData, socket) {
+ *     for await (const frame of socket) {   // Buffer or string, in order
+ *       await socket.send(frame);           // Buffer -> binary, string -> text,
+ *     }                                     // anything else -> JSON text
+ *     return { ... };
+ *   }
+ * }
+ * ```
+ *
+ * The function runs until it returns; its return value is the result the
+ * platform records. Frames from the client arrive in order; the iterator ends
+ * (and `recv()` resolves to null) when the client closes. Returning ends the
+ * stream for the client. This is a different thing from the platform's app
+ * session (a worker leased across several calls): a stream function runs as
+ * one call, inside an app session or on its own.
+ *
+ * The object the kernel passes in implements this interface; the interface
+ * here is for typing.
+ */
+export {};

package/dist/stream.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Live fields: input and output that flow over a stream function's socket.
+ *
+ * A stream function's input is still its input schema. Some of its fields are
+ * live: their values arrive over the socket while the task runs, instead of in
+ * the request body. The output schema works the same way in the other
+ * direction:
+ *
+ * ```js
+ * const TalkInput = z.object({
+ *   voice: z.enum(["ara", "eve"]).default("ara"),          // ordinary: set at the start
+ *   audio: createStreamSchema(z, pcm16(z, 16000)),         // live media
+ *   events: createStreamSchema(z, z.union([Interrupt, UserText])), // live typed messages
+ * });
+ *
+ * const TalkOutput = z.object({
+ *   audio: createStreamSchema(z, pcm16(z, 24000)),
+ *   seconds: z.number().default(0),
+ * });
+ * ```
+ *
+ * In the JSON schema a live field is an array delivered over time, marked
+ * `"format": "stream"` the way a file field is marked `"format": "file"`:
+ *
+ * ```json
+ * "audio": {"type": "array", "format": "stream",
+ *           "items": {"type": "string", "format": "binary",
+ *                     "contentMediaType": "audio/pcm;format=s16le;rate=16000;channels=1"}}
+ * ```
+ *
+ * Live fields are never required, so the request body is the ordinary fields
+ * only. File and stream fields are siblings: the same media, by reference or
+ * live.
+ *
+ * On the wire:
+ *
+ * - a binary frame is one item of the schema's binary live field (a schema has
+ *   at most one per direction, because a binary frame carries no field name);
+ * - a JSON text frame is a partial object of the schema keyed by field name:
+ *   `{"events": {"type": "interrupt"}}` is one item of a live field, and
+ *   `{"voice": "eve"}` changes an ordinary field while the task runs.
+ *
+ * `Live` applies that mapping to a socket, with the schemas as the contract.
+ *
+ * Zod is never imported: the app's own zod (v3 or v4) is passed in, and the
+ * schemas are read by duck-typing `_def`, the same way the kernel does.
+ */
+import type { Socket } from "./socket.js";
+/**
+ * Marks a live field's schema. The value on `_def` is the item schema.
+ * The kernel's zodToJsonSchema reads this and emits `format: "stream"`.
+ */
+export declare const STREAM_SCHEMA_MARKER: unique symbol;
+/**
+ * Marks a binary item schema. The value on `_def` is the content type.
+ * The kernel's zodToJsonSchema reads this and emits
+ * `{type: "string", format: "binary", contentMediaType}`.
+ */
+export declare const BINARY_SCHEMA_MARKER: unique symbol;
+/**
+ * A field whose values travel over the socket while the task runs.
+ *
+ * Parsing always yields the placeholder `[]`, whatever the caller put in the
+ * request body (items come over the socket), and a missing key parses too.
+ * Read and write the items with `Live`.
+ *
+ * @param z the app's zod instance
+ * @param item the schema of one item (`pcm16(z)`, `media(z, "image/jpeg")`, or any zod schema)
+ */
+export declare function createStreamSchema(z: any, item: any): any;
+/**
+ * Binary items of a media type, e.g. `createStreamSchema(z, media(z, "image/jpeg"))`.
+ * Accepts a Buffer or any Uint8Array.
+ */
+export declare function media(z: any, contentType: string): any;
+/**
+ * Raw 16-bit little-endian PCM audio. One frame is one chunk of samples;
+ * 20 ms (`rate / 50` samples) is the usual size for live audio.
+ */
+export declare function pcm16(z: any, rate?: number, channels?: number): any;
+/**
+ * One thing the caller sent: an item of a live field, or a new value for an
+ * ordinary field (already applied to the input data).
+ */
+export interface Update {
+    field: string;
+    value: unknown;
+}
+/** The object schema's live fields and their item schemas. */
+export declare function liveFields(objectSchema: any): Record<string, any>;
+/**
+ * The object schema's binary live field, or null. More than one is an error:
+ * a binary frame carries no field name.
+ */
+export declare function binaryField(objectSchema: any): string | null;
+/**
+ * A socket read and written through the function's schemas.
+ *
+ * ```js
+ * async talk(inputData, socket) {
+ *   const live = new Live(socket, inputData, TalkInput, TalkOutput);
+ *   for await (const update of live) {
+ *     if (update.field === "audio") {
+ *       await live.send({ audio: process(update.value, inputData.voice) });
+ *     } else if (update.field === "events") {
+ *       ...                      // update.value is an Interrupt or a UserText
+ *     }
+ *     // an ordinary field (voice) is already set on inputData
+ *   }
+ *   return { seconds: ... };
+ * }
+ * ```
+ *
+ * A frame that does not fit the input schema is answered with
+ * `{"error": {"field": ..., "message": ...}}` and skipped; the stream goes on.
+ */
+export declare class Live {
+    readonly socket: Socket;
+    readonly input: Record<string, unknown>;
+    private readonly inShape;
+    private readonly inLive;
+    private readonly inBinary;
+    private readonly outShape;
+    private readonly outBinary;
+    constructor(socket: Socket, inputData: Record<string, unknown>, inputSchema: any, outputSchema: any);
+    [Symbol.asyncIterator](): AsyncGenerator<Update, void, undefined>;
+    private frames;
+    private read;
+    private refuse;
+    /**
+     * Send items of live output fields, or new values of ordinary ones.
+     *
+     * `await live.send({ audio: pcm })` is a binary frame;
+     * `await live.send({ transcript: word })` and
+     * `await live.send({ effect: "echo" })` are JSON frames. Keys in one call
+     * other than the binary field go out together as one JSON frame.
+     */
+    send(fields: Record<string, unknown>): Promise<void>;
+}

package/dist/stream.js

@@ -0,0 +1,315 @@
+/**
+ * Live fields: input and output that flow over a stream function's socket.
+ *
+ * A stream function's input is still its input schema. Some of its fields are
+ * live: their values arrive over the socket while the task runs, instead of in
+ * the request body. The output schema works the same way in the other
+ * direction:
+ *
+ * ```js
+ * const TalkInput = z.object({
+ *   voice: z.enum(["ara", "eve"]).default("ara"),          // ordinary: set at the start
+ *   audio: createStreamSchema(z, pcm16(z, 16000)),         // live media
+ *   events: createStreamSchema(z, z.union([Interrupt, UserText])), // live typed messages
+ * });
+ *
+ * const TalkOutput = z.object({
+ *   audio: createStreamSchema(z, pcm16(z, 24000)),
+ *   seconds: z.number().default(0),
+ * });
+ * ```
+ *
+ * In the JSON schema a live field is an array delivered over time, marked
+ * `"format": "stream"` the way a file field is marked `"format": "file"`:
+ *
+ * ```json
+ * "audio": {"type": "array", "format": "stream",
+ *           "items": {"type": "string", "format": "binary",
+ *                     "contentMediaType": "audio/pcm;format=s16le;rate=16000;channels=1"}}
+ * ```
+ *
+ * Live fields are never required, so the request body is the ordinary fields
+ * only. File and stream fields are siblings: the same media, by reference or
+ * live.
+ *
+ * On the wire:
+ *
+ * - a binary frame is one item of the schema's binary live field (a schema has
+ *   at most one per direction, because a binary frame carries no field name);
+ * - a JSON text frame is a partial object of the schema keyed by field name:
+ *   `{"events": {"type": "interrupt"}}` is one item of a live field, and
+ *   `{"voice": "eve"}` changes an ordinary field while the task runs.
+ *
+ * `Live` applies that mapping to a socket, with the schemas as the contract.
+ *
+ * Zod is never imported: the app's own zod (v3 or v4) is passed in, and the
+ * schemas are read by duck-typing `_def`, the same way the kernel does.
+ */
+/**
+ * Marks a live field's schema. The value on `_def` is the item schema.
+ * The kernel's zodToJsonSchema reads this and emits `format: "stream"`.
+ */
+export const STREAM_SCHEMA_MARKER = Symbol.for("inferencesh.streamSchema");
+/**
+ * Marks a binary item schema. The value on `_def` is the content type.
+ * The kernel's zodToJsonSchema reads this and emits
+ * `{type: "string", format: "binary", contentMediaType}`.
+ */
+export const BINARY_SCHEMA_MARKER = Symbol.for("inferencesh.binarySchema");
+/**
+ * A field whose values travel over the socket while the task runs.
+ *
+ * Parsing always yields the placeholder `[]`, whatever the caller put in the
+ * request body (items come over the socket), and a missing key parses too.
+ * Read and write the items with `Live`.
+ *
+ * @param z the app's zod instance
+ * @param item the schema of one item (`pcm16(z)`, `media(z, "image/jpeg")`, or any zod schema)
+ */
+export function createStreamSchema(z, item) {
+    const schema = z.preprocess(() => [], z.array(item));
+    schema._def[STREAM_SCHEMA_MARKER] = item;
+    return schema;
+}
+/**
+ * Binary items of a media type, e.g. `createStreamSchema(z, media(z, "image/jpeg"))`.
+ * Accepts a Buffer or any Uint8Array.
+ */
+export function media(z, contentType) {
+    const schema = z.custom((v) => v instanceof Uint8Array, {
+        message: "expected binary data",
+    });
+    schema._def[BINARY_SCHEMA_MARKER] = contentType;
+    return schema;
+}
+/**
+ * Raw 16-bit little-endian PCM audio. One frame is one chunk of samples;
+ * 20 ms (`rate / 50` samples) is the usual size for live audio.
+ */
+export function pcm16(z, rate = 16000, channels = 1) {
+    return media(z, `audio/pcm;format=s16le;rate=${rate};channels=${channels}`);
+}
+// --- schema walking (zod v3 and v4 `_def` shapes) ---------------------------
+/** Inner schemas of a wrapper def, in the order worth checking. */
+function innerSchemas(def) {
+    const out = [];
+    // v3 + v4: optional / default / nullable / catch / readonly
+    if (def.innerType)
+        out.push(def.innerType);
+    // v3: effects (preprocess / transform / refine), v4: some wrappers
+    if (def.schema)
+        out.push(def.schema);
+    if (def.inner)
+        out.push(def.inner);
+    // v4: pipe (preprocess, transform) — in, then out
+    if (def.in)
+        out.push(def.in);
+    if (def.out)
+        out.push(def.out);
+    return out;
+}
+/** The marker's value on the schema or any schema it wraps, or undefined. */
+function findMarker(schema, marker, seen = new Set()) {
+    if (!schema || typeof schema !== "object" || seen.has(schema))
+        return undefined;
+    seen.add(schema);
+    const def = schema._def;
+    if (!def || typeof def !== "object")
+        return undefined;
+    if (Object.prototype.hasOwnProperty.call(def, marker))
+        return def[marker];
+    for (const inner of innerSchemas(def)) {
+        const found = findMarker(inner, marker, seen);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** The fields of a zod object schema. v3: `_def.shape()`, v4: `_def.shape`. */
+function shapeOf(objectSchema) {
+    const def = objectSchema?._def;
+    if (!def)
+        throw new TypeError("expected a zod object schema");
+    const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+    if (!shape || typeof shape !== "object")
+        throw new TypeError("expected a zod object schema");
+    return shape;
+}
+function isBinaryItem(item) {
+    return typeof findMarker(item, BINARY_SCHEMA_MARKER) === "string";
+}
+/** The object schema's live fields and their item schemas. */
+export function liveFields(objectSchema) {
+    const found = {};
+    for (const [name, field] of Object.entries(shapeOf(objectSchema))) {
+        const item = findMarker(field, STREAM_SCHEMA_MARKER);
+        if (item !== undefined)
+            found[name] = item;
+    }
+    return found;
+}
+/**
+ * The object schema's binary live field, or null. More than one is an error:
+ * a binary frame carries no field name.
+ */
+export function binaryField(objectSchema) {
+    const names = Object.entries(liveFields(objectSchema))
+        .filter(([, item]) => isBinaryItem(item))
+        .map(([name]) => name);
+    if (names.length > 1) {
+        throw new TypeError(`the schema has ${names.length} binary live fields (${names.join(", ")}); ` +
+            "a schema can have one per direction because a binary frame carries no field name");
+    }
+    return names[0] ?? null;
+}
+// --- frames -----------------------------------------------------------------
+function isBinaryFrame(frame) {
+    return frame instanceof Uint8Array || frame instanceof ArrayBuffer;
+}
+function toBuffer(value) {
+    if (Buffer.isBuffer(value))
+        return value;
+    if (value instanceof Uint8Array)
+        return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    if (value instanceof ArrayBuffer)
+        return Buffer.from(value);
+    throw new TypeError("a binary field takes a Buffer, Uint8Array or ArrayBuffer");
+}
+function firstIssue(result) {
+    const issue = result?.error?.issues?.[0];
+    return (issue && issue.message) || String(result?.error ?? "invalid value");
+}
+/**
+ * A socket read and written through the function's schemas.
+ *
+ * ```js
+ * async talk(inputData, socket) {
+ *   const live = new Live(socket, inputData, TalkInput, TalkOutput);
+ *   for await (const update of live) {
+ *     if (update.field === "audio") {
+ *       await live.send({ audio: process(update.value, inputData.voice) });
+ *     } else if (update.field === "events") {
+ *       ...                      // update.value is an Interrupt or a UserText
+ *     }
+ *     // an ordinary field (voice) is already set on inputData
+ *   }
+ *   return { seconds: ... };
+ * }
+ * ```
+ *
+ * A frame that does not fit the input schema is answered with
+ * `{"error": {"field": ..., "message": ...}}` and skipped; the stream goes on.
+ */
+export class Live {
+    socket;
+    input;
+    inShape;
+    inLive;
+    inBinary;
+    outShape;
+    outBinary;
+    constructor(socket, inputData, inputSchema, outputSchema) {
+        this.socket = socket;
+        this.input = inputData;
+        this.inShape = shapeOf(inputSchema);
+        this.inLive = liveFields(inputSchema);
+        this.inBinary = binaryField(inputSchema);
+        this.outShape = shapeOf(outputSchema);
+        this.outBinary = binaryField(outputSchema);
+    }
+    async *[Symbol.asyncIterator]() {
+        for await (const frame of this.frames()) {
+            for (const update of await this.read(frame))
+                yield update;
+        }
+    }
+    async *frames() {
+        const socket = this.socket;
+        if (typeof socket[Symbol.asyncIterator] === "function") {
+            for await (const frame of socket)
+                yield frame;
+            return;
+        }
+        for (;;) {
+            const frame = await socket.recv();
+            if (frame == null)
+                return;
+            yield frame;
+        }
+    }
+    async read(frame) {
+        if (isBinaryFrame(frame)) {
+            if (this.inBinary === null) {
+                await this.refuse(null, "this function takes no binary frames");
+                return [];
+            }
+            return [{ field: this.inBinary, value: toBuffer(frame) }];
+        }
+        let patch;
+        try {
+            patch = typeof frame === "string" ? JSON.parse(frame) : frame;
+        }
+        catch {
+            patch = undefined;
+        }
+        if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+            await this.refuse(null, "a text frame is a JSON object keyed by field name");
+            return [];
+        }
+        const updates = [];
+        for (const [key, raw] of Object.entries(patch)) {
+            if (Object.prototype.hasOwnProperty.call(this.inLive, key)) {
+                if (key === this.inBinary) {
+                    await this.refuse(key, "send this field's items as binary frames");
+                    continue;
+                }
+                const result = this.inLive[key].safeParse(raw);
+                if (!result.success) {
+                    await this.refuse(key, firstIssue(result));
+                    continue;
+                }
+                updates.push({ field: key, value: result.data });
+            }
+            else if (Object.prototype.hasOwnProperty.call(this.inShape, key)) {
+                const result = this.inShape[key].safeParse(raw);
+                if (!result.success) {
+                    await this.refuse(key, firstIssue(result));
+                    continue;
+                }
+                this.input[key] = result.data;
+                updates.push({ field: key, value: result.data });
+            }
+            else {
+                await this.refuse(key, "no such field");
+            }
+        }
+        return updates;
+    }
+    async refuse(field, message) {
+        await this.socket.send({ error: { field, message } });
+    }
+    /**
+     * Send items of live output fields, or new values of ordinary ones.
+     *
+     * `await live.send({ audio: pcm })` is a binary frame;
+     * `await live.send({ transcript: word })` and
+     * `await live.send({ effect: "echo" })` are JSON frames. Keys in one call
+     * other than the binary field go out together as one JSON frame.
+     */
+    async send(fields) {
+        const patch = {};
+        for (const [key, value] of Object.entries(fields)) {
+            if (!Object.prototype.hasOwnProperty.call(this.outShape, key)) {
+                throw new Error(`the output schema has no field "${key}"`);
+            }
+            if (key === this.outBinary) {
+                await this.socket.send(toBuffer(value));
+                continue;
+            }
+            patch[key] = value;
+        }
+        if (Object.keys(patch).length > 0) {
+            await this.socket.send(patch);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/app",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "App framework for building inference.sh apps — File handling, output metadata, storage utilities",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,8 @@
     "@types/node": "^22.0.0",
     "rimraf": "^6.0.1",
     "typescript": "~6.0.3",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "zod3": "npm:zod@^3.25.76"
   },
   "files": [
     "dist",