Val Town Utils Documentation

 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  \"serve-immutable-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\": [\n    \"serveFile\",\n    \"serveImmutableFile\",\n    \"immutableFileUrl\",\n    \"getContentType\",\n    \"hotReload\",\n  ],\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;","label",[18],"pulls",2,"branches","forks",9,"envVars",{"_177":26,"_179":26},"connections",{"_177":26,"_178":26},"count","unfilledCount","emptyCount",{"_32":339,"_13":340,"_66":341,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":342,"_38":26,"_68":21,"_164":343,"_70":24,"_166":-5,"_207":344,"_17":345},{"_32":160,"_13":18,"_66":67,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":336,"_38":26,"_68":69,"_164":165,"_70":24,"_166":-5,"_207":337,"_17":338},{"_32":329,"_13":330,"_66":331,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":332,"_38":26,"_68":69,"_164":333,"_70":24,"_166":-5,"_207":334,"_17":335},{"_32":322,"_13":323,"_66":324,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":325,"_38":26,"_68":69,"_164":326,"_70":24,"_166":-5,"_207":327,"_17":328},{"_32":315,"_13":316,"_66":317,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":318,"_38":26,"_68":69,"_164":319,"_70":24,"_166":-5,"_207":320,"_17":321},{"_32":308,"_13":309,"_66":310,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":311,"_38":26,"_68":205,"_164":312,"_70":24,"_166":-5,"_207":313,"_17":314},{"_32":301,"_13":302,"_66":303,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":304,"_38":26,"_68":69,"_164":305,"_70":24,"_166":-5,"_207":306,"_17":307},{"_32":294,"_13":295,"_66":296,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":297,"_38":26,"_68":205,"_164":298,"_70":24,"_166":-5,"_207":299,"_17":300},{"_32":287,"_13":288,"_66":289,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":290,"_38":26,"_68":205,"_164":291,"_70":24,"_166":-5,"_207":292,"_17":293},{"_32":280,"_13":281,"_66":282,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":283,"_38":26,"_68":205,"_164":284,"_70":24,"_166":-5,"_207":285,"_17":286},{"_32":273,"_13":274,"_66":275,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":276,"_38":26,"_68":69,"_164":277,"_70":24,"_166":-5,"_207":278,"_17":279},{"_32":266,"_13":267,"_66":268,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":269,"_38":26,"_68":205,"_164":270,"_70":24,"_166":-5,"_207":271,"_17":272},{"_32":259,"_13":260,"_66":261,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":262,"_38":26,"_68":69,"_164":263,"_70":24,"_166":-5,"_207":264,"_17":265},{"_32":252,"_13":253,"_66":254,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":255,"_38":26,"_68":205,"_164":256,"_70":24,"_166":-5,"_207":257,"_17":258},{"_32":245,"_13":246,"_66":247,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":248,"_38":26,"_68":69,"_164":249,"_70":24,"_166":-5,"_207":250,"_17":251},{"_32":238,"_13":239,"_66":240,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":241,"_38":26,"_68":205,"_164":242,"_70":24,"_166":-5,"_207":243,"_17":244},{"_32":231,"_13":232,"_66":233,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":234,"_38":26,"_68":69,"_164":235,"_70":24,"_166":-5,"_207":236,"_17":237},{"_32":224,"_13":225,"_66":226,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":227,"_38":26,"_68":205,"_164":228,"_70":24,"_166":-5,"_207":229,"_17":230},{"_32":217,"_13":218,"_66":219,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":220,"_38":26,"_68":69,"_164":221,"_70":24,"_166":-5,"_207":222,"_17":223},{"_32":210,"_13":211,"_66":212,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":213,"_38":26,"_68":205,"_164":214,"_70":24,"_166":-5,"_207":215,"_17":216},{"_32":201,"_13":202,"_66":203,"_42":-5,"_34":35,"_161":39,"_162":89,"_36":204,"_38":26,"_68":205,"_164":206,"_70":24,"_166":-5,"_207":208,"_17":209},"de174fc3-710a-4cd7-b864-f46ab81c2b66","test.tsx","01a086e3-3b6c-7531-a408-fd4f280e5672",["D",1788969433967],"script","/** @jsxImportSource npm:preact */\nimport { makeBadge } from \"npm:badge-maker\";\nimport { render } from \"npm:preact-render-to-string\";\nimport prettyMilliseconds from \"npm:pretty-ms\";\n\ninterface TestGroup {\n  name: string;\n  tests: TestCase[];\n  before?: () => void;\n  after?: () => void;\n}\n\ninterface TestCase {\n  name: string;\n  // deno-lint-ignore ban-types\n  function: Function;\n}\n\ninterface TestOutput {\n  message?: string;\n  pass: boolean;\n  duration: number;\n}\n\nasync function runTest(test: TestCase): Promise {\n  let pass, message;\n  const start = performance.now();\n  try {\n    await test.function();\n    pass = true;\n  } catch (e: any) {\n    message = e.message;\n    pass = false;\n  }\n  return {\n    message,\n    pass,\n    duration: performance.now() - start,\n  };\n}\n\nfunction renderBadge(\n  { label, passedCount, testCount }: {\n    label?: string;\n    passedCount: number;\n    testCount: number;\n  },\n) {\n  return makeBadge({\n    label: label ?? \"Tests\",\n    message: `${passedCount}/${testCount} passed`,\n    color: passedCount === testCount ? \"brightgreen\" : \"red\",\n  });\n}\n\nfunction Badge(\n  { label, passedCount, testCount }: {\n    label?: string;\n    passedCount: number;\n    testCount: number;\n  },\n) {\n  const svgMarkup = renderBadge({ label, passedCount, testCount });\n  const srcDoc = `${svgMarkup}`;\n  return (\n    \n  );\n}\n\nfunction renderTestResults(\n  testGroups: TestGroup[],\n  outputs: { [groupName: string]: TestOutput[] },\n) {\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  return render(\n    \n      \n        Tests\n      \n      \n        \n          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                  \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                        \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};","children",[],[202],"60296ac9-298e-44e5-9d8f-5a5f729735e3","static.tsx","01a086e3-3b6c-7531-a408-fa836d3e4439",["D",1788969433967],"import { parseVal } from \"./parseImportMeta.ts\";\nimport { serveFile } from \"./serve-file.ts\";\nimport { serveImmutableFile } from \"./serve-immutable-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 * Asset files are served via `serveImmutableFile`, so they get immutable\n * version-addressed browser caching automatically (bare paths 302 into\n * `/__immutable//`, and publishing the val bumps the version, invalidating\n * every cached file at once); `/` and `/index.html` always serve fresh.\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, serveFn: typeof serveFile = serveFile) => {\n    try {\n      return await serveFn(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    // \"/\" and /index.html — the HTML shell — always serve fresh (never immutable),\n    // so a new publish shows up on the next page load.\n    if (pathname === \"/\" || pathname === \"/index.html\") {\n      return await serve(\"/index.html\");\n    }\n\n    // serveImmutableFile 302s bare paths into /__immutable//, serves\n    // current-version paths with immutable browser caching, 404s other versions.\n    return await serve(pathname, serveImmutableFile);\n  };\n}",[],[211],"c7f5e715-33bb-4906-82d2-b22898fe3b39","static.test.ts","01a086e3-3b6c-7531-a408-f784823d214d",["D",1788969433967],"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: \"bare file paths 302 into /__immutable//\",\n        function: async () => {\n          const server = staticHTTPServer(import.meta.url);\n          const { version } = parseVal(import.meta.url);\n\n          const response = await server(\n            new Request(\"https://example.com/README.md\"),\n          );\n          expect(response.status).toBe(302);\n          expect(response.headers.get(\"Location\")).toBe(\n            `/__immutable/${version}/README.md`,\n          );\n        },\n      },\n      {\n        name: \"stamped paths serve the file with immutable cache headers\",\n        function: async () => {\n          const server = staticHTTPServer(import.meta.url);\n          const { version } = parseVal(import.meta.url);\n\n          const response = await server(\n            new Request(`https://example.com/__immutable/${version}/test.tsx`),\n          );\n          expect(response.status).toBe(200);\n          expect(response.headers.get(\"Content-Type\")).toBe(\"text/javascript\");\n          expect(response.headers.get(\"Cache-Control\")).toBe(\n            \"public, max-age=31536000, immutable\",\n          );\n\n          const content = await response.text();\n          expect(content).toContain(\"testServer\");\n        },\n      },\n      {\n        name: \"non-current version paths return 404\",\n        function: async () => {\n          const server = staticHTTPServer(import.meta.url);\n          const response = await server(\n            new Request(\"https://example.com/__immutable/1/README.md\"),\n          );\n          expect(response.status).toBe(404);\n        },\n      },\n      {\n        name: \"non-existent file returns 404\",\n        function: async () => {\n          const server = staticHTTPServer(import.meta.url);\n          const { version } = parseVal(import.meta.url);\n          const request = new Request(\n            `https://example.com/__immutable/${version}/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          // bare paths 302 into versioned space\n          const fileResponse = await server(\n            new Request(\"https://example.com/README.md\"),\n          );\n          expect(fileResponse.status).toBe(302);\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 { version } = parseVal(import.meta.url);\n          const response = await server(\n            new Request(`https://example.com/__immutable/${version}/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        name: \"root index.html stays fresh: no redirect, no immutable header\",\n        function: async () => {\n          const server = staticHTTPServer(import.meta.url);\n\n          // 404 only because std/utils has no index.html — the point is \"/\"\n          // hits the fresh serveFile path: no 302, no Cache-Control.\n          const root = await server(new Request(\"https://example.com/\"));\n          expect(root.status).toBe(404);\n          expect(root.headers.get(\"Cache-Control\")).toBeNull();\n\n          // Bare /index.html requests take the same fresh path.\n          const indexHtml = await server(\n            new Request(\"https://example.com/index.html\"),\n          );\n          expect(indexHtml.status).toBe(404);\n          expect(indexHtml.headers.get(\"Cache-Control\")).toBeNull();\n        },\n      },\n    ],\n  },\n];\n\nexport default testServer(staticTests);\n",[],[218],"49eb7b92-d20f-4473-bda4-734a66c75f29","serve-immutable-file.ts","01a086e3-3b6c-7531-a408-f1296c78d334",["D",1788969433967],"import { parseVal } from \"./parseImportMeta.ts\";\nimport { serveFile } from \"./serve-file.ts\";\n\n/** Cache-Control for version-addressed files: cache for a year, never revalidate. */\nconst IMMUTABLE = \"public, max-age=31536000, immutable\";\n\n/** Matches the reserved prefix \"/__immutable//\", e.g. \"/__immutable/45/frontend/index.tsx\". */\nconst IMMUTABLE_PATH = /^\\/__immutable\\/(\\d+)\\/(.*)$/;\n\n/**\n * Makes your val's frontend faster by letting browsers cache its files immutably —\n * repeat visits load them straight from the cache instead of re-downloading them.\n * Works by putting the val's current version in the URL:\n * `immutableFileUrl(\"/frontend/index.tsx\")` → `\"/__immutable/45/frontend/index.tsx\"`.\n * Publishing the val bumps the version, which changes every URL at once — browsers\n * refetch each file exactly once, and caches never go stale.\n *\n * Use it in your (never-cached) HTML shell to stamp the client entry script and\n * favicon, and route `/__immutable/*` to `serveImmutableFile`. The version prefixes\n * the whole path, so the entry's relative imports stay in versioned space — the\n * entire client graph ends up immutably cached.\n *\n * @param path - The file path to stamp (e.g. \"/frontend/index.tsx\" or \"/logo.png\")\n * @param metaImportUrl - Optional. The import.meta.url to determine which val's version to stamp. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns The version-addressed URL (e.g. \"/__immutable/45/frontend/index.tsx\")\n *\n * @example\n * ```ts\n * // In your (never-cached) HTML shell:\n * `;\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}",[],[288],"79739402-899f-43c1-b0d0-1b1df9ff1f71","hot-reload.test.ts","01a086e3-3b6b-76c1-827d-6a5d5f362efa",["D",1788969433967],"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",[],[295],"ea52f6b9-e650-4bd0-8517-8e5be86e21fc","hot-reload.example.tsx","01a086e3-3b6b-76c1-827d-67033dc0d234",["D",1788969433967],"/** @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        \n          🔥 Hot Reload Demo!!
