@vyckr/tachyon 1.1.11 → 1.3.0

package/.env.example

@@ -1,10 +1,13 @@
 # Tachyon environment variables
 PORT=8000
-NODE_ENV=development|production
+TIMEOUT=70
+DEV=
+VALIDATE=
 HOSTNAME=127.0.0.1
 ALLOW_HEADERS=*
-ALLOW_ORGINS=*
-ALLOW_CREDENTIALS=true|false
+ALLOW_ORIGINS=*
+ALLOW_CREDENTIALS=
 ALLOW_EXPOSE_HEADERS=*
 ALLOW_MAX_AGE=3600
-ALLOW_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
+ALLOW_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
+BASIC_AUTH=username:password

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chidelma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,20 @@
 # Tachyon
 
-Tachyon is a simple to use API framework built with TypeScript (Bun). Tachyon aim to provide a simple and intuitive API framework for building serverless applications and abstracts away the complexity of configuations, letting you focus on building your application.
+Tachyon is a **polyglot, file-system-routed full-stack framework for [Bun](https://bun.sh)**. It lets you define API routes as plain executable files written in any language, and build reactive front-end pages with a lightweight HTML template syntax — all without configuration.
 
 ## Features
 
-- Customizable methods for routes
-- Use of file-system based routing
-- Hot reloading of routes in development mode
-- Supports dynamic routes
+- **File-system routing** — routes are directories; HTTP methods are files
+- **Polyglot handlers** — write routes in Bun, Python, Ruby, Go, Rust, Java, or any language with a shebang
+- **Reactive front-end (Yon)** — HTML templates with bindings, loops, conditionals, and custom components
+- **Lazy component loading** — defer component rendering until visible with `IntersectionObserver`
+- **NPM dependency bundling** — use npm packages in front-end code via `/modules/` imports
+- **Hot Module Replacement** — watches `routes/` and `components/` and reloads on change
+- **Custom 404 page** — drop a `404.html` in your project root to override the default
+- **Schema validation** — per-route request/response validation via `OPTIONS` files
+- **Status code routing** — map response schemas to HTTP status codes; the framework picks the code automatically
+- **Auth** — built-in Basic Auth and JWT decoding
+- **Streaming** — SSE responses via `Accept: text/event-stream`
 
 ## Installation
 
@@ -15,140 +22,276 @@ Tachyon is a simple to use API framework built with TypeScript (Bun). Tachyon ai
 bun add @vyckr/tachyon
 ```
 
-## Configuration
+## Quick Start
+
+```bash
+# Start the development server (expects routes/ in the current directory)
+tach.serve
 
-The .env file should be in the root directory of your project. The following environment variables:
+# Build front-end assets into dist/
+tach.bundle
 ```
-# Tachyon environment variables
-PORT=8000 (optional)
-NODE_ENV=development|production (optional)
-HOSTNAME=127.0.0.1 (optional)
-ALLOW_HEADERS=* (optional)
-ALLOW_ORGINS=* (optional)
-ALLOW_CREDENTIALS=true|false (optional)
-ALLOW_EXPOSE_HEADERS=* (optional)
-ALLOW_MAX_AGE=3600 (optional)
-ALLOW_METHODS=GET,POST,PUT,DELETE,PATCH (optional)
+
+Or via npm scripts if you declare them in your own `package.json`:
+
+```json
+{
+  "scripts": {
+    "start":  "tach.serve",
+    "bundle": "tach.bundle"
+  }
+}
 ```
 
-### Requirements
-- Make sure to have a 'routes' directory in the root of your project
-- Dynamic routes should start with a colon `:`
-- The first parameter should NOT be a dynamic route (e.g. /:version/doc/GET)
-- All dynamic routes should be within odd indexes (e.g. /v1/:path/login/:id/POST)
-- The last parameter in the route should always be a capitalized method as a file name without file extension (e.g. /v1/:path/login/:id/name/DELETE)
-- Front-end Pages end with capitalized `HTML` filename (e.g. /v1/HTML)
-- Node modules should be imported dynamically with `modules` prefix (e.g. const { default: dayjs } = await import(`/modules/dayjs.js`))
-- Components should be in the `components` folder and end with `.html` extension (e.g. /components/counter.html)
-- First line of the file should be a shebang for the executable file (e.g. #!/usr/bin/env python3)
-- Request context can be retrieved by extracting the last element in args and parsing it.
-- Response of executable script must be in a String format and must written to the `/tmp` folder with the the process ID as the file name (e.g. `/tmp/1234`).
-- Use the exit method of the executable script with a status code to end the process of the executable script
-
-### Examples
+## Configuration
 
+Create a `.env` file in your project root. All variables are optional.
 
-```html
-<!-- /routes/HTML  -->
-<script>
-    // top-level await
-    const { default: dayjs } = await import("/modules/dayjs.js")
+```env
+PORT=8000
+HOSTNAME=127.0.0.1
+TIMEOUT=70
+DEV=true
 
-    console.log(dayjs().format())
+# CORS
+ALLOW_HEADERS=*
+ALLOW_ORIGINS=*
+ALLOW_CREDENTIALS=false
+ALLOW_EXPOSE_HEADERS=*
+ALLOW_MAX_AGE=3600
+ALLOW_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
 
-    const greeting = "Hello World!"
-</script>
+# Auth
+BASIC_AUTH=username:password
+
+# Validation (set to any value to enable)
+VALIDATE=true
 
-<p>${greeting}</p>
+# Custom route/asset paths (defaults to <cwd>/routes, <cwd>/components, <cwd>/assets)
+ROUTES_PATH=
+COMPONENTS_PATH=
+ASSETS_PATH=
 ```
 
-```typescript
-// routes/v1/:collection/GET
+## Route Structure
 
-#!/usr/bin/env bun
+```
+routes/
+  GET               →  GET  /
+  POST              →  POST /
+  api/
+    GET             →  GET  /api
+    :version/
+      GET           →  GET  /api/:version
+      DELETE        →  DELETE /api/:version
+  dashboard/
+    HTML            →  front-end page at /dashboard
+  OPTIONS           →  schema file (optional, enables validation)
+```
 
-for await(const chunk of Bun.stdin.stream()) {
+### Requirements
 
-    console.log("Executing Bun....");
+- Every route handler is an **executable file** — include a shebang on the first line
+- The last path segment must be an **uppercase HTTP method** (e.g. `GET`, `POST`, `DELETE`) or `HTML` for a front-end page
+- Dynamic segments start with `:` (e.g. `:version`, `:id`)
+- The first path segment must **not** be dynamic
+- Adjacent dynamic segments are not allowed (e.g. `/:a/:b/GET` is invalid)
+- Node modules must be imported dynamically with the `/modules/` prefix: `await import('/modules/dayjs.js')`
+- Components live in `components/` and must have a `.html` extension
+
+### Request Context
+
+Every handler receives the full request context on `stdin` as a JSON object:
+
+```json
+{
+  "headers": { "content-type": "application/json" },
+  "body":    { "name": "Alice" },
+  "query":   { "page": 1 },
+  "paths":   { "version": "v2" },
+  "context": {
+    "ipAddress": "127.0.0.1",
+    "bearer":    { "header": {}, "payload": {}, "signature": "..." }
+  }
+}
+```
 
-    const data = new TextDecoder().decode(chunk)
+### Route Handler Examples
 
-    const ctx = JSON.parse(data)
+**Bun (TypeScript)**
+```typescript
+// routes/v1/:collection/GET
+#!/usr/bin/env bun
 
-    ctx.message = "Hello from Bun!"
+const { body, paths, context } = await Bun.stdin.json()
 
-    const response = JSON.stringify(ctx)
+const response = { collection: paths.collection, from: context.ipAddress }
 
-    await Bun.write(`/tmp/${process.pid}`, response)
-}
+Bun.stdout.write(JSON.stringify(response))
 ```
 
+**Python**
 ```python
 # routes/v1/:collection/POST
