acrylblends 0.7.1 → 0.7.2

package/docs/framework/guides/client-modules.md

@@ -0,0 +1,175 @@
+# Client components without a bundler
+
+A page can run [client components](jsx-dom.md) written in TypeScript and JSX with no bundler and no build configuration. `clientModules` from
+`acrylblends/node-server` serves a folder of client modules to the browser: each `.tsx`, `.ts` or `.jsx` file is compiled when the browser asks
+for it, with your app's own `typescript`, and the framework's browser imports are pointed at the browser builds the package ships. The page
+needs one script tag.
+
+It runs on Node, the runtime the framework targets. For a large client app with many npm packages, a bundler (Vite, esbuild) remains the
+better tool; see [The `acrylblends/jsx/dom` runtime](jsx-dom.md#the-acrylblendsjsxdom-runtime).
+
+## Set up
+
+The routes, with the type the browser's typed client uses, in a file of their own (`app.ts`):
+
+```ts
+import { Acryl } from 'acrylblends'
+
+export const app = new Acryl()
+  .get('/', (c) =>
+    c.html(
+      '<!doctype html><div id="counter"></div><p id="greeting"></p>' +
+        '<script type="module" src="/client/counter.tsx"></script>'
+    )
+  )
+  .get('/api/hello', (c) => c.json({ hello: 'browser' }))
+
+export type AppType = typeof app
+```
+
+The Node entry routes the client modules next to them (`site.ts`):
+
+```ts
+import { Acryl } from 'acrylblends'
+import { clientModules, serve } from 'acrylblends/node-server'
+import { app } from './app.ts'
+
+const site = new Acryl()
+  .route('/', app)
+  .route('/client', clientModules({ root: 'src/client', compiled: 'dist/client' }))
+
+serve({ fetch: site.fetch, port: 3000 })
+```
+
+A client component (`src/client/counter.tsx`), with a helper module beside it (`src/client/parts/label.ts`):
+
+```tsx
+import { render, useState } from 'acrylblends/jsx/dom'
+import { hc } from 'acrylblends/client'
+import type { AppType } from '../../app.ts'
+import { label } from './parts/label.ts'
+
+const Counter = () => {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{label(count)}</button>
+}
+
+render(<Counter />, document.getElementById('counter')!)
+
+const client = hc<AppType>(location.origin)
+const { hello } = await (await client.api.hello.$get()).json()
+document.getElementById('greeting')!.textContent = `hello ${hello}`
+```
+
+```ts
+export const label = (count: number): string => `Count ${count}`
+```
+
+Start the site with `node site.ts` and open `http://localhost:3000`. Edit `counter.tsx` and reload: the module is compiled again.
+
+Your editor checks the client folder as browser code with its own `src/client/tsconfig.json`: the DOM library, the DOM renderer, no Node
+types. This is why `AppType` comes from `app.ts`, which does not import the Node adapter.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "acrylblends/jsx/dom",
+    "types": []
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}
+```
+
+## Server markup and `hydrateRoot`
+
+A page can carry server-rendered markup for an island and take it over in the browser with `hydrateRoot` from `acrylblends/jsx/dom/client`:
+
+```tsx
+import { useState } from 'acrylblends/jsx/dom'
+import { hydrateRoot } from 'acrylblends/jsx/dom/client'
+
+const Counter = () => {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>Count {count}</button>
+}
+
+hydrateRoot(document.getElementById('island')!, <Counter />)
+```
+
+The DOM renderer does not reuse server markup: `hydrateRoot` renders the component and replaces the element's children with its output
+in one step, so the page shows the server markup until the module runs and the component from then on, with no empty frame between. The
+server's nodes are gone afterwards, together with anything the visitor did to them before the module ran: focus, a selection, text typed
+into an input. Keep the server markup the same as the component's first render, so the swap does not show, and keep inputs out of the
+server markup of an island, or render them only in the browser.
+
+## How the imports reach the browser
+
+- JSX in a client module always compiles for the DOM renderer (`acrylblends/jsx/dom`), whatever the server's `tsconfig.json` says. A file's
+  own `/** @jsxImportSource ... */` comment still wins.
+- `acrylblends/jsx/dom`, its `jsx-runtime`, `jsx-dev-runtime` and `client` are one browser module (`@acrylblends/jsx-dom.js`), and
+  `acrylblends/client` is another (`@acrylblends/client.js`). Neither imports anything. The same app serves them, and each import is
+  rewritten to a URL relative to the module, so the setup works under whatever path you route `clientModules` at.
+- Import your own modules with their file names, as the browser fetches them: `import { label } from './parts/label.ts'`.
+- Another package (`import confetti from 'canvas-confetti'`) is left as it is: add an
+  [import map](https://developer.mozilla.org/docs/Web/HTML/Element/script/type/importmap) to the page for it, or use a bundler.
+- `.js` and `.mjs` files are served unchanged.
+
+A module is compiled once and kept in memory until its file changes, up to 16 MiB of compiled code (the least recently served goes first;
+set `cacheBytes` to change the bound). Responses carry an `ETag` and `Cache-Control: no-cache`, so the browser revalidates and an edit shows
+on the next reload. Only files inside the folder are served: a path with `..` or a dot segment, a `.d.ts` file, a symbolic link out of the
+folder and other file types answer 404.
+
+## In production
+
+Templates install `typescript` as a development dependency, and a deploy that leaves those out (`npm ci --omit=dev`) has no compiler.
+Compile the client folder once when you build, as the `build` script of your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "acrylblends build-client"
+  }
+}
+```
+
+`acrylblends build-client [root] [outDir]` (from acrylblends 0.7.2; `src/client` and `dist/client` when not given) calls
+`buildClientModules`. With an earlier version, or without the command line tool, call the function itself:
+
+```json
+{
+  "scripts": {
+    "build": "node --input-type=module -e \"import { buildClientModules } from 'acrylblends/node-server'; buildClientModules({ root: 'src/client', outDir: 'dist/client' })\""
+  }
+}
+```
+
+It writes each module compiled to `dist/client` at the same path and file name, so the page's URLs stay the same, and copies the two
+browser modules to `dist/client/@acrylblends/`. Run it where `typescript` is installed, before the development dependencies are removed.
+
+With `NODE_ENV=production` and the `compiled` option set, `clientModules` serves only that folder and compiles nothing. A module that is in
+`src/client` but missing from `dist/client` answers 500 with a message to build again, and a `compiled` folder that does not exist stops the
+server at startup. Outside production, modules are always compiled on request, so a stale `dist/client` never hides an edit.
+
+When `typescript` is missing where a module has to be compiled, the module answers 500 with the message
+`... is a client module, and compiling it needs the typescript package in this app: npm install --save-dev typescript`.
+
+## Reference
+
+`clientModules(options)` returns an app; route it where the page's script tags point.
+
+| Option | Meaning |
+| --- | --- |
+| `root` | The folder of client modules, absolute or relative to the working directory. |
+| `compiled` | The folder `buildClientModules` wrote. Served instead of compiling when `NODE_ENV` is `production`. |
+| `cacheBytes` | The bound of the in-memory cache of compiled modules, in bytes. 16 MiB when not given. |
+
+`buildClientModules({ root, outDir })` compiles every module below `root` (dot files, `node_modules` and `.d.ts` files skipped) into `outDir`,
+which must not lie inside `root`, and returns the paths it wrote. Files already in `outDir` that no source produces are left there.

