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 test groups, where each group contains a name, array of test cases, and optional before/after hooks\n * @returns A fetch-compatible handler function that runs all tests and returns an HTML response\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",[138],"3f12aabc-2e94-11f1-822c-42dde27851f2","static.tsx","019d4e4a-0606-740e-b478-6876bee2e53f",["D",1775134967315],"import { Hono } from \"npm:hono@4.11.9\";\nimport { serveFile } from \"./serve-file.ts\";\n\n/**\n * Creates a simple static HTTP server that serves HTML, CSS, and JS files from your val.\n *\n * The server automatically serves `/index.html` for root requests and handles all other file paths.\n *\n * @param importMetaURL - Optional. The import.meta.url to determine which val to serve files from. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns A fetch-compatible handler function that serves static 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\n * export default staticHTTPServer();\n *\n * // Explicit val specification\n * export default staticHTTPServer(import.meta.url);\n * ```\n */\nexport function staticHTTPServer(\n importMetaURL: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): (\n request: Request,\n env?: any,\n executionCtx?: any,\n) => Response | Promise {\n const app = new Hono();\n\n const serve = async (path: string) => {\n try {\n return await serveFile(path, importMetaURL);\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 app.get(\"/\", () => serve(\"/index.html\"));\n app.get(\"/**/*\", (c) => serve(c.req.path));\n\n // Unwrap Hono errors to see original error details\n app.onError((err) => Promise.reject(err));\n\n return app.fetch;\n}",[156],"3f129cfc-2e94-11f1-822c-42dde27851f2","static.test.ts","019d4e4a-0606-740e-b478-67248399af79",["D",1775134967315],"http","import { expect } from \"jsr:@std/expect\";\nimport { testServer } from \"./test.tsx\";\nimport { staticHTTPServer } from \"./static.tsx\";\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(\"/\");\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(\"/\");\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(\"/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(\"/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 \"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 },\n];\n\nexport default testServer(staticTests);",[162],"3f1290b8-2e94-11f1-822c-42dde27851f2","serve-file.ts","019d4e4a-0606-740e-b478-60ecb7bc72bb",["D",1775134967315],"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",[169],"3f127b96-2e94-11f1-822c-42dde27851f2","serve-file.test.ts","019d4e4a-0606-740e-b478-5ca00e4fae50",["D",1775134967315],"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);",[175],"3f12701a-2e94-11f1-822c-42dde27851f2","parseImportMeta.ts","019d4e4a-0606-740e-b478-58451ddebda3",["D",1775134967315],"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 url - Optional. The import.meta.url to parse. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns An object containing username, name, version, branch, path, and links to the val\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(url: 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 = url.match(pattern);\n\n if (!match) {\n throw new Error(`Invalid ESM Town URL format: ${url}`);\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",[181],"3f125cec-2e94-11f1-822c-42dde27851f2","parseImportMeta.test.ts","019d4e4a-0606-740e-b478-560ba328f395",["D",1775134967315],"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);",[187],"3f125508-2e94-11f1-822c-42dde27851f2","is-main.ts","019d4e4a-0606-740e-b478-510a0b8c622a",["D",1775134967315],"/**\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 importMetaURL - 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(importMetaURL: string): boolean {\n return importMetaURL === Deno.env.get(\"VALTOWN_ENTRYPOINT\");\n}",[193],"3f123d20-2e94-11f1-822c-42dde27851f2","is-main.test.ts","019d4e4a-0606-740e-b478-4ce24491541e",["D",1775134967315],"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);",[199],"3f1237bc-2e94-11f1-822c-42dde27851f2","index.ts","019d4e4a-0606-740e-b478-4a25d308feff",["D",1775134967315],"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\";\n\n// for backwards compatibility\nexport { parseProject } from \"https://esm.town/v/std/utils@105-main/parseImportMeta/project.ts\";",[205],"3f11fff4-2e94-11f1-822c-42dde27851f2","file.ts","019d4e4a-0606-740e-b478-45c2b41071b9",["D",1775134967315],"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, or undefined 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 let text: string;\n try {\n text = 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 return text;\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 objects with metadata\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 objects in the specified directory\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}",[211],"3f11dbc8-2e94-11f1-822c-42dde27851f2","file.test.ts","019d4e4a-0606-740e-b478-40b7fe22d8f8",["D",1775134967315],"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);",[217],"3f11d678-2e94-11f1-822c-42dde27851f2","example.test.ts","019d4e4a-0606-740e-b478-3ebfaee2621b",["D",1775134967315],"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);",[223],"3f11d16e-2e94-11f1-822c-42dde27851f2","_tests.ts","019d4e4a-0606-740e-b478-3a0570cf7647",["D",1775134967315],"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]);",[229],"564488fe-2e94-11f1-822c-42dde27851f2","_docs.tsx","019d4e4a-0606-740e-b478-34bbfaf73483",["D",1775135006240],2,"/** @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 return (anyNode.name && anyNode.name.escapedText) ||\n (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 // Extract param name and description\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\nfunction signatureFor(node: ts.Node, checker: ts.TypeChecker): string | null {\n if (!(\"parameters\" in (node as any))) return null;\n const fn = node as ts.FunctionDeclaration | ts.MethodDeclaration | any;\n const sig = checker.getSignatureFromDeclaration(fn as any);\n if (!sig) return null;\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 return `${pn}${opt}: ${tStr}`;\n }).join(\", \");\n const name = getName(node);\n return `function ${name}(${params}): ${retStr}`;\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 signature = signatureFor(node, checker);\n items.push({\n name,\n filePath,\n start: startLine + 1,\n end: endLine + 1,\n description,\n tags: byTag,\n signature,\n });\n }\n ts.forEachChild(node, walk);\n });\n\n return items;\n}\n\n// JSX Components\nfunction Sidebar({ categories, documentedFunctions }: any) {\n return (\n \n );\n}\n\nfunction FunctionDoc({ doc }: any) {\n const sourceUrl =\n `https://www.val.town/x/stevekrouse/utils/code/${doc.filePath}#L${doc.start}-${doc.end}`;\n\n return (\n