-
 #!/usr/bin/env python3
-import json
-import sys
-import os
+import json, sys
+
+stdin = json.loads(sys.stdin.read())
+sys.stdout.write(json.dumps({ "message": "Hello from Python!" }))
+```
+
+**Ruby**
+```ruby
+# routes/v1/:collection/DELETE
+#!/usr/bin/env ruby
+require 'json'
 
-print("Executing Python....")
+stdin = JSON.parse(ARGF.read)
+print JSON.generate({ message: "Hello from Ruby!" })
+```
 
-ctx = json.loads(sys.stdin.read())
+### Schema Validation
+
+Place an `OPTIONS` file in any route directory to enable validation:
+
+```json
+{
+  "POST": {
+    "req": {
+      "name":   "string",
+      "age?":   0
+    },
+    "res": {
+      "message": "string"
+    },
+    "err": {
+      "detail": "string"
+    }
+  }
+}
+```
 
-ctx["message"] = "Hello from Python!"
+Nullable fields are suffixed with `?`. Set `VALIDATE=true` in your `.env` to enable.
 
-file = open(f"/tmp/{os.getpid()}", "w")
+### Status Code Routing
 
-file.write(json.dumps(ctx))
+Instead of `res`/`err`, you can key response schemas by HTTP status code. Tachyon matches the handler's JSON output against each schema in ascending order — the first match determines the response status code.
 
-file.close()
+```json
+{
+  "POST": {
+    "req": { "name": "string" },
+    "201": { "id": "string", "name": "string" },
+    "400": { "detail": "string" },
+    "503": { "detail": "string", "retryAfter": 0 }
+  },
+  "DELETE": {
+    "204": {}
+  }
+}
 ```
 
-```ruby
-# routes/v1/:collection/DELETE
+Handlers write their normal JSON to stdout — no changes required. The framework determines the status code from whichever schema the output matches. If no numeric schemas are defined, the default behaviour applies (stdout → 200, stderr → 500).
 
