ovr 6.2.4 → 7.0.0-next.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.
Files changed (136) hide show
  1. package/README.md +3 -1
  2. package/dist/app/index.d.ts +51 -7
  3. package/dist/app/index.d.ts.map +1 -1
  4. package/dist/app/index.js +163 -28
  5. package/dist/auth/auth-data.d.ts +26 -0
  6. package/dist/auth/auth-data.d.ts.map +1 -0
  7. package/dist/auth/auth-data.js +42 -0
  8. package/dist/auth/cbor.d.ts +50 -0
  9. package/dist/auth/cbor.d.ts.map +1 -0
  10. package/dist/auth/cbor.js +200 -0
  11. package/dist/auth/client-source.d.ts +3 -0
  12. package/dist/auth/client-source.d.ts.map +1 -0
  13. package/dist/auth/client-source.js +3 -0
  14. package/dist/auth/client.d.ts +3 -0
  15. package/dist/auth/client.d.ts.map +1 -0
  16. package/dist/auth/client.js +186 -0
  17. package/dist/auth/configure.d.ts +28 -0
  18. package/dist/auth/configure.d.ts.map +1 -0
  19. package/dist/auth/configure.js +228 -0
  20. package/dist/auth/der.d.ts +6 -0
  21. package/dist/auth/der.d.ts.map +1 -0
  22. package/dist/auth/der.js +36 -0
  23. package/dist/auth/index.d.ts +242 -0
  24. package/dist/auth/index.d.ts.map +1 -0
  25. package/dist/auth/index.js +152 -0
  26. package/dist/auth/issue.d.ts +36 -0
  27. package/dist/auth/issue.d.ts.map +1 -0
  28. package/dist/auth/issue.js +47 -0
  29. package/dist/auth/metadata.d.ts +22 -0
  30. package/dist/auth/metadata.d.ts.map +1 -0
  31. package/dist/auth/metadata.js +134 -0
  32. package/dist/auth/oauth.d.ts +29 -0
  33. package/dist/auth/oauth.d.ts.map +1 -0
  34. package/dist/auth/oauth.js +724 -0
  35. package/dist/auth/passkey.d.ts +101 -0
  36. package/dist/auth/passkey.d.ts.map +1 -0
  37. package/dist/auth/passkey.js +393 -0
  38. package/dist/auth/state.d.ts +49 -0
  39. package/dist/auth/state.d.ts.map +1 -0
  40. package/dist/auth/state.js +184 -0
  41. package/dist/auth/storage.d.ts +193 -0
  42. package/dist/auth/storage.d.ts.map +1 -0
  43. package/dist/auth/storage.js +410 -0
  44. package/dist/auth/token.d.ts +12 -0
  45. package/dist/auth/token.d.ts.map +1 -0
  46. package/dist/auth/token.js +39 -0
  47. package/dist/context/index.d.ts +86 -16
  48. package/dist/context/index.d.ts.map +1 -1
  49. package/dist/context/index.js +166 -42
  50. package/dist/cookie/index.d.ts +3 -0
  51. package/dist/cookie/index.d.ts.map +1 -1
  52. package/dist/cookie/index.js +1 -0
  53. package/dist/database/index.d.ts +262 -0
  54. package/dist/database/index.d.ts.map +1 -0
  55. package/dist/database/index.js +807 -0
  56. package/dist/form/index.d.ts +699 -0
  57. package/dist/form/index.d.ts.map +1 -0
  58. package/dist/form/index.js +901 -0
  59. package/dist/index.d.ts +10 -3
  60. package/dist/index.d.ts.map +1 -1
  61. package/dist/index.js +9 -3
  62. package/dist/jsx/elements.d.ts +28 -2
  63. package/dist/jsx/elements.d.ts.map +1 -1
  64. package/dist/jsx/index.d.ts +20 -4
  65. package/dist/jsx/index.d.ts.map +1 -1
  66. package/dist/jsx/index.js +6 -65
  67. package/dist/limiter/index.d.ts +65 -0
  68. package/dist/limiter/index.d.ts.map +1 -0
  69. package/dist/limiter/index.js +157 -0
  70. package/dist/markdown/index.d.ts +61 -0
  71. package/dist/markdown/index.d.ts.map +1 -0
  72. package/dist/markdown/index.js +1160 -0
  73. package/dist/markup/index.d.ts +188 -0
  74. package/dist/markup/index.d.ts.map +1 -0
  75. package/dist/markup/index.js +718 -0
  76. package/dist/mcp/index.d.ts +73 -0
  77. package/dist/mcp/index.d.ts.map +1 -0
  78. package/dist/mcp/index.js +988 -0
  79. package/dist/middleware/index.d.ts +3 -4
  80. package/dist/middleware/index.d.ts.map +1 -1
  81. package/dist/multipart/index.d.ts +53 -7
  82. package/dist/multipart/index.d.ts.map +1 -1
  83. package/dist/multipart/index.js +332 -124
  84. package/dist/route/index.d.ts +226 -80
  85. package/dist/route/index.d.ts.map +1 -1
  86. package/dist/route/index.js +239 -99
  87. package/dist/schema/index.d.ts +307 -734
  88. package/dist/schema/index.d.ts.map +1 -1
  89. package/dist/schema/index.js +783 -1050
  90. package/dist/table/index.d.ts +132 -0
  91. package/dist/table/index.d.ts.map +1 -0
  92. package/dist/table/index.js +188 -0
  93. package/dist/trie/index.js +4 -4
  94. package/dist/util/index.d.ts +37 -5
  95. package/dist/util/index.d.ts.map +1 -1
  96. package/dist/util/index.js +156 -41
  97. package/package.json +11 -4
  98. package/src/app/index.ts +230 -42
  99. package/src/auth/auth-data.ts +56 -0
  100. package/src/auth/cbor.ts +231 -0
  101. package/src/auth/client-source.ts +3 -0
  102. package/src/auth/client.ts +205 -0
  103. package/src/auth/configure.ts +279 -0
  104. package/src/auth/der.ts +35 -0
  105. package/src/auth/index.ts +387 -0
  106. package/src/auth/issue.ts +52 -0
  107. package/src/auth/metadata.ts +149 -0
  108. package/src/auth/oauth.ts +882 -0
  109. package/src/auth/passkey.ts +556 -0
  110. package/src/auth/state.ts +213 -0
  111. package/src/auth/storage.ts +572 -0
  112. package/src/auth/token.ts +67 -0
  113. package/src/context/index.ts +240 -65
  114. package/src/cookie/index.ts +3 -0
  115. package/src/database/index.ts +1193 -0
  116. package/src/form/index.ts +1720 -0
  117. package/src/index.ts +10 -3
  118. package/src/jsx/elements.ts +45 -25
  119. package/src/jsx/index.ts +24 -69
  120. package/src/limiter/index.ts +221 -0
  121. package/src/markdown/index.ts +1322 -0
  122. package/src/markup/index.ts +853 -0
  123. package/src/mcp/conformance.2025-11-25.yml +39 -0
  124. package/src/mcp/conformance.2026-07-28.yml +56 -0
  125. package/src/mcp/index.ts +1262 -0
  126. package/src/middleware/index.ts +5 -6
  127. package/src/multipart/index.ts +410 -158
  128. package/src/route/index.ts +559 -278
  129. package/src/schema/index.ts +1542 -2256
  130. package/src/table/index.ts +387 -0
  131. package/src/trie/index.ts +4 -4
  132. package/src/util/index.ts +163 -49
  133. package/dist/render/index.d.ts +0 -79
  134. package/dist/render/index.d.ts.map +0 -1
  135. package/dist/render/index.js +0 -257
  136. package/src/render/index.ts +0 -314