\n          \n            ✅ Hot reload is active! Try editing this file and saving.\n          
\n          \n            Edit anything below this line and save to see the page refresh\n            automatically:\n          
\n          Hello, world!
\n          \n            The current time at deploy was:{\" \"}\n            \n              {new Date().toLocaleTimeString()}\n            \n          
\n        
\n      \n    ,\n  );\n});\n\napp.onError((err) => Promise.reject(err));\n\nexport default hotReload(app.fetch);",[],[302],"c16e76f0-cf47-40f1-9c7d-c5bc0b71510c","file.ts","01a086e3-3b6b-76c1-827d-62386a3f0b98",["D",1788969433967],"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 ? \"VT-Serve-File\" : \"Deno/VT-Serve-File\",\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}",[],[309],"baff76a1-d0e9-48d4-87c7-6934a403921e","file.test.ts","01a086e3-3b6b-76c1-827d-5c30e33acf6c",["D",1788969433967],"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);",[],[316],"1f4ce2be-ff71-45f0-ba83-46ebcc571fcf","example.test.ts","01a086e3-3b6b-76c1-827d-5967e4733416",["D",1788969433967],"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);",[],[323],"0029ddb3-cdc4-4bbe-a391-e8eae862a18e","_tests.ts","01a086e3-3b6b-76c1-827d-571b3fd175de",["D",1788969433967],"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 { serveImmutableFileTests } from \"./serve-immutable-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  ...serveImmutableFileTests,\n  ...staticTests,\n  ...isMainTests,\n]);",[],[330],["D",1788969433967],[],[18],"181f174c-7c79-478f-9e8f-131b20833254","README.md","01a086e3-3b6b-76c1-827d-4e79a24bdbec",["D",1788969433967],"# @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, assets by path with automatic immutable caching, 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| `serveImmutableFile` | Serve `/__immutable//` URLs with immutable browser caching; bare paths 302 into the current version, other versions 404 |\n| `immutableFileUrl` | Version-address a file path for immutable caching (`/frontend/index.tsx` → `/__immutable/45/frontend/index.tsx`) |\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## 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| `serve-immutable-file.ts` | script | Version-addressed file serving with immutable caching (`serveImmutableFile`, `immutableFileUrl`) |\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",[],[340],["D",1740674076598],["D",1789681830046],{"_11":12,"_132":128},{"_11":12,"_127":-5,"_73":128,"_30":-5,"_129":130,"_131":24},{"_38":39,"_13":16,"_32":35,"_118":76,"_119":62,"_120":121,"_122":80,"_123":76,"_124":95,"_125":14,"_126":12},"ctx",{"_51":-5,"_152":384,"_385":386,"_387":388,"_389":24,"_390":24,"_391":24,"_392":89,"_393":-5,"_394":-7,"_395":-7,"_396":26,"_397":24,"_398":24,"_399":-5,"_400":24,"_401":24,"_402":24,"_403":-5},"ENV",{"_355":356,"_357":358,"_359":63,"_360":361,"_362":363,"_364":365,"_366":367,"_368":369,"_370":371,"_372":373,"_374":375,"_376":377,"_378":379,"_380":381,"_382":383},"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"]
History · _docs.tsx