-#!/usr/bin/env ruby
-require 'json'
+When `VALIDATE=true` is set, the matched schema is also used for strict validation.
 
-puts "Executing Ruby...."
+## Front-end Pages (Yon)
 
-ctx = JSON.parse(ARGF.read)
+Create an `HTML` file inside any route directory to define a front-end page:
 
-ctx["message"] = "Hello from Ruby!"
+```html
+<!-- routes/HTML -->
+<script>
+  document.title = "Home"
+  let count = 0
+</script>
 
-File.write("/tmp/#{Process.pid}", JSON.unparse(ctx))
+<h1>Count: {count}</h1>
+<button @click="count++">Increment</button>
 ```
 
-To run the application, you can use the following command:
+### Template Syntax
+
+| Syntax | Description |
+|--------|-------------|
+| `{expr}` | Interpolate expression |
+| `@event="handler()"` | Event binding |
+| `:prop="value"` | Bind attribute to expression |
+| `:value="variable"` | Two-way input binding |
+| `<loop :for="...">` | Loop block |
+| `<logic :if="...">` | Conditional block |
+| `<myComp_ prop=val />` | Custom component (trailing `_`) |
+| `<myComp_ lazy />` | Lazy-loaded component (renders when visible) |
+
+### Custom Components
 
-```bash 
-bun tach
+```html
+<!-- components/counter.html -->
+<script>
+  let count = 0
+</script>
+
+<button @click="count++">Clicked {count} times</button>
 ```
 
-To invoke the API endpoints, you can use the following commands:
+Use in a page:
 
-```bash
-curl -X GET http://localhost:8000/v1/users
+```html
+<counter_ />
 ```
 
-```bash
-curl -X POST http://localhost:8000/v1/users -d '{"name": "John Doe", "age": 30}'
+### Lazy Loading
+
+Add the `lazy` attribute to defer a component's loading until it scrolls into view. The component renders a lightweight placeholder and uses `IntersectionObserver` to load the module on demand.
+
+```html
+<!-- Eager (default) — loaded immediately -->
+<counter_ />
+
+<!-- Lazy — loaded when visible in the viewport -->
+<counter_ lazy />
 ```
 
-```bash
-curl -X PATCH http://localhost:8000/v1/users -d '{"name": "Jane Doe", "age": 31}'
+Lazy components are fully interactive once loaded — event delegation and state management work identically to eager components.
+
+### NPM Modules in Front-end Code
+
+Any package listed in your project's `dependencies` is automatically bundled and served at `/modules/<name>.js`. Import them dynamically in your `<script>` blocks:
+
+```html
+<script>
+  const { default: dayjs } = await import('/modules/dayjs.js')
+  let timestamp = dayjs().format('MMM D, YYYY h:mm A')
+</script>
+
+<p>Last updated: {timestamp}</p>
 ```
 
