ovr 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1 +1,306 @@
1
- # oru
1
+ # ovr
2
+
3
+ **ovr** is a lightweight toolkit for building fast, streaming web applications using asynchronous JSX and a modern Fetch API-based router.
4
+
5
+ It's designed for server-side rendering (SSR) where performance and Time-To-First-Byte (TTFB) matter. ovr evaluates components concurrently but streams the resulting HTML **in order**, allowing browsers to render content progressively as it arrives.
6
+
7
+ ## Features
8
+
9
+ - **Asynchronous Streaming JSX**: Write components that perform async operations (like data fetching) directly. ovr handles concurrent evaluation and ordered streaming output.
10
+ - **Performance Focused**: Deliver HTML faster to the client by streaming content as it becomes ready, improving performance and TTFB.
11
+ - **Fetch API Router**: A modern, flexible router built on the standard Fetch API `Request` and `Response` objects.
12
+ - **Minimal & Platform Agnostic**: Uses standard JavaScript/Web APIs, allowing it to run in Node.js, Deno, Bun, Cloudflare Workers, browsers, and other environments.
13
+ - **[Trie](https://en.wikipedia.org/wiki/Radix_tree)-Based Routing**: Efficient and fast route matching, supporting static paths, parameters, and wildcards with clear prioritization. Performance does not degrade as you add more routes.
14
+
15
+ ## Table of Contents
16
+
17
+ - [JSX](#jsx)
18
+ - [Router](#router)
19
+ - [Trie](#trie)
20
+
21
+ ## JSX
22
+
23
+ ovr provides an asynchronous JSX runtime designed for server-side rendering. Instead of building the entire HTML string in memory, it produces an `AsyncGenerator` that yields HTML chunks.
24
+
25
+ When you render multiple asynchronous components (e.g., components fetching data), ovr initiates their evaluation concurrently. As each component resolves, its corresponding HTML is generated.
26
+
27
+ Crucially, ovr ensures that these HTML chunks are yielded in the original source order, even if components finish evaluating out of order. This allows the browser to start parsing and rendering the initial parts of your page while waiting for slower data fetches further down, significantly improving perceived load times.
28
+
29
+ For example, ovr will immediately send the `<head>` of your document for the browser to start requesting the linked assets. Then the rest of the page streams in as it becomes available.
30
+
31
+ > [!WARNING]
32
+ >
33
+ > ovr does not escape HTML automatically, use the `escape` function provided.
34
+
35
+ ### Configuration
36
+
37
+ Add the following to your `tsconfig.json` to enable the JSX transform,
38
+
39
+ ```json
40
+ {
41
+ "jsx": "react-jsx",
42
+ "jsxImportSource": "ovr"
43
+ }
44
+ ```
45
+
46
+ or use JSDoc comments within a module.
47
+
48
+ ```ts
49
+ /** @jsx jsx */
50
+ /** @jsxImportSource ovr */
51
+ ```
52
+
53
+ ### Usage
54
+
55
+ JSX evaluates to an `AsyncGenerator`, with this, the `Router` creates an in-order stream of components.
56
+
57
+ ```tsx
58
+ // Basic component with props
59
+ const Component = (props: { foo: string }) => <div>{props.foo}</div>;
60
+
61
+ // Components can be asynchronous, for example you can fetch directly in a component
62
+ const Data = async () => {
63
+ const res = await fetch("...");
64
+ const data = await res.json();
65
+
66
+ return <div>{JSON.stringify(data)}</div>;
67
+ };
68
+
69
+ // Components can also be generators, `yield` values instead of `return`
70
+ async function* Generator() {
71
+ yield <p>start</p>; // streamed immediately
72
+ await promise;
73
+ yield <p>after</p>;
74
+ }
75
+
76
+ const Page = () => {
77
+ return (
78
+ <div>
79
+ <Component foo="bar" />
80
+
81
+ {/* These three components await in parallel when this component is called. */}
82
+ {/* Then they will stream in order as soon as they are ready. */}
83
+ <Generator />
84
+ <Data />
85
+ <Data />
86
+ </div>
87
+ );
88
+ };
89
+ ```
90
+
91
+ You can `return` or `yield` most data types from a component, they will be rendered as you might expect.
92
+
93
+ ```tsx
94
+ function* DataTypes() {
95
+ yield null; // ""
96
+ yield undefined; // ""
97
+ yield false; // ""
98
+ yield "string"; // "string"
99
+ yield 0; // "0";
100
+ yield BigInt(9007199254740991); // "9007199254740991"
101
+ yield true; // "true"
102
+ yield { foo: "bar" }; // '{ "foo": "bar" }'
103
+ yield <p>jsx</p>; // "<p>jsx</p>"
104
+ yield ["any-", "iterable", 1, null]; // "any-iterable1"
105
+ yield () => "function"; // "function"
106
+ yield async () => "async"; // "async"
107
+ }
108
+ ```
109
+
110
+ ## Router
111
+
112
+ ```ts
113
+ import { Router } from "ovr";
114
+
115
+ const router = new Router();
116
+
117
+ router.get("/", (c) => c.text("Hello world"));
118
+ ```
119
+
120
+ ### Configuration
121
+
122
+ Optional configuration when creating the router.
123
+
124
+ ```ts
125
+ const router = new Router({
126
+ // redirect trailing slash preference
127
+ trailingSlash: "always",
128
+
129
+ // runs at the start of each request
130
+ start(c) {
131
+ // customize the not found response
132
+ c.notFound = (c) => c.res("custom", { status: 404 });
133
+
134
+ // add a global error handler
135
+ c.error = (c, error) => c.res(error.message, { status: 500 });
136
+
137
+ // base HTML to inject head and body elements into, this is the default
138
+ c.base =
139
+ '<!doctype html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"></head><body></body></html>';
140
+ // (these can be set in middleware as well)
141
+
142
+ // return state to use in middleware
143
+ return { foo: "bar" };
144
+ },
145
+ });
146
+ ```
147
+
148
+ ### Context
149
+
150
+ `Context` contains context for the current request.
151
+
152
+ ```tsx
153
+ router.get("/api/:id", (c) => {
154
+ // Request Info
155
+ c.req; // The original Request object
156
+ c.url; // The parsed URL object
157
+ c.params; // Type-safe route parameters (e.g., { id: "123" })
158
+ c.route; // The matched Route object (contains pattern, store)
159
+ c.state; // State returned from `config.start` (e.g., { dbClient, user })
160
+
161
+ // Response Building Methods
162
+ c.res(body, init); // Generic response (like `new Response()`)
163
+ c.html(body, status); // Set HTML response
164
+ c.text(body, status); // Set plain text response
165
+ c.json(data, status); // Set JSON response
166
+ c.redirect(location, status); // Set redirect response
167
+
168
+ // JSX Page Building Methods (Leverages Streaming JSX)
169
+ c.head(<meta name="description" content="..." />); // Add elements to <head>
170
+ c.layout(MainLayout); // Wrap page content with layout components
171
+ c.page(<UserProfilePage userId={c.params.id} />); // Render JSX page, streaming enabled!
172
+
173
+ // Other Utilities
174
+ c.etag("content-to-hash"); // Generate and check ETag for caching
175
+ c.build(); // (Internal) Builds the final Response object
176
+ });
177
+ ```
178
+
179
+ ### Examples
180
+
181
+ #### Overview
182
+
183
+ ```ts
184
+ // Basic
185
+ router.get("/", (c) => c.text("Hello world"));
186
+
187
+ // Params
188
+ router.post("/api/:id", (c) => {
189
+ // matches "/api/123"
190
+ c.params; // { id: "123" }
191
+ });
192
+
193
+ // Wildcard - add an asterisk `*` to match all remaining segments in the route
194
+ router.get("/files/*", (c) => {
195
+ // c.params["*"] contains the matched wildcard path (e.g., "images/logo.png")
196
+ return c.text(`Serving file: ${c.params["*"]}`);
197
+ });
198
+
199
+ // Other or custom methods
200
+ router.on("METHOD", "/pattern", () => {
201
+ // ...
202
+ });
203
+ ```
204
+
205
+ #### Middleware
206
+
207
+ Add middleware to a route, the first middleware added to the route will be called, and the `next` middleware can be called within the first by using `await next()`. Middleware is based on [koa-compose](https://github.com/koajs/compose).
208
+
209
+ ```ts
210
+ router.get(
211
+ "/multi",
212
+ async (c, next) => {
213
+ // middleware
214
+ console.log("pre"); // 1
215
+ await next(); // calls the next middleware below
216
+ console.log("post"); // 3
217
+ },
218
+ () => console.log("final"); // 2
219
+ );
220
+ ```
221
+
222
+ `Context` is passed between between each middleware that is stored in the matched `Route`. After all the handlers have been run, the `Context` will `build` and return the final response.
223
+
224
+ #### Multiple patterns
225
+
226
+ Apply handlers to multiple patterns at once with type safe parameters.
227
+
228
+ ```ts
229
+ router.get(["/multi/:param", "/pattern/:another"], (c) => {
230
+ c.param; // { param: string } | { another: string }
231
+ });
232
+ ```
233
+
234
+ ### fetch
235
+
236
+ Use the `fetch` method to create a response,
237
+
238
+ ```ts
239
+ const res = await router.fetch(new Request("https://example.com/"));
240
+ ```
241
+
242
+ or use in a framework.
243
+
244
+ ```ts
245
+ // next, sveltekit, astro...
246
+ export const GET = router.fetch;
247
+ ```
248
+
249
+ ```ts
250
+ // bun, deno, cloudflare...
251
+ export default router;
252
+ ```
253
+
254
+ ### mount
255
+
256
+ Mount routers onto another with a base pattern.
257
+
258
+ ```ts
259
+ const app = new Router();
260
+
261
+ const hello = new Router();
262
+
263
+ hello.get("/world", (c) => c.text("hello world"));
264
+
265
+ app.mount("/hello", hello); // creates route at "/hello/world"
266
+ ```
267
+
268
+ ## Trie
269
+
270
+ [Router](#router) is built using the `Trie` and `Route` classes. You can build your own trie based router by importing them.
271
+
272
+ The trie is forked and adapted from [memoirist](https://github.com/SaltyAom/memoirist) and [@medley/router](https://github.com/medleyjs/router).
273
+
274
+ ```ts
275
+ import { Trie, Route } from "ovr";
276
+
277
+ // specify the type of the store in the generic
278
+ const trie = new Trie<string>();
279
+ const route = new Route("/hello/:name", "store");
280
+
281
+ trie.add(route);
282
+
283
+ const match = trie.find("/hello/world"); // { route, params: { name: "world" } }
284
+ ```
285
+
286
+ ### Prioritization
287
+
288
+ The trie prioritizes matches in this order: **Static > Parametric > Wildcard**.
289
+
290
+ Given three routes are added in any order,
291
+
292
+ ```ts
293
+ trie.add(new Route("/hello/world", "store"));
294
+ trie.add(new Route("/hello/:name", "store"));
295
+ trie.add(new Route("/hello/*", "store"));
296
+ ```
297
+
298
+ The following pathnames would match the corresponding patterns.
299
+
300
+ | pathname | Route.pattern |
301
+ | --------------------- | ---------------- |
302
+ | `"/hello/world"` | `"/hello/world"` |
303
+ | `"/hello/john"` | `"/hello/:name"` |
304
+ | `"/hello/john/smith"` | `"/hello/*"` |
305
+
306
+ More specific matches are prioritized. First, the static match is found, then the parametric, and finally the wildcard.
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Escapes strings of HTML.
3
+ *
4
+ * @param v value to escape
5
+ * @param attr set to `true` if the value is an attribute, otherwise it's a string of HTML content
6
+ * @returns escaped string of HTML
7
+ */
8
+ export declare const escape: (v: unknown, attr?: boolean) => string;
@@ -0,0 +1,33 @@
1
+ // Copied and adapted from https://github.com/sveltejs/svelte/blob/main/packages/svelte/src/escaping.js
2
+ const attrRegex = /[&"<]/g;
3
+ const contentRegex = /[&<]/g;
4
+ /**
5
+ * Escapes strings of HTML.
6
+ *
7
+ * @param v value to escape
8
+ * @param attr set to `true` if the value is an attribute, otherwise it's a string of HTML content
9
+ * @returns escaped string of HTML
10
+ */
11
+ export const escape = (v, attr) => {
12
+ const s = String(v ?? "");
13
+ const regex = attr ? attrRegex : contentRegex;
14
+ // search starts at beginning of the string
15
+ regex.lastIndex = 0;
16
+ // tracks the position of the last successful match in the input string
17
+ let start = 0;
18
+ let result = "";
19
+ // since `g` flag is used, regex maintains state with each loop,
20
+ // checking from the lastIndex onward each time
21
+ while (regex.test(s)) {
22
+ // index of the match
23
+ const i = regex.lastIndex - 1;
24
+ const match = s[i];
25
+ result +=
26
+ // everything that didn't match during this test
27
+ s.slice(start, i) +
28
+ // replacement
29
+ (match === "&" ? "&amp;" : match === '"' ? "&quot;" : "&lt;");
30
+ start = regex.lastIndex;
31
+ }
32
+ return result + s.slice(start);
33
+ };
package/dist/index.d.ts CHANGED
@@ -1 +1,5 @@
1
- export {};
1
+ export { Context } from "./router/context.js";
2
+ export { Router, type Middleware, type Params } from "./router/index.js";
3
+ export { Trie, Route } from "./trie/index.js";
4
+ export { escape } from "./escape/index.js";
5
+ export { jsx, jsx as jsxs, jsx as jsxDEV, Fragment, toGenerator, toString, type FC, type JSX, } from "./jsx/index.js";
package/dist/index.js CHANGED
@@ -1 +1,5 @@
1
- export {};
1
+ export { Context } from "./router/context.js";
2
+ export { Router } from "./router/index.js";
3
+ export { Trie, Route } from "./trie/index.js";
4
+ export { escape } from "./escape/index.js";
5
+ export { jsx, jsx as jsxs, jsx as jsxDEV, Fragment, toGenerator, toString, } from "./jsx/index.js";