@rsc-kit/core 0.16.3 → 0.18.0

package/dist/events.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A route that streams: server-sent events from an async generator.
+ *
+ *     // app/api/orders/[id]/events/route.ts
+ *     export const GET = events(async function* ({ params, signal }) {
+ *       for await (const status of orderStatus((await params).id, { signal })) {
+ *         yield { status }
+ *       }
+ *     })
+ *
+ * An ordinary route.ts, so it lives beside its pages, runs the middleware.ts
+ * above it and takes the same params. What this adds is the framing - one
+ * `data:` line per yield, JSON - a keepalive comment every fifteen seconds
+ * so a proxy does not drop an idle stream, the headers a stream needs, and
+ * an end to the generator when the browser goes away, which is what `signal`
+ * is for. `useEvents` on the client reads it.
+ *
+ * Not a query. A query answers once and is cacheable; a stream answers for
+ * as long as the tab is open and is not. A server component cannot await a
+ * stream, so it has no place in the payload either.
+ */
+export interface EventsInput<P = Record<string, string>> {
+    params: Promise<P>;
+    searchParams: Promise<URLSearchParams>;
+    /** Aborted when the browser disconnects. Pass it on, or check `aborted`. */
+    signal: AbortSignal;
+    request: Request;
+}
+/** A message with a name or an id, for a client that listens by name or resumes. Made by `named()`. */
+export interface NamedEvent {
+    readonly [NAMED]: true;
+    event?: string;
+    id?: string;
+    data: unknown;
+}
+declare const NAMED: unique symbol;
+/**
+ * A message with a name or an id: `yield named('paid', order)`, or
+ * `named('paid', order, { id: order.id })` for one a client can resume from.
+ * Built by a function rather than by shape, so a message that happens to
+ * have a `data` key is still data, and the generator's own type stays the
+ * type of what it yields.
+ */
+export declare function named<D>(event: string, data: D, options?: {
+    id?: string;
+}): NamedEvent;
+/** How often a comment goes out on an idle stream, so a proxy keeps it open. */
+export declare const KEEPALIVE_MS = 15000;
+/** One message, framed. */
+export declare function frame(value: unknown): string;
+export declare function events<P = Record<string, string>, T = unknown>(produce: (input: EventsInput<P>) => AsyncIterable<T | NamedEvent>, options?: {
+    keepaliveMs?: number;
+}): (request: Request, input: {
+    params: Promise<P>;
+    searchParams: Promise<URLSearchParams>;
+}) => Response;
+export {};

package/dist/events.js