-```bash
-curl -X DELETE http://localhost:8000/v1/users/5e8b0a9c-c0d1-4d3b-a0b1-e2d8e0e9a1c0
+### Custom 404 Page
+
+Place a `404.html` file in your project root to override the default 404 page. It uses the same Yon template syntax:
+
+```html
+<!-- 404.html -->
+<script>
+  document.title = "Not Found"
+</script>
+
+<h1>Oops!</h1>
+<p>This page doesn't exist.</p>
+<a href="/">Go home</a>
 ```
 
-To to build front-end assets into a `dist` folder, use the following command:
+If no custom `404.html` is found, Tachyon serves a built-in styled 404 page.
+
+## Building for Production
 
-```bash 
-bun yon
+```bash
+tach.bundle
 ```
 
-# License
+Outputs compiled assets to `dist/`.
+
+## License
 
-Tachyon is licensed under the MIT License.
+MIT

package/package.json

@@ -1,35 +1,52 @@
 {
-  "name": "@vyckr/tachyon",
-  "version": "1.1.11",
-  "author": "Chidelma",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Chidelma/Tachyon.git"
-  },
-  "devDependencies": {
-    "@types/bun": "~1.2.8",
-    "@types/deno": "^2.0.0",
-    "@types/jsdom": "^21.1.7",
-    "@types/node": "^20.4.2"
-  },
-  "bin": {
-    "tach": "./src/serve.ts",
-    "yon": "./src/client/dist.ts"
-  },
-  "bugs": {
-    "url": "https://github.com/Chidelma/Tachyon/issues"
-  },
-  "keywords": [
-    "tachyon",
-    "api",
-    "framework",
-    "typescript",
-    "bun"
-  ],
-  "license": "MIT",
-  "type": "module",
-  "dependencies": {
-    "dayjs": "^1.11.13",
-    "jsdom": "^26.0.0"
-  }
+    "name": "@vyckr/tachyon",
+    "version": "1.3.0",
+    "description": "A polyglot, file-system-routed full-stack framework for Bun",
+    "author": "Chidelma",
+    "license": "MIT",
+    "type": "module",
+    "main": "./src/server/route-handler.ts",
+    "exports": {
+        ".": "./src/server/route-handler.ts",
+        "./server": "./src/server/process-executor.ts",
+        "./compiler": "./src/compiler/template-compiler.ts"
+    },
+    "bin": {
+        "tach.serve": "./src/cli/serve.ts",
+        "tach.bundle": "./src/cli/bundle.ts"
+    },
+    "scripts": {
+        "start": "bun src/cli/serve.ts",
+        "bundle": "bun src/cli/bundle.ts",
+        "typecheck": "tsc --noEmit",
+        "test": "bun test"
+    },
+    "files": [
+        "src/",
+        "README.md",
+        ".env.example"
+    ],
+    "keywords": [
+        "tachyon",
+        "bun",
+        "framework",
+        "api",
+        "polyglot",
+        "file-system-routing",
+        "typescript"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Chidelma/Tachyon.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Chidelma/Tachyon/issues"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.4",
+        "@types/deno": "^2.0.0",
+        "@types/node": "^20.4.2",
+        "playwright": "^1.59.1",
+        "typescript": "^6.0.2"
+    }
 }