@@ -1,74 +1,240 @@
1
+ import { Form as FormSchema, forms, query } from "../form/index.js";
1
2
  import { jsx } from "../jsx/index.js";
2
- import { Form as FormSchema } from "../schema/index.js";
3
+ import { Schema as ValueSchema } from "../schema/index.js";
3
4
  import { Checksum, Method, Mime } from "../util/index.js";
5
+ /** Finishes a route's configuration, `app.use(route)` calls it */
6
+ export const freeze = Symbol("freeze");
7
+ /**
8
+ * Matches a pattern's parameters, as the router reads them: `:name` up to the
9
+ * next slash, anywhere in a segment, and a final `*`, the wildcard, which
10
+ * has no name. Internal to ovr.
11
+ */
12
+ export const parameters = /:([^/]+?)(?=\/|\*?$)|\*$/g;
13
+ /** Internal protocol for the MCP endpoint, to read a route's parameter schemas. */
14
+ export const schemas = Symbol("schemas");
4
15
  /**
5
16
  * Route to use in the application.
6
17
  *
18
+ * Each method adds to the route and returns it, so a route reads as a chain:
19
+ *
20
+ * ```ts
21
+ * const update = Route.post("/posts/:id")
22
+ * .describe("Change a post's title or body")
23
+ * .params({ id: Schema.string().uuid() })
24
+ * .fields({ title, body })
25
+ * .use(async (c) => {
26
+ * // ...
27
+ * });
28
+ * ```
29
+ *
7
30
  * @template Pattern Route pattern
31
+ * @template Params Parameters passed to middleware
32
+ * @template Shape Form field shape
33
+ * @template Kind Components the route has
8
34
  */
