Tests

\n \n \n ({prettyMilliseconds(\n Object.values(outputs).flat().reduce(\n (sum, output) => sum + output.duration,\n 0,\n ),\n )})\n \n

\n {testGroups.map((group: TestGroup) => {\n return (\n

\n output.pass).length}\n testCount={group.tests.length}\n />\n \n ({prettyMilliseconds(\n outputs[group.name].reduce(\n (sum, output) => sum + output.duration,\n 0,\n ),\n )})\n \n

\n\n {outputs[group.name].map((\n output: TestOutput,\n index: number,\n ) => (\n

\n \n {output.message && (\n {output.message}\n )}\n \n ({prettyMilliseconds(output.duration)})\n \n

\n \n {`${output.pass ? \"✓\" : \"✗\"} ${output.duration.toFixed(3)}ms`}\n \n

\n ))}\n

\n );\n })}\n

\n \n \n ,\n );\n}\n\n/**\n * Creates a test runner that displays test results as an HTML page with badges and detailed output.\n *\n * @param testGroups - Array of `{ name, tests, before?, after? }` objects. Each test is `{ name, function }` — throw to fail, return to pass.\n * @returns A `(req: Request) => Promise` handler. Returns an HTML results page, or an SVG badge at `/badge.svg`.\n *\n * @example\n * ```ts\n * import { testServer } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * const myTests = [{\n * name: \"Math tests\",\n * tests: [\n * { name: \"addition\", function: () => { if (1 + 1 !== 2) throw new Error(\"Math is broken\"); } },\n * { name: \"subtraction\", function: () => { if (5 - 3 !== 2) throw new Error(\"Wrong result\"); } }\n * ]\n * }];\n *\n * export default testServer(myTests);\n * ```\n */\nexport const testServer = (testGroups: TestGroup[]) => async (req: Request) => {\n const url = new URL(req.url);\n const outputs: { [groupName: string]: TestOutput[] } = {};\n\n for (const group of testGroups) {\n group.before?.();\n outputs[group.name] = await Promise.all(group.tests.map(runTest));\n group.after?.();\n }\n\n if (url.pathname === \"/badge.svg\") {\n const totalPassed =\n Object.values(outputs).flat().filter((output: TestOutput) => output.pass)\n .length;\n const totalTests = testGroups.reduce(\n (sum, group) => sum + group.tests.length,\n 0,\n );\n\n return new Response(\n renderBadge({\n label: \"Tests\",\n passedCount: totalPassed,\n testCount: totalTests,\n }),\n {\n headers: {\n \"content-type\": \"image/svg+xml;charset=UTF-8\",\n },\n },\n );\n }\n return new Response(renderTestResults(testGroups, outputs), {\n headers: {\n \"content-type\": \"text/html;charset=UTF-8\",\n },\n });\n};","deleted","label",[141],"5b39c48d-5391-4a20-afb5-a95bea6aa006","static.tsx","019f3942-6872-71dc-8b70-6386ef7578b3",["D",1783372081272],"import { parseVal } from \"./parseImportMeta.ts\";\nimport { serveFile } from \"./serve-file.ts\";\n\n/** A fetch-standard handler. Return a `Response` to handle the request, or `null`/`undefined` to defer to the static server. */\ntype FetchHandler = (\n request: Request,\n) =>\n | Response\n | null\n | undefined\n | Promise;\n\n/**\n * Creates a simple static HTTP server that serves HTML, CSS, and JS files from your val.\n *\n * This is the easiest way to deploy a static site or single-page app on Val Town: drop\n * an `index.html` (plus any CSS/JS/assets) into your val and `export default staticHTTPServer()`.\n *\n * The server automatically serves `/index.html` for root requests and handles all other file paths.\n * It also exposes a `/source` route that redirects to the val's source code on Val Town, so visitors\n * can always click through to view how a page was built.\n *\n * If you need a little custom routing (an API route, a redirect) but mostly want a static\n * server, pass a fetch handler as the second argument. It's tried first on every request:\n * return a `Response` to handle the request yourself, or return `null`/`undefined` to fall\n * through to the static server (and the `/source` redirect). This is just the fetch standard —\n * pass a plain function, or any framework's handler (e.g. Hono's `app.fetch`). See the second example.\n *\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to serve files from. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @param handler - Optional. A fetch handler `(request: Request) => Response | null | undefined` (or a promise thereof). Tried before static serving: return a `Response` to handle the request, or `null`/`undefined` to defer to the static server and the `/source` redirect. Pass a plain function or any framework's fetch handler (e.g. Hono's `app.fetch`).\n * @returns A fetch-compatible handler function `(request: Request) => Response | Promise` that serves static files with correct Content-Type headers. Returns 404 for missing files.\n *\n * @example\n * ```ts\n * import { staticHTTPServer } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // Most common usage - serves files from current val, plus a /source redirect\n * export default staticHTTPServer();\n *\n * // Explicit val specification\n * export default staticHTTPServer(import.meta.url);\n * ```\n *\n * @example\n * ```ts\n * // Mostly static, but with a bit of custom routing.\n * // Pass a fetch handler: return a Response to handle a request,\n * // or null/undefined to fall through to static file serving.\n * import { staticHTTPServer } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * export default staticHTTPServer(import.meta.url, (req) => {\n * const { pathname } = new URL(req.url);\n * if (pathname === \"/api/hello\") return Response.json({ hello: \"world\" });\n * return null; // defer to the static server (index.html / assets / /source)\n * });\n * ```\n *\n * @example\n * ```ts\n * // Any framework works too, since app.fetch is just a fetch handler.\n * import { Hono } from \"npm:hono@4.11.9\";\n * import { staticHTTPServer } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * const app = new Hono();\n * app.get(\"/api/hello\", (c) => c.json({ hello: \"world\" }));\n * // Return 404s as null so unmatched routes fall through to the static server.\n * app.notFound(() => null as any);\n *\n * export default staticHTTPServer(import.meta.url, app.fetch);\n * ```\n */\nexport function staticHTTPServer(\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n handler?: FetchHandler,\n): (request: Request) => Promise {\n const serve = async (path: string) => {\n try {\n return await serveFile(path, metaImportUrl);\n } catch (error) {\n if (error.message.includes(\"File not found\")) {\n return new Response(`File not found: ${path}`, { status: 404 });\n }\n throw error;\n }\n };\n\n return async (request: Request): Promise => {\n // Give the custom handler first crack at the request. A Response wins;\n // null/undefined means \"not handled\" and falls through to static serving.\n if (handler) {\n const handled = await handler(request);\n if (handled instanceof Response) return handled;\n }\n\n const { pathname } = new URL(request.url);\n\n // Redirect to the val's source code on Val Town.\n if (pathname === \"/source\") {\n return new Response(null, {\n status: 302,\n headers: { Location: parseVal(metaImportUrl).links.self.val },\n });\n }\n\n return await serve(pathname === \"/\" ? \"/index.html\" : pathname);\n };\n}",[158],"e2cec9b4-de22-4562-a0c5-bba6f4380342","static.test.ts","019f3942-6872-71dc-8b70-5f8b46a49acb",["D",1783372081272],"http","import { expect } from \"jsr:@std/expect\";\nimport { testServer } from \"./test.tsx\";\nimport { staticHTTPServer } from \"./static.tsx\";\nimport { parseVal } from \"./parseImportMeta.ts\";\n\nexport const staticTests = [\n {\n name: \"staticHTTPServer Tests\",\n sourceFile: \"static.tsx\",\n tests: [\n {\n name: \" return a function\",\n function: () => {\n const server = staticHTTPServer(import.meta.url);\n expect(typeof server).toBe(\"function\");\n },\n },\n {\n name: \"root path request\",\n function: async () => {\n const server = staticHTTPServer(import.meta.url);\n const request = new Request(\"https://example.com/\");\n\n const response = await server(request);\n expect(response).toBeInstanceOf(Response);\n // No index.html exists in this val, so we expect a 404\n expect(response.status).toBe(404);\n },\n },\n {\n name: \"root req w/op import.meta.url\",\n function: async () => {\n const server = staticHTTPServer();\n const request = new Request(\"https://example.com/\");\n\n const response = await server(request);\n expect(response).toBeInstanceOf(Response);\n // No index.html exists in this val, so we expect a 404\n expect(response.status).toBe(404);\n },\n },\n {\n name: \"file path requests\",\n function: async () => {\n const server = staticHTTPServer(import.meta.url);\n const request = new Request(\"https://example.com/README.md\");\n\n const response = await server(request);\n expect(response).toBeInstanceOf(Response);\n expect(response.headers.get(\"Content-Type\")).toBe(\n \"text/markdown; charset=utf-8\",\n );\n\n const content = await response.text();\n expect(typeof content).toBe(\"string\");\n expect(content.length).toBeGreaterThan(0);\n },\n },\n {\n name: \"nested path requests\",\n function: async () => {\n const server = staticHTTPServer(import.meta.url);\n const request = new Request(\"https://example.com/test.tsx\");\n\n const response = await server(request);\n expect(response).toBeInstanceOf(Response);\n expect(response.headers.get(\"Content-Type\")).toBe(\"text/javascript\");\n\n const content = await response.text();\n expect(content).toContain(\"testServer\");\n },\n },\n {\n name: \"non-existent file returns 404\",\n function: async () => {\n const server = staticHTTPServer(import.meta.url);\n const request = new Request(\n \"https://example.com/non-existent-file.txt\",\n );\n\n const response = await server(request);\n expect(response).toBeInstanceOf(Response);\n expect(response.status).toBe(404);\n const text = await response.text();\n expect(text).toContain(\"not found\");\n },\n },\n {\n name: \"/source redirects to the val's source\",\n function: async () => {\n const server = staticHTTPServer(import.meta.url);\n const request = new Request(\"https://example.com/source\");\n\n const response = await server(request);\n expect(response).toBeInstanceOf(Response);\n expect(response.status).toBe(302);\n expect(response.headers.get(\"Location\")).toBe(\n parseVal(import.meta.url).links.self.val,\n );\n },\n },\n {\n name: \"custom fetch handler takes precedence over static serving\",\n function: async () => {\n // A plain fetch handler: return a Response to handle, null to defer.\n const handler = (req: Request) => {\n const { pathname } = new URL(req.url);\n if (pathname === \"/api/hello\") {\n return Response.json({ hello: \"world\" });\n }\n return null;\n };\n const server = staticHTTPServer(import.meta.url, handler);\n\n // Custom handler wins\n const apiResponse = await server(\n new Request(\"https://example.com/api/hello\"),\n );\n expect(apiResponse.status).toBe(200);\n expect(await apiResponse.json()).toEqual({ hello: \"world\" });\n\n // Static serving still works as a fallback (handler returned null)\n const fileResponse = await server(\n new Request(\"https://example.com/README.md\"),\n );\n expect(fileResponse.headers.get(\"Content-Type\")).toBe(\n \"text/markdown; charset=utf-8\",\n );\n\n // The built-in /source redirect still works as a fallback\n const sourceResponse = await server(\n new Request(\"https://example.com/source\"),\n );\n expect(sourceResponse.status).toBe(302);\n },\n },\n {\n name: \"handler returning undefined falls through to static serving\",\n function: async () => {\n // Handler that never handles anything (always defers).\n const server = staticHTTPServer(import.meta.url, () => undefined);\n\n const response = await server(\n new Request(\"https://example.com/README.md\"),\n );\n expect(response.headers.get(\"Content-Type\")).toBe(\n \"text/markdown; charset=utf-8\",\n );\n },\n },\n {\n name: \"async fetch handler is awaited\",\n function: async () => {\n const handler = async (req: Request) => {\n const { pathname } = new URL(req.url);\n if (pathname === \"/async\") return new Response(\"async!\");\n return null;\n };\n const server = staticHTTPServer(import.meta.url, handler);\n\n const response = await server(new Request(\"https://example.com/async\"));\n expect(response.status).toBe(200);\n expect(await response.text()).toBe(\"async!\");\n },\n },\n ],\n },\n];\n\nexport default testServer(staticTests);\n",[164],"b46c51fd-28ae-49e7-a3d3-e1618438104a","serve-file.ts","019f3942-6872-71dc-8b70-58f9aa5e7f09",["D",1783372081272],"import { contentType } from \"npm:mime-types@2.1.35\";\nimport { readFileTranspiled } from \"./file.ts\";\n\n/**\n * Serves a file from the val as an HTTP Response with the correct Content-Type header.\n *\n * @param path - The file path to serve\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to serve from. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to an HTTP Response with the file content and appropriate Content-Type header\n *\n * @example\n * ```ts\n * import { serveFile } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // In a Hono app - most common usage\n * app.get(\"/assets/*\", async (c) => {\n * return await serveFile(c.req.path);\n * });\n *\n * // Explicit val specification\n * app.get(\"/assets/*\", async (c) => {\n * return await serveFile(c.req.path, import.meta.url);\n * });\n * ```\n */\nexport async function serveFile(\n path: string,\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n const text = await readFileTranspiled(path, metaImportUrl);\n const content_type = getContentType(path);\n return new Response(text, {\n headers: {\n \"Content-Type\": content_type,\n },\n });\n}\n\n/**\n * Determines the appropriate MIME type for a file based on its extension.\n *\n * @param path - The file path to get the content type for\n * @returns The MIME type string (e.g., \"text/html\", \"application/json\")\n *\n * @example\n * ```ts\n * import { getContentType } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * console.log(getContentType(\"index.html\")); // \"text/html; charset=utf-8\"\n * console.log(getContentType(\"script.ts\")); // \"text/javascript\"\n * console.log(getContentType(\"data.json\")); // \"application/json; charset=utf-8\"\n * ```\n */\nexport function getContentType(path: string): string {\n if (path.endsWith(\".ts\") || path.endsWith(\".jsx\") || path.endsWith(\".tsx\")) {\n return \"text/javascript\";\n }\n const ext = path.split(\".\").pop();\n return contentType(ext) || \"application/octet-stream\";\n}\n",[171],"4afebbb6-bb28-4186-9776-d20d4c8f13be","serve-file.test.ts","019f3942-6872-71dc-8b70-54ffeda0803f",["D",1783372081272],"import { expect } from \"jsr:@std/expect\";\nimport { testServer } from \"./test.tsx\";\nimport { getContentType, serveFile } from \"./serve-file.ts\";\n\nexport const serveFileTests = [\n {\n name: \"getContentType Tests\",\n sourceFile: \"serve-file.ts\",\n tests: [\n {\n name: \"text/javascript for TypeScript files\",\n function: () => {\n expect(getContentType(\"test.ts\")).toBe(\"text/javascript\");\n expect(getContentType(\"component.tsx\")).toBe(\"text/javascript\");\n expect(getContentType(\"module.jsx\")).toBe(\"text/javascript\");\n },\n },\n {\n name: \"common file extensions\",\n function: () => {\n expect(getContentType(\"index.html\")).toBe(\"text/html; charset=utf-8\");\n expect(getContentType(\"styles.css\")).toBe(\"text/css; charset=utf-8\");\n expect(getContentType(\"script.js\")).toBe(\n \"application/javascript; charset=utf-8\",\n );\n expect(getContentType(\"data.json\")).toBe(\n \"application/json; charset=utf-8\",\n );\n expect(getContentType(\"image.png\")).toBe(\"image/png\");\n expect(getContentType(\"document.pdf\")).toBe(\"application/pdf\");\n },\n },\n {\n name: \"octet-stream for unknown extensions\",\n function: () => {\n expect(getContentType(\"file.unknown\")).toBe(\n \"application/octet-stream\",\n );\n expect(getContentType(\"noextension\")).toBe(\n \"application/octet-stream\",\n );\n },\n },\n {\n name: \" handle files with multiple dots\",\n function: () => {\n expect(getContentType(\"file.min.js\")).toBe(\n \"application/javascript; charset=utf-8\",\n );\n expect(getContentType(\"component.test.ts\")).toBe(\"text/javascript\");\n expect(getContentType(\"data.backup.json\")).toBe(\n \"application/json; charset=utf-8\",\n );\n },\n },\n ],\n },\n {\n name: \"serveFile Tests\",\n sourceFile: \"serve-file.ts\",\n tests: [\n {\n name: \"correct content type\",\n function: async () => {\n const hasToken = !!Deno.env.get(\"valtown\");\n if (!hasToken) {\n return; // Skip if no token\n }\n\n const response = await serveFile(\"/README.md\", import.meta.url);\n expect(response).toBeInstanceOf(Response);\n expect(response.headers.get(\"Content-Type\")).toBe(\n \"text/markdown; charset=utf-8\",\n );\n\n const content = await response.text();\n expect(typeof content).toBe(\"string\");\n expect(content.length).toBeGreaterThan(0);\n },\n },\n {\n name: \"serve TypeScript files as JavaScript\",\n function: async () => {\n const hasToken = !!Deno.env.get(\"valtown\");\n if (!hasToken) {\n return; // Skip if no token\n }\n\n const response = await serveFile(\"/index.ts\", import.meta.url);\n expect(response.headers.get(\"Content-Type\")).toBe(\"text/javascript\");\n\n const content = await response.text();\n expect(content).toContain(\"export\");\n },\n },\n {\n name: \"errors gracefully\",\n function: async () => {\n const hasToken = !!Deno.env.get(\"valtown\");\n if (!hasToken) {\n return; // Skip if no token\n }\n\n // This should throw an error which will be caught by the test framework\n await expect(serveFile(\"/non-existent-file.txt\", import.meta.url))\n .rejects.toThrow(\"File not found\");\n },\n },\n {\n name: \" work with default metaImportUrl parameter\",\n function: async () => {\n const hasToken = !!Deno.env.get(\"valtown\");\n if (!hasToken) {\n return; // Skip if no token\n }\n\n // Test serving file with default parameter\n const response = await serveFile(\"/README.md\");\n expect(response).toBeInstanceOf(Response);\n expect(response.headers.get(\"Content-Type\")).toBe(\n \"text/markdown; charset=utf-8\",\n );\n\n const content = await response.text();\n expect(typeof content).toBe(\"string\");\n expect(content.length).toBeGreaterThan(0);\n },\n },\n ],\n },\n];\n\nexport default testServer(serveFileTests);",[177],"3c75fddb-5293-4f0d-9766-dfba41c4b1f4","parseImportMeta.ts","019f3942-6872-71dc-8b70-5290e427476d",["D",1783372081272],"interface Val {\n username: string;\n name: string;\n version: string;\n branch: string;\n path: string;\n links: {\n self: {\n latest: string;\n pinned: string;\n val: string;\n };\n module: {\n latest: string;\n pinned: string;\n val: string;\n valPinned: string;\n };\n };\n}\n\n/**\n * Parses Val Town metadata from an import.meta.url.\n *\n * @param metaImportUrl - Optional. The import.meta.url to parse. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns A `Val` object with `username`, `name`, `version`, `branch`, `path`, and `links` (containing `self` and `module` URL variants)\n *\n * @example\n * ```ts\n * import { parseVal } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * const val = parseVal(import.meta.url);\n * console.log(val);\n * // Output: { username: \"username\", name: \"valname\", version: \"1\", branch: \"main\", path: \"\", links: {...} }\n * ```\n */\nexport function parseVal(metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\"): Val {\n // Updated pattern to capture the prefix (v or p) and handle URL format variations\n const pattern =\n /^https:\\/\\/esm\\.town\\/(v|p)\\/([^/]+)\\/([^@]+)@(\\d+)-(.+?)(\\/.*)?$/;\n const match = metaImportUrl.match(pattern);\n\n if (!match) {\n throw new Error(`Invalid ESM Town URL format: ${metaImportUrl}`);\n }\n\n let [, prefix, username, name, version, branch, path = \"\"] = match;\n // Remove leading slash if present\n path = path && path.startsWith(\"/\") ? path.substring(1) : path;\n\n const branchPath = branch === \"main\" ? \"\" : `/branch/${branch}`;\n\n const valURL = `https://www.val.town/x/${username}/${name}`;\n\n return {\n username,\n name,\n version,\n branch,\n path,\n links: {\n self: {\n latest: `${valURL}${branchPath}/code/${path}`,\n pinned: `${valURL}/branch/${branch}/version/${version}/code/${path}`,\n val: valURL,\n },\n module: {\n latest:\n `https://esm.town/${prefix}/${username}/${name}${branchPath}/${path}`,\n pinned:\n `https://esm.town/${prefix}/${username}/${name}@${version}-${branch}/${path}`,\n val: `https://esm.town/${prefix}/${username}/${name}/`,\n valPinned:\n `https://esm.town/${prefix}/${username}/${name}@${version}-${branch}/`,\n },\n },\n };\n}\n",[183],"96fedad8-cf1c-44d1-abfa-211d61891ee8","parseImportMeta.test.ts","019f3942-6872-71dc-8b70-4ea580afb66b",["D",1783372081272],"import { expect } from \"jsr:@std/expect\";\nimport { testServer } from \"./test.tsx\";\nimport { parseVal } from \"./parseImportMeta.ts\";\n\nexport const parseValTests = [\n {\n name: \"parseVal Tests\",\n sourceFile: \"parseImportMeta.ts\",\n tests: [\n {\n name: \"val on main branch\",\n function: () => {\n const input = \"https://esm.town/v/maxm/queue@11-main/runMigrations\";\n const expected = {\n username: \"maxm\",\n name: \"queue\",\n version: \"11\",\n branch: \"main\",\n path: \"runMigrations\",\n links: {\n self: {\n latest: \"https://www.val.town/x/maxm/queue/code/runMigrations\",\n pinned:\n \"https://www.val.town/x/maxm/queue/branch/main/version/11/code/runMigrations\",\n val: \"https://www.val.town/x/maxm/queue\",\n },\n module: {\n latest: \"https://esm.town/v/maxm/queue/runMigrations\",\n pinned: \"https://esm.town/v/maxm/queue@11-main/runMigrations\",\n val: \"https://esm.town/v/maxm/queue/\",\n valPinned: \"https://esm.town/v/maxm/queue@11-main/\",\n },\n },\n };\n expect(parseVal(input)).toEqual(expected);\n },\n },\n {\n name: \"val with p prefix instead of v\",\n function: () => {\n const input = \"https://esm.town/p/stevekrouse/status2@1-main/notify\";\n const expected = {\n username: \"stevekrouse\",\n name: \"status2\",\n version: \"1\",\n branch: \"main\",\n path: \"notify\",\n links: {\n self: {\n latest:\n \"https://www.val.town/x/stevekrouse/status2/code/notify\",\n pinned:\n \"https://www.val.town/x/stevekrouse/status2/branch/main/version/1/code/notify\",\n val: \"https://www.val.town/x/stevekrouse/status2\",\n },\n module: {\n latest: \"https://esm.town/p/stevekrouse/status2/notify\",\n pinned: \"https://esm.town/p/stevekrouse/status2@1-main/notify\",\n val: \"https://esm.town/p/stevekrouse/status2/\",\n valPinned: \"https://esm.town/p/stevekrouse/status2@1-main/\",\n },\n },\n };\n expect(parseVal(input)).toEqual(expected);\n },\n },\n {\n name: \"val on feature branch\",\n function: () => {\n const input =\n \"https://esm.town/v/user/val@1-feature-branch-name/path/asdf/asfd/asdf/asfd\";\n const expected = {\n username: \"user\",\n name: \"val\",\n version: \"1\",\n branch: \"feature-branch-name\",\n path: \"path/asdf/asfd/asdf/asfd\",\n links: {\n self: {\n latest:\n \"https://www.val.town/x/user/val/branch/feature-branch-name/code/path/asdf/asfd/asdf/asfd\",\n pinned:\n \"https://www.val.town/x/user/val/branch/feature-branch-name/version/1/code/path/asdf/asfd/asdf/asfd\",\n val: \"https://www.val.town/x/user/val\",\n },\n module: {\n latest:\n \"https://esm.town/v/user/val/branch/feature-branch-name/path/asdf/asfd/asdf/asfd\",\n pinned:\n \"https://esm.town/v/user/val@1-feature-branch-name/path/asdf/asfd/asdf/asfd\",\n val: \"https://esm.town/v/user/val/\",\n valPinned: \"https://esm.town/v/user/val@1-feature-branch-name/\",\n },\n },\n };\n expect(parseVal(input)).toEqual(expected);\n },\n },\n {\n name: \"complex branch & file name\",\n function: () => {\n const input =\n \"https://esm.town/v/dev/app@22-complex-branch-with-dashes/val.foo.bar\";\n const expected = {\n username: \"dev\",\n name: \"app\",\n version: \"22\",\n branch: \"complex-branch-with-dashes\",\n path: \"val.foo.bar\",\n links: {\n self: {\n latest:\n \"https://www.val.town/x/dev/app/branch/complex-branch-with-dashes/code/val.foo.bar\",\n pinned:\n \"https://www.val.town/x/dev/app/branch/complex-branch-with-dashes/version/22/code/val.foo.bar\",\n val: \"https://www.val.town/x/dev/app\",\n },\n module: {\n latest:\n \"https://esm.town/v/dev/app/branch/complex-branch-with-dashes/val.foo.bar\",\n pinned:\n \"https://esm.town/v/dev/app@22-complex-branch-with-dashes/val.foo.bar\",\n val: \"https://esm.town/v/dev/app/\",\n valPinned:\n \"https://esm.town/v/dev/app@22-complex-branch-with-dashes/\",\n },\n },\n };\n expect(parseVal(input)).toEqual(expected);\n },\n },\n ],\n },\n];\n\nexport default testServer(parseValTests, import.meta.url);",[189],"7ecc0b5e-1384-4f61-8d2e-3790361578f9","is-main.ts","019f3942-6872-71dc-8b70-48e647e179b4",["D",1783372081272],"/**\n * Checks if the current file is the main entry point of the val.\n *\n * This is a replacement for `import.meta.main` which is not available in Val Town's environment.\n *\n * @param metaImportUrl - The `import.meta.url` of the current file\n * @returns `true` if the file is the main entry point, `false` otherwise\n *\n * @example\n * ```ts\n * import { isMain } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * if (isMain(import.meta.url)) {\n * // Code that doesn't run if this file is imported\n * // Useful for testing functions near their definitions\n * }\n * ```\n */\nexport function isMain(metaImportUrl: string): boolean {\n return metaImportUrl === Deno.env.get(\"VALTOWN_ENTRYPOINT\");\n}",[195],"4482c375-c045-4cee-9e54-2b19f87d8c9c","is-main.test.ts","019f3942-6872-71dc-8b70-470363e73432",["D",1783372081272],"import { expect } from \"jsr:@std/expect\";\nimport { testServer } from \"./test.tsx\";\nimport { isMain } from \"./is-main.ts\";\n\nexport const isMainTests = [\n {\n name: \"isMain Tests\",\n sourceFile: \"isMain.ts\",\n tests: [\n {\n name: \" return true when current file is the entry point\",\n function: () => {\n // Test with the actual current file - this should return true\n // since this test file is being executed directly\n const result = isMain(Deno.env.get(\"VALTOWN_ENTRYPOINT\"));\n expect(result).toBe(true);\n },\n },\n {\n name: \" return false for different URL\",\n function: () => {\n // Test with a different URL that's definitely not the entry point\n const differentURL = \"https://esm.town/v/user/test@1-main/helper.ts\";\n const result = isMain(differentURL);\n expect(result).toBe(false);\n },\n },\n ],\n },\n];\n\nexport default testServer(isMainTests);",[201],"e3f831ca-d246-40eb-8c24-a2d3a0c6bc3e","index.ts","019f3942-6872-71dc-8b70-41fef6ecb903",["D",1783372081272],"export {\n emailAddress,\n fetchTranspiledJavaScript,\n getValId,\n httpEndpoint,\n listFiles,\n listFilesByPath,\n readFile,\n readFileTranspiled,\n} from \"./file.ts\";\nexport { parseVal } from \"./parseImportMeta.ts\";\nexport { getContentType, serveFile } from \"./serve-file.ts\";\nexport { testServer } from \"./test.tsx\";\nexport { staticHTTPServer } from \"./static.tsx\";\nexport { isMain } from \"./is-main.ts\";\nexport { hotReload } from \"./hot-reload.ts\";\n\n// for backwards compatibility\nexport { parseProject } from \"https://esm.town/v/std/utils@105-main/parseImportMeta/project.ts\";",[207],"222731d6-9a0c-4f30-b3a9-6c038880a391","hot-reload.ts","019f3942-6872-71dc-8b70-3f5b16fbb1e6",["D",1783372081272],"import ValTown from \"npm:@valtown/sdk@1.9.0\";\nimport { parseVal } from \"./parseImportMeta.ts\";\nimport { API_URL } from \"https://esm.town/v/std/API_URL\";\n\nconst POLL_PATH = \"/__vt_hot_reload\";\nconst HOLD_DURATION_MS = 30_000;\nconst CHECK_INTERVAL_MS = 500;\n\n/**\n * Wraps an HTTP handler to enable hot reload during development.\n *\n * When a val is served on a `.val.run` domain, this wrapper:\n * 1. Injects a small script into HTML responses that long-polls for version changes\n * 2. Handles the long-poll endpoint (`/__vt_hot_reload`)\n * 3. Actively checks the Val Town API for new versions of the current branch\n * 4. When a new version is deployed, the client detects the change and reloads the page\n *\n * On custom domains (non `.val.run`), the handler passes through unmodified.\n *\n * @param handler - Your HTTP fetch handler\n * @returns A wrapped handler with hot reload support\n *\n * @example\n * ```ts\n * import { hotReload } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * export default hotReload(async (req: Request) => {\n * return new Response(\"

Hello!

\", {\n * headers: { \"Content-Type\": \"text/html\" },\n * });\n * });\n * ```\n */\nexport function hotReload(\n handler: (req: Request) => Response | Promise,\n): (req: Request) => Promise {\n const val = parseVal();\n const startVersion = parseInt(val.version, 10);\n\n // Lazily initialize the SDK and val/branch IDs on first poll request\n let pollContext:\n | Promise<{ vt: ValTown; valId: string; branchName: string }>\n | null = null;\n\n function getPollContext() {\n if (!pollContext) {\n pollContext = (async () => {\n const vt = new ValTown({ baseURL: API_URL });\n const { id: valId } = await vt.alias.username.valName.retrieve(\n val.username,\n val.name,\n );\n return { vt, valId, branchName: val.branch };\n })();\n }\n return pollContext;\n }\n\n return async (req: Request): Promise => {\n const url = new URL(req.url);\n\n // Only activate on val.run domains\n if (!url.hostname.endsWith(\".val.run\")) {\n return handler(req);\n }\n\n // Handle long-poll endpoint\n if (url.pathname === POLL_PATH) {\n return handlePoll(getPollContext, startVersion);\n }\n\n // Normal request — call user handler, maybe inject script\n const res = await handler(req);\n\n // Don't inject into iframe responses — Sec-Fetch-Dest is \"iframe\" for\n // iframe loads and \"document\" for top-level navigations.\n const fetchDest = req.headers.get(\"sec-fetch-dest\");\n if (fetchDest && fetchDest !== \"document\") {\n return res;\n }\n\n return maybeInjectScript(res, startVersion);\n };\n}\n\n/**\n * Handles the long-poll request from the client.\n *\n * Actively polls the Val Town API for branch version changes.\n * If the branch version has increased, respond immediately (triggering reload).\n * Otherwise, keep checking every ~1s for up to ~30s, then respond 304.\n */\nasync function handlePoll(\n getPollContext: () => Promise<\n { vt: ValTown; valId: string; branchName: string }\n >,\n startVersion: number,\n): Promise {\n const { vt, valId, branchName } = await getPollContext();\n const deadline = Date.now() + HOLD_DURATION_MS;\n\n while (Date.now() < deadline) {\n try {\n const latestVersion = await getBranchVersion(vt, valId, branchName);\n if (latestVersion !== null && latestVersion > startVersion) {\n return Response.json({ version: latestVersion });\n }\n } catch {\n // API error — don't crash, just retry next interval\n }\n // Wait before next check (but don't overshoot the deadline)\n const remaining = deadline - Date.now();\n if (remaining <= 0) break;\n await new Promise((resolve) =>\n setTimeout(resolve, Math.min(CHECK_INTERVAL_MS, remaining))\n );\n }\n\n return new Response(null, { status: 304 });\n}\n\n/**\n * Gets the current version of a branch from the Val Town API.\n */\nasync function getBranchVersion(\n vt: ValTown,\n valId: string,\n branchName: string,\n): Promise {\n const branches = await Array.fromAsync(vt.vals.branches.list(valId, {}));\n const branch = branches.find((b) => b.name === branchName);\n return branch ? branch.version : null;\n}\n\n/**\n * If the response is HTML, inject the hot-reload client script before or .\n * Otherwise, return the response unmodified.\n */\nasync function maybeInjectScript(\n res: Response,\n version: number,\n): Promise {\n const contentType = res.headers.get(\"content-type\") || \"\";\n if (!contentType.includes(\"text/html\")) {\n return res;\n }\n\n const script = clientScript(version);\n\n // If the response body is a ReadableStream, use the streaming injector\n if (res.body) {\n const injected = res.body\n .pipeThrough(new TextDecoderStream())\n .pipeThrough(new InjectBeforeCloseStream(script))\n .pipeThrough(new TextEncoderStream());\n\n return new Response(injected, {\n status: res.status,\n statusText: res.statusText,\n headers: res.headers,\n });\n }\n\n // Fallback for bodyless responses\n return res;\n}\n\n/**\n * Generates the inline client-side script that long-polls for version changes.\n */\nfunction clientScript(version: number): string {\n return ``;\n}\n\n/**\n * A TransformStream that injects a string before or in an HTML stream.\n * If neither tag is found, appends at the end.\n */\nclass InjectBeforeCloseStream extends TransformStream {\n constructor(content: string) {\n const state = { injected: false, buffer: \"\" };\n\n super({\n transform(chunk, controller) {\n if (state.injected) {\n controller.enqueue(chunk);\n return;\n }\n\n const combined = state.buffer + chunk;\n state.buffer = \"\";\n\n // Try to inject before or \n const bodyMatch = combined.match(/(<\\/body[\\s>])/i);\n const htmlMatch = combined.match(/(<\\/html[\\s>])/i);\n const match = bodyMatch || htmlMatch;\n\n if (match && match.index !== undefined) {\n const before = combined.slice(0, match.index);\n const after = combined.slice(match.index);\n controller.enqueue(before + content + after);\n state.injected = true;\n return;\n }\n\n // Buffer the tail in case = 1; i--) {\n const slice = combined.slice(-i);\n if (\"\".startsWith(slice) || \"\".startsWith(slice)) {\n state.buffer = slice;\n controller.enqueue(combined.slice(0, -i));\n return;\n }\n }\n\n controller.enqueue(combined);\n },\n flush(controller) {\n if (state.buffer) {\n controller.enqueue(state.buffer);\n }\n if (!state.injected) {\n controller.enqueue(content);\n }\n },\n });\n }\n}",[213],"c595daa6-6abd-44cb-9678-ed7f264235ff","hot-reload.test.ts","019f3942-6872-71dc-8b70-3be5f3cb6bdd",["D",1783372081272],"import { hotReload } from \"./hot-reload.ts\";\n\n// Simple HTML handler for testing\nconst htmlHandler = (_req: Request) =>\n new Response(\"

Hello

\", {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n });\n\nconst jsonHandler = (_req: Request) => Response.json({ ok: true });\n\nconst wrapped = hotReload(htmlHandler);\nconst wrappedJson = hotReload(jsonHandler);\n\n// === Test: script injection into HTML ===\nconst htmlRes = await wrapped(new Request(\"https://test--abc.web.val.run/\"));\nconst htmlBody = await htmlRes.text();\n\nconsole.assert(\n htmlBody.includes(\"__vt_hot_reload\"),\n \"Should inject hot reload script into HTML on val.run\",\n);\nconsole.assert(\n htmlBody.includes(\"

Hello

\"),\n \"Should preserve original HTML content\",\n);\nconsole.assert(\n htmlBody.indexOf(\"__vt_hot_reload\") < htmlBody.indexOf(\"\"),\n \"Script should be injected before \",\n);\nconsole.log(\"✅ HTML injection works on val.run\");\n\n// === Test: no injection on custom domains ===\nconst customRes = await hotReload(htmlHandler)(\n new Request(\"https://myapp.example.com/\"),\n);\nconst customBody = await customRes.text();\nconsole.assert(\n !customBody.includes(\"__vt_hot_reload\"),\n \"Should NOT inject script on custom domains\",\n);\nconsole.log(\"✅ No injection on custom domains\");\n\n// === Test: no injection on JSON responses ===\nconst jsonRes = await wrappedJson(\n new Request(\"https://test--abc.web.val.run/api\"),\n);\nconst jsonBody = await jsonRes.text();\nconsole.assert(\n !jsonBody.includes(\"__vt_hot_reload\"),\n \"Should NOT inject script into JSON responses\",\n);\nconsole.log(\"✅ No injection on JSON responses\");\n\n// === Test: no injection when loaded in an iframe ===\nconst iframeRes = await wrapped(\n new Request(\"https://test--abc.web.val.run/\", {\n headers: { \"Sec-Fetch-Dest\": \"iframe\" },\n }),\n);\nconst iframeBody = await iframeRes.text();\nconsole.assert(\n !iframeBody.includes(\"__vt_hot_reload\"),\n \"Should NOT inject script when Sec-Fetch-Dest is iframe\",\n);\nconsole.log(\"✅ No injection in iframes (Sec-Fetch-Dest: iframe)\");\n\n// === Test: injection works for top-level document navigations ===\nconst docRes = await wrapped(\n new Request(\"https://test--abc.web.val.run/\", {\n headers: { \"Sec-Fetch-Dest\": \"document\" },\n }),\n);\nconst docBody = await docRes.text();\nconsole.assert(\n docBody.includes(\"__vt_hot_reload\"),\n \"Should inject script when Sec-Fetch-Dest is document\",\n);\nconsole.log(\"✅ Injection works for Sec-Fetch-Dest: document\");\n\n// === Test: HTML without tag ===\nconst noBodyHandler = (_req: Request) =>\n new Response(\"

No body tag

\", {\n headers: { \"Content-Type\": \"text/html\" },\n });\nconst noBodyRes = await hotReload(noBodyHandler)(\n new Request(\"https://test--abc.web.val.run/\"),\n);\nconst noBodyHtml = await noBodyRes.text();\nconsole.assert(\n noBodyHtml.includes(\"__vt_hot_reload\"),\n \"Should inject before when no \",\n);\nconsole.log(\"✅ Injection works with fallback\");\n\n// === Test: HTML without or ===\nconst bareHandler = (_req: Request) =>\n new Response(\"

Bare HTML

\", {\n headers: { \"Content-Type\": \"text/html\" },\n });\nconst bareRes = await hotReload(bareHandler)(\n new Request(\"https://test--abc.web.val.run/\"),\n);\nconst bareHtml = await bareRes.text();\nconsole.assert(\n bareHtml.includes(\"__vt_hot_reload\"),\n \"Should append script when no closing tags found\",\n);\nconsole.log(\"✅ Injection works on bare HTML (appended)\");\n\nconsole.log(\"\\n🎉 All hot-reload tests passed!\");\n",[219],"f1a33486-5b9e-4068-950f-db36c9efe48c","hot-reload.example.tsx","019f3942-6872-71dc-8b70-352486a9fad0",["D",1783372081272],"/** @jsxImportSource npm:hono@4.11.9/jsx */\nimport { Hono } from \"npm:hono@4.11.9\";\nimport { hotReload } from \"./hot-reload.ts\";\n\nconst app = new Hono();\n\napp.get(\"/\", (c) => {\n return c.html(\n \n \n Hot Reload Demo\n \n \n \n

🔥 Hot Reload Demo!!

\n ✅ Hot reload is active! Try editing this file and saving.\n

\n Edit anything below this line and save to see the page refresh\n automatically:\n

Hello, world!

\n The current time at deploy was:{\" \"}\n \n {new Date().toLocaleTimeString()}\n \n

\n \n ,\n );\n});\n\napp.onError((err) => Promise.reject(err));\n\nexport default hotReload(app.fetch);",[225],"42f7f396-34aa-47d1-acae-56e12a373cb9","file.ts","019f3942-6872-71dc-8b70-30167ed35d01",["D",1783372081272],"import ValTown from \"npm:@valtown/sdk@1.9.0\";\nimport { parseVal } from \"./parseImportMeta.ts\";\nimport { API_URL } from \"https://esm.town/v/std/API_URL\";\n\nconst vt = new ValTown({\n baseURL: API_URL,\n});\n\n/**\n * Reads the contents of a file.\n *\n * Use `readFileTranspiled` if you need transpiled JavaScript for execution, like in a browser.\n *\n * Note: Val Town doesn't provide direct file system access. This function uses the Val Town API to read your val files, allowing Val Town to more efficiently provide a scalable serverless runtime.\n *\n * @param path - The file path to read (with or without leading slash)\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to read from. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to the raw file contents as a string. Throws if the file doesn't exist.\n *\n * @example\n * ```ts\n * import { readFile } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // Most common usage - reads raw TypeScript from current val\n * const content = await readFile(\"/utils/helper.ts\");\n * console.log(content); // Contains TypeScript with type annotations\n *\n * // Explicit val specification\n * const content2 = await readFile(\"/README.md\", import.meta.url);\n * console.log(content2);\n * ```\n */\nexport async function readFile(\n path: string,\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n const val = parseVal(metaImportUrl);\n const pathFragment = path.startsWith(\"/\") ? path.slice(1) : path;\n const esmURL = val.links.module.valPinned + pathFragment;\n try {\n return await fetchFile(esmURL, false);\n } catch (err: any) {\n if (err.message === \"File not found\") {\n throw err;\n }\n throw new Error(\"Failed to fetch file \" + esmURL);\n }\n}\n\n/**\n * Reads the transpiled JavaScript contents of a file from the current val.\n *\n * Returns the transpiled JavaScript code ready for execution. Type annotations are stripped. Use `readFile` if you need the original TypeScript source with type annotations.\n *\n * Note: Val Town doesn't provide direct file system access. This function uses esm.town to fetch transpiled code.\n *\n * @param path - The file path to read (with or without leading slash)\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to read from. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to the transpiled JavaScript code as a string\n *\n * @example\n * ```ts\n * import { readFileTranspiled } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // Read transpiled JavaScript for serving or execution\n * const jsCode = await readFileTranspiled(\"/app.ts\");\n * console.log(jsCode); // Contains JavaScript without type annotations\n * ```\n */\nexport async function readFileTranspiled(\n path: string,\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n const val = parseVal(metaImportUrl);\n const pathFragment = path.startsWith(\"/\") ? path.slice(1) : path;\n const esmURL = val.links.module.valPinned + pathFragment;\n let text: string;\n try {\n text = await fetchTranspiledJavaScript(esmURL);\n } catch (err: any) {\n if (err.message === \"File not found\") {\n throw err;\n }\n throw new Error(\"Failed to fetch file \" + esmURL);\n }\n return text;\n}\n\n/**\n * Gets the HTTP endpoint URL for the currently running val or a specific file in the val.\n *\n * @param path - Optional. The file path to get the endpoint for. Defaults to the currently running endpoint.\n * @param metaImportUrl - Optional. The import.meta.url to determine which val the file belongs to. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to the full HTTP URL for the endpoint\n *\n * @example\n * ```ts\n * import { httpEndpoint } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * const endpoint = await httpEndpoint();\n * console.log(endpoint); // Returns the full HTTP URL for the endpoint\n * ```\n */\nexport async function httpEndpoint(\n path: string = \"\",\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n const normalizedPath = path.startsWith(\"/\") ? path.slice(1) : path;\n\n const files = await listFilesByPath(normalizedPath, metaImportUrl);\n const file = path === \"\"\n ? files.find((f) => f.path === parseVal().path) ??\n files.find((f) => f.links?.endpoint)\n : files.find((f) => f.path === normalizedPath);\n\n if (!file) {\n throw new Error(`File not found: ${path}`);\n }\n\n if (!file.links?.endpoint) {\n throw new Error(`No HTTP endpoint available for file: ${path}`);\n }\n\n return file.links.endpoint;\n}\n\n/**\n * Gets the email address for a file with an email trigger in the val.\n *\n * Note: This function does not work for vanity email addresses. It only works for the UUID version.\n *\n * @param path - The file path to get the email address for\n * @param metaImportUrl - Optional. The import.meta.url to determine which val the file belongs to. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to the email address in format: `{username}-{fileIdWithoutDashes}@valtown.email`\n *\n * @example\n * ```ts\n * import { emailAddress } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // Get the email address for a file with email trigger\n * const email = await emailAddress(\"/handlers/processEmail.ts\");\n * console.log(email); // Returns: username-fileid@valtown.email\n * ```\n */\nexport async function emailAddress(\n path: string,\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n const normalizedPath = path.startsWith(\"/\") ? path.slice(1) : path;\n\n const files = await listFilesByPath(normalizedPath, metaImportUrl);\n const file = files.find((f) => f.path === normalizedPath);\n\n if (!file) {\n throw new Error(`File not found: ${path}`);\n }\n\n if (file.type !== \"email\") {\n throw new Error(`File does not have email trigger: ${path}`);\n }\n\n const username = parseVal(metaImportUrl).username;\n return `${username}-${file.id.replaceAll(\"-\", \"\")}@valtown.email`;\n}\n\n/**\n * Lists all files in the current val with their metadata.\n *\n * Note: Val Town doesn't provide direct file system access. This function uses the Val Town API to list your val files, enabling a more scalable serverless runtime.\n *\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to list files from. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to an array of file metadata objects — see the signature above for the full type\n *\n * @example\n * ```ts\n * import { listFiles } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // Most common usage - lists files from current val\n * const files = await listFiles();\n * files.forEach((file) => console.log(file.path));\n *\n * // Explicit val specification\n * const files2 = await listFiles(import.meta.url);\n * files2.forEach((file) => console.log(file.path));\n * ```\n */\nexport function listFiles(\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n return listFilesByPath(\"\", metaImportUrl);\n}\n\n/**\n * Gets the ID of a val.\n *\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to get the ID for. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to the val ID as a string\n *\n * @example\n * ```ts\n * import { getValId } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // Get the val id for the val this code is in\n * const id = await getValId();\n * console.log(id); // Returns: \"bb8f592e-f528-11ef-b06d-569c3dd06744\"\n * ```\n */\nexport async function getValId(\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n const val = parseVal(metaImportUrl);\n const { id } = await vt.alias.username.valName.retrieve(\n val.username,\n val.name,\n );\n return id;\n}\n\n/**\n * Lists files in a specific directory path within the current val.\n *\n * @param path - The directory path to list files from\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to list files from. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to an array of file metadata objects (same shape as `listFiles`)\n *\n * @example\n * ```ts\n * import { listFilesByPath } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // List files in a specific directory\n * const frontendFiles = await listFilesByPath(\"frontend/\");\n * frontendFiles.forEach((file) => console.log(file.path));\n * ```\n */\nexport async function listFilesByPath(\n path: string,\n metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n const val = parseVal(metaImportUrl);\n const valId = await getValId(metaImportUrl);\n\n const params: {\n path: string;\n recursive: boolean;\n branch_id?: string;\n } = {\n path,\n recursive: true,\n };\n\n if (val.branch !== \"main\") {\n const branches = await Array.fromAsync(vt.vals.branches.list(valId, {}));\n const branch = branches.find((b) => b.name === val.branch);\n if (!branch) {\n throw new Error(\"Failed to find branch \" + val.branch);\n }\n params.branch_id = branch.id; // set like this because of a stainless bug\n }\n\n const files = await Array.fromAsync(vt.vals.files.retrieve(valId, params));\n return files;\n}\n\n/**\n * Fetches and transpiles TypeScript/JavaScript code from esm.town URLs.\n *\n * @param url - The esm.town URL to fetch (e.g., \"https://esm.town/v/username/valname@version-branch/file.ts\")\n * @returns Promise that resolves to the transpiled JavaScript code as a string\n *\n * @example\n * ```ts\n * import { fetchTranspiledJavaScript } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * const code = await fetchTranspiledJavaScript(\n * \"https://esm.town/v/std/utils@85-main/index.ts\"\n * );\n * console.log(code);\n * ```\n */\nexport async function fetchTranspiledJavaScript(url: string): Promise {\n return await fetchFile(url, true);\n}\n\nasync function fetchFile(url: string, isTranspiled: boolean): Promise {\n if (!url.startsWith(\"https://esm.town\")) {\n throw Error(\"Can only fetch from https://esm.town\");\n }\n const res = await fetch(url, {\n headers: {\n // Always transpile TS to JS\n // Learn more: https://www.val.town/v/stevekrouse/esmTownTranspileDemo\n \"User-Agent\": isTranspiled ? \"\" : \"Deno\",\n \"Authorization\": \"Bearer \" + Deno.env.get(\"valtown\"),\n },\n });\n if (res.status === 404) {\n throw new Error(\"File not found\");\n }\n if (!res.ok) {\n throw new Error(\"Failed to fetch \" + url + res.status);\n }\n return await res.text();\n}",[231],"2a6aeef3-b805-4e0c-b19a-da30d7a37d8f","file.test.ts","019f3942-6872-71dc-8b70-2fa1d26c7a58",["D",1783372081272],"import { expect } from \"jsr:@std/expect\";\nimport { testServer } from \"./test.tsx\";\nimport {\n emailAddress,\n fetchTranspiledJavaScript,\n httpEndpoint,\n listFiles,\n listFilesByPath,\n readFile,\n readFileTranspiled,\n} from \"./file.ts\";\n\nexport const fileTests = [\n {\n name: \"fetchTranspiledJavaScript Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \"valid esm.town URL format\",\n function: async () => {\n // Test with a known public val\n const url = \"https://esm.town/v/std/utils@85-main/index.ts\";\n const result = await fetchTranspiledJavaScript(url);\n expect(typeof result).toBe(\"string\");\n expect(result.length).toBeGreaterThan(0);\n },\n },\n ],\n },\n {\n name: \"readFile Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \"read file from val\",\n function: async () => {\n // Test reading this very test file\n const content = await readFile(\"/file.test.ts\", import.meta.url);\n expect(typeof content).toBe(\"string\");\n expect(content).toContain(\"readFile Tests\");\n },\n },\n {\n name: \"paths with and without leading slash\",\n function: async () => {\n // Both should work the same way\n const contentWithSlash = await readFile(\n \"/README.md\",\n import.meta.url,\n );\n const contentWithoutSlash = await readFile(\n \"README.md\",\n import.meta.url,\n );\n expect(contentWithSlash).toBe(contentWithoutSlash);\n },\n },\n {\n name: \"throwsfor non-existent file\",\n function: async () => {\n await expect(\n readFile(\"/non-existent-file.txt\", import.meta.url),\n )\n .rejects.toThrow();\n },\n },\n ],\n },\n {\n name: \"readFileTranspiled Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \"read transpiled JavaScript from val\",\n function: async () => {\n // Test reading transpiled JavaScript\n const content = await readFileTranspiled(\n \"/index.ts\",\n import.meta.url,\n );\n expect(typeof content).toBe(\"string\");\n expect(content.length).toBeGreaterThan(0);\n // Transpiled code should be JavaScript (not contain TypeScript type annotations in executable parts)\n expect(content).toContain(\"export\");\n },\n },\n {\n name: \"work with default metaImportUrl parameter\",\n function: async () => {\n // Test with default parameter\n const content = await readFileTranspiled(\"/index.ts\");\n expect(typeof content).toBe(\"string\");\n expect(content.length).toBeGreaterThan(0);\n },\n },\n ],\n },\n {\n name: \"listFiles Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \" list files in val\",\n function: async () => {\n const files = await listFiles(import.meta.url);\n expect(Array.isArray(files)).toBe(true);\n expect(files.length).toBeGreaterThan(0);\n\n // Should contain some expected files\n const filePaths = files.map((f) => f.path);\n expect(filePaths).toContain(\"README.md\");\n expect(filePaths).toContain(\"index.ts\");\n },\n },\n ],\n },\n {\n name: \"listFilesByPath Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \" list files in specific directory\",\n function: async () => {\n // Test listing files in root directory (empty path)\n const rootFiles = await listFilesByPath(\"\", import.meta.url);\n expect(Array.isArray(rootFiles)).toBe(true);\n expect(rootFiles.length).toBeGreaterThan(0);\n\n // Should contain some expected files\n const filePaths = rootFiles.map((f) => f.path);\n expect(filePaths).toContain(\"README.md\");\n expect(filePaths).toContain(\"index.ts\");\n },\n },\n {\n name: \" work with default metaImportUrl\",\n function: async () => {\n // Test with default parameter (should use VALTOWN_ENTRYPOINT)\n const files = await listFilesByPath(\"\");\n expect(Array.isArray(files)).toBe(true);\n },\n },\n ],\n },\n {\n name: \"httpEndpoint Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \" get HTTP endpoint for file\",\n function: async () => {\n // Test getting endpoint for a test file\n const endpoint = await httpEndpoint(\"/file.test.ts\", import.meta.url);\n expect(typeof endpoint).toBe(\"string\");\n expect(endpoint).toContain(\"https://\");\n expect(endpoint).toContain(\".web.val.run\");\n },\n },\n {\n name: \" work with default metaImportUrl\",\n function: async () => {\n // Test with default parameter\n const endpoint = await httpEndpoint(\"/file.test.ts\");\n expect(typeof endpoint).toBe(\"string\");\n expect(endpoint).toContain(\"https://\");\n },\n },\n {\n name: \" work with no parameters\",\n function: async () => {\n // Test with no params\n const endpoint = await httpEndpoint();\n expect(typeof endpoint).toBe(\"string\");\n expect(endpoint).toContain(\"https://\");\n },\n },\n ],\n },\n {\n name: \"emailAddress Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \" get email address for email trigger file\",\n function: async () => {\n // This test would need a file with email trigger to work properly\n // For now, we'll test the error case for a non-email file\n try {\n await emailAddress(\"/file.test.ts\", import.meta.url);\n // If we get here, the file unexpectedly has an email trigger\n expect(false).toBe(true); // Force failure\n } catch (error) {\n expect(error.message).toContain(\"File does not have email trigger\");\n }\n },\n },\n {\n name: \" throw error for non-existent file\",\n function: async () => {\n await expect(emailAddress(\"/non-existent-file.ts\", import.meta.url))\n .rejects.toThrow(\"File not found\");\n },\n },\n {\n name: \" work with default metaImportUrl\",\n function: async () => {\n // Test with default parameter (should use VALTOWN_ENTRYPOINT)\n try {\n await emailAddress(\"/file.test.ts\");\n expect(false).toBe(true); // Force failure if no error\n } catch (error) {\n expect(error.message).toContain(\"File does not have email trigger\");\n }\n },\n },\n ],\n },\n {\n name: \"readFile with default parameter Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \" work without metaImportUrl\",\n function: async () => {\n // Test reading file with default parameter\n const content = await readFile(\"/file.test.ts\");\n expect(typeof content).toBe(\"string\");\n expect(content).toContain(\"Test reading file with default parameter\");\n },\n },\n ],\n },\n {\n name: \"listFiles with default parameter Tests\",\n sourceFile: \"file.ts\",\n tests: [\n {\n name: \" work without metaImportUrl\",\n function: async () => {\n // Test listing files with default parameter\n const files = await listFiles();\n expect(Array.isArray(files)).toBe(true);\n expect(files.length).toBeGreaterThan(0);\n\n // Should contain some expected files\n const filePaths = files.map((f) => f.path);\n expect(filePaths).toContain(\"README.md\");\n expect(filePaths).toContain(\"index.ts\");\n },\n },\n ],\n },\n];\n\nexport default testServer(fileTests);",[237],"7b17aed2-3ecf-4025-bee0-f13da6ebe47f","example.test.ts","019f3942-6872-71dc-8b70-28df1feadf5b",["D",1783372081272],"import { expect } from \"jsr:@std/expect\";\nimport { testServer } from \"./test.tsx\";\n\nexport default testServer([\n {\n name: \"Test Group 1\",\n sourceFile: \"test.tsx\",\n tests: [\n {\n name: \"no-op\",\n function: () => {\n return true;\n },\n },\n {\n name: \"passing test\",\n function: () => {\n expect(1).toBe(1);\n },\n },\n {\n name: \"passing test 2\",\n function: () => {\n expect(1).toBe(1);\n },\n },\n ],\n },\n {\n name: \"This is an example of a failing test.\",\n sourceFile: \"test.tsx\",\n tests: [\n {\n name: \"Failing test\",\n function: () => {\n expect(1).toBe(2);\n },\n },\n ],\n },\n], import.meta.url);",[243],"d8f6a6a8-ff83-484c-bcd3-79b7a4e91db3","_tests.ts","019f3942-6872-71dc-8b70-277be8f3edda",["D",1783372081272],"import { testServer } from \"./index.ts\";\n\n// Import all test definitions\nimport { parseValTests } from \"./parseImportMeta.test.ts\";\nimport { fileTests } from \"./file.test.ts\";\nimport { serveFileTests } from \"./serve-file.test.ts\";\nimport { staticTests } from \"./static.test.ts\";\nimport { isMainTests } from \"./is-main.test.ts\";\n\n// Combine all tests into a single test server\nexport default testServer([\n ...parseValTests,\n ...fileTests,\n ...serveFileTests,\n ...staticTests,\n ...isMainTests,\n]);",[249],"35388663-0e23-4c11-8417-c62557b156ad","_docs.tsx","019f3942-6872-71dc-8b70-20747fba2efb",["D",1783372081272],"/** @jsxImportSource npm:hono@4.10.4/jsx */\nimport { Hono } from \"npm:hono@4.10.4\";\nimport { readFile } from \"./file.ts\";\nimport testsServer from \"./_tests.ts\";\nimport ts from \"npm:typescript@5.9.3\";\n\nconst app = new Hono();\n\napp.get(\"/badge.svg\", (c) => testsServer(c.req.raw));\n\n// Helper functions for TypeScript doc extraction\nfunction isExported(node: ts.Node): boolean {\n const mods = (node as any).modifiers as ts.NodeArray | undefined;\n return !!(mods && mods.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));\n}\n\nfunction getName(node: ts.Node): string {\n const anyNode = node as any;\n const hasDefault = anyNode.modifiers &&\n anyNode.modifiers.some((m: ts.Modifier) =>\n m.kind === ts.SyntaxKind.DefaultKeyword\n );\n\n // Handle direct name on function/class declarations\n if (anyNode.name && anyNode.name.escapedText) {\n return anyNode.name.escapedText;\n }\n\n // Handle variable declarations: export const foo = ...\n if (ts.isVariableStatement(node)) {\n const decls = node.declarationList.declarations;\n if (decls.length > 0 && ts.isIdentifier(decls[0].name)) {\n return decls[0].name.escapedText as string;\n }\n }\n\n return hasDefault ? \"default\" : \"(anonymous)\";\n}\n\nfunction collectJsDoc(node: ts.Node) {\n const tags = ts.getJSDocTags(node) || [];\n const docNodes = (node as any).jsDoc as any[] | undefined;\n\n const descParts = docNodes\n ? docNodes.map((d: any) => d.comment).filter(Boolean)\n : [];\n const description = descParts.length ? descParts.join(\"\\n\") : \"\";\n\n const byTag: Record = {};\n\n for (const tag of tags) {\n const tagName = (tag as any).tagName?.escapedText?.toString() ?? \"\";\n\n let entry: any = {};\n\n if (tagName === \"param\") {\n const paramName = tag.name?.getText?.() ?? tag.name?.escapedText ?? \"\";\n const comment = tag.comment ||\n (tag.text ? tag.text.map((x: any) => x.text).join(\"\") : \"\") ||\n \"\";\n entry = { name: String(paramName), description: String(comment) };\n } else {\n const comment = tag.comment ||\n (tag.text ? tag.text.map((x: any) => x.text).join(\"\") : \"\") ||\n \"\";\n entry = String(comment);\n }\n\n if (!byTag[tagName]) byTag[tagName] = [];\n byTag[tagName].push(entry);\n }\n\n return { description, byTag };\n}\n\ninterface TypeInfo {\n signature: string | null;\n paramTypes: Record; // paramName -> TS type string\n returnType: string | null;\n}\n\nfunction extractTypeInfo(node: ts.Node, checker: ts.TypeChecker): TypeInfo {\n const paramTypes: Record = {};\n\n // Handle variable statements with arrow functions: export const foo = (...) => ...\n if (ts.isVariableStatement(node)) {\n const decl = node.declarationList.declarations[0];\n if (decl && decl.initializer) {\n const name = ts.isIdentifier(decl.name) ? decl.name.escapedText as string : \"(anonymous)\";\n const type = checker.getTypeAtLocation(decl);\n const callSigs = type.getCallSignatures();\n if (callSigs.length > 0) {\n const sig = callSigs[0];\n const params = sig.getParameters().map((p) => {\n const paramType = checker.getTypeOfSymbolAtLocation(p, decl);\n const typeStr = checker.typeToString(paramType);\n const opt = (p.declarations?.[0] as any)?.questionToken ? \"?\" : \"\";\n paramTypes[p.getName()] = typeStr;\n return `${p.getName()}${opt}: ${typeStr}`;\n }).join(\", \");\n const ret = checker.getReturnTypeOfSignature(sig);\n const retStr = checker.typeToString(ret);\n return {\n signature: `function ${name}(${params}): ${retStr}`,\n paramTypes,\n returnType: retStr,\n };\n }\n }\n return { signature: null, paramTypes, returnType: null };\n }\n\n if (!(\"parameters\" in (node as any))) {\n return { signature: null, paramTypes, returnType: null };\n }\n\n const fn = node as ts.FunctionDeclaration | ts.MethodDeclaration | any;\n const sig = checker.getSignatureFromDeclaration(fn as any);\n if (!sig) return { signature: null, paramTypes, returnType: null };\n\n const ret = checker.getReturnTypeOfSignature(sig);\n const retStr = checker.typeToString(ret);\n const params = (fn.parameters || []).map((p: ts.ParameterDeclaration) => {\n const t = checker.getTypeAtLocation(p);\n const tStr = checker.typeToString(t);\n const pn = ((p.name as any).escapedText) ||\n checker.typeToString(checker.getTypeAtLocation(p.name));\n const opt = (p as any).questionToken ? \"?\" : \"\";\n paramTypes[pn] = tStr;\n return `${pn}${opt}: ${tStr}`;\n }).join(\", \");\n\n const name = getName(node);\n return {\n signature: `function ${name}(${params}): ${retStr}`,\n paramTypes,\n returnType: retStr,\n };\n}\n\n// Hardcoded return type overrides for functions whose return types the in-memory\n// TS compiler can't resolve (e.g. SDK types like ValTown.Vals.Files.FileRetrieveResponse).\n// These may go stale if the @valtown/sdk return types change — update them if so.\n// See https://sdk.val.town/api/typescript/resources/files/methods/retrieve for the current shape.\nconst FILE_METADATA_TYPE = `{\n name: string;\n id: string;\n path: string;\n version: number;\n updatedAt: string;\n type: \"directory\" | \"file\" | \"interval\" | \"http\" | \"email\" | \"script\";\n links: {\n self: string;\n html: string;\n module: string;\n endpoint?: string;\n email?: string;\n };\n}`;\n\nconst VAL_TYPE = `{\n username: string;\n name: string;\n version: string;\n branch: string;\n path: string;\n links: {\n self: {\n latest: string;\n pinned: string;\n val: string;\n };\n module: {\n latest: string;\n pinned: string;\n val: string;\n valPinned: string;\n };\n };\n}`;\n\nconst RETURN_TYPE_OVERRIDES: Record = {\n listFiles: `Promise<${FILE_METADATA_TYPE}[]>`,\n listFilesByPath: `Promise<${FILE_METADATA_TYPE}[]>`,\n parseVal: VAL_TYPE,\n testServer: `(req: Request) => Promise`,\n staticHTTPServer: `(request: Request) => Response | Promise`,\n};\n\nasync function extractDocs(filePath: string) {\n const sourceText = await readFile(filePath);\n\n const fileName = `/${filePath}`;\n const compilerOptions: ts.CompilerOptions = {\n target: ts.ScriptTarget.ES2022,\n module: ts.ModuleKind.ESNext,\n };\n const host: ts.CompilerHost = {\n getSourceFile: (fn, lv) =>\n ts.createSourceFile(\n fn,\n fn === fileName ? sourceText : \"\",\n lv,\n true,\n ts.ScriptKind.TS,\n ),\n writeFile: () => {},\n getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),\n useCaseSensitiveFileNames: () => true,\n getCanonicalFileName: (f) => f,\n getCurrentDirectory: () => \"/\",\n getNewLine: () => \"\\n\",\n fileExists: (fn) => fn === fileName,\n readFile: (fn) => fn === fileName ? sourceText : undefined,\n getDirectories: () => [],\n };\n\n const program = ts.createProgram([fileName], compilerOptions, host);\n const checker = program.getTypeChecker();\n const sf = program.getSourceFile(fileName)!;\n\n const items: any[] = [];\n sf.forEachChild(function walk(node) {\n if (isExported(node)) {\n const { line: startLine } = sf.getLineAndCharacterOfPosition(\n node.getStart(sf),\n );\n const { line: endLine } = sf.getLineAndCharacterOfPosition(node.getEnd());\n const { description, byTag } = collectJsDoc(node);\n const name = getName(node);\n const typeInfo = extractTypeInfo(node, checker);\n\n let { signature, returnType } = typeInfo;\n const { paramTypes } = typeInfo;\n\n // Apply hardcoded return type overrides for unresolvable SDK types\n if (RETURN_TYPE_OVERRIDES[name]) {\n returnType = RETURN_TYPE_OVERRIDES[name];\n if (signature) {\n const lastParen = signature.lastIndexOf(\")\");\n if (lastParen !== -1) {\n signature = signature.slice(0, lastParen + 1) + \": \" + returnType;\n }\n }\n }\n\n items.push({\n name,\n filePath,\n start: startLine + 1,\n end: endLine + 1,\n description,\n tags: byTag,\n signature,\n paramTypes,\n returnType,\n });\n }\n ts.forEachChild(node, walk);\n });\n\n return items;\n}\n\n/** Render inline backtick text as

 elements, and linkify VALTOWN_ENTRYPOINT references */\nfunction renderInline(text: string) {\n  // First split on the VALTOWN_ENTRYPOINT pattern to linkify it\n  const entrypointPattern = /(`Deno\\.env\\.get\\(\"VALTOWN_ENTRYPOINT\"\\)`)/g;\n  const segments = text.split(entrypointPattern);\n\n  return segments.flatMap((segment, si) => {\n    if (segment === '`Deno.env.get(\"VALTOWN_ENTRYPOINT\")`') {\n      return the entrypoint;\n    }\n    // Then split remaining text on backtick code spans\n    const parts = segment.split(/(`[^`]+`)/g);\n    return parts.map((part, i) => {\n      if (part.startsWith(\"`\") && part.endsWith(\"`\")) {\n        const code = part.slice(1, -1);\n        return {code};\n      }\n      return part;\n    });\n  });\n}\n\n/**\n * Render a multi-paragraph description as a list of  elements. Blank lines in the\n * JSDoc source separate paragraphs; single newlines (from hard-wrapped comments) are\n * collapsed into spaces so text reflows naturally instead of breaking mid-sentence.\n */\nfunction renderDescription(text: string) {\n  const paragraphs = text\n    .split(/\\n\\s*\\n/)\n    .map((p) => p.replace(/\\s*\\n\\s*/g, \" \").trim())\n    .filter(Boolean);\n\n  return paragraphs.map((paragraph, i) => (\n    
\n      {renderInline(paragraph)}\n    
\n  ));\n}\n\n/** Render an inline (single-line) description with code spans, collapsing any newlines. */\nfunction renderInlineDescription(text: string) {\n  return renderInline(text.replace(/\\s*\\n\\s*/g, \" \").trim());\n}\n\n/** Strip the leading dash / \"Optional.\" / \"The\" boilerplate from a @param description and render it inline. */\nfunction renderParamDescription(text: string) {\n  const cleaned = text\n    .replace(/^ *-\\s*/, \"\")\n    .replace(/^Optional\\.\\s*/, \"\")\n    .replace(/^The\\s+/, \"the \");\n  return renderInlineDescription(cleaned);\n}\n\n/**\n * Join one or more `@example` blocks into a single code listing, stripping the\n * ```ts fences from each one. Handles functions with multiple `@example` tags\n * (a single .replace() would only strip the first block's fences).\n */\nfunction formatExamples(examples: string[]): string {\n  return examples\n    .map((ex) => ex.replace(/^```\\w*\\n?/, \"\").replace(/\\n?```\\s*$/, \"\").trim())\n    .join(\"\\n\\n\");\n}\n\n// JSX Components\nfunction Sidebar({ categories, documentedFunctions }: any) {\n  return (\n    \n      Val Town Utils
\n      {Object.entries(categories).map(([category, funcs]: [string, any]) => {\n        const items = (funcs as string[]).filter((name) =>\n          documentedFunctions.some((d: any) => d.name === name)\n        );\n        if (items.length === 0) return null;\n\n        return (\n          \n            \n              {category}\n            
\n            \n              {items.map((name) => (\n                \n                  \n                    {name}\n                  \n                
\n              ))}\n            
\n          
\n        );\n      })}\n    
\n  );\n}\n\nfunction CopyButton() {\n  return (\n     {\n          this.textContent = 'Copied!';\n          setTimeout(() => this.textContent = 'Copy', 1500);\n        });\n      \"\n    >\n      Copy\n    \n  );\n}\n\nfunction FunctionDoc({ doc }: any) {\n  const sourceUrl =\n    `https://www.val.town/x/std/utils/code/${doc.filePath}#L${doc.start}-${doc.end}`;\n\n  return (\n    \n      \n        \n          {doc.name}\n        \n      
\n      \n        \n          source\n        \n      
\n\n      {renderDescription(doc.description)}\n\n      {doc.tags.param && doc.tags.param.length > 0 && (\n        \n          \n            Arguments\n          
\n          \n            {doc.tags.param.map((\n              param: { name: string; description: string },\n              i: number,\n            ) => {\n              const typeStr = doc.paramTypes?.[param.name];\n              return (\n                \n                  {param.name}\n                  {typeStr ?  ({typeStr}) : \"\"}\n                  {param.description ? \": \" : \"\"}\n                  {param.description && (\n                    \n                      {renderParamDescription(param.description)}\n                    \n                  )}\n                
\n              );\n            })}\n          
\n        
\n      )}\n\n      {doc.returnType && (() => {\n        const isMultiline = doc.returnType.includes(\"\\n\");\n        const returnsDesc = doc.tags.returns && doc.tags.returns.length > 0 ? doc.tags.returns[0] : null;\n        return (\n          \n            Returns
\n            {isMultiline ? (\n              \n                {doc.returnType}
\n                {returnsDesc && (\n                  {renderInlineDescription(returnsDesc)}
\n                )}\n              
\n            ) : (\n              \n                ({doc.returnType})\n                {returnsDesc ? \": \" : \"\"}\n                {returnsDesc && (\n                  {renderInlineDescription(returnsDesc)}\n                )}\n              
\n            )}\n          
\n        );\n      })()}\n\n      {doc.tags.example && doc.tags.example.length > 0 && (\n        \n          Example
\n          \n            \n            {formatExamples(doc.tags.example)}\n          
\n        
\n      )}\n    
\n  );\n}\n\n// `static.tsx` is listed first so `staticHTTPServer` — the most common starting point —\n// renders at the top of the docs page.\nconst DOC_FILES = [\n  \"static.tsx\",\n  \"file.ts\",\n  \"serve-file.ts\",\n  \"parseImportMeta.ts\",\n  \"is-main.ts\",\n  \"test.tsx\",\n  \"hot-reload.ts\",\n];\n\nconst CATEGORIES: Record = {\n  \"Deploy a static site\": [\"staticHTTPServer\"],\n  \"File Operations\": [\n    \"readFile\",\n    \"listFiles\",\n    \"listFilesByPath\",\n    \"httpEndpoint\",\n    \"emailAddress\",\n    \"getValId\",\n    \"fetchTranspiledJavaScript\",\n  ],\n  \"HTTP Utilities\": [\"serveFile\", \"getContentType\", \"hotReload\"],\n  \"Val Metadata\": [\"parseVal\", \"isMain\"],\n  \"Testing\": [\"testServer\"],\n};\n\nasync function getDocumentedFunctions() {\n  const allDocs = await Promise.all(DOC_FILES.map((file) => extractDocs(file)));\n  const docs = allDocs.flat();\n  return docs.filter((d) => d.description);\n}\n\n/** Strip backtick-wrapped code in descriptions for plain text / markdown output */\nfunction stripBackticks(text: string): string {\n  return text.replace(/`([^`]+)`/g, \"`$1`\");\n}\n\nfunction renderDocsMarkdown(documentedFunctions: any[]): string {\n  const lines: string[] = [];\n\n  lines.push(\"# Val Town Utils Documentation\\n\");\n  lines.push(\"[View val on Val Town](https://www.val.town/x/std/utils)\\n\");\n  lines.push(\n    \"@std/utils is a collection of utilities for Val Town, including \" +\n    \"reading files, serving static content, getting Val Town metadata, \" +\n    \"and more.\\n\",\n  );\n\n  lines.push(\"## What is the entrypoint?\\n\");\n  lines.push(\n    \"Many functions below accept an optional `metaImportUrl` parameter \" +\n    \"that defaults to the entrypoint. \" +\n    \"The entrypoint is the `import.meta.url` of the file that Val Town executed — \" +\n    \"the HTTP handler that received a request, the cron job that fired, the email handler that received a message, or the script you clicked \\\"Run\\\" on. \" +\n    \"Val Town sets this automatically via `Deno.env.get(\\\"VALTOWN_ENTRYPOINT\\\")`, \" +\n    \"so you almost never need to pass it yourself. The main reason to pass `import.meta.url` explicitly \" +\n    \"is when you're calling these functions from a different val than the one that was triggered.\\n\",\n  );\n\n  lines.push(\"---\\n\");\n\n  // Table of contents\n  lines.push(\"## Table of Contents\\n\");\n  for (const [category, funcs] of Object.entries(CATEGORIES)) {\n    const items = funcs.filter((name) =>\n      documentedFunctions.some((d: any) => d.name === name)\n    );\n    if (items.length === 0) continue;\n    lines.push(`### ${category}\\n`);\n    for (const name of items) {\n      lines.push(`- [${name}](#${name.toLowerCase()})`);\n    }\n    lines.push(\"\");\n  }\n\n  lines.push(\"---\\n\");\n\n  // Function docs\n  for (const doc of documentedFunctions) {\n    const sourceUrl = `https://www.val.town/x/std/utils/code/${doc.filePath}#L${doc.start}-${doc.end}`;\n\n    lines.push(`## ${doc.name}\\n`);\n    lines.push(`[source](${sourceUrl})\\n`);\n\n    if (doc.description) {\n      lines.push(`${stripBackticks(doc.description)}\\n`);\n    }\n\n    if (doc.signature) {\n      lines.push(\"```ts\");\n      lines.push(doc.signature);\n      lines.push(\"```\\n\");\n    }\n\n    if (doc.tags.param && doc.tags.param.length > 0) {\n      lines.push(\"### Arguments\\n\");\n      for (const param of doc.tags.param) {\n        const typeStr = doc.paramTypes?.[param.name];\n        const desc = param.description\n          ? param.description.replace(/^ *-\\s*/, \"\").replace(/^Optional\\.\\s*/, \"\").replace(/^The\\s+/, \"the \")\n          : \"\";\n        const typePart = typeStr ? ` (\\`${typeStr}\\`)` : \"\";\n        const descPart = desc ? `: ${stripBackticks(desc)}` : \"\";\n        lines.push(`- **${param.name}**${typePart}${descPart}`);\n      }\n      lines.push(\"\");\n    }\n\n    if (doc.returnType) {\n      lines.push(\"### Returns\\n\");\n      const isMultiline = doc.returnType.includes(\"\\n\");\n      const returnsDesc = doc.tags.returns && doc.tags.returns.length > 0 ? doc.tags.returns[0] : null;\n      if (isMultiline) {\n        lines.push(\"```ts\");\n        lines.push(doc.returnType);\n        lines.push(\"```\");\n        if (returnsDesc) lines.push(`\\n${stripBackticks(returnsDesc)}`);\n      } else {\n        const descPart = returnsDesc ? `: ${stripBackticks(returnsDesc)}` : \"\";\n        lines.push(`\\`${doc.returnType}\\`${descPart}`);\n      }\n      lines.push(\"\");\n    }\n\n    if (doc.tags.example && doc.tags.example.length > 0) {\n      lines.push(\"### Example\\n\");\n      lines.push(\"```ts\");\n      lines.push(formatExamples(doc.tags.example));\n      lines.push(\"```\\n\");\n    }\n\n    lines.push(\"---\\n\");\n  }\n\n  return lines.join(\"\\n\");\n}\n\napp.get(\"/docs.md\", async (c) => {\n  const documentedFunctions = await getDocumentedFunctions();\n  const markdown = renderDocsMarkdown(documentedFunctions);\n  return c.text(markdown, 200, { \"Content-Type\": \"text/markdown; charset=utf-8\" });\n});\n\napp.get(\"/\", async (c) => {\n  const documentedFunctions = await getDocumentedFunctions();\n  const categories = CATEGORIES;\n\n  return c.render(\n    \n      \n        \n        Val Town Utils Documentation\n        \n        \n        \n        \n        \n        \n      \n      \n        \n          \n          \n            \n              Val Town Utils Documentation\n            
\n            \n              \n                View val on Val Town\n              \n              |\n              \n                docs.md (for LLMs)\n              \n              \n            
\n            \n              @std/utils is a collection of utilities for Val Town, including\n              reading files, serving static content, getting Val Town metadata,\n              and more.\n            
\n\n            \n              \n                💡 What is the entrypoint?\n              
\n              \n                Many functions below accept an optional metaImportUrl parameter\n                that defaults to the entrypoint.\n                The entrypoint is the import.meta.url of the file that Val Town executed —\n                the HTTP handler that received a request, the cron job that fired, the email handler that received a message, or the script you clicked \"Run\" on.\n                Val Town sets this automatically via Deno.env.get(\"VALTOWN_ENTRYPOINT\"),\n                so you almost never need to pass it yourself. The main reason to pass import.meta.url explicitly\n                is when you're calling these functions from a different val than the one that was triggered.\n              
\n            
\n\n            
\n\n            {documentedFunctions.map((doc) => (\n              \n            ))}\n          
\n        
\n      \n    ,\n  );\n});\n\napp.onError((err) => Promise.reject(err));\n\nexport default app.fetch;",[255],"539dd15f-4411-4898-9b03-96418895a678","README.md","019f3942-6871-71de-8250-91f2e4d322cb",["D",1783372081272],"# @std/utils\n\nStandard utility library for [Val Town](https://www.val.town). Provides helpers for reading files, serving static content, parsing val metadata, and testing.\n\n📖 **[Full API documentation](https://utilities.val.run/)**\n\n## Installation\n\n```ts\nimport { readFile, serveFile, parseVal, listFiles } from \"https://esm.town/v/std/utils/index.ts\";\n```\n\n## Quick start\n\n### Deploy a static site (most common)\n\n`staticHTTPServer` is the fastest way to ship HTML/CSS/JS from a val. Drop an `index.html`\n(plus any assets) into your val and:\n\n```ts\nimport { staticHTTPServer } from \"https://esm.town/v/std/utils/index.ts\";\n\n// Serves index.html at \"/\", every other file by path, and a /source redirect.\nexport default staticHTTPServer();\n```\n\nThis automatically:\n- serves `/index.html` at `/`\n- serves any other path as a static file with the correct `Content-Type`\n- exposes **`/source`**, which 302-redirects to the val's source code on Val Town — so\n  visitors can always click through to see how a page was built.\n\n#### Mostly static, but with a little custom routing\n\nNeed an API route or a redirect alongside your static files? Pass a **fetch handler** as the\nsecond argument — it's just the web standard `(request) => Response`. It's tried first on\nevery request: return a `Response` to handle it yourself, or return `null`/`undefined` to\nfall through to static serving (and `/source`):\n\n```ts\nimport { staticHTTPServer } from \"https://esm.town/v/std/utils/index.ts\";\n\nexport default staticHTTPServer(import.meta.url, (req) => {\n  const { pathname } = new URL(req.url);\n  if (pathname === \"/api/hello\") return Response.json({ hello: \"world\" });\n  return null; // defer to the static server (index.html / assets / /source)\n});\n```\n\nSince it's the fetch standard, any framework's handler works too — e.g. pass Hono's\n`app.fetch` (have its `notFound` return `null` so unmatched routes fall through):\n\n```ts\nimport { Hono } from \"npm:hono@4.11.9\";\nimport { staticHTTPServer } from \"https://esm.town/v/std/utils/index.ts\";\n\nconst app = new Hono();\napp.get(\"/api/hello\", (c) => c.json({ hello: \"world\" }));\napp.notFound(() => null as any);\n\nexport default staticHTTPServer(import.meta.url, app.fetch);\n```\n\n### Other common tasks\n\n```ts\n// Read a file from your val\nconst content = await readFile(\"/README.md\");\n\n// Serve static files in a Hono app\napp.get(\"/assets/*\", (c) => serveFile(c.req.path));\n\n// Get the current val's metadata\nconst val = parseVal(import.meta.url);\nconsole.log(val.username, val.name);\n```\n\n## Exported functions\n\n| Function | Description |\n|---|---|\n| `staticHTTPServer` | **Deploy a static site in one line.** Serves `/index.html` at root, any file by path, and a `/source` redirect. Optionally pass a fetch handler for custom routing. |\n| `readFile` | Read raw file contents from your val |\n| `readFileTranspiled` | Read transpiled JS (types stripped) for browser use |\n| `listFiles` | List all files in the current val with metadata |\n| `listFilesByPath` | List files in a specific directory |\n| `httpEndpoint` | Get the live HTTP URL for a file |\n| `emailAddress` | Get the email address for an email-trigger file |\n| `getValId` | Get the current val's UUID |\n| `fetchTranspiledJavaScript` | Fetch transpiled JS from any esm.town URL |\n| `serveFile` | Serve a file as an HTTP Response with correct Content-Type |\n| `getContentType` | Get MIME type for a file path |\n| `parseVal` | Parse val metadata (username, name, version, branch, links) from `import.meta.url` |\n| `isMain` | Check if the current file is the entrypoint |\n| `testServer` | Create an HTML test runner with pass/fail badges |\n\n## Architecture\n\n```mermaid\ngraph TD\n    index[index.ts
re-exports everything]\n\n    index --> file[file.ts
readFile, listFiles, httpEndpoint,
emailAddress, getValId, etc.]\n    index --> serveFile[serve-file.ts
serveFile, getContentType]\n    index --> parseVal[parseImportMeta.ts
parseVal]\n    index --> isMain[is-main.ts
isMain]\n    index --> testServer[test.tsx
testServer]\n    index --> staticServer[static.tsx
staticHTTPServer]\n\n    file --> parseVal\n    serveFile --> file\n    staticServer --> serveFile\n\n    docs[_docs.tsx
auto-generated API docs site]\n    tests[_tests.ts
test runner endpoint]\n\n    style docs fill:#e8f4fd,stroke:#4a90d9\n    style tests fill:#e8f4fd,stroke:#4a90d9\n    style index fill:#f0f9e8,stroke:#5cb85c\n```\n\n## File overview\n\n| File | Type | Purpose |\n|---|---|---|\n| `index.ts` | script | Public entry point — re-exports all utilities |\n| `file.ts` | script | File I/O: read, list, transpile, endpoints, email addresses |\n| `serve-file.ts` | script | HTTP file serving with MIME type detection |\n| `parseImportMeta.ts` | script | Parse `import.meta.url` into val metadata |\n| `is-main.ts` | script | Entrypoint detection (`import.meta.main` replacement) |\n| `test.tsx` | script | Test runner with HTML output and SVG badges |\n| `static.tsx` | script | Static file server (fetch-standard, no framework dependency) |\n| `_docs.tsx` | http | Auto-generated documentation site at [utilities.val.run](https://utilities.val.run/) |\n| `_tests.ts` | http | Test suite endpoint |\n| `*.test.ts` | http | Per-module test files |\n\n## Development\n\nTests run as HTTP endpoints. Each source file has a corresponding `.test.ts` file. The `_tests.ts` file aggregates all tests and serves a badge at `/badge.svg`.\n\nThe `_docs.tsx` file uses the TypeScript compiler API to extract JSDoc from source files and render them as an HTML documentation site. Return type overrides for SDK types that can't be resolved by the in-memory compiler are hardcoded in `RETURN_TYPE_OVERRIDES` — these may need updating if the `@valtown/sdk` types change.\n",[261],"pulls",2,"branches","forks",9,"envVars",{"_275":149,"_277":149},"connections",{"_275":149,"_276":149},"count","unfilledCount","emptyCount",{"_18":260,"_20":261,"_142":262,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":352,"_69":149,"_150":102,"_152":264,"_154":26,"_155":-5,"_298":353,"_91":354},{"_18":254,"_20":255,"_142":256,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":349,"_69":149,"_150":167,"_152":258,"_154":26,"_155":-5,"_298":350,"_91":351},{"_18":248,"_20":249,"_142":250,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":346,"_69":149,"_150":167,"_152":252,"_154":26,"_155":-5,"_298":347,"_91":348},{"_18":242,"_20":243,"_142":244,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":343,"_69":149,"_150":167,"_152":246,"_154":26,"_155":-5,"_298":344,"_91":345},{"_18":236,"_20":237,"_142":238,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":340,"_69":149,"_150":167,"_152":240,"_154":26,"_155":-5,"_298":341,"_91":342},{"_18":230,"_20":231,"_142":232,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":337,"_69":149,"_150":151,"_152":234,"_154":26,"_155":-5,"_298":338,"_91":339},{"_18":224,"_20":225,"_142":226,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":334,"_69":149,"_150":167,"_152":228,"_154":26,"_155":-5,"_298":335,"_91":336},{"_18":218,"_20":219,"_142":220,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":331,"_69":149,"_150":151,"_152":222,"_154":26,"_155":-5,"_298":332,"_91":333},{"_18":212,"_20":213,"_142":214,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":328,"_69":149,"_150":151,"_152":216,"_154":26,"_155":-5,"_298":329,"_91":330},{"_18":206,"_20":207,"_142":208,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":325,"_69":149,"_150":151,"_152":210,"_154":26,"_155":-5,"_298":326,"_91":327},{"_18":200,"_20":201,"_142":202,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":322,"_69":149,"_150":167,"_152":204,"_154":26,"_155":-5,"_298":323,"_91":324},{"_18":194,"_20":195,"_142":196,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":319,"_69":149,"_150":151,"_152":198,"_154":26,"_155":-5,"_298":320,"_91":321},{"_18":188,"_20":189,"_142":190,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":316,"_69":149,"_150":167,"_152":192,"_154":26,"_155":-5,"_298":317,"_91":318},{"_18":182,"_20":183,"_142":184,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":313,"_69":149,"_150":151,"_152":186,"_154":26,"_155":-5,"_298":314,"_91":315},{"_18":176,"_20":177,"_142":178,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":310,"_69":149,"_150":167,"_152":180,"_154":26,"_155":-5,"_298":311,"_91":312},{"_18":170,"_20":171,"_142":172,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":307,"_69":149,"_150":151,"_152":174,"_154":26,"_155":-5,"_298":308,"_91":309},{"_18":163,"_20":164,"_142":165,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":304,"_69":149,"_150":167,"_152":168,"_154":26,"_155":-5,"_298":305,"_91":306},{"_18":157,"_20":158,"_142":159,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":301,"_69":149,"_150":151,"_152":161,"_154":26,"_155":-5,"_298":302,"_91":303},{"_18":140,"_20":141,"_142":143,"_144":-5,"_145":72,"_146":70,"_147":38,"_22":297,"_69":149,"_150":151,"_152":153,"_154":26,"_155":-5,"_298":299,"_91":300},["D",1783372081272],"children",[],[141],["D",1783372081272],[],[158],["D",1783372081272],[],[164],["D",1783372081272],[],[171],["D",1783372081272],[],[177],["D",1783372081272],[],[183],["D",1783372081272],[],[189],["D",1783372081272],[],[195],["D",1783372081272],[],[201],["D",1783372081272],[],[207],["D",1783372081272],[],[213],["D",1783372081272],[],[219],["D",1783372081272],[],[225],["D",1783372081272],[],[231],["D",1783372081272],[],[237],["D",1783372081272],[],[243],["D",1783372081272],[],[249],["D",1783372081272],[],[255],["D",1783372081272],[],[261],["D",1740674076598],["D",1789594873133],{"_16":17,"_89":85},{"_16":17,"_83":-5,"_84":85,"_33":-5,"_86":87,"_88":26},{"_69":70,"_20":71,"_18":72,"_73":19,"_74":75,"_76":77,"_78":28,"_79":19,"_80":45,"_81":21,"_82":17},"ctx",{"_62":-5,"_111":393,"_394":395,"_396":397,"_398":26,"_399":26,"_400":26,"_401":38,"_402":-5,"_403":-7,"_404":-7,"_405":149,"_406":26,"_407":26,"_408":-5,"_409":26,"_410":26,"_411":26,"_412":-5},"ENV",{"_364":365,"_366":367,"_368":117,"_369":370,"_371":372,"_373":374,"_375":376,"_377":378,"_379":380,"_381":382,"_383":384,"_385":386,"_387":388,"_389":390,"_391":392},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e8c4b7030cb7600e4eb0736b15f422c8b8bd130f","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Search