package/src/cli/bundle.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+import Router from "../server/route-handler.js"
+import Yon from "../compiler/template-compiler.js"
+import "../server/console-logger.js"
+import { mkdir } from "node:fs/promises"
+
+const start = Date.now()
+
+const distPath = `${process.cwd()}/dist`
+
+await mkdir(distPath, { recursive: true })
+
+await Yon.createStaticRoutes()
+
+for (const route in Router.reqRoutes) {
+
+    // Skip the HMR script — it is a dev-only asset
+    if (route.includes('hot-reload-client')) continue
+
+    const handler = Router.reqRoutes[route]['GET']
+
+    if (!handler) continue
+
+    try {
+        const res = await handler()
+        await Bun.write(Bun.file(`${distPath}${route}`), await res.blob())
+    } catch (err) {
+        console.error(`Failed to build route ${route}: ${(err as Error).message}`, process.pid)
+    }
+}
+
+await Bun.write(
+    Bun.file(`${distPath}/index.html`),
+    await Bun.file(`${import.meta.dir}/../runtime/shells/production.html`).text()
+)
+
+console.info(`Built in ${Date.now() - start}ms`, process.pid)

package/src/cli/serve.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+import Tach from "../server/process-executor.js"
+import Pool from "../server/process-pool.js"
+import Router from "../server/route-handler.js"
+import Yon from "../compiler/template-compiler.js"
+import "../server/console-logger.js"
+import { watch } from "fs"
+import { access } from "fs/promises"
+import type { Middleware } from "../server/route-handler.js"
+
+/** Debounce delay (ms) applied to file-watcher events before triggering an HMR reload */
+const HMR_DEBOUNCE_MS = 1000
+
+const start = Date.now()
+
+async function pathExists(path: string): Promise<boolean> {
+    try { await access(path); return true } catch { return false }
+}
+
+async function loadMiddleware() {
+    const extensions = ['.ts', '.js']
+    for (const ext of extensions) {
+        const filePath = `${Router.middlewarePath}${ext}`
+        if (await pathExists(filePath)) {
+            const mod = await import(filePath)
+            Router.middleware = (mod.default ?? mod) as Middleware
+            return
+        }
+    }
+    Router.middleware = null
+}
+
+async function configureRoutes(isReload = false) {
+    if (isReload) Pool.clearWarmedProcesses()
+    await loadMiddleware()
+    await Router.validateRoutes()
+    Tach.createServerRoutes()
+    Pool.prewarmAllHandlers()
+    await Yon.createStaticRoutes()
+}
+
+await configureRoutes()
+
+let debounceTimer: Timer
+
+const server = Bun.serve({
+    idleTimeout: process.env.TIMEOUT ? Number(process.env.TIMEOUT) : 0,
+
+    fetch(req, server) {
+
+        if (new URL(req.url).pathname !== "/hmr") {
+            return new Response("Not Found", { status: 404 })
+        }
+
+        server.timeout(req, 0)
+
+        return new Response(new ReadableStream({
+            async start(controller) {
+
+                const onFileChange = () => {
+                    clearTimeout(debounceTimer)
+                    debounceTimer = setTimeout(async () => {
+                        try {
+                            console.info("HMR Update", process.pid)
+                            await configureRoutes(true)
+                            server.reload({ routes: Router.reqRoutes })
+                            controller.enqueue("\n\n")
+                        } catch (err) {
+                            console.error(`HMR reload failed: ${(err as Error).message}`, process.pid)
+                        }
+                    }, HMR_DEBOUNCE_MS)
+                }
+
+                if (await pathExists(Router.routesPath))     watch(Router.routesPath,     { recursive: true }, onFileChange)
+                if (await pathExists(Router.componentsPath)) watch(Router.componentsPath, { recursive: true }, onFileChange)
+            }
+        }), { headers: { "Content-Type": "text/event-stream" } })
+    },
+
+    routes:      Router.reqRoutes,
+    port:        process.env.PORT     || 8080,
+    hostname:    process.env.HOSTNAME || '0.0.0.0',
+    development: !!process.env.DEV,
+})
+
+console.info(`Server running on http://${server.hostname}:${server.port} — started in ${Date.now() - start}ms`, process.pid)
+
+process.on('SIGINT', () => {
+    clearTimeout(debounceTimer)
+    Pool.clearWarmedProcesses()
+    server.stop()
+    process.exit(0)
+})
+
+process.on('SIGTERM', () => {
+    clearTimeout(debounceTimer)
+    Pool.clearWarmedProcesses()
+    server.stop()
+    process.exit(0)
+})