@barefootjs/streaming 0.1.0

package/dist/html.d.ts

@@ -0,0 +1,46 @@
+/**
+ * BarefootJS Streaming - HTML Chunk Generators
+ *
+ * Backend-agnostic functions for generating OOS (Out-of-Order Streaming)
+ * HTML chunks. These produce plain strings that any HTTP server can
+ * write to a response stream.
+ */
+/**
+ * Render an async boundary placeholder with fallback content.
+ *
+ * This HTML should be sent in the initial response (first flush)
+ * and will be replaced when the async data resolves.
+ *
+ * @param id - Unique boundary ID (e.g., "a0")
+ * @param fallbackHtml - HTML string to show while loading
+ * @param tag - Wrapper element tag (default: "div")
+ * @returns HTML string: `<div bf-async="a0">...fallback...</div>`
+ */
+export declare function renderAsyncBoundary(id: string, fallbackHtml: string, tag?: string): string;
+/**
+ * Render a resolve chunk for an async boundary.
+ *
+ * This HTML should be appended to the response stream after the async
+ * data resolves. It contains the resolved content in a `<template>`
+ * element and an inline `<script>` that triggers the swap.
+ *
+ * @param id - Boundary ID matching the placeholder
+ * @param contentHtml - Resolved HTML content (including hydration markers)
+ * @returns HTML string with template + swap script
+ */
+export declare function renderAsyncResolve(id: string, contentHtml: string): string;
+/**
+ * Generate the inline bootstrap script for OOS streaming.
+ *
+ * This script must be included once per page, before any streaming
+ * resolve chunks arrive. It defines the `__bf_swap` function that
+ * swaps fallback content with resolved content.
+ *
+ * The script is intentionally minimal (~300 bytes) and has no
+ * dependencies on the BarefootJS runtime — it only manipulates DOM.
+ * Full hydration is triggered via `__bf_hydrate` which is set up
+ * by the BarefootJS client runtime's `setupStreaming()`.
+ *
+ * @returns A `<script>` tag string
+ */
+export declare function streamingBootstrap(): string;

package/dist/id.d.ts

@@ -0,0 +1,13 @@
+/**
+ * BarefootJS Streaming - Async Boundary ID Generator
+ *
+ * Generates unique, sequential IDs for async streaming boundaries.
+ * Each page render should create a fresh generator instance.
+ */
+export declare class AsyncIdGenerator {
+    private counter;
+    /** Generate the next async boundary ID (e.g., "a0", "a1", "a2"). */
+    next(): string;
+    /** Reset the counter (e.g., between requests). */
+    reset(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { renderAsyncBoundary, renderAsyncResolve, streamingBootstrap, } from './html';
+export { AsyncIdGenerator } from './id';

package/dist/index.js

@@ -0,0 +1,27 @@
+// src/html.ts
+import { BF_ASYNC, BF_ASYNC_RESOLVE } from "@barefootjs/shared";
+function renderAsyncBoundary(id, fallbackHtml, tag = "div") {
+  return `<${tag} ${BF_ASYNC}="${id}">${fallbackHtml}</${tag}>`;
+}
+function renderAsyncResolve(id, contentHtml) {
+  return `<template ${BF_ASYNC_RESOLVE}="${id}">${contentHtml}</template>` + `<script>__bf_swap("${id}")</script>`;
+}
+function streamingBootstrap() {
+  return `<script>(function(){function s(id){var a=document.querySelector('[${BF_ASYNC}="'+id+'"]');var t=document.querySelector('template[${BF_ASYNC_RESOLVE}="'+id+'"]');if(!a||!t)return;a.replaceChildren(t.content.cloneNode(true));a.removeAttribute('${BF_ASYNC}');t.remove();requestAnimationFrame(function(){if(window.__bf_hydrate)window.__bf_hydrate()})};window.__bf_swap=s})()</script>`;
+}
+// src/id.ts
+class AsyncIdGenerator {
+  counter = 0;
+  next() {
+    return `a${this.counter++}`;
+  }
+  reset() {
+    this.counter = 0;
+  }
+}
+export {
+  streamingBootstrap,
+  renderAsyncResolve,
+  renderAsyncBoundary,
+  AsyncIdGenerator
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@barefootjs/streaming",
+  "version": "0.1.0",
+  "description": "Backend-agnostic SSR streaming helpers for BarefootJS",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/index.ts --outdir ./dist --format esm --external @barefootjs/shared",
+    "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
+    "clean": "rm -rf dist",
+    "prepack": "node ../../scripts/swap-publish-config.mjs pack",
+    "postpack": "node ../../scripts/swap-publish-config.mjs unpack"
+  },
+  "keywords": [
+    "barefoot",
+    "streaming",
+    "ssr"
+  ],
+  "author": "kobaken <kentafly88@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/piconic-ai/barefootjs",
+    "directory": "packages/streaming"
+  },
+  "dependencies": {
+    "@barefootjs/shared": "workspace:*"
+  }
+}