package/docs/framework/guides/forms-and-sessions.md

@@ -228,4 +228,4 @@ export const Field = () => (
 )
 ```
 
-[Client Components](jsx-dom.md) (`acrylblends/jsx/dom`) are for pages that need components and state in the browser; they have to be bundled for the browser first (with Vite or esbuild).
+[Client Components](jsx-dom.md) (`acrylblends/jsx/dom`) are for pages that need components and state in the browser; on Node, [Client components without a bundler](client-modules.md) serves them to the browser with one script tag, or bundle them with Vite or esbuild.

package/docs/framework/guides/jsx-dom.md

@@ -2,7 +2,9 @@
 
 `acrylblends/jsx` supports not only server side but also client side. This means that it is possible to create an interactive UI that runs in the browser. We call it Client Components or `acrylblends/jsx/dom`.
 
-It is fast and very small. The counter program in `acrylblends/jsx/dom` is only 2.8KB with Brotli compression, but 47.8KB for React.
+It is small and imports nothing. Measured with Node's `zlib.brotliCompressSync` at the highest quality: the whole runtime as
+[`clientModules`](client-modules.md) serves it (`jsx-dom.js`, not minified) is 11,209 bytes with Brotli compression, and the counter
+below, bundled and minified with tsdown so only the parts it uses are kept, is 5,804 bytes.
 
 This section introduces Client Components-specific features.
 
@@ -272,6 +274,9 @@ export default function App() {
 
 ## The `acrylblends/jsx/dom` runtime
 
+On Node you can skip the bundler: [Client components without a bundler](client-modules.md) serves `.tsx` client modules to the browser with
+this runtime and one script tag, in development and in production.
+
 There is a small JSX Runtime for Client Components. Using this will result in smaller bundled results than using `acrylblends/jsx`. Specify `acrylblends/jsx/dom` in `tsconfig.json`. For Deno, modify the deno.json.
 
 ```json