@@ -0,0 +1,113 @@
+/**
+ * A route that streams: server-sent events from an async generator.
+ *
+ *     // app/api/orders/[id]/events/route.ts
+ *     export const GET = events(async function* ({ params, signal }) {
+ *       for await (const status of orderStatus((await params).id, { signal })) {
+ *         yield { status }
+ *       }
+ *     })
+ *
+ * An ordinary route.ts, so it lives beside its pages, runs the middleware.ts
+ * above it and takes the same params. What this adds is the framing - one
+ * `data:` line per yield, JSON - a keepalive comment every fifteen seconds
+ * so a proxy does not drop an idle stream, the headers a stream needs, and
+ * an end to the generator when the browser goes away, which is what `signal`
+ * is for. `useEvents` on the client reads it.
+ *
+ * Not a query. A query answers once and is cacheable; a stream answers for
+ * as long as the tab is open and is not. A server component cannot await a
+ * stream, so it has no place in the payload either.
+ */
+const NAMED = Symbol.for("@rsc-kit/core.named-event");
+/**
+ * A message with a name or an id: `yield named('paid', order)`, or
+ * `named('paid', order, { id: order.id })` for one a client can resume from.
+ * Built by a function rather than by shape, so a message that happens to
+ * have a `data` key is still data, and the generator's own type stays the
+ * type of what it yields.
+ */
+export function named(event, data, options = {}) {
+    return { [NAMED]: true, event, id: options.id, data };
+}
+/** How often a comment goes out on an idle stream, so a proxy keeps it open. */
+export const KEEPALIVE_MS = 15_000;
+function isNamed(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[NAMED] === true);
+}
+/** One message, framed. */
+export function frame(value) {
+    const named = isNamed(value) ? value : null;
+    const lines = [];
+    if (named?.event)
+        lines.push(`event: ${named.event}`);
+    if (named?.id)
+        lines.push(`id: ${named.id}`);
+    lines.push(`data: ${JSON.stringify(named ? named.data : value)}`);
+    return lines.join("\n") + "\n\n";
+}
+export function events(produce, options = {}) {
+    const keepaliveMs = options.keepaliveMs ?? KEEPALIVE_MS;
+    return (request, input) => {
+        const controller = new AbortController();
+        const encoder = new TextEncoder();
+        request.signal.addEventListener("abort", () => controller.abort(), {
+            once: true,
+        });
+        const stream = new ReadableStream({
+            async start(sink) {
+                // The retry hint first, so a browser that loses the connection waits
+                // a moment rather than hammering.
+                sink.enqueue(encoder.encode("retry: 1000\n\n"));
+                const keepalive = setInterval(() => {
+                    try {
+                        sink.enqueue(encoder.encode(": keepalive\n\n"));
+                    }
+                    catch {
+                        // Closed between the check and the write; the loop below ends it.
+                    }
+                }, keepaliveMs);
+                try {
+                    for await (const value of produce({
+                        ...input,
+                        signal: controller.signal,
+                        request,
+                    })) {
+                        if (controller.signal.aborted)
+                            break;
+                        sink.enqueue(encoder.encode(frame(value)));
+                    }
+                }
+                catch (error) {
+                    if (!controller.signal.aborted)
+                        sink.error(error);
+                }
+                finally {
+                    clearInterval(keepalive);
+                    if (!controller.signal.aborted) {
+                        try {
+                            sink.close();
+                        }
+                        catch {
+                            // Already closed by the consumer.
+                        }
+                    }
+                }
+            },
+            cancel() {
+                controller.abort();
+            },
+        });
+        return new Response(stream, {
+            headers: {
+                "Content-Type": "text/event-stream; charset=utf-8",
+                "Cache-Control": "no-store",
+                // Nginx buffers by default, which turns a stream into one late burst.
+                "X-Accel-Buffering": "no",
+            },
+        });
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A route that streams: server-sent events from an async generator.\n *\n *     // app/api/orders/[id]/events/route.ts\n *     export const GET = events(async function* ({ params, signal }) {\n *       for await (const status of orderStatus((await params).id, { signal })) {\n *         yield { status }\n *       }\n *     })\n *\n * An ordinary route.ts, so it lives beside its pages, runs the middleware.ts\n * above it and takes the same params. What this adds is the framing - one\n * `data:` line per yield, JSON - a keepalive comment every fifteen seconds\n * so a proxy does not drop an idle stream, the headers a stream needs, and\n * an end to the generator when the browser goes away, which is what `signal`\n * is for. `useEvents` on the client reads it.\n *\n * Not a query. A query answers once and is cacheable; a stream answers for\n * as long as the tab is open and is not. A server component cannot await a\n * stream, so it has no place in the payload either.\n */\n\nexport interface EventsInput<P = Record<string, string>> {\n  params: Promise<P>;\n  searchParams: Promise<URLSearchParams>;\n  /** Aborted when the browser disconnects. Pass it on, or check `aborted`. */\n  signal: AbortSignal;\n  request: Request;\n}\n\n/** A message with a name or an id, for a client that listens by name or resumes. Made by `named()`. */\nexport interface NamedEvent {\n  readonly [NAMED]: true;\n  event?: string;\n  id?: string;\n  data: unknown;\n}\n\nconst NAMED = Symbol.for(\"@rsc-kit/core.named-event\");\n\n/**\n * A message with a name or an id: `yield named('paid', order)`, or\n * `named('paid', order, { id: order.id })` for one a client can resume from.\n * Built by a function rather than by shape, so a message that happens to\n * have a `data` key is still data, and the generator's own type stays the\n * type of what it yields.\n */\nexport function named<D>(\n  event: string,\n  data: D,\n  options: { id?: string } = {},\n): NamedEvent {\n  return { [NAMED]: true, event, id: options.id, data };\n}\n\n/** How often a comment goes out on an idle stream, so a proxy keeps it open. */\nexport const KEEPALIVE_MS = 15_000;\n\nfunction isNamed(value: unknown): value is NamedEvent {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    (value as { [NAMED]?: true })[NAMED] === true\n  );\n}\n\n/** One message, framed. */\nexport function frame(value: unknown): string {\n  const named = isNamed(value) ? value : null;\n  const lines: string[] = [];\n\n  if (named?.event) lines.push(`event: ${named.event}`);\n  if (named?.id) lines.push(`id: ${named.id}`);\n  lines.push(`data: ${JSON.stringify(named ? named.data : value)}`);\n\n  return lines.join(\"\\n\") + \"\\n\\n\";\n}\n\nexport function events<P = Record<string, string>, T = unknown>(\n  produce: (input: EventsInput<P>) => AsyncIterable<T | NamedEvent>,\n  options: { keepaliveMs?: number } = {},\n): (\n  request: Request,\n  input: { params: Promise<P>; searchParams: Promise<URLSearchParams> },\n) => Response {\n  const keepaliveMs = options.keepaliveMs ?? KEEPALIVE_MS;\n\n  return (request, input) => {\n    const controller = new AbortController();\n    const encoder = new TextEncoder();\n\n    request.signal.addEventListener(\"abort\", () => controller.abort(), {\n      once: true,\n    });\n\n    const stream = new ReadableStream<Uint8Array>({\n      async start(sink) {\n        // The retry hint first, so a browser that loses the connection waits\n        // a moment rather than hammering.\n        sink.enqueue(encoder.encode(\"retry: 1000\\n\\n\"));\n\n        const keepalive = setInterval(() => {\n          try {\n            sink.enqueue(encoder.encode(\": keepalive\\n\\n\"));\n          } catch {\n            // Closed between the check and the write; the loop below ends it.\n          }\n        }, keepaliveMs);\n\n        try {\n          for await (const value of produce({\n            ...input,\n            signal: controller.signal,\n            request,\n          })) {\n            if (controller.signal.aborted) break;\n\n            sink.enqueue(encoder.encode(frame(value)));\n          }\n        } catch (error) {\n          if (!controller.signal.aborted) sink.error(error);\n        } finally {\n          clearInterval(keepalive);\n\n          if (!controller.signal.aborted) {\n            try {\n              sink.close();\n            } catch {\n              // Already closed by the consumer.\n            }\n          }\n        }\n      },\n      cancel() {\n        controller.abort();\n      },\n    });\n\n    return new Response(stream, {\n      headers: {\n        \"Content-Type\": \"text/event-stream; charset=utf-8\",\n        \"Cache-Control\": \"no-store\",\n        // Nginx buffers by default, which turns a stream into one late burst.\n        \"X-Accel-Buffering\": \"no\",\n      },\n    });\n  };\n}\n"]}

package/dist/host.d.ts

@@ -1,9 +1,19 @@
-export { revalidate } from './revalidate.js';
-export { redirect } from './redirect.js';
-export { matchIntercept, matchRoute, sharedDepth } from './routing.js';
-export type { MatchedRoute } from './routing.js';
-import type { MatchedRoute } from './routing.js';
-import type { RouteManifest } from './manifest.js';
+/**
+ * @internal For a host adapter that embeds the engine. An app imports this
+ * from `@rsc-kit/core/revalidate`.
+ */
+export { revalidate } from "./revalidate.js";
+/**
+ * @internal For a host adapter that embeds the engine. An app imports this
+ * from `@rsc-kit/core/redirect` - the one the guides teach, and the one an
+ * editor should offer first.
+ */
+export { redirect } from "./redirect.js";
+/** @internal For a host adapter. An app never matches its own routes. */
+export { matchIntercept, matchRoute, sharedDepth } from "./routing.js";
+export type { MatchedRoute } from "./routing.js";
+import type { MatchedRoute } from "./routing.js";
+import type { RouteManifest } from "./manifest.js";
 /** The built server bundle. Only the parts a host calls. */
 export interface RscEngine {
     /** The route table this bundle was built from. */