@tanstack/router-core
Version:
Modern and scalable routing for React applications
1 lines • 18.5 kB
Source Map (JSON)
{"version":3,"file":"RawStream.cjs","names":[],"sources":["../../../../src/ssr/serializer/RawStream.ts"],"sourcesContent":["import { createPlugin, createStream } from 'seroval'\nimport type { Plugin } from 'seroval'\n\n/**\n * Hint for RawStream encoding strategy during SSR serialization.\n * - 'binary': Always use base64 encoding (best for binary data like files, images)\n * - 'text': Try UTF-8 first, fallback to base64 (best for text-heavy data like RSC payloads)\n */\nexport type RawStreamHint = 'binary' | 'text'\n\n/**\n * Options for RawStream configuration.\n */\nexport interface RawStreamOptions {\n /**\n * Encoding hint for SSR serialization.\n * - 'binary' (default): Always use base64 encoding\n * - 'text': Try UTF-8 first, fallback to base64 for invalid UTF-8 chunks\n */\n hint?: RawStreamHint\n}\n\n/**\n * Marker class for ReadableStream<Uint8Array> that should be serialized\n * with base64 encoding (SSR) or binary framing (server functions).\n *\n * Wrap your binary streams with this to get efficient serialization:\n * ```ts\n * // For binary data (files, images, etc.)\n * return { data: new RawStream(file.stream()) }\n *\n * // For text-heavy data (RSC payloads, etc.)\n * return { data: new RawStream(rscStream, { hint: 'text' }) }\n * ```\n */\nexport class RawStream {\n public readonly hint: RawStreamHint\n\n constructor(\n public readonly stream: ReadableStream<Uint8Array>,\n options?: RawStreamOptions,\n ) {\n this.hint = options?.hint ?? 'binary'\n }\n}\n\n/**\n * Callback type for RPC plugin to register raw streams with multiplexer\n */\nexport type OnRawStreamCallback = (\n streamId: number,\n stream: ReadableStream<Uint8Array>,\n) => void\n\n// Base64 helpers used in both Node and browser.\n// In Node-like runtimes, prefer Buffer for speed and compatibility.\nconst BufferCtor: any = (globalThis as any).Buffer\nconst hasNodeBuffer = !!BufferCtor && typeof BufferCtor.from === 'function'\n\nfunction uint8ArrayToBase64(bytes: Uint8Array): string {\n if (bytes.length === 0) return ''\n\n if (hasNodeBuffer) {\n return BufferCtor.from(bytes).toString('base64')\n }\n\n // Browser fallback: chunked String.fromCharCode + btoa\n const CHUNK_SIZE = 0x8000 // 32KB chunks to avoid stack overflow\n const chunks: Array<string> = []\n for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {\n const chunk = bytes.subarray(i, i + CHUNK_SIZE)\n chunks.push(String.fromCharCode.apply(null, chunk as any))\n }\n return btoa(chunks.join(''))\n}\n\nfunction base64ToUint8Array(base64: string): Uint8Array {\n if (base64.length === 0) return new Uint8Array(0)\n\n if (hasNodeBuffer) {\n const buf = BufferCtor.from(base64, 'base64')\n return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)\n }\n\n const binary = atob(base64)\n const bytes = new Uint8Array(binary.length)\n for (let i = 0; i < binary.length; i++) {\n bytes[i] = binary.charCodeAt(i)\n }\n return bytes\n}\n\n// Factory sentinels - use null-proto objects to avoid prototype surprises\nconst RAW_STREAM_FACTORY_BINARY: Record<string, never> = Object.create(null)\nconst RAW_STREAM_FACTORY_TEXT: Record<string, never> = Object.create(null)\n\n// Factory constructor for binary mode - converts seroval stream to ReadableStream<Uint8Array>\n// All chunks are base64 encoded strings\nconst RAW_STREAM_FACTORY_CONSTRUCTOR_BINARY = (\n stream: ReturnType<typeof createStream>,\n) =>\n new ReadableStream<Uint8Array>({\n start(controller) {\n stream.on({\n next(base64: string) {\n try {\n controller.enqueue(base64ToUint8Array(base64))\n } catch {\n // Stream may be closed\n }\n },\n throw(error: unknown) {\n controller.error(error)\n },\n return() {\n try {\n controller.close()\n } catch {\n // Stream may already be closed\n }\n },\n })\n },\n })\n\n// Factory constructor for text mode - converts seroval stream to ReadableStream<Uint8Array>\n// Chunks are either strings (UTF-8) or { $b64: string } (base64 fallback)\n// Use module-level TextEncoder to avoid per-factory allocation\nconst textEncoderForFactory = new TextEncoder()\nconst RAW_STREAM_FACTORY_CONSTRUCTOR_TEXT = (\n stream: ReturnType<typeof createStream>,\n) => {\n return new ReadableStream<Uint8Array>({\n start(controller) {\n stream.on({\n next(value: string | { $b64: string }) {\n try {\n if (typeof value === 'string') {\n controller.enqueue(textEncoderForFactory.encode(value))\n } else {\n controller.enqueue(base64ToUint8Array(value.$b64))\n }\n } catch {\n // Stream may be closed\n }\n },\n throw(error: unknown) {\n controller.error(error)\n },\n return() {\n try {\n controller.close()\n } catch {\n // Stream may already be closed\n }\n },\n })\n },\n })\n}\n\n// Minified factory function for binary mode - all chunks are base64 strings\n// This must be self-contained since it's injected into the HTML\nconst FACTORY_BINARY = `(s=>new ReadableStream({start(c){s.on({next(b){try{const d=atob(b),a=new Uint8Array(d.length);for(let i=0;i<d.length;i++)a[i]=d.charCodeAt(i);c.enqueue(a)}catch(_){}},throw(e){c.error(e)},return(){try{c.close()}catch(_){}}})}}))`\n\n// Minified factory function for text mode - chunks are string or {$b64: string}\n// Uses cached TextEncoder for performance\nconst FACTORY_TEXT = `(s=>{const e=new TextEncoder();return new ReadableStream({start(c){s.on({next(v){try{if(typeof v==='string'){c.enqueue(e.encode(v))}else{const d=atob(v.$b64),a=new Uint8Array(d.length);for(let i=0;i<d.length;i++)a[i]=d.charCodeAt(i);c.enqueue(a)}}catch(_){}},throw(x){c.error(x)},return(){try{c.close()}catch(_){}}})}})})`\n\n// Convert ReadableStream<Uint8Array> to seroval stream with base64-encoded chunks (binary mode)\nfunction toBinaryStream(readable: ReadableStream<Uint8Array>) {\n const stream = createStream()\n const reader = readable.getReader()\n\n // Use iterative loop instead of recursive async to avoid stack accumulation\n ;(async () => {\n try {\n while (true) {\n const { done, value } = await reader.read()\n if (done) {\n stream.return(undefined)\n break\n }\n stream.next(uint8ArrayToBase64(value))\n }\n } catch (error) {\n stream.throw(error)\n } finally {\n reader.releaseLock()\n }\n })()\n\n return stream\n}\n\n// Convert ReadableStream<Uint8Array> to seroval stream with UTF-8 first, base64 fallback (text mode)\nfunction toTextStream(readable: ReadableStream<Uint8Array>) {\n const stream = createStream()\n const reader = readable.getReader()\n const decoder = new TextDecoder('utf-8', { fatal: true })\n\n // Use iterative loop instead of recursive async to avoid stack accumulation\n ;(async () => {\n try {\n while (true) {\n const { done, value } = await reader.read()\n if (done) {\n // Flush any remaining bytes in the decoder\n try {\n const remaining = decoder.decode()\n if (remaining.length > 0) {\n stream.next(remaining)\n }\n } catch {\n // Ignore decode errors on flush\n }\n stream.return(undefined)\n break\n }\n\n try {\n // Try UTF-8 decode first\n const text = decoder.decode(value, { stream: true })\n if (text.length > 0) {\n stream.next(text)\n }\n } catch {\n // UTF-8 decode failed, fallback to base64\n stream.next({ $b64: uint8ArrayToBase64(value) })\n }\n }\n } catch (error) {\n stream.throw(error)\n } finally {\n reader.releaseLock()\n }\n })()\n\n return stream\n}\n\n// Factory plugin for binary mode\nconst RawStreamFactoryBinaryPlugin = createPlugin<\n Record<string, never>,\n undefined\n>({\n tag: 'tss/RawStreamFactory',\n test(value) {\n return value === RAW_STREAM_FACTORY_BINARY\n },\n parse: {\n sync() {\n return undefined\n },\n async() {\n return Promise.resolve(undefined)\n },\n stream() {\n return undefined\n },\n },\n serialize() {\n return FACTORY_BINARY\n },\n deserialize() {\n return RAW_STREAM_FACTORY_BINARY\n },\n})\n\n// Factory plugin for text mode\nconst RawStreamFactoryTextPlugin = createPlugin<\n Record<string, never>,\n undefined\n>({\n tag: 'tss/RawStreamFactoryText',\n test(value) {\n return value === RAW_STREAM_FACTORY_TEXT\n },\n parse: {\n sync() {\n return undefined\n },\n async() {\n return Promise.resolve(undefined)\n },\n stream() {\n return undefined\n },\n },\n serialize() {\n return FACTORY_TEXT\n },\n deserialize() {\n return RAW_STREAM_FACTORY_TEXT\n },\n})\n\n/**\n * SSR Plugin - uses base64 or UTF-8+base64 encoding for chunks, delegates to seroval's stream mechanism.\n * Used during SSR when serializing to JavaScript code for HTML injection.\n *\n * Supports two modes based on RawStream hint:\n * - 'binary': Always base64 encode (default)\n * - 'text': Try UTF-8 first, fallback to base64 for invalid UTF-8\n */\nexport const RawStreamSSRPlugin: Plugin<any, any> = createPlugin({\n tag: 'tss/RawStream',\n extends: [RawStreamFactoryBinaryPlugin, RawStreamFactoryTextPlugin],\n\n test(value: unknown) {\n return value instanceof RawStream\n },\n\n parse: {\n sync(value: RawStream, ctx) {\n // Sync parse not really supported for streams, return empty stream\n const factory =\n value.hint === 'text'\n ? RAW_STREAM_FACTORY_TEXT\n : RAW_STREAM_FACTORY_BINARY\n return {\n hint: value.hint,\n factory: ctx.parse(factory),\n stream: ctx.parse(createStream()),\n }\n },\n async async(value: RawStream, ctx) {\n const factory =\n value.hint === 'text'\n ? RAW_STREAM_FACTORY_TEXT\n : RAW_STREAM_FACTORY_BINARY\n const encodedStream =\n value.hint === 'text'\n ? toTextStream(value.stream)\n : toBinaryStream(value.stream)\n return {\n hint: value.hint,\n factory: await ctx.parse(factory),\n stream: await ctx.parse(encodedStream),\n }\n },\n stream(value: RawStream, ctx) {\n const factory =\n value.hint === 'text'\n ? RAW_STREAM_FACTORY_TEXT\n : RAW_STREAM_FACTORY_BINARY\n const encodedStream =\n value.hint === 'text'\n ? toTextStream(value.stream)\n : toBinaryStream(value.stream)\n return {\n hint: value.hint,\n factory: ctx.parse(factory),\n stream: ctx.parse(encodedStream),\n }\n },\n },\n\n serialize(node: { hint: RawStreamHint; factory: any; stream: any }, ctx) {\n return (\n '(' +\n ctx.serialize(node.factory) +\n ')(' +\n ctx.serialize(node.stream) +\n ')'\n )\n },\n\n deserialize(\n node: { hint: RawStreamHint; factory: any; stream: any },\n ctx,\n ): any {\n const stream: ReturnType<typeof createStream> = ctx.deserialize(node.stream)\n return node.hint === 'text'\n ? RAW_STREAM_FACTORY_CONSTRUCTOR_TEXT(stream)\n : RAW_STREAM_FACTORY_CONSTRUCTOR_BINARY(stream)\n },\n}) as Plugin<any, any>\n\n/**\n * Node type for RPC plugin serialization\n */\ninterface RawStreamRPCNode {\n streamId: number\n}\n\n/**\n * Creates an RPC plugin instance that registers raw streams with a multiplexer.\n * Used for server function responses where we want binary framing.\n * Note: RPC always uses binary framing regardless of hint.\n *\n * @param onRawStream Callback invoked when a RawStream is encountered during serialization\n */\nexport function createRawStreamRPCPlugin(\n onRawStream: OnRawStreamCallback,\n): Plugin<any, any> {\n // Own stream counter - sequential IDs starting at 1, independent of seroval internals\n let nextStreamId = 1\n\n return createPlugin({\n tag: 'tss/RawStream',\n\n test(value: unknown) {\n return value instanceof RawStream\n },\n\n parse: {\n async(value: RawStream) {\n const streamId = nextStreamId++\n onRawStream(streamId, value.stream)\n return Promise.resolve({ streamId })\n },\n stream(value: RawStream) {\n const streamId = nextStreamId++\n onRawStream(streamId, value.stream)\n return { streamId }\n },\n },\n\n serialize(): never {\n // RPC uses toCrossJSONStream which produces JSON nodes, not JS code.\n // This method is only called by crossSerialize* which we don't use.\n throw new Error(\n 'RawStreamRPCPlugin.serialize should not be called. RPC uses JSON serialization, not JS code generation.',\n )\n },\n\n deserialize(): never {\n // Client uses createRawStreamDeserializePlugin instead\n throw new Error(\n 'RawStreamRPCPlugin.deserialize should not be called. Use createRawStreamDeserializePlugin on client.',\n )\n },\n }) as Plugin<any, any>\n}\n\n/**\n * Creates a deserialize-only plugin for client-side stream reconstruction.\n * Used in serverFnFetcher to wire up streams from frame decoder.\n *\n * @param getOrCreateStream Function to get/create a stream by ID from frame decoder\n */\nexport function createRawStreamDeserializePlugin(\n getOrCreateStream: (id: number) => ReadableStream<Uint8Array>,\n): Plugin<any, any> {\n return createPlugin({\n tag: 'tss/RawStream',\n\n test: () => false, // Client never serializes RawStream\n\n parse: {}, // Client only deserializes, never parses\n\n serialize(): never {\n // Client never serializes RawStream back to server\n throw new Error(\n 'RawStreamDeserializePlugin.serialize should not be called. Client only deserializes.',\n )\n },\n\n deserialize(node: RawStreamRPCNode) {\n return getOrCreateStream(node.streamId)\n },\n }) as Plugin<any, any>\n}\n"],"mappings":"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"}