package/docs/framework/guides/validation.md

@@ -144,6 +144,93 @@ app.post(
 )
 ```
 
+## Validating an HTML form
+
+A browser posts a `<form>` as `application/x-www-form-urlencoded`, or as `multipart/form-data` when it has `enctype="multipart/form-data"` (needed
+for file inputs). `validator('form', ...)` parses both. Each field arrives as a `string`, a file input as a `File`, and a name that appears more
+than once (several checkboxes, or a name ending in `[]`) as an array, so the value has the type `Record<string, string | File | (string | File)[]>`.
+
+This page shows a form and re-renders it with a message when a field is wrong:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { html } from 'acrylblends/html'
+import { validator } from 'acrylblends/validator'
+
+const page = (error?: string) => html`<!doctype html>
+  <form method="post" action="/notes" enctype="multipart/form-data">
+    <input name="title" required>
+    <textarea name="body"></textarea>
+    <input type="file" name="attachment">
+    <button>Save</button>
+    ${error === undefined ? '' : html`<p role="alert">${error}</p>`}
+  </form>`
+
+const app = new Acryl()
+  .get('/notes/new', (c) => c.html(page()))
+  .post(
+    '/notes',
+    validator('form', (form, c) => {
+      const { title, body, attachment } = form
+      if (typeof title !== 'string' || title.trim() === '') return c.html(page('Title is required'), 400)
+      if (body !== undefined && typeof body !== 'string') return c.html(page('Body must be text'), 400)
+      if (attachment !== undefined && !(attachment instanceof File)) return c.html(page('Attachment must be one file'), 400)
+      return {
+        title: title.trim(),
+        body: body ?? '',
+        // A file input left empty still sends a part: a File with no name and no bytes.
+        attachment: attachment !== undefined && attachment.size > 0 ? attachment : undefined,
+      }
+    }),
+    (c) => {
+      const { title, attachment } = c.req.valid('form') // { title: string, body: string, attachment: File | undefined }
+      return c.text(`Saved ${title}${attachment === undefined ? '' : ` with ${attachment.name}`}`, 201)
+    }
+  )
+```
+
+The messages are escaped by `html`, so a field value shown back in the page cannot inject markup.
+
+### With a schema
+
+`schemaValidator('form', schema)` takes the same value. It answers a failure with 400 and JSON issues, which suits a form your own script submits
+with `fetch()`:
+
+```ts
+import * as z from 'zod'
+import { schemaValidator } from 'acrylblends/schema-validator'
+
+const NoteForm = z.object({
+  title: z.string().trim().min(1, 'Title is required'),
+  body: z.string().default(''),
+  attachment: z.instanceof(File).optional(),
+})
+
+app.post('/api/notes', schemaValidator('form', NoteForm), (c) => {
+  const { title } = c.req.valid('form') // typed by the schema's output
+  return c.json({ title }, 201)
+})
+```
+
+For a plain HTML form, call the schema inside `validator('form', ...)` to re-render the page with the first message instead:
+
+```ts
+validator('form', (form, c) => {
+  const result = NoteForm.safeParse(form)
+  return result.success ? result.data : c.html(page(result.error.issues[0]?.message), 400)
+})
+```
+
+To test a form route, send a `FormData`: `app.request` sets the `multipart/form-data` content type with its boundary itself.
+
+```ts
+const form = new FormData()
+form.set('title', 'Groceries')
+form.set('attachment', new File(['milk'], 'list.txt', { type: 'text/plain' }))
+const res = await app.request('/notes', { method: 'POST', body: form })
+// res.status === 201, await res.text() === 'Saved Groceries with list.txt'
+```
+
 ## Multiple validators
 
 You can also include multiple validators to validate different parts of request:

