@convex-dev/persistent-text-streaming 0.0.1

package/src/component/_generated/dataModel.d.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.d.ts

@@ -0,0 +1,149 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import {
+  ActionBuilder,
+  AnyComponents,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+  FunctionReference,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const query: QueryBuilder<DataModel, "public">;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalQuery: QueryBuilder<DataModel, "internal">;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const mutation: MutationBuilder<DataModel, "public">;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalMutation: MutationBuilder<DataModel, "internal">;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export declare const action: ActionBuilder<DataModel, "public">;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalAction: ActionBuilder<DataModel, "internal">;
+
+/**
+ * Define an HTTP action.
+ *
+ * This function will be used to respond to HTTP requests received by a Convex
+ * deployment if the requests matches the path and method where this action
+ * is routed. Be sure to route your action in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export declare const httpAction: HttpActionBuilder;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * This differs from the {@link MutationCtx} because all of the services are
+ * read-only.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/_generated/server.js

@@ -0,0 +1,90 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+  componentsGeneric,
+} from "convex/server";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery = internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation = internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction = internalActionGeneric;
+
+/**
+ * Define a Convex HTTP action.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument, and a `Request` object
+ * as its second.
+ * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`.
+ */
+export const httpAction = httpActionGeneric;

package/src/component/convex.config.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("persistentTextStreaming");

package/src/component/crons.ts

@@ -0,0 +1,13 @@
+import { cronJobs } from "convex/server";
+import { internal } from "./_generated/api";
+
+const crons = cronJobs();
+
+// Run every minute
+crons.interval(
+  "cleanup expired streams",
+  { minutes: 1 },
+  internal.lib.cleanupExpiredStreams
+);
+
+export default crons;

package/src/component/lib.test.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+import { describe, it } from "vitest";
+
+describe("persistent-text-streaming", () => {
+  it("should be implemented", () => {
+    // TODO: Add tests for persistent text streaming functionality
+  });
+});

package/src/component/lib.ts

@@ -0,0 +1,149 @@
+import { v } from "convex/values";
+import { internalMutation, mutation, query } from "./_generated/server";
+import { streamStatusValidator } from "./schema";
+
+// Create a new stream with zero chunks.
+export const createStream = mutation({
+  args: {},
+  handler: async (ctx) => {
+    const streamId = await ctx.db.insert("streams", {
+      status: "pending",
+    });
+    return streamId;
+  },
+});
+
+// Add a chunk to a stream.
+// If final is true, set the stream to done.
+// Can only be done on streams which are pending or streaming.
+export const addChunk = mutation({
+  args: {
+    streamId: v.id("streams"),
+    text: v.string(),
+    final: v.boolean(),
+  },
+  handler: async (ctx, args) => {
+    const stream = await ctx.db.get(args.streamId);
+    if (!stream) {
+      throw new Error("Stream not found");
+    }
+    if (stream.status === "pending") {
+      await ctx.db.patch(args.streamId, {
+        status: "streaming",
+      });
+    } else if (stream.status !== "streaming") {
+      throw new Error("Stream is not streaming; did it timeout?");
+    }
+    await ctx.db.insert("chunks", {
+      streamId: args.streamId,
+      text: args.text,
+    });
+    if (args.final) {
+      await ctx.db.patch(args.streamId, {
+        status: "done",
+      });
+    }
+  },
+});
+
+// Set the status of a stream.
+// Can only be done on streams which are pending or streaming.
+export const setStreamStatus = mutation({
+  args: {
+    streamId: v.id("streams"),
+    status: v.union(
+      v.literal("pending"),
+      v.literal("streaming"),
+      v.literal("done"),
+      v.literal("error"),
+      v.literal("timeout")
+    ),
+  },
+  handler: async (ctx, args) => {
+    const stream = await ctx.db.get(args.streamId);
+    if (!stream) {
+      throw new Error("Stream not found");
+    }
+    if (stream.status !== "pending" && stream.status !== "streaming") {
+      console.log(
+        "Stream is already finalized; ignoring status change",
+        stream
+      );
+      return;
+    }
+    await ctx.db.patch(args.streamId, {
+      status: args.status,
+    });
+  },
+});
+
+// Get the status of a stream.
+export const getStreamStatus = query({
+  args: {
+    streamId: v.id("streams"),
+  },
+  returns: streamStatusValidator,
+  handler: async (ctx, args) => {
+    const stream = await ctx.db.get(args.streamId);
+    return stream?.status ?? "error";
+  },
+});
+
+// Get the full text of a stream.
+// Involves concatenating all the chunks.
+export const getStreamText = query({
+  args: {
+    streamId: v.id("streams"),
+  },
+  returns: v.object({
+    text: v.string(),
+    status: streamStatusValidator,
+  }),
+  handler: async (ctx, args) => {
+    const stream = await ctx.db.get(args.streamId);
+    if (!stream) {
+      throw new Error("Stream not found");
+    }
+    let text = "";
+    if (stream.status !== "pending") {
+      const chunks = await ctx.db
+        .query("chunks")
+        .withIndex("byStream", (q) => q.eq("streamId", args.streamId))
+        .collect();
+      text = chunks.map((chunk) => chunk.text).join("");
+    }
+    return {
+      text,
+      status: stream.status,
+    };
+  },
+});
+
+const EXPIRATION_TIME = 20 * 60 * 1000; // 20 minutes in milliseconds
+const BATCH_SIZE = 100;
+
+// If the last chunk of a stream was added more than 20 minutes ago,
+// set the stream to timeout. The action feeding it has to be dead.
+export const cleanupExpiredStreams = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    const now = Date.now();
+    const pendingStreams = await ctx.db
+      .query("streams")
+      .withIndex("byStatus", (q) => q.eq("status", "pending"))
+      .take(BATCH_SIZE);
+    const streamingStreams = await ctx.db
+      .query("streams")
+      .withIndex("byStatus", (q) => q.eq("status", "streaming"))
+      .take(BATCH_SIZE);
+
+    for (const stream of [...pendingStreams, ...streamingStreams]) {
+      if (now - stream._creationTime > EXPIRATION_TIME) {
+        console.log("Cleaning up expired stream", stream._id);
+        await ctx.db.patch(stream._id, {
+          status: "timeout",
+        });
+      }
+    }
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,21 @@
+import { defineSchema, defineTable } from "convex/server";
+import { Infer, v } from "convex/values";
+
+export const streamStatusValidator = v.union(
+  v.literal("pending"),
+  v.literal("streaming"),
+  v.literal("done"),
+  v.literal("error"),
+  v.literal("timeout")
+);
+export type StreamStatus = Infer<typeof streamStatusValidator>;
+
+export default defineSchema({
+  streams: defineTable({
+    status: streamStatusValidator,
+  }).index("byStatus", ["status"]),
+  chunks: defineTable({
+    streamId: v.id("streams"),
+    text: v.string(),
+  }).index("byStream", ["streamId"]),
+});

package/src/react/index.ts

@@ -0,0 +1,158 @@
+"use client";
+
+/// React helpers for persistent text streaming.
+import { StreamStatus } from "../component/schema";
+import { useQuery } from "convex/react";
+import { StreamBody, StreamId } from "../client";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { FunctionReference } from "convex/server";
+
+if (typeof window === "undefined") {
+  throw new Error("this is frontend code, but it's running somewhere else!");
+}
+
+/**
+ * React hook for persistent text streaming.
+ *
+ * @param getPersistentBody - A query function reference that returns the body
+ * of a stream using the component's `getStreamBody` method.
+ * @param streamUrl - The URL of the http action that will kick off the stream
+ * generation and stream the result back to the client using the component's
+ * `stream` method.
+ * @param driven - Whether this particular session is driving the stream. Set this
+ * to true if this is the client session that first created the stream using the
+ * component's `createStream` method. If you're simply reloading an existing
+ * stream, set this to false.
+ * @param streamId - The ID of the stream. If this is not provided, the return
+ * value will be an empty string for the stream body and the status will be
+ * `pending`.
+ * @returns The body and status of the stream.
+ */
+export function useStream(
+  getPersistentBody: FunctionReference<
+    "query",
+    "public",
+    { streamId: string },
+    StreamBody
+  >,
+  streamUrl: URL,
+  driven: boolean,
+  streamId?: StreamId
+) {
+  const [streamEnded, setStreamEnded] = useState(null as boolean | null);
+
+  // Used to prevent strict mode from causing multiple streams to be started.
+  const streamStarted = useRef(false);
+
+  const usePersistence = useMemo(() => {
+    // Something is wrong with the stream, so we need to use the database value.
+    if (streamEnded === false) {
+      return true;
+    }
+    // If we're not driving the stream, we must use the database value.
+    if (!driven) {
+      return true;
+    }
+    // Otherwise, we'll try to drive the stream and use the HTTP response.
+    return false;
+  }, [driven, streamId, streamEnded]);
+//  console.log("usePersistence", usePersistence);
+  const persistentBody = useQuery(
+    getPersistentBody,
+    usePersistence && streamId ? { streamId: streamId! } : "skip"
+  );
+  const [streamBody, setStreamBody] = useState<string>("");
+
+  useEffect(() => {
+    if (driven && streamId && !streamStarted.current) {
+      // Kick off HTTP action.
+      void (async () => {
+        const success = await startStreaming(streamUrl, streamId, (text) => {
+          setStreamBody((prev) => prev + text);
+        });
+        setStreamEnded(success);
+      })();
+      // If we get remounted, we don't want to start a new stream.
+      return () => {
+        streamStarted.current = true;
+      };
+    }
+  }, [driven, streamId, setStreamEnded, streamStarted]);
+
+  const body = useMemo<StreamBody>(() => {
+    // console.log(
+    //   "body info p vs. s",
+    //   persistentBody?.text?.length ?? 0,
+    //   streamBody.length
+    //);
+    if (persistentBody) {
+      return persistentBody;
+    }
+    let status: StreamStatus;
+    if (streamEnded === null) {
+      status = streamBody.length > 0 ? "streaming" : "pending";
+    } else {
+      status = streamEnded ? "done" : "error";
+    }
+    return {
+      text: streamBody,
+      status: status as StreamStatus,
+    };
+  }, [persistentBody, streamBody, streamEnded]);
+
+  return body;
+}
+
+/**
+ * Internal helper for starting a stream.
+ *
+ * @param url - The URL of the http action that will kick off the stream
+ * generation and stream the result back to the client using the component's
+ * `stream` method.
+ * @param streamId - The ID of the stream.
+ * @param onUpdate - A function that updates the stream body.
+ * @returns A promise that resolves to a boolean indicating whether the stream
+ * was started successfully. It can fail if the http action is not found, or
+ * CORS fails, or an exception is raised, or the stream is already running
+ * or finished, etc.
+ */
+async function startStreaming(
+  url: URL,
+  streamId: StreamId,
+  onUpdate: (text: string) => void
+) {
+  const response = await fetch(url, {
+    method: "POST",
+    body: JSON.stringify({
+      streamId: streamId,
+    }),
+    headers: { "Content-Type": "application/json" },
+  });
+  // Adapted from https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams
+  if (response.status === 205) {
+    console.error("Stream already finished", response);
+    return false;
+  }
+  if (!response.ok) {
+    console.error("Failed to reach streaming endpoint", response);
+    return false;
+  }
+  if (!response.body) {
+    console.error("No body in response", response);
+    return false;
+  }
+  const reader = response.body.getReader();
+  while (true) {
+    try {
+      const { done, value } = await reader.read();
+      if (done) {
+        onUpdate(new TextDecoder().decode(value));
+        return true;
+      }
+      onUpdate(new TextDecoder().decode(value));
+    } catch (e) {
+      console.error("Error reading stream", e);
+      return false;
+    }
+  }
+}