w/cobweb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

implementing routing and streamline tsx runtime

Browse source
This commit is contained in:
laura 2025-11-08 04:52:45 -03:00
parent 3d733cfe0b
commit 4af7b21171
Signed by: w
GPG key ID: BCD2117C99E69817
14 changed files with 820 additions and 451 deletions
Download patch file Download diff file Expand all files Collapse all files

17
README.md
View file

@ -1,3 +1,18 @@
# 🕸️ cobweb
a lightweight, tiny web framework for deno
a lightweight, tiny web framework for deno designed for dynamic no-js
applications
# status
- [x] type-safe routing
- [x] html streaming support
- [x] jsx runtime
- [ ] intutive high-level apis
- [ ] safely defer html streams
- [ ] isolated deferred rendering through iframes
- [ ] scoped css through shadow dom
- [ ] css-in-js library
- [ ] interactives structures and dynamic data visibility toggling via modern
css features
- [ ] only use html streaming shenanigans for noscript environments

3
deno.json
View file

@ -1,6 +1,9 @@
{
"tasks": {},
"imports": {
"cobweb/": "./src/",
"cobweb/routing": "./src/router.ts",
"cobweb/helpers": "./src/helpers.ts",
"cobweb/jsx-runtime": "./src/jsx.ts"
},
"fmt": {

85
example.tsx Normal file
View file

@ -0,0 +1,85 @@
/**
* Copyright (c) 2025 favewa
* SPDX-License-Identifier: BSD-3-Clause
*/
import { createRouter } from "cobweb/routing";
import { Defer, render } from "cobweb/jsx-runtime";
interface Todo {
id: string;
text: string;
done: boolean;
createdAt: Date;
}
const todos: Todo[] = [
{ id: "1", text: "meow", done: true, createdAt: new Date() },
{ id: "2", text: "mrrp", done: false, createdAt: new Date() },
{ id: "3", text: "mrrp", done: false, createdAt: new Date() },
{ id: "4", text: "mrrp", done: false, createdAt: new Date() },
];
async function* fetchTodos(): AsyncGenerator<Todo> {
for (const todo of todos) {
await new Promise((r) => setTimeout(r, 300));
yield todo;
}
}
const Layout = (props: { title: string; children: any }) => (
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>{props.title}</title>
<style>
{`
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: system-ui, sans-serif;
max-width: 600px;
margin: 2rem auto;
padding: 0 1rem;
}`}
</style>
</head>
<body>{props.children}</body>
</html>
);
const TodoList = async function* (): AsyncGenerator<any> {
yield <div class="loading">Loading todos...</div>;
for await (const todo of fetchTodos()) {
yield (
<div class={`todo ${todo.done ? "done" : ""}`}>
<span class="text">{todo.text}</span>
</div>
);
}
};
const app = createRouter();
app.get("/", async (ctx) => {
const { html } = ctx;
await render(
<Layout title="Todo App">
<h1>My Todos</h1>
<Defer>
<TodoList />
</Defer>
</Layout>,
html.chunks,
);
return html.response;
});
app.get("/meow/:test?", async (ctx) => {
console.log(ctx.params.test);
});
Deno.serve({ port: 8000 }, app.fetch);

6
scripts/copyright.ts
View file

@ -14,11 +14,13 @@ const copyrightHeader = `/**
const dir = "./";
for await (const entry of walk(dir, {
for await (
const entry of walk(dir, {
exts: [".ts", ".tsx"],
includeDirs: false,
skip: [/node_modules/, /copyright\.ts$/],
})) {
})
) {
const filePath = entry.path;
const content = await Deno.readTextFile(filePath);

7
src/global.d.ts vendored
View file

@ -12,6 +12,7 @@ type HTMLAttributeMap<T = HTMLElement> = Partial<
style?: string;
class?: string;
children?: any;
charset?: string;
[key: `data-${string}`]: string | number | boolean | null | undefined;
[key: `aria-${string}`]: string | number | boolean | null | undefined;
}
@ -26,11 +27,13 @@ declare global {
children: {};
}
export type IntrinsicElements = {
export type IntrinsicElements =
& {
[K in keyof HTMLElementTagNameMap]: HTMLAttributeMap<
HTMLElementTagNameMap[K]
>;
} & {
}
& {
[K in keyof SVGElementTagNameMap]: HTMLAttributeMap<
SVGElementTagNameMap[K]
>;

46
src/helpers.ts Normal file
View file

@ -0,0 +1,46 @@
/**
* Copyright (c) 2025 favewa
* SPDX-License-Identifier: BSD-3-Clause
*/
export function json(data: unknown, init?: ResponseInit): Response {
const headers = new Headers({
"Content-Type": "application/json",
...init?.headers,
});
return new Response(JSON.stringify(data), { ...init, headers });
}
export function text(body: string, init?: ResponseInit): Response {
const headers = new Headers({
"Content-Type": "text/plain",
...init?.headers,
});
return new Response(body, { ...init, headers });
}
export function html(body: string, init?: ResponseInit): Response {
const headers = new Headers({
"Content-Type": "text/html; charset=utf-8",
...init?.headers,
});
return new Response(body, { ...init, headers });
}
export function redirect(url: string | URL, status = 302): Response {
const headers = new Headers({ Location: url.toString() });
return new Response(null, { status, headers });
}
export function stream(
body: ReadableStream<Uint8Array>,
init?: ResponseInit,
): Response {
const headers = new Headers({
"Content-Type": "text/html; charset=utf-8",
"Transfer-Encoding": "chunked",
"Cache-Control": "no-cache",
...init?.headers,
});
return new Response(body, { ...init, headers });
}

8
src/index.ts
View file

@ -1,8 +0,0 @@
/**
* Copyright (c) 2025 favewa
* SPDX-License-Identifier: BSD-3-Clause
*/
export * from "./html.ts";
export * from "./http.ts";
export * from "./jsx.ts";

145
src/jsx.ts
View file

@ -3,17 +3,45 @@
* SPDX-License-Identifier: BSD-3-Clause
*/
import { Attrs, escape, html, VOID_TAGS } from "./html.ts";
import { escape, html, VOID_TAGS } from "./html.ts";
import { ChunkedStream } from "./stream.ts";
import type { Promisable, Streamable } from "./utils.ts";
export const Fragment = Symbol("Fragment");
export const Fragment = Symbol("jsx.fragment") as any as (
props: any,
) => JsxElement;
export const Defer = Symbol("jsx.async") as any as (props: any) => JsxElement;
type Props = Attrs & { children?: any };
type Component = (props: Props) => JsxElement | AsyncGenerator<JsxElement>;
type Component<P = Props> = (props: P) => Promisable<Streamable<JsxElement>>;
interface DeferProps {
fallback?: JsxChild;
children: JsxChild;
}
type Props = {
children?: JsxChild | JsxChild[];
key?: string | number;
};
export type JsxChildBase =
| string
| number
| boolean
| null
| undefined;
export type JsxChild =
| JsxElement
| JsxChildBase
| Promisable<Streamable<JsxChildBase | JsxElement>>;
export type JsxElement =
| ((chunks: ChunkedStream<string>) => Promise<void>)
| AsyncGenerator<JsxElement, void, unknown>;
| AsyncGenerator<any, void, unknown>;
const write = (chunks: ChunkedStream<string>, data: string) =>
!chunks.closed && chunks.write(data);
async function render(
child: any,
@ -22,66 +50,110 @@ async function render(
): Promise<void> {
if (child == null || child === false || child === true) return;
if (typeof child === "string") return chunks.write(escape(child));
if (typeof child === "number") return chunks.write(String(child));
if (typeof child === "function") return await child(chunks);
if (typeof child === "string") {
return chunks.write(escape(child));
}
if (typeof child === "function") {
return await child(chunks, context);
}
if (child instanceof Promise) {
return await render(await child, chunks, context);
}
if (typeof child === "object" && Symbol.asyncIterator in child) {
(async () => {
for await (const item of child) {
await render(item, chunks, context);
}
})();
return;
}
if (Array.isArray(child)) {
for (const item of child) await render(item, chunks, context);
return;
}
if (typeof child === "object" && Symbol.asyncIterator in child) {
for await (const item of child as AsyncIterable<JsxChild>) {
await render(item, chunks, context);
}
return;
}
chunks.write(escape(String(child)));
}
export function jsx(
tag: string | Component | typeof Fragment,
props: Props | null = {},
export function jsx<P extends Props = Props>(
tag: string | Component<P> | typeof Fragment | typeof Defer,
props: Props | null = {} as P,
): JsxElement {
props ||= {};
props ??= {} as P;
return async (chunks: ChunkedStream<string>) => {
const context = html(chunks);
const { children, ...attrs } = props;
if (tag === Fragment) {
if (!Array.isArray(children)) {
return await render([children], chunks, context);
}
for (const child of children) {
for (const child of Array.isArray(children) ? children : [children]) {
await render(child, chunks, context);
}
return;
}
if (typeof tag === "function") {
return await render(tag(props), chunks, context);
if (tag === Defer) {
const { fallback = "", children } = props as DeferProps;
const id = `s${Math.random().toString(36).slice(2)}`;
write(chunks, `<div id="${id}">`);
await render(fallback, chunks, context);
write(chunks, `</div>`);
Promise.resolve(children).then(async (resolved) => {
const buffer = new ChunkedStream<string>();
await render(resolved, buffer, html(buffer));
buffer.close();
const content: string[] = [];
for await (const chunk of buffer) content.push(chunk);
write(chunks, `<div id="${id}">`);
write(
chunks,
`<template shadowrootmode="open">${content.join("")}</template>`,
);
write(chunks, `</div>`);
});
return;
}
const childr = children == null ? [] : [].concat(children);
const attributes = Object.keys(attrs).length ? attrs : {};
if (typeof tag === "function") {
const result = await tag(props as P);
if (!childr.length || VOID_TAGS.has(tag)) {
await context[tag](childr);
if (typeof result === "object" && Symbol.asyncIterator in result) {
for await (const element of result as AsyncIterable<JsxElement>) {
await render(element, chunks, context);
}
} else {
await context[tag](attributes, async () => {
for (const child of childr) {
await render(result as JsxElement, chunks, context);
}
return;
}
const kids = children == null ? [] : [children];
const isVoid = VOID_TAGS.has(tag);
if (!Object.keys(attrs).length && (!kids.length || isVoid)) {
return await context[tag]();
}
write(chunks, `<${tag}`);
for (const key in attrs) {
const val = (attrs as any)[key];
val && write(
chunks,
val === true ? ` ${key}` : ` ${key}="${escape(String(val))}"`,
);
}
write(chunks, isVoid ? "/>" : ">");
if (!isVoid) {
for (const child of kids) {
await render(child, chunks, context);
}
});
write(chunks, `</${tag}>`);
}
};
}
@ -110,8 +182,7 @@ async function renderJsx(
}
export const raw =
(html: string): JsxElement =>
async (chunks: ChunkedStream<string>) =>
(html: string): JsxElement => async (chunks: ChunkedStream<string>) =>
void (!chunks.closed && chunks.write(html));
export const open = <K extends keyof HTMLElementTagNameMap>(tag: K) =>

68
src/middleware.ts Normal file
View file

@ -0,0 +1,68 @@
/**
* Copyright (c) 2025 favewa
* SPDX-License-Identifier: BSD-3-Clause
*/
import { HtmlStream } from "./http.ts";
import { Promisable } from "./utils.ts";
export interface Context<Params = Record<string, string>> {
readonly request: Request;
readonly url: URL;
readonly method: string;
readonly params: Params;
readonly pattern: URLPatternResult;
readonly html: HtmlStream;
readonly signal: AbortSignal;
state: Map<string | symbol, unknown>;
}
export async function createContext<P = Record<string, string>>(
request: Request,
pattern: URLPatternResult,
html: HtmlStream,
): Promise<Context<P>> {
return {
request,
url: new URL(request.url),
method: request.method,
params: (pattern.pathname.groups || {}) as P,
pattern,
html,
signal: request.signal,
state: new Map(),
};
}
export interface Handler<P = Record<string, string>> {
(ctx: Context<P>): Promisable<Response | void>;
}
export interface Middleware {
(ctx: Context, next: () => Promise<Response>): Promisable<Response>;
}
export function compose(
middlewares: readonly Middleware[],
handler: Handler,
): Handler {
if (!middlewares.length) return handler;
return (ctx) => {
let index = -1;
async function dispatch(i: number): Promise<Response> {
if (i <= index) throw new Error("next() called multiple times");
index = i;
const fn = i < middlewares.length ? middlewares[i] : handler;
if (!fn) throw new Error("No handler found");
const result = await fn(ctx, () => dispatch(i + 1));
if (!result) throw new Error("Handler must return Response");
return result;
}
return dispatch(0);
};
}

151
src/router.ts Normal file
View file

@ -0,0 +1,151 @@
/**
* Copyright (c) 2025 favewa
* SPDX-License-Identifier: BSD-3-Clause
*/
import { createHtmlStream } from "./http.ts";
import { compose, createContext, Handler, Middleware } from "./middleware.ts";
// why is Request["method"] a bare `string` oh my lord kill me
type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
type ExtractParameterNames<S extends string> = S extends
`${string}:${infer Param}/${infer Rest}`
? Param | ExtractParameterNames<`/${Rest}`>
: S extends `${string}:${infer Param}` ? Param
: never;
type Skippable<S extends string, T> = S extends `${string}?` ? T | undefined
: T;
type StripOptional<S extends string> = S extends `${infer P}?` ? P : S;
export type ParametersOf<S extends string> = {
[K in ExtractParameterNames<S> as StripOptional<K>]: Skippable<
K,
string
>;
};
export interface TypedURLPattern<S extends string> extends URLPattern {
readonly raw: S;
}
export function url<const S extends string>(
init: URLPatternInit & { pathname: S },
): TypedURLPattern<S> {
const pattern = new URLPattern(init) as TypedURLPattern<S>;
return (((pattern as any).raw = init.pathname), pattern);
}
export interface Route {
readonly pattern: URLPattern;
handler: Handler;
method: Method;
}
type HandlerParams<P> = P extends TypedURLPattern<any> ? ParametersOf<P["raw"]>
: P extends string ? ParametersOf<P>
: P extends URLPattern ? Record<string, string>
: never;
interface BaseRouter {
routes: Route[];
middlewares: Middleware[];
namespace?: string;
use: (...middlewares: Middleware[]) => this;
on<P extends string | TypedURLPattern<any> | URLPattern>(
method: Method,
path: P,
handler: Handler<HandlerParams<P>>,
): P;
fetch: (request: Request) => Promise<Response>;
}
type Router =
& BaseRouter
& {
[M in Method as Lowercase<M>]: <
P extends string | TypedURLPattern<any> | URLPattern,
>(
path: P,
handler: Handler<HandlerParams<P>>,
) => Router;
};
export function createRouter(namespace?: string): Router {
const routes: Route[] = [];
const middlewares: Middleware[] = [];
const router: BaseRouter = {
routes,
middlewares,
namespace,
use(...mw: Middleware[]) {
middlewares.push(...mw);
return router;
},
on<P extends string | TypedURLPattern<any> | URLPattern>(
method: Method,
path: P,
handler: Handler<HandlerParams<P>>,
): P {
const pattern: URLPattern = typeof path === "string"
? url({ pathname: path })
: (path as URLPattern);
routes.push({
method,
pattern,
handler: handler as Handler,
});
return path;
},
async fetch(request: Request): Promise<Response> {
const method = request.method.toUpperCase() as Method;
for (const route of routes) {
if (route.method !== method) continue;
const match = route.pattern.exec(request.url);
if (!match) continue;
const html = await createHtmlStream();
const ctx = await createContext(request, match, html);
return (
(await compose(middlewares, route.handler)(ctx)) ||
new Response("", { status: 200 })
);
}
return new Response("Not Found", {
status: 404,
headers: new Headers({ "Content-Type": "text/plain" }),
});
},
};
["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].forEach(
(method) => {
const lower = method.toLowerCase() as Lowercase<Method>;
(router as any)[lower] = <
P extends string | TypedURLPattern<any> | URLPattern,
>(
path: P,
handler: Handler<HandlerParams<P>>,
) => router.on(method as Method, path, handler);
},
);
return router as Router;
}
export * from "./middleware.ts";

75
src/stream.ts
View file

@ -68,78 +68,3 @@ export class ChunkedStream<T> implements AsyncIterable<T> {
return this;
}
}
export const mapStream = <T, U>(
fn: (chunk: T, index: number) => U | Promise<U>,
) =>
async function* (source: AsyncIterable<T>): AsyncIterable<U> {
let index = 0;
for await (const chunk of source) yield await fn(chunk, index++);
};
export const filterStream = <T>(
pred: (chunk: T, index: number) => boolean | Promise<boolean>,
) =>
async function* (source: AsyncIterable<T>): AsyncIterable<T> {
let index = 0;
for await (const chunk of source) {
if (await pred(chunk, index++)) yield chunk;
}
};
export const takeStream = <T>(count: number) =>
async function* (source: AsyncIterable<T>): AsyncIterable<T> {
let taken = 0;
for await (const chunk of source) {
if (taken++ >= count) return;
yield chunk;
}
};
export const skipStream = <T>(count: number) =>
async function* (source: AsyncIterable<T>): AsyncIterable<T> {
let index = 0;
for await (const chunk of source) {
if (index++ >= count) yield chunk;
}
};
export const batchStream = <T>(size: number) =>
async function* (source: AsyncIterable<T>): AsyncIterable<T[]> {
let batch: T[] = [];
for await (const chunk of source) {
batch.push(chunk);
if (batch.length >= size) {
yield batch;
batch = [];
}
}
if (batch.length) yield batch;
};
export const tapStream = <T>(
fn: (chunk: T, index: number) => void | Promise<void>,
) =>
async function* (source: AsyncIterable<T>): AsyncIterable<T> {
let index = 0;
for await (const chunk of source) {
yield chunk;
await fn(chunk, index++);
}
};
export const catchStream = <T>(
handler: (error: Error) => void | Promise<void>,
) =>
async function* (source: AsyncIterable<T>): AsyncIterable<T> {
try {
for await (const chunk of source) yield chunk;
} catch (err) {
await handler(err instanceof Error ? err : new Error(String(err)));
}
};
export const pipe =
<T>(...fns: Array<(src: AsyncIterable<T>) => AsyncIterable<any>>) =>
(source: AsyncIterable<T>) =>
fns.reduce((acc, fn) => fn(acc), source);

8
src/utils.ts Normal file
View file

@ -0,0 +1,8 @@
/**
* Copyright (c) 2025 favewa
* SPDX-License-Identifier: BSD-3-Clause
*/
export type Promisable<T> = T | Promise<T>;
export type Streamable<T> = T | AsyncIterable<T>;