package/docs/framework/helpers/testing.md

@@ -99,3 +99,20 @@ describe('Search Endpoint', () => {
   })
 })
 ```
+
+### Default request options
+
+`testClient(app, env?, executionCtx?, options?)` takes the client's request options as its fourth argument, so headers every request of a test
+needs, such as a session cookie, are set once. Headers given to a single call are merged over them.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getCookie } from 'acrylblends/cookie'
+import { testClient } from 'acrylblends/testing'
+
+const app = new Acryl().get('/me', (c) => c.json({ session: getCookie(c, 'session') ?? null }))
+
+const client = testClient(app, undefined, undefined, { headers: { cookie: 'session=abc' } })
+await (await client.me.$get()).json() // { session: 'abc' }
+await (await client.me.$get(undefined, { headers: { cookie: 'session=xyz' } })).json() // { session: 'xyz' }
+```

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "524406d2033cdc5ca5e01207f9ce29543bbf221b"
+    "commit": "cdc083e1bbaedaeafa7494fe646bdb202ce86d09"
   },
-  "files": 89,
-  "digest": "sha256:fe2da945c3286e316a0412b2d3cfccc4dbf8d1c082e283b77606b45e27b778aa"
+  "files": 91,
+  "digest": "sha256:964e5ff58d487ce53394469d359a251265a3ef093354f55b6b4c47c55051774b"
 }

package/lib/browser/client.js

