npm package: @t8n/stream
Description: A high-performance TitanPL extension.
Latest version: 1.0.0

# @t8n/stream

**The High-Performance Static Serving & Dynamic Content Delivery Engine for TitanPL.**

`@t8n/stream` is a lightweight, ultra-fast extension designed to turn your TitanPL application into a powerful static file server or a high-performance content delivery node. Whether you are hosting a modern **Vite + React** build or building a custom **CDN**, `@t8n/stream` provides the primitives to serve assets with zero overhead and automatic MIME detection.

---

## 🚀 Speed & Simplicity

- **Vite/React Ready**: Host full-stack SPAs by pointing to your `dist` folder.
- **Smart MIME Detection**: Automatic recognition of 30+ file types (JS, CSS, Images, Videos, etc.).
- **Media Previews**: Built-in HTML5 player for images and videos when accessed directly.
- **CORS Support**: Integrated `Access-Control-Allow-Origin` handling for cross-domain asset sharing.
- **Raw Data Access**: Fetch file contents as Base64/Raw via query parameters (`?format=raw`).

---

## 🛠️ Essential Functions

### 1. `client(dirPath, req, entryFile)`
The core utility for hosting static directories. It perfectly handles routing, trailing slashes, and fallbacks to an entry file (like `index.html`).

> [!TIP]
> Use this to host your production builds from frameworks like Vite, React, or Next.js (Static Export).

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `dirPath` | `string` | — | The physical path to your static folder (e.g., `"./dist"`). |
| `req` | `Request` | — | The TitanPL request object containing `params`. |
| `entryFile` | `string` | `"index.html"` | The file served at the root `/` or when no specific path is found. |

#### 📦 Example: Hosting a Vite Production Build
```javascript
import stream from "@t8n/stream";

// In your app.js / route registration
// t.get("/:static*").action("static");
```

---

### 2. `serveFile(filePath, req, allowOrigin)`
A precision tool for serving a single file. Perfect for building asset routes or specialized delivery endpoints.

#### 🎥 Example: Custom CDN Route
```javascript
import stream from "@t8n/stream";
import { defineAction } from "@titanpl/native";


export default defineAction((req) => {
    const assetId = req.params.id;
    // Serve a specific asset with automatic MIME detection and Preview
    return stream.serveFile(`./storage/assets/${assetId}.png`, req, "*");
});
```

---

## 🎨 Best-in-Class Features

### 🖼️ Automatic Media Previews
When you access a binary file (Image or Video) directly in the browser via `serveFile`, `@t8n/stream` doesn't just download it—it generates a sleek, dark-themed **HTML5 Preview** automatically.

### 🔌 Raw Data API (The CDN Secret)
Need just the content of a file for your client-side application? Add `?format=raw` to any request, and the extension will skip the preview/headers and return the **Raw Base64** string.

```bash
# Get the raw base64 of an image instead of the HTML preview
GET /assets/logo.png?format=raw
```

---

## 📦 Installation

```bash
# Add to your TitanPL project
npm install @t8n/stream
```

---

> [!IMPORTANT]
> Since TitanPL runs on a strictly synchronous Worker runtime, `@t8n/stream` leverages high-performance file-system bindings to ensure your assets are delivered with minimal latency and maximum reliability.

Built with ❤️ for the **Titan Planet** Ecosystem.