package/src/html.ts

@@ -0,0 +1,65 @@
+/**
+ * BarefootJS Streaming - HTML Chunk Generators
+ *
+ * Backend-agnostic functions for generating OOS (Out-of-Order Streaming)
+ * HTML chunks. These produce plain strings that any HTTP server can
+ * write to a response stream.
+ */
+
+import { BF_ASYNC, BF_ASYNC_RESOLVE } from '@barefootjs/shared'
+
+/**
+ * Render an async boundary placeholder with fallback content.
+ *
+ * This HTML should be sent in the initial response (first flush)
+ * and will be replaced when the async data resolves.
+ *
+ * @param id - Unique boundary ID (e.g., "a0")
+ * @param fallbackHtml - HTML string to show while loading
+ * @param tag - Wrapper element tag (default: "div")
+ * @returns HTML string: `<div bf-async="a0">...fallback...</div>`
+ */
+export function renderAsyncBoundary(
+  id: string,
+  fallbackHtml: string,
+  tag: string = 'div',
+): string {
+  return `<${tag} ${BF_ASYNC}="${id}">${fallbackHtml}</${tag}>`
+}
+
+/**
+ * Render a resolve chunk for an async boundary.
+ *
+ * This HTML should be appended to the response stream after the async
+ * data resolves. It contains the resolved content in a `<template>`
+ * element and an inline `<script>` that triggers the swap.
+ *
+ * @param id - Boundary ID matching the placeholder
+ * @param contentHtml - Resolved HTML content (including hydration markers)
+ * @returns HTML string with template + swap script
+ */
+export function renderAsyncResolve(id: string, contentHtml: string): string {
+  return (
+    `<template ${BF_ASYNC_RESOLVE}="${id}">${contentHtml}</template>` +
+    `<script>__bf_swap("${id}")</script>`
+  )
+}
+
+/**
+ * Generate the inline bootstrap script for OOS streaming.
+ *
+ * This script must be included once per page, before any streaming
+ * resolve chunks arrive. It defines the `__bf_swap` function that
+ * swaps fallback content with resolved content.
+ *
+ * The script is intentionally minimal (~300 bytes) and has no
+ * dependencies on the BarefootJS runtime — it only manipulates DOM.
+ * Full hydration is triggered via `__bf_hydrate` which is set up
+ * by the BarefootJS client runtime's `setupStreaming()`.
+ *
+ * @returns A `<script>` tag string
+ */
+export function streamingBootstrap(): string {
+  // Minified inline resolver — no external dependencies
+  return `<script>(function(){function s(id){var a=document.querySelector('[${BF_ASYNC}="'+id+'"]');var t=document.querySelector('template[${BF_ASYNC_RESOLVE}="'+id+'"]');if(!a||!t)return;a.replaceChildren(t.content.cloneNode(true));a.removeAttribute('${BF_ASYNC}');t.remove();requestAnimationFrame(function(){if(window.__bf_hydrate)window.__bf_hydrate()})};window.__bf_swap=s})()</script>`
+}

package/src/id.ts

@@ -0,0 +1,20 @@
+/**
+ * BarefootJS Streaming - Async Boundary ID Generator
+ *
+ * Generates unique, sequential IDs for async streaming boundaries.
+ * Each page render should create a fresh generator instance.
+ */
+
+export class AsyncIdGenerator {
+  private counter = 0
+
+  /** Generate the next async boundary ID (e.g., "a0", "a1", "a2"). */
+  next(): string {
+    return `a${this.counter++}`
+  }
+
+  /** Reset the counter (e.g., between requests). */
+  reset(): void {
+    this.counter = 0
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+  renderAsyncBoundary,
+  renderAsyncResolve,
+  streamingBootstrap,
+} from './html'
+
+export { AsyncIdGenerator } from './id'