@@ -0,0 +1,307 @@
+//#region ../../plugins/acryl-router/src/core/utils/cookie.ts
+const validCookieNameRegEx = /^[\w!#$%&'*.^`|~+-]+$/;
+const _serialize = (name, value, opt = {}) => {
+	if (!validCookieNameRegEx.test(name)) throw new Error("Invalid cookie name");
+	let cookie = `${name}=${value}`;
+	if (name.startsWith("__Secure-") && !opt.secure) throw new Error("__Secure- Cookie must have Secure attributes");
+	if (name.startsWith("__Host-")) {
+		if (!opt.secure) throw new Error("__Host- Cookie must have Secure attributes");
+		if (opt.path !== "/") throw new Error("__Host- Cookie must have Path attributes with \"/\"");
+		if (opt.domain) throw new Error("__Host- Cookie must not have Domain attributes");
+	}
+	for (const key of [
+		"domain",
+		"path",
+		"sameSite",
+		"priority"
+	]) if (opt[key] && /[;\r\n]/.test(opt[key])) throw new Error(`${key} must not contain ";", "\\r", or "\\n"`);
+	if (opt && typeof opt.maxAge === "number" && opt.maxAge >= 0) {
+		if (opt.maxAge > 3456e4) throw new Error("Cookies Max-Age SHOULD NOT be greater than 400 days (34560000 seconds) in duration.");
+		cookie += `; Max-Age=${opt.maxAge | 0}`;
+	}
+	if (opt.domain && opt.prefix !== "host") cookie += `; Domain=${opt.domain}`;
+	if (opt.path) cookie += `; Path=${opt.path}`;
+	if (opt.expires) {
+		if (opt.expires.getTime() - Date.now() > 3456e7) throw new Error("Cookies Expires SHOULD NOT be greater than 400 days (34560000 seconds) in the future.");
+		cookie += `; Expires=${opt.expires.toUTCString()}`;
+	}
+	if (opt.httpOnly) cookie += "; HttpOnly";
+	if (opt.secure) cookie += "; Secure";
+	if (opt.sameSite) cookie += `; SameSite=${opt.sameSite.charAt(0).toUpperCase() + opt.sameSite.slice(1)}`;
+	if (opt.priority) cookie += `; Priority=${opt.priority.charAt(0).toUpperCase() + opt.priority.slice(1)}`;
+	if (opt.partitioned) {
+		if (!opt.secure) throw new Error("Partitioned Cookie must have Secure attributes");
+		cookie += "; Partitioned";
+	}
+	return cookie;
+};
+const serialize = (name, value, opt) => {
+	value = encodeURIComponent(value);
+	return _serialize(name, value, opt);
+};
+//#endregion
+//#region ../../plugins/acryl-router/src/core/client/fetch-result-please.ts
+/**
+* @description This file is a modified version of `fetch-result-please` (`ofetch`), minimalized and adapted to Acryl's custom needs.
+*
+* @link https://www.npmjs.com/package/fetch-result-please
+*/
+const nullBodyResponses = /* @__PURE__ */ new Set([
+	101,
+	204,
+	205,
+	304
+]);
+/**
+* Smartly parses and return the consumable result from a fetch `Response`.
+*
+* Throwing a structured error if the response is not `ok`. ({@link DetailedError})
+*/
+async function fetchRP(fetchRes) {
+	const _fetchRes = await fetchRes;
+	if ((_fetchRes.body || _fetchRes._bodyInit) && !nullBodyResponses.has(_fetchRes.status)) _fetchRes._data = await _fetchRes[detectResponseType(_fetchRes)]();
+	if (!_fetchRes.ok) throw new DetailedError(`${_fetchRes.status} ${_fetchRes.statusText}`, {
+		statusCode: _fetchRes?.status,
+		detail: {
+			data: _fetchRes?._data,
+			statusText: _fetchRes?.statusText
+		}
+	});
+	return _fetchRes._data;
+}
+var DetailedError = class extends Error {
+	/**
+	* Additional `message` that will be logged AND returned to client
+	*/
+	detail;
+	/**
+	* Additional `code` that will be logged AND returned to client
+	*/
+	code;
+	/**
+	* Additional value that will be logged AND NOT returned to client
+	*/
+	log;
+	/**
+	* Optionally set the status code to return, in a web server context
+	*/
+	statusCode;
+	constructor(message, options = {}) {
+		super(message);
+		this.name = "DetailedError";
+		this.log = options.log;
+		this.detail = options.detail;
+		this.code = options.code;
+		this.statusCode = options.statusCode;
+	}
+};
+const jsonRegex = /^application\/(?:[\w!#$%&*.^`~-]*\+)?json(?:;.+)?$/i;
+function detectResponseType(response) {
+	const _contentType = response.headers.get("content-type");
+	if (!_contentType) return "text";
+	const contentType = _contentType.split(";").shift();
+	if (jsonRegex.test(contentType)) return "json";
+	return "text";
+}
+//#endregion
+//#region ../../plugins/acryl-router/src/core/client/utils.ts
+const mergePath = (base, path) => {
+	base = base.replace(/\/+$/, "");
+	base = base + "/";
+	path = path.replace(/^\/+/, "");
+	return base + path;
+};
+const replaceUrlParam = (urlString, params) => {
+	for (const [k, v] of Object.entries(params)) {
+		const reg = new RegExp("/:" + k + "(?:{[^/]+})?\\??(?=/|$)");
+		urlString = urlString.replace(reg, () => v ? `/${v}` : "");
+	}
+	return urlString;
+};
+const buildSearchParams = (query) => {
+	const searchParams = new URLSearchParams();
+	for (const [k, v] of Object.entries(query)) {
+		if (v === void 0) continue;
+		if (Array.isArray(v)) for (const v2 of v) {
+			if (v2 === void 0) continue;
+			searchParams.append(k, v2);
+		}
+		else searchParams.set(k, v);
+	}
+	return searchParams;
+};
+const replaceUrlProtocol = (urlString, protocol) => {
+	switch (protocol) {
+		case "ws": return urlString.replace(/^http/, "ws");
+		case "http": return urlString.replace(/^ws/, "http");
+	}
+};
+const removeIndexString = (urlString) => {
+	if (/^https?:\/\/[^\/]+?\/index(?=\?|$)/.test(urlString)) return urlString.replace(/\/index(?=\?|$)/, "/");
+	return urlString.replace(/\/index(?=\?|$)/, "");
+};
+function isObject(item) {
+	return typeof item === "object" && item !== null && !Array.isArray(item);
+}
+function deepMerge(target, source) {
+	if (!isObject(target) && !isObject(source)) return source;
+	const merged = { ...target };
+	for (const key in source) {
+		const value = source[key];
+		if (isObject(merged[key]) && isObject(value)) merged[key] = deepMerge(merged[key], value);
+		else merged[key] = value;
+	}
+	return merged;
+}
+/**
+* Shortcut to get a consumable response from `hc`'s fetch calls (Response), with types inference.
+*
+* Smartly parse the response data, throwing a structured error if the response is not `ok`. ({@link DetailedError})
+*
+* @example const result = await parseResponse(client.posts.$get())
+*/
+async function parseResponse(fetchRes) {
+	return fetchRP(fetchRes);
+}
+//#endregion
+//#region ../../plugins/acryl-router/src/core/client/client.ts
+const createProxy = (callback, path) => {
+	return new Proxy(() => {}, {
+		get(_obj, key) {
+			if (typeof key !== "string" || key === "then") return;
+			return createProxy(callback, [...path, key]);
+		},
+		apply(_1, _2, args) {
+			return callback({
+				path,
+				args
+			});
+		}
+	});
+};
+const appendQueryParams = (url, searchParams) => {
+	const queryString = searchParams.toString();
+	return queryString ? `${url}?${queryString}` : url;
+};
+var ClientRequestImpl = class {
+	url;
+	method;
+	buildSearchParams;
+	queryParams = void 0;
+	pathParams = {};
+	rBody;
+	cType = void 0;
+	constructor(url, method, options) {
+		this.url = url;
+		this.method = method;
+		this.buildSearchParams = options.buildSearchParams;
+	}
+	fetch = async (args, opt) => {
+		if (args) {
+			if (args.query) this.queryParams = this.buildSearchParams(args.query);
+			if (args.form) {
+				const form = new FormData();
+				for (const [k, v] of Object.entries(args.form)) {
+					if (v === void 0) continue;
+					if (Array.isArray(v)) for (const v2 of v) {
+						if (v2 === void 0) continue;
+						form.append(k, v2);
+					}
+					else form.append(k, v);
+				}
+				this.rBody = form;
+			}
+			if (args.json !== void 0) {
+				this.rBody = JSON.stringify(args.json);
+				this.cType = "application/json";
+			}
+			if (args.param) this.pathParams = args.param;
+		}
+		let methodUpperCase = this.method.toUpperCase();
+		const headerValues = {
+			...args?.header,
+			...typeof opt?.headers === "function" ? await opt.headers() : opt?.headers
+		};
+		if (args?.cookie) {
+			const cookies = [];
+			for (const [key, value] of Object.entries(args.cookie)) {
+				if (value === void 0) continue;
+				cookies.push(serialize(key, value));
+			}
+			if (cookies.length > 0) headerValues["Cookie"] = cookies.join("; ");
+		}
+		if (this.cType) headerValues["Content-Type"] = this.cType;
+		const headers = new Headers();
+		for (const [key, value] of Object.entries(headerValues)) if (value !== void 0) headers.set(key, value);
+		let url = this.url;
+		url = removeIndexString(url);
+		url = replaceUrlParam(url, this.pathParams);
+		if (this.queryParams) url = appendQueryParams(url, this.queryParams);
+		methodUpperCase = this.method.toUpperCase();
+		const setBody = !(methodUpperCase === "GET" || methodUpperCase === "HEAD");
+		return (opt?.fetch || fetch)(url, {
+			body: setBody ? this.rBody : void 0,
+			method: methodUpperCase,
+			headers,
+			...opt?.init
+		});
+	};
+};
+const hc = (baseUrl, options) => createProxy(function proxyCallback(opts) {
+	const buildSearchParamsOption = options?.buildSearchParams ?? buildSearchParams;
+	const parts = [...opts.path];
+	const lastParts = parts.slice(-3).reverse();
+	if (lastParts[0] === "toString") {
+		if (lastParts[1] === "name") return lastParts[2] || "";
+		return proxyCallback.toString();
+	}
+	if (lastParts[0] === "valueOf") {
+		if (lastParts[1] === "name") return lastParts[2] || "";
+		return proxyCallback;
+	}
+	let method = "";
+	if (/^\$/.test(lastParts[0])) {
+		const last = parts.pop();
+		if (last) method = last.replace(/^\$/, "");
+	}
+	const url = mergePath(baseUrl, parts.join("/"));
+	if (method === "url" || method === "path") {
+		let result = removeIndexString(url);
+		if (opts.args[0]) {
+			if (opts.args[0].param) result = replaceUrlParam(result, opts.args[0].param);
+			if (opts.args[0].query) result = appendQueryParams(result, buildSearchParamsOption(opts.args[0].query));
+		}
+		if (method === "url") return new URL(result);
+		return result.slice(baseUrl.replace(/\/+$/, "").length).replace(/^\/?/, "/");
+	}
+	if (method === "ws") {
+		const normalizedUrl = removeIndexString(url);
+		const webSocketUrl = replaceUrlProtocol(opts.args[0]?.param ? replaceUrlParam(normalizedUrl, opts.args[0].param) : normalizedUrl, "ws");
+		const targetUrl = new URL(webSocketUrl);
+		const queryParams = opts.args[0]?.query;
+		if (queryParams) buildSearchParamsOption(queryParams).forEach((value, key) => {
+			targetUrl.searchParams.append(key, value);
+		});
+		const establishWebSocket = (...args) => {
+			if (options?.webSocket !== void 0 && typeof options.webSocket === "function") return options.webSocket(...args);
+			return new WebSocket(...args);
+		};
+		return establishWebSocket(targetUrl.toString());
+	}
+	const req = new ClientRequestImpl(url, method, { buildSearchParams: buildSearchParamsOption });
+	if (method) {
+		options ??= {};
+		const reqOptions = { ...opts.args[1] };
+		const baseHeaders = options.headers;
+		const reqHeaders = reqOptions.headers;
+		if (baseHeaders && reqHeaders) reqOptions.headers = async () => ({
+			...typeof baseHeaders === "function" ? await baseHeaders() : baseHeaders,
+			...typeof reqHeaders === "function" ? await reqHeaders() : reqHeaders
+		});
+		const args = deepMerge(options, reqOptions);
+		return req.fetch(opts.args[0], args);
+	}
+	return req;
+}, []);
+//#endregion
+export { DetailedError, hc, parseResponse };