@convex-dev/persistent-text-streaming 0.0.1

package/dist/esm/component/schema.d.ts

@@ -0,0 +1,23 @@
+import { Infer } from "convex/values";
+export declare const streamStatusValidator: import("convex/values").VUnion<"pending" | "streaming" | "done" | "error" | "timeout", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"streaming", "required">, import("convex/values").VLiteral<"done", "required">, import("convex/values").VLiteral<"error", "required">, import("convex/values").VLiteral<"timeout", "required">], "required", never>;
+export type StreamStatus = Infer<typeof streamStatusValidator>;
+declare const _default: import("convex/server").SchemaDefinition<{
+    streams: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        status: "pending" | "streaming" | "done" | "error" | "timeout";
+    }, {
+        status: import("convex/values").VUnion<"pending" | "streaming" | "done" | "error" | "timeout", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"streaming", "required">, import("convex/values").VLiteral<"done", "required">, import("convex/values").VLiteral<"error", "required">, import("convex/values").VLiteral<"timeout", "required">], "required", never>;
+    }, "required", "status">, {
+        byStatus: ["status", "_creationTime"];
+    }, {}, {}>;
+    chunks: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        streamId: import("convex/values").GenericId<"streams">;
+        text: string;
+    }, {
+        streamId: import("convex/values").VId<import("convex/values").GenericId<"streams">, "required">;
+        text: import("convex/values").VString<string, "required">;
+    }, "required", "streamId" | "text">, {
+        byStream: ["streamId", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

package/dist/esm/component/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/component/schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAK,MAAM,eAAe,CAAC;AAEzC,eAAO,MAAM,qBAAqB,uYAMjC,CAAC;AACF,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;;;;;;;;;;;;;;;;;;;AAE/D,wBAQG"}

package/dist/esm/component/schema.js

@@ -0,0 +1,13 @@
+import { defineSchema, defineTable } from "convex/server";
+import { 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 default defineSchema({
+    streams: defineTable({
+        status: streamStatusValidator,
+    }).index("byStatus", ["status"]),
+    chunks: defineTable({
+        streamId: v.id("streams"),
+        text: v.string(),
+    }).index("byStream", ["streamId"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/esm/component/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAS,CAAC,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAC1C,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EACtB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EACjB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAClB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CACrB,CAAC;AAGF,eAAe,YAAY,CAAC;IAC1B,OAAO,EAAE,WAAW,CAAC;QACnB,MAAM,EAAE,qBAAqB;KAC9B,CAAC,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,EAAE,WAAW,CAAC;QAClB,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC;QACzB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;KACjB,CAAC,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,UAAU,CAAC,CAAC;CACnC,CAAC,CAAC"}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/react/index.d.ts

@@ -0,0 +1,23 @@
+import { StreamBody, StreamId } from "../client";
+import { FunctionReference } from "convex/server";
+/**
+ * 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 declare function useStream(getPersistentBody: FunctionReference<"query", "public", {
+    streamId: string;
+}, StreamBody>, streamUrl: URL, driven: boolean, streamId?: StreamId): StreamBody;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMlD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACvB,iBAAiB,EAAE,iBAAiB,CAClC,OAAO,EACP,QAAQ,EACR;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EACpB,UAAU,CACX,EACD,SAAS,EAAE,GAAG,EACd,MAAM,EAAE,OAAO,EACf,QAAQ,CAAC,EAAE,QAAQ,cAgEpB"}

package/dist/esm/react/index.js

@@ -0,0 +1,131 @@
+"use client";
+import { useQuery } from "convex/react";
+import { useEffect, useMemo, useRef, useState } from "react";
+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, streamUrl, driven, streamId) {
+    const [streamEnded, setStreamEnded] = useState(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("");
+    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(() => {
+        // console.log(
+        //   "body info p vs. s",
+        //   persistentBody?.text?.length ?? 0,
+        //   streamBody.length
+        //);
+        if (persistentBody) {
+            return persistentBody;
+        }
+        let status;
+        if (streamEnded === null) {
+            status = streamBody.length > 0 ? "streaming" : "pending";
+        }
+        else {
+            status = streamEnded ? "done" : "error";
+        }
+        return {
+            text: streamBody,
+            status: status,
+        };
+    }, [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, streamId, onUpdate) {
+    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;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@convex-dev/persistent-text-streaming",
+  "description": "A Convex component for streaming durable text to the client, from LLMs and other sources.",
+  "repository": "github:get-convex/persistent-text-streaming",
+  "homepage": "https://github.com/get-convex/persistent-text-streaming#readme",
+  "bugs": {
+    "email": "support@convex.dev",
+    "url": "https://github.com/get-convex/persistent-text-streaming/issues"
+  },
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "component"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc --project ./esm.json && echo '{\\n  \"type\": \"module\"\\n}' > dist/esm/package.json",
+    "build:cjs": "tsc --project ./commonjs.json && echo '{\\n  \"type\": \"commonjs\"\\n}' > dist/commonjs/package.json",
+    "dev": "cd example; npm run dev",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build",
+    "prepack": "node node10stubs.mjs",
+    "postpack": "node node10stubs.mjs --cleanup",
+    "test": "vitest run",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text"
+  },
+  "files": [
+    "dist",
+    "src",
+    "react"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "@convex-dev/component-source": "./src/client/index.ts",
+        "types": "./dist/esm/client/index.d.ts",
+        "default": "./dist/esm/client/index.js"
+      },
+      "require": {
+        "@convex-dev/component-source": "./src/client/index.ts",
+        "types": "./dist/commonjs/client/index.d.ts",
+        "default": "./dist/commonjs/client/index.js"
+      }
+    },
+    "./react": {
+      "import": {
+        "@convex-dev/component-source": "./src/react/index.ts",
+        "types": "./dist/esm/react/index.d.ts",
+        "default": "./dist/esm/react/index.js"
+      },
+      "require": {
+        "@convex-dev/component-source": "./src/react/index.ts",
+        "types": "./dist/commonjs/react/index.d.ts",
+        "default": "./dist/commonjs/react/index.js"
+      }
+    },
+    "./convex.config": {
+      "import": {
+        "@convex-dev/component-source": "./src/component/convex.config.ts",
+        "types": "./dist/esm/component/convex.config.d.ts",
+        "default": "./dist/esm/component/convex.config.js"
+      }
+    }
+  },
+  "peerDependencies": {
+    "convex": "~1.16.5 || ~1.17.0 || ~1.18.0 || ~1.19.0",
+    "react": "~18.3.1 || ~19.0.0",
+    "react-dom": "~18.3.1 || ~19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.1",
+    "@types/node": "^18.17.0",
+    "@types/react": "^19.0.10",
+    "convex-test": "^0.0.36",
+    "eslint": "^9.9.1",
+    "globals": "^15.9.0",
+    "prettier": "3.2.5",
+    "typescript": "~5.0.3",
+    "typescript-eslint": "^8.4.0",
+    "vitest": "^2.1.4"
+  },
+  "main": "./dist/commonjs/client/index.js",
+  "types": "./dist/commonjs/client/index.d.ts",
+  "module": "./dist/esm/client/index.js"
+}

package/react/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../dist/commonjs/./react/index.js",
+  "module": "../dist/esm/./react/index.js",
+  "types": "../dist/commonjs/./react/index.d.ts"
+}

package/src/client/index.ts

@@ -0,0 +1,223 @@
+import {
+  Expand,
+  FunctionReference,
+  GenericActionCtx,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+} from "convex/server";
+import { GenericId, v } from "convex/values";
+import { api } from "../component/_generated/api";
+import { StreamStatus } from "../component/schema";
+
+export type StreamId = string & { __isStreamId: true };
+export const StreamIdValidator = v.string();
+export type StreamBody = {
+  text: string;
+  status: StreamStatus;
+};
+
+export type ChunkAppender = (text: string) => Promise<void>;
+export type StreamWriter<A extends GenericActionCtx<GenericDataModel>> = (
+  ctx: A,
+  request: Request,
+  streamId: StreamId,
+  chunkAppender: ChunkAppender
+) => Promise<void>;
+
+// TODO -- make more flexible. # of bytes, etc?
+const hasDelimeter = (text: string) => {
+  return text.includes(".") || text.includes("!") || text.includes("?");
+};
+
+// TODO -- some sort of wrapper with easy ergonomics for working with LLMs?
+export class PersistentTextStreaming {
+  constructor(
+    public component: UseApi<typeof api>,
+    public options?: object
+  ) {}
+
+  /**
+   * Create a new stream. This will return a stream ID that can be used
+   * in an HTTP action to stream data back out to the client while also
+   * permanently persisting the final stream in the database.
+   *
+   * @param ctx - A convex context capable of running mutations.
+   * @returns The ID of the new stream.
+   * @example
+   * ```ts
+   * const streaming = new PersistentTextStreaming(api);
+   * const streamId = await streaming.createStream(ctx);
+   * await streaming.stream(ctx, request, streamId, async (ctx, req, id, append) => {
+   *   await append("Hello ");
+   *   await append("World!");
+   * });
+   * ```
+   */
+
+  async createStream(ctx: RunMutationCtx): Promise<StreamId> {
+    const id = await ctx.runMutation(this.component.lib.createStream);
+    return id as StreamId;
+  }
+
+  /**
+   * Get the body of a stream. This will return the full text of the stream
+   * and the status of the stream.
+   *
+   * @param ctx - A convex context capable of running queries.
+   * @param streamId - The ID of the stream to get the body of.
+   * @returns The body of the stream and the status of the stream.
+   * @example
+   * ```ts
+   * const streaming = new PersistentTextStreaming(api);
+   * const { text, status } = await streaming.getStreamBody(ctx, streamId);
+   * ```
+   */
+  async getStreamBody(
+    ctx: RunQueryCtx,
+    streamId: StreamId
+  ): Promise<StreamBody> {
+    const { text, status } = await ctx.runQuery(
+      this.component.lib.getStreamText,
+      { streamId }
+    );
+    return { text, status: status as StreamStatus };
+  }
+
+  /**
+   * Inside an HTTP action, this will stream data back to the client while
+   * also persisting the final stream in the database.
+   *
+   * @param ctx - A convex context capable of running actions.
+   * @param request - The HTTP request object.
+   * @param streamId - The ID of the stream.
+   * @param streamWriter - A function that generates chunks and writes them
+   * to the stream with the given `StreamWriter`.
+   * @returns A promise that resolves to an HTTP response. You may need to adjust
+   * the headers of this response for CORS, etc.
+   * @example
+   * ```ts
+   * const streaming = new PersistentTextStreaming(api);
+   * const streamId = await streaming.createStream(ctx);
+   * const response = await streaming.stream(ctx, request, streamId, async (ctx, req, id, append) => {
+   *   await append("Hello ");
+   *   await append("World!");
+   * });
+   * ```
+   */
+  async stream<A extends GenericActionCtx<GenericDataModel>>(
+    ctx: A,
+    request: Request,
+    streamId: StreamId,
+    streamWriter: StreamWriter<A>
+  ) {
+    const streamState = await ctx.runQuery(this.component.lib.getStreamStatus, {
+      streamId,
+    });
+    if (streamState !== "pending") {
+      console.log("Stream was already started");
+      return new Response("", {
+        status: 205,
+      });
+    }
+    // Create a TransformStream to handle streaming data
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    const textEncoder = new TextEncoder();
+    let pending = "";
+
+    const doStream = async () => {
+      const chunkAppender: ChunkAppender = async (text) => {
+        // write to this handler's response stream on every update
+        await writer.write(textEncoder.encode(text));
+        pending += text;
+        // write to the database periodically, like at the end of sentences
+        if (hasDelimeter(text)) {
+          await this.addChunk(ctx, streamId, pending, false);
+          pending = "";
+        }
+      };
+      try {
+        await streamWriter(ctx, request, streamId, chunkAppender);
+      } catch (e) {
+        await this.setStreamStatus(ctx, streamId, "error");
+        await writer.close();
+        throw e;
+      }
+
+      // Success? Flush any last updates
+      await this.addChunk(ctx, streamId, pending, true);
+
+      await writer.close();
+    };
+
+    // Kick off the streaming, but don't await it.
+    void doStream();
+
+    // Send the readable back to the browser
+    return new Response(readable);
+  }
+
+  // Internal helper -- add a chunk to the stream.
+  private async addChunk(
+    ctx: RunMutationCtx,
+    streamId: StreamId,
+    text: string,
+    final: boolean
+  ) {
+    await ctx.runMutation(this.component.lib.addChunk, {
+      streamId,
+      text,
+      final,
+    });
+  }
+
+  // Internal helper -- set the status of a stream.
+  private async setStreamStatus(
+    ctx: RunMutationCtx,
+    streamId: StreamId,
+    status: StreamStatus
+  ) {
+    await ctx.runMutation(this.component.lib.setStreamStatus, {
+      streamId,
+      status,
+    });
+  }
+}
+
+/* Type utils follow */
+
+type RunQueryCtx = {
+  runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+};
+type RunMutationCtx = {
+  runMutation: GenericMutationCtx<GenericDataModel>["runMutation"];
+};
+
+export type OpaqueIds<T> = T extends GenericId<infer _T> | string
+  ? string
+  : T extends (infer U)[]
+    ? OpaqueIds<U>[]
+    : T extends ArrayBuffer
+      ? ArrayBuffer
+      : T extends object
+        ? { [K in keyof T]: OpaqueIds<T[K]> }
+        : T;
+
+export type UseApi<API> = Expand<{
+  [mod in keyof API]: API[mod] extends FunctionReference<
+    infer FType,
+    "public",
+    infer FArgs,
+    infer FReturnType,
+    infer FComponentPath
+  >
+    ? FunctionReference<
+        FType,
+        "internal",
+        OpaqueIds<FArgs>,
+        OpaqueIds<FReturnType>,
+        FComponentPath
+      >
+    : UseApi<API[mod]>;
+}>;

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

@@ -0,0 +1,80 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as crons from "../crons.js";
+import type * as lib from "../lib.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+declare const fullApi: ApiFromModules<{
+  crons: typeof crons;
+  lib: typeof lib;
+}>;
+export type Mounts = {
+  lib: {
+    addChunk: FunctionReference<
+      "mutation",
+      "public",
+      { final: boolean; streamId: string; text: string },
+      any
+    >;
+    createStream: FunctionReference<"mutation", "public", {}, any>;
+    getStreamStatus: FunctionReference<
+      "query",
+      "public",
+      { streamId: string },
+      "pending" | "streaming" | "done" | "error" | "timeout"
+    >;
+    getStreamText: FunctionReference<
+      "query",
+      "public",
+      { streamId: string },
+      {
+        status: "pending" | "streaming" | "done" | "error" | "timeout";
+        text: string;
+      }
+    >;
+    setStreamStatus: FunctionReference<
+      "mutation",
+      "public",
+      {
+        status: "pending" | "streaming" | "done" | "error" | "timeout";
+        streamId: string;
+      },
+      any
+    >;
+  };
+};
+// For now fullApiWithMounts is only fullApi which provides
+// jump-to-definition in component client code.
+// Use Mounts for the same type without the inference.
+declare const fullApiWithMounts: typeof fullApi;
+
+export declare const api: FilterApi<
+  typeof fullApiWithMounts,
+  FunctionReference<any, "public">
+>;
+export declare const internal: FilterApi<
+  typeof fullApiWithMounts,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};

package/src/component/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();