\n \n {doc.name}\n \n

\n \n source\n \n

\n\n {doc.signature && (\n

\n          {doc.signature}\n

\n )}\n\n

\n {doc.description}\n

\n\n {doc.tags.param && doc.tags.param.length > 0 && (\n

\n Parameters\n

\n {param.name} – {param.description.replace(/^ *-/, \"\")}\n

\n )}\n\n {(doc.tags.returns || doc.tags.return) &&\n (doc.tags.returns || doc.tags.return).length > 0 && (\n

Returns

{(doc.tags.returns || doc.tags.return)[0]}

\n )}\n\n {doc.tags.example && doc.tags.example.length > 0 && (\n

Example

\n            {doc.tags.example.join('\\n\\n').replace(\"```ts\\n\", \"\").replace(\"```\", \"\")}\n

\n )}\n

\n );\n}\n\n// Content negotiation: returns true if the client prefers HTML (i.e. is a browser)\nfunction wantsHtml(accept: string | undefined): boolean {\n if (!accept) return false;\n // Parse Accept header media types (ignore parameters/quality for ordering)\n const types = accept.split(\",\").map((t) => {\n const [mediaType, ...params] = t.trim().split(\";\");\n const q = params\n .map((p) => p.trim())\n .find((p) => p.startsWith(\"q=\"));\n return {\n type: mediaType.trim().toLowerCase(),\n q: q ? parseFloat(q.split(\"=\")[1]) : 1.0,\n };\n }).sort((a, b) => b.q - a.q);\n\n for (const { type } of types) {\n if (type === \"text/html\") return true;\n if (type === \"text/markdown\" || type === \"text/plain\") return false;\n // */* is ambiguous — but browsers always list text/html before */*\n // so if we hit */* first it means no explicit HTML preference\n if (type === \"*/*\") return false;\n }\n return false;\n}\n\n// Convert extracted docs to Markdown\nfunction docsToMarkdown(\n documentedFunctions: any[],\n categories: Record,\n): string {\n const lines: string[] = [];\n lines.push(\"# Val Town Utils Documentation\");\n lines.push(\"\");\n lines.push(\n \"@std/utils is a collection of utilities for Val Town, including reading files, serving static content, getting Val Town metadata, and more.\",\n );\n lines.push(\"\");\n lines.push(\"[View val on Val Town](https://www.val.town/x/std/utils)\");\n lines.push(\"\");\n\n // Table of contents grouped by category\n for (const [category, funcNames] of Object.entries(categories)) {\n const items = funcNames.filter((name) =>\n documentedFunctions.some((d) => d.name === name)\n );\n if (items.length === 0) continue;\n lines.push(`## ${category}`);\n lines.push(\"\");\n\n for (const name of items) {\n const doc = documentedFunctions.find((d) => d.name === name);\n if (!doc) continue;\n\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 lines.push(\"\");\n lines.push(`[source](${sourceUrl})`);\n lines.push(\"\");\n\n if (doc.signature) {\n lines.push(\"```typescript\");\n lines.push(doc.signature);\n lines.push(\"```\");\n lines.push(\"\");\n }\n\n if (doc.description) {\n lines.push(doc.description);\n lines.push(\"\");\n }\n\n if (doc.tags.param && doc.tags.param.length > 0) {\n lines.push(\"**Parameters**\");\n lines.push(\"\");\n for (const param of doc.tags.param) {\n lines.push(\n `- **${param.name}** – ${param.description.replace(/^ *-/, \"\")}`,\n );\n }\n lines.push(\"\");\n }\n\n const returns = doc.tags.returns || doc.tags.return;\n if (returns && returns.length > 0) {\n lines.push(`**Returns:** ${returns[0]}`);\n lines.push(\"\");\n }\n\n if (doc.tags.example && doc.tags.example.length > 0) {\n lines.push(\"**Example**\");\n lines.push(\"\");\n const exampleText = doc.tags.example.join(\"\\n\\n\");\n // If the example already has code fences, use as-is; otherwise wrap\n if (exampleText.includes(\"```\")) {\n lines.push(exampleText);\n } else {\n lines.push(\"```ts\");\n lines.push(exampleText);\n lines.push(\"```\");\n }\n lines.push(\"\");\n }\n\n lines.push(\"---\");\n lines.push(\"\");\n }\n }\n\n return lines.join(\"\\n\");\n}\n\nconst SOURCE_FILES = [\n \"file.ts\",\n \"serve-file.ts\",\n \"parseImportMeta.ts\",\n \"is-main.ts\",\n \"test.tsx\",\n \"static.tsx\",\n];\n\nconst CATEGORIES: Record = {\n \"File Operations\": [\n \"readFile\",\n \"listFiles\",\n \"listFilesByPath\",\n \"httpEndpoint\",\n \"emailAddress\",\n \"getValId\",\n \"fetchTranspiledJavaScript\",\n ],\n \"HTTP Utilities\": [\"serveFile\", \"getContentType\", \"staticHTTPServer\"],\n \"Val Metadata\": [\"parseVal\", \"isMain\"],\n \"Testing\": [\"testServer\"],\n};\n\napp.get(\"/\", async (c) => {\n // Extract docs from all utility files\n const allDocs = await Promise.all(\n SOURCE_FILES.map((file) => extractDocs(file)),\n );\n const docs = allDocs.flat();\n\n // Filter to only documented functions\n const documentedFunctions = docs.filter((d) => d.description);\n\n const accept = c.req.header(\"Accept\");\n\n // Return Markdown for agents / non-browser clients\n if (!wantsHtml(accept)) {\n const markdown = docsToMarkdown(documentedFunctions, CATEGORIES);\n return new Response(markdown, {\n headers: { \"Content-Type\": \"text/markdown; charset=utf-8\" },\n });\n }\n\n // Return HTML for browsers\n return c.render(\n \n \n \n Val Town Utils Documentation\n \n \n \n \n \n \n \n

\n \n

\n Val Town Utils Documentation\n

\n \n View val on Val Town\n \n \n

\n @std/utils is a collection of utilities Val Town, including\n reading files, serving static content, getting Val Town metadata,\n and more.\n

\n\n

\n\n {documentedFunctions.map((doc) => (\n \n ))}\n

\n \n ,\n );\n});\n\napp.onError((err) => Promise.reject(err));\n\nexport default app.fetch;",[235],"3f115158-2e94-11f1-822c-42dde27851f2","README.md","019d4e4a-0605-750c-8d57-694f7184c908",["D",1775134967315],"# Val Town Standard Utilities\n\n## TODOs\n\n- [ ] Bug: why is testServer not properly shown in the left sidebar and is\n listed as (anonymous) in the docs?\n- [ ] In the parameters section, any code (ie `backticks`) should be\n syntax-highlighted as \\ blocks.\n- [ ] Bug: Figure out how to get `text-sm` to affect \\ blocks with syntax\n highlighting. Right now, the size from the typescript syntax highlighting\n takes precedence.\n- [ ] The syntax highlighting looks a little weird with background color of\n white on certain elements.\n- [ ] Add a copy button on the example\n- [ ] Add precise type information for all inputs and outputs. Users should know\n exactly every field of every input and every output type. This should be\n easy given the typescript info we have on all inputs and ouputs. If any\n are underspecified, let me know. same as before.",[242],"pulls","branches","forks",9,"envVars",{"_255":147,"_257":147},"connections",{"_255":147,"_256":147},"count","unfilledCount","emptyCount",{"_18":241,"_20":242,"_139":243,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":320,"_69":147,"_148":102,"_150":245,"_152":26,"_153":-5,"_275":321,"_91":322},{"_18":234,"_20":235,"_139":236,"_141":-5,"_142":72,"_143":70,"_145":38,"_22":317,"_69":238,"_148":165,"_150":239,"_152":26,"_153":-5,"_275":318,"_91":319},{"_18":228,"_20":229,"_139":230,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":314,"_69":147,"_148":165,"_150":232,"_152":26,"_153":-5,"_275":315,"_91":316},{"_18":222,"_20":223,"_139":224,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":311,"_69":147,"_148":165,"_150":226,"_152":26,"_153":-5,"_275":312,"_91":313},{"_18":216,"_20":217,"_139":218,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":308,"_69":147,"_148":165,"_150":220,"_152":26,"_153":-5,"_275":309,"_91":310},{"_18":210,"_20":211,"_139":212,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":305,"_69":147,"_148":149,"_150":214,"_152":26,"_153":-5,"_275":306,"_91":307},{"_18":204,"_20":205,"_139":206,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":302,"_69":147,"_148":149,"_150":208,"_152":26,"_153":-5,"_275":303,"_91":304},{"_18":198,"_20":199,"_139":200,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":299,"_69":147,"_148":165,"_150":202,"_152":26,"_153":-5,"_275":300,"_91":301},{"_18":192,"_20":193,"_139":194,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":296,"_69":147,"_148":149,"_150":196,"_152":26,"_153":-5,"_275":297,"_91":298},{"_18":186,"_20":187,"_139":188,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":293,"_69":147,"_148":165,"_150":190,"_152":26,"_153":-5,"_275":294,"_91":295},{"_18":180,"_20":181,"_139":182,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":290,"_69":147,"_148":149,"_150":184,"_152":26,"_153":-5,"_275":291,"_91":292},{"_18":174,"_20":175,"_139":176,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":287,"_69":147,"_148":165,"_150":178,"_152":26,"_153":-5,"_275":288,"_91":289},{"_18":168,"_20":169,"_139":170,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":284,"_69":147,"_148":149,"_150":172,"_152":26,"_153":-5,"_275":285,"_91":286},{"_18":161,"_20":162,"_139":163,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":281,"_69":147,"_148":165,"_150":166,"_152":26,"_153":-5,"_275":282,"_91":283},{"_18":155,"_20":156,"_139":157,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":278,"_69":147,"_148":149,"_150":159,"_152":26,"_153":-5,"_275":279,"_91":280},{"_18":137,"_20":138,"_139":140,"_141":-5,"_142":72,"_143":144,"_145":38,"_22":274,"_69":147,"_148":149,"_150":151,"_152":26,"_153":-5,"_275":276,"_91":277},["D",1775134967315],"children",[],[138],["D",1775134967315],[],[156],["D",1775134967315],[],[162],["D",1775134967315],[],[169],["D",1775134967315],[],[175],["D",1775134967315],[],[181],["D",1775134967315],[],[187],["D",1775134967315],[],[193],["D",1775134967315],[],[199],["D",1775134967315],[],[205],["D",1775134967315],[],[211],["D",1775134967315],[],[217],["D",1775134967315],[],[223],["D",1775134967315],[],[229],["D",1775135006240],[],[235],["D",1775134967315],[],[242],["D",1740674076598],["D",1789681830046],{"_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":361,"_362":363,"_364":365,"_366":26,"_367":26,"_368":26,"_369":38,"_370":-5,"_371":-7,"_372":-7,"_373":147,"_374":26,"_375":26,"_376":-5,"_377":26,"_378":26,"_379":26,"_380":-5},"ENV",{"_332":333,"_334":335,"_336":117,"_337":338,"_339":340,"_341":342,"_343":344,"_345":346,"_347":348,"_349":350,"_351":352,"_353":354,"_355":356,"_357":358,"_359":360},"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