9
35
  export class Route {
10
- /** Route pattern */
11
- pattern;
12
36
  /** HTTP method */
13
37
  method;
14
- /** Route middleware stack, runs after global middleware */
15
- middleware; // any so you can use other middleware
16
- /** Pattern parts */
17
- #parts;
38
+ /** Description for agents */
39
+ #description;
40
+ /** Schemas that check and convert pattern parameters */
41
+ #paramSchemas;
42
+ /** Mounted, so its configuration is final */
43
+ #frozen = false;
44
+ /** Route pattern */
45
+ #pattern;
46
+ /** Middleware added with `use` */
47
+ #stack = [];
18
48
  /**
19
49
  * Create a new route.
20
50
  *
21
51
  * @param method HTTP Method
22
52
  * @param pattern Route pattern
23
- * @param middleware Route middleware
24
53
  */
25
- constructor(method, pattern, ...middleware) {
54
+ constructor(method, pattern) {
26
55
  this.method = method;
27
- this.pattern = pattern;
28
- this.middleware = middleware;
29
- this.#parts = pattern.split("/");
56
+ // the message type only reaches here from a pattern already rejected
57
+ this.#pattern = pattern;
58
+ }
59
+ /** Description for agents, only described routes are served to them */
60
+ get description() {
61
+ return this.#description;
62
+ }
63
+ /** Schemas that check and convert pattern parameters */
64
+ get [schemas]() {
65
+ return this.#paramSchemas;
66
+ }
67
+ /** Route pattern */
68
+ get pattern() {
69
+ return this.#pattern;
70
+ }
71
+ /** Route middleware stack, runs after global middleware */
72
+ get middleware() {
73
+ const params = this.#paramSchemas;
74
+ // a copy, so a mounted route's middleware cannot be changed through it
75
+ if (!params)
76
+ return [...this.#stack];
77
+ return [
78
+ (c, next) => {
79
+ for (const name in params) {
80
+ const result = params[name].parse(c.params[name]);
81
+ // a parameter that does not match is a resource that does not exist
82
+ if (result.issues)
83
+ return void (c.res.status = 404);
84
+ c.params[name] = result.data;
85
+ }
86
+ return next();
87
+ },
88
+ ...this.#stack,
89
+ ];
90
+ }
91
+ /**
92
+ * The tool agents call the route as, through MCP and the route's `Form`.
93
+ * Only described routes are tools, so mounting a route never lets agents
94
+ * call it; GET tools are read-only.
95
+ */
96
+ get tool() {
97
+ const { description, method, pattern } = this;
98
+ if (!description || method === Method.head)
99
+ return;
100
+ const read = method === Method.get;
101
+ const segments = pattern
102
+ .split("/")
103
+ .filter(Boolean)
104
+ .map((segment) => segment === "*" ? "wildcard" : segment.replace(/^:/, ""));
105
+ let name = `${method.toLowerCase()}_${segments.join("_") || "index"}`;
106
+ // `_` and other punctuation could make two patterns' names the same,
107
+ // such as `/a/b` and `/a_b`, so those names end with the pattern's hash
108
+ if (!segments.every((segment) => /^[A-Za-z0-9-]+$/.test(segment)) ||
109
+ name.length > 64)
110
+ name = `${name
111
+ .replace(/[^\w-]+/g, "_")
112
+ .replace(/_+/g, "_")
113
+ .slice(0, 56)}_${Checksum.djb2(`${method} ${pattern}`).slice(0, 7)}`;
114
+ return { name, description, read };
115
+ }
116
+ /**
117
+ * Describe the route for agents. Only described routes are served to
118
+ * them: as MCP tools, and GET routes as resources too.
119
+ *
120
+ * @template D Description, a string literal that is not blank
121
+ * @param description What the route does, written for an agent, not blank
122
+ * @returns The route
123
+ */
124
+ describe(description) {
125
+ this.#configure("describe");
126
+ this.#description = description;
127
+ return this;
30
128
  }
31
129
  /**
32
- * Constructs a _relative_ URL for the route.
130
+ * Check and convert pattern parameters before the middleware runs.
131
+ * A parameter that fails its schema responds `404`.
33
132
  *
34
- * @param [options] Options with type safe pathname parameters
133
+ * @template P Schemas keyed by parameter name
134
+ * @param schemas Schemas keyed by parameter name
135
+ * @returns The route, with converted `c.params` types
136
+ */
137
+ params(
138
+ // a name the pattern does not have is a type error
139
+ schemas) {
140
+ this.#configure("params");
141
+ this.#paramSchemas = { ...this.#paramSchemas, ...schemas };
142
+ return this;
143
+ }
144
+ /**
145
+ * Set the form fields that `c.data()` parses, and that the route's `Form`
146
+ * renders by default.
147
+ *
148
+ * @template S Field shape
149
+ * @param fields Field shape
150
+ * @returns The route with form helpers
151
+ */
152
+ fields(fields) {
153
+ this.#configure("fields");
154
+ let form = new FormSchema(fields);
155
+ // a GET form's submission is the URL, so its fields read from it
156
+ if (this.method === Method.get)
157
+ form = form[query]();
158
+ forms.set(this, form);
159
+ const { Field, Fields, component } = form;
160
+ return Object.assign(this, { Field, Fields, component });
161
+ }
162
+ /**
163
+ * A mounted route is final, so the app's tools and middleware stay as
164
+ * they were when it was mounted. Changing the types middleware is given
165
+ * after `use()` is a type error instead, see `Route.Used`.
166
+ *
167
+ * @param method Method that changes the route
168
+ */
169
+ #configure(method) {
170
+ if (this.#frozen)
171
+ throw new TypeError(`Call .${method}() before app.use() on route "${this.pattern}".`);
172
+ }
173
+ /** Finish the configuration, when an app mounts the route. */
174
+ [freeze]() {
175
+ this.#frozen = true;
176
+ }
177
+ /**
178
+ * Add middleware to the route. The last one usually responds.
179
+ *
180
+ * @param middleware Route middleware
181
+ * @returns The route
182
+ */
183
+ use(...middleware) {
184
+ this.#configure("use");
185
+ this.#stack.push(...middleware);
186
+ // a named type, not `this`, so an app's own routes can be named in
187
+ // its declarations
188
+ return this;
189
+ }
190
+ /**
191
+ * Construct a _relative_ URL for the route. Parameter values are encoded,
192
+ * so each stays in its own segment, and a wildcard keeps its slashes.
193
+ *
194
+ * @template O Options, the exact path type when only `params` are given
195
+ * @param [options] Parameters, search, and hash
35
196
  * @returns `pathname` + `search` + `hash`
36
197
  */
37
198
  url(...[options]) {
38
- return (this.pathname(
39
- // @ts-expect-error - do not have to pass in {} if no params
40
- options?.params) +
41
- (options?.search
199
+ const params = options?.params;
200
+ const path = params
201
+ ? this.pattern.replace(parameters, (_, name) => name
202
+ ? Route.#segment(String(params[name]))
203
+ : // the wildcard keeps its slashes, each of its segments is encoded
204
+ String(params["*"])
205
+ .split("/")
206
+ .map((segment) => (segment ? Route.#segment(segment) : segment))
207
+ .join("/"))
208
+ : this.pattern;
209
+ // a value starting with a slash, such as a wildcard of `/host/path`,
210
+ // would make a path that browsers read as another origin
211
+ if (path.startsWith("//"))
212
+ throw new TypeError(`Route path "${path}" would start with "//", which is read as another host`);
213
+ const { search, hash } = options ?? {};
214
+ return (path +
215
+ (search
42
216
  ? // use the value as the init
43
- // @ts-expect-error - see type above
44
- "?" + new URLSearchParams(options.search)
217
+ "?" +
218
+ new URLSearchParams(search)
45
219
  : "") +
46
- (options?.hash
220
+ (hash
47
221
  ? // adding # prefix if not present matches the URL setter:
48
222
  // https://developer.mozilla.org/en-US/docs/Web/API/URL/hash
49
- options.hash[0] === "#"
50
- ? options.hash
51
- : "#" + options.hash
223
+ hash[0] === "#"
224
+ ? hash
225
+ : "#" + hash
52
226
  : ""));
53
227
  }
54
228
  /**
55
- * @template Params Parameters to create the pathname with
56
- * @param [params] Parameters to insert
57
- * @returns Resolved `pathname` with params
229
+ * @param value Parameter value
230
+ * @returns The value encoded as one segment
231
+ * @throws When it would not stay in its segment: empty, `.`, or `..`,
232
+ * which a URL resolves away
58
233
  */
59
- pathname(...[params]) {
60
- if (!params)
61
- return this.pattern;
62
- return this.#parts
63
- .map((part) => {
64
- if (part.startsWith(":")) {
65
- return params[part.slice(1)];
66
- }
67
- if (part === "*")
68
- return params[part];
69
- return part;
70
- })
71
- .join("/");
234
+ static #segment(value) {
235
+ if (value === "" || value === "." || value === "..")
236
+ throw new TypeError(`Route parameter "${value}" cannot be a path segment, it would change the path`);
237
+ return encodeURIComponent(value);
72
238
  }
73
239
  /**
74
240
  * @template Pattern Route pattern
@@ -84,7 +250,7 @@ export class Route {
84
250
  formenctype: enctype,
85
251
  ...rest,
86
252
  })),
87
- Form: (({ params, search, hash, state, ...rest }) => {
253
+ Form: (({ params, search, hash, state, values, submit = "Submit", ...rest }) => {
88
254
  let query;
89
255
  if (route.method === Method.post && state) {
90
256
  const target = new URL(state);
@@ -96,6 +262,8 @@ export class Route {
96
262
  search);
97
263
  query.set(FormSchema.params[0], target.pathname + target.search + target.hash);
98
264
  }
265
+ const { Fields } = route;
266
+ const { tool } = route;
99
267
  return jsx("form", {
100
268
  action: route.url({
101
269
  params,
@@ -104,6 +272,22 @@ export class Route {
104
272
  }),
105
273
  method: route.method,
106
274
  enctype,
275
+ // default to the fields, if any, and a submit button, so a form
276
+ // without fields, such as a delete, is still one to submit
277
+ children: [
278
+ Fields?.({ state, values }),
279
+ jsx("button", { children: submit }),
280
+ ],
281
+ // WebMCP, browser agents call the form as the route's tool. A form
282
+ // bound to a parameter, like a delete form in each row, would repeat
283
+ // the name, so those set the attributes themselves when they are unique
284
+ ...(tool &&
285
+ !/[:*]/.test(route.pattern) && {
286
+ toolname: tool.name,
287
+ tooldescription: tool.description,
288
+ // a form that may change data waits for the user to submit it
289
+ toolautosubmit: tool.read,
290
+ }),
107
291
  ...rest,
108
292
  });
109
293
  }),
@@ -111,68 +295,24 @@ export class Route {
111
295
  }
112
296
  /**
113
297
  * @template Pattern Route pattern
114
- * @template R Route type with Form component
115
- * @param route Route to add schema behavior to
116
- * @param schema Form schema
117
- * @returns Route with schema behavior attached
298
+ * @param pattern Route pattern
299
+ * @returns GET `Route` with added components
118
300
  */
119
- static #withSchema(route, schema) {
120
- if (!schema)
121
- return route;
122
- // original form shell from normal route
123
- const { Form } = route;
124
- return Object.assign(route, schema, {
125
- Form: (({ state, ...rest }) => Form({
126
- // add in the default children (Fields) with state and submit button
127
- children: [
128
- schema.Fields({ state }),
129
- jsx("button", { children: "Submit" }),
130
- ],
131
- state,
132
- ...rest,
133
- })),
134
- });
135
- }
136
- static get(pattern, schemaOrMiddleware, ...middleware) {
137
- let schema;
138
- if (schemaOrMiddleware) {
139
- if (typeof schemaOrMiddleware === "function") {
140
- middleware.unshift(schemaOrMiddleware);
141
- }
142
- else {
143
- schema = FormSchema.from(schemaOrMiddleware);
144
- }
145
- }
146
- const route = Route.#withComponents(new Route(Method.get, pattern, ...middleware));
147
- return Route.#withSchema(Object.assign(route, {
301
+ static get(pattern) {
302
+ const route = Route.#withComponents(new Route(Method.get, pattern));
303
+ return Object.assign(route, {
148
304
  Anchor: (({ params, search, hash, ...rest }) => jsx("a", {
149
305
  href: route.url({ params, search, hash }),
150
306
  ...rest,
151
307
  })),
152
- }), schema);
153
- }
154
- static post(patternOrSchemaOrMiddleware, schemaOrMiddleware, ...middleware) {
155
- let pattern;
156
- let schema;
157
- const resolve = (psm) => {
158
- if (psm) {
159
- if (typeof psm === "string") {
160
- pattern = psm;
161
- }
162
- else if (typeof psm !== "function") {
163
- schema = FormSchema.from(psm);
164
- }
165
- else {
166
- middleware.unshift(psm);
167
- }
168
- }
169
- };
170
- resolve(patternOrSchemaOrMiddleware);
171
- resolve(schemaOrMiddleware);
172
- if (!pattern) {
173
- // create pattern with checksum of all mw stringified
174
- pattern = `/_p/${Checksum.djb2(middleware.join())}`;
175
- }
176
- return Route.#withSchema(Route.#withComponents(new Route(Method.post, pattern, ...middleware)), schema);
308
+ });
309
+ }
310
+ /**
311
+ * @template Pattern Route pattern
312
+ * @param pattern Route pattern
313
+ * @returns POST `Route` with added components
314
+ */
315
+ static post(pattern) {
316
+ return Route.#withComponents(new Route(Method.post, pattern));
177
317
  }
178
318
  }