Val Town Utils Documentation

[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_386":387,"_388":389},"routes/_app.x.$handle.$name",{"_106":105,"_38":51,"_114":96,"_33":115,"_13":14,"_116":-5,"_11":117,"_118":119,"_120":121,"_122":123,"_124":125,"_26":-5,"_126":-5,"_127":-5,"_128":31,"_129":130,"_131":64,"_132":-5,"_133":-5,"_134":135},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":18,"_19":-5},"project",{"_49":50,"_38":51,"_44":52,"_53":-5,"_54":31,"_55":56,"_57":56,"_58":59,"_60":-5,"_19":61,"_62":37,"_63":64,"_65":-5,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":77,"_78":-5,"_79":80,"_81":80,"_82":83,"_84":83,"_85":83,"_86":80,"_87":80,"_88":89,"_90":91,"_92":93,"_94":31},"version",256,"changes",[25],"aiChatInfo",{"_20":21,"_22":-5,"_23":-5,"_24":-5},"userId","aiChatMessageId","e9a52a71-8974-4b37-832b-3253dfcf98f9","aiChatThreadId","aiChatThreadUserId","aiChatThreadTitle",{"_26":27,"_28":29,"_30":31,"_32":31,"_33":34,"_35":34},"file",{"_36":37,"_38":34,"_39":40,"_41":43,"_44":45,"_46":14,"_47":48,"_30":31},"previous",{"_36":37,"_38":34,"_39":40,"_41":42},"deleted",false,"deletedHere","path","_docs.tsx","latestPath","fileId","99a9eff8-b82e-11f0-9e55-0224a6c84d84","name","fileType","http","content","/** @jsxImportSource npm:hono@4.10.4/jsx */\nimport { Hono } from \"npm:hono@4.10.4\";\nimport { readFile } from \"./file.ts\";\nimport testsServer from \"./_tests.ts\";\nimport ts from \"npm:typescript@5.9.3\";\n\nconst app = new Hono();\n\napp.get(\"/badge.svg\", (c) => testsServer(c.req.raw));\n\n// Helper functions for TypeScript doc extraction\nfunction isExported(node: ts.Node): boolean {\n const mods = (node as any).modifiers as ts.NodeArray | undefined;\n return !!(mods && mods.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));\n}\n\nfunction getName(node: ts.Node): string {\n const anyNode = node as any;\n const hasDefault = anyNode.modifiers &&\n anyNode.modifiers.some((m: ts.Modifier) =>\n m.kind === ts.SyntaxKind.DefaultKeyword\n );\n\n // Handle direct name on function/class declarations\n if (anyNode.name && anyNode.name.escapedText) {\n return anyNode.name.escapedText;\n }\n\n // Handle variable declarations: export const foo = ...\n if (ts.isVariableStatement(node)) {\n const decls = node.declarationList.declarations;\n if (decls.length > 0 && ts.isIdentifier(decls[0].name)) {\n return decls[0].name.escapedText as string;\n }\n }\n\n return hasDefault ? \"default\" : \"(anonymous)\";\n}\n\nfunction collectJsDoc(node: ts.Node) {\n const tags = ts.getJSDocTags(node) || [];\n const docNodes = (node as any).jsDoc as any[] | undefined;\n\n const descParts = docNodes\n ? docNodes.map((d: any) => d.comment).filter(Boolean)\n : [];\n const description = descParts.length ? descParts.join(\"\\n\") : \"\";\n\n const byTag: Record = {};\n\n for (const tag of tags) {\n const tagName = (tag as any).tagName?.escapedText?.toString() ?? \"\";\n\n let entry: any = {};\n\n if (tagName === \"param\") {\n const paramName = tag.name?.getText?.() ?? tag.name?.escapedText ?? \"\";\n const comment = tag.comment ||\n (tag.text ? tag.text.map((x: any) => x.text).join(\"\") : \"\") ||\n \"\";\n entry = { name: String(paramName), description: String(comment) };\n } else {\n const comment = tag.comment ||\n (tag.text ? tag.text.map((x: any) => x.text).join(\"\") : \"\") ||\n \"\";\n entry = String(comment);\n }\n\n if (!byTag[tagName]) byTag[tagName] = [];\n byTag[tagName].push(entry);\n }\n\n return { description, byTag };\n}\n\ninterface TypeInfo {\n signature: string | null;\n paramTypes: Record; // paramName -> TS type string\n returnType: string | null;\n}\n\nfunction extractTypeInfo(node: ts.Node, checker: ts.TypeChecker): TypeInfo {\n const paramTypes: Record = {};\n\n // Handle variable statements with arrow functions: export const foo = (...) => ...\n if (ts.isVariableStatement(node)) {\n const decl = node.declarationList.declarations[0];\n if (decl && decl.initializer) {\n const name = ts.isIdentifier(decl.name) ? decl.name.escapedText as string : \"(anonymous)\";\n const type = checker.getTypeAtLocation(decl);\n const callSigs = type.getCallSignatures();\n if (callSigs.length > 0) {\n const sig = callSigs[0];\n const params = sig.getParameters().map((p) => {\n const paramType = checker.getTypeOfSymbolAtLocation(p, decl);\n const typeStr = checker.typeToString(paramType);\n const opt = (p.declarations?.[0] as any)?.questionToken ? \"?\" : \"\";\n paramTypes[p.getName()] = typeStr;\n return `${p.getName()}${opt}: ${typeStr}`;\n }).join(\", \");\n const ret = checker.getReturnTypeOfSignature(sig);\n const retStr = checker.typeToString(ret);\n return {\n signature: `function ${name}(${params}): ${retStr}`,\n paramTypes,\n returnType: retStr,\n };\n }\n }\n return { signature: null, paramTypes, returnType: null };\n }\n\n if (!(\"parameters\" in (node as any))) {\n return { signature: null, paramTypes, returnType: null };\n }\n\n const fn = node as ts.FunctionDeclaration | ts.MethodDeclaration | any;\n const sig = checker.getSignatureFromDeclaration(fn as any);\n if (!sig) return { signature: null, paramTypes, returnType: null };\n\n const ret = checker.getReturnTypeOfSignature(sig);\n const retStr = checker.typeToString(ret);\n const params = (fn.parameters || []).map((p: ts.ParameterDeclaration) => {\n const t = checker.getTypeAtLocation(p);\n const tStr = checker.typeToString(t);\n const pn = ((p.name as any).escapedText) ||\n checker.typeToString(checker.getTypeAtLocation(p.name));\n const opt = (p as any).questionToken ? \"?\" : \"\";\n paramTypes[pn] = tStr;\n return `${pn}${opt}: ${tStr}`;\n }).join(\", \");\n\n const name = getName(node);\n return {\n signature: `function ${name}(${params}): ${retStr}`,\n paramTypes,\n returnType: retStr,\n };\n}\n\n// Hardcoded return type overrides for functions whose return types the in-memory\n// TS compiler can't resolve (e.g. SDK types like ValTown.Vals.Files.FileRetrieveResponse).\n// These may go stale if the @valtown/sdk return types change — update them if so.\n// See https://sdk.val.town/api/typescript/resources/files/methods/retrieve for the current shape.\nconst FILE_METADATA_TYPE = `{\n name: string;\n id: string;\n path: string;\n version: number;\n updatedAt: string;\n type: \"directory\" | \"file\" | \"interval\" | \"http\" | \"email\" | \"script\";\n links: {\n self: string;\n html: string;\n module: string;\n endpoint?: string;\n email?: string;\n };\n}`;\n\nconst VAL_TYPE = `{\n username: string;\n name: string;\n version: string;\n branch: string;\n path: string;\n links: {\n self: {\n latest: string;\n pinned: string;\n val: string;\n };\n module: {\n latest: string;\n pinned: string;\n val: string;\n valPinned: string;\n };\n };\n}`;\n\nconst RETURN_TYPE_OVERRIDES: Record = {\n listFiles: `Promise<${FILE_METADATA_TYPE}[]>`,\n listFilesByPath: `Promise<${FILE_METADATA_TYPE}[]>`,\n parseVal: VAL_TYPE,\n testServer: `(req: Request) => Promise`,\n staticHTTPServer: `(request: Request) => Response | Promise`,\n};\n\nasync function extractDocs(filePath: string) {\n const sourceText = await readFile(filePath);\n\n const fileName = `/${filePath}`;\n const compilerOptions: ts.CompilerOptions = {\n target: ts.ScriptTarget.ES2022,\n module: ts.ModuleKind.ESNext,\n };\n const host: ts.CompilerHost = {\n getSourceFile: (fn, lv) =>\n ts.createSourceFile(\n fn,\n fn === fileName ? sourceText : \"\",\n lv,\n true,\n ts.ScriptKind.TS,\n ),\n writeFile: () => {},\n getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),\n useCaseSensitiveFileNames: () => true,\n getCanonicalFileName: (f) => f,\n getCurrentDirectory: () => \"/\",\n getNewLine: () => \"\\n\",\n fileExists: (fn) => fn === fileName,\n readFile: (fn) => fn === fileName ? sourceText : undefined,\n getDirectories: () => [],\n };\n\n const program = ts.createProgram([fileName], compilerOptions, host);\n const checker = program.getTypeChecker();\n const sf = program.getSourceFile(fileName)!;\n\n const items: any[] = [];\n sf.forEachChild(function walk(node) {\n if (isExported(node)) {\n const { line: startLine } = sf.getLineAndCharacterOfPosition(\n node.getStart(sf),\n );\n const { line: endLine } = sf.getLineAndCharacterOfPosition(node.getEnd());\n const { description, byTag } = collectJsDoc(node);\n const name = getName(node);\n const typeInfo = extractTypeInfo(node, checker);\n\n let { signature, returnType } = typeInfo;\n const { paramTypes } = typeInfo;\n\n // Apply hardcoded return type overrides for unresolvable SDK types\n if (RETURN_TYPE_OVERRIDES[name]) {\n returnType = RETURN_TYPE_OVERRIDES[name];\n if (signature) {\n const lastParen = signature.lastIndexOf(\")\");\n if (lastParen !== -1) {\n signature = signature.slice(0, lastParen + 1) + \": \" + returnType;\n }\n }\n }\n\n items.push({\n name,\n filePath,\n start: startLine + 1,\n end: endLine + 1,\n description,\n tags: byTag,\n signature,\n paramTypes,\n returnType,\n });\n }\n ts.forEachChild(node, walk);\n });\n\n return items;\n}\n\n/** Render inline backtick text as
 elements, and linkify VALTOWN_ENTRYPOINT references */\nfunction renderDescription(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/** Strip leading dash and render with inline code */\nfunction renderParamDescription(text: string) {\n  const cleaned = text.replace(/^ *-\\s*/, \"\").replace(/^Optional\\.\\s*/, \"\").replace(/^The\\s+/, \"the \");\n  return renderDescription(cleaned);\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      \n        {renderDescription(doc.description)}\n      
\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                  {renderDescription(returnsDesc)}
\n                )}\n              
\n            ) : (\n              \n                ({doc.returnType})\n                {returnsDesc ? \": \" : \"\"}\n                {returnsDesc && (\n                  {renderDescription(returnsDesc)}\n                )}\n              
\n            )}\n          
\n        );\n      })()}\n\n      {doc.tags.example && doc.tags.example.length > 0 && (\n        \n          Example
\n          \n            \n            {doc.tags.example.join('\\n\\n').replace(\"```ts\\n\", \"\").replace(\"```\", \"\")}\n          
\n        
\n      )}\n    
\n  );\n}\n\napp.get(\"/\", async (c) => {\n  // Extract docs from all utility files\n  const files = [\n    \"file.ts\",\n    \"serve-file.ts\",\n    \"parseImportMeta.ts\",\n    \"is-main.ts\",\n    \"test.tsx\",\n    \"static.tsx\",\n    \"hot-reload.ts\",\n  ];\n  const allDocs = await Promise.all(files.map((file) => extractDocs(file)));\n  const docs = allDocs.flat();\n\n  // Filter to only documented functions\n  const documentedFunctions = docs.filter((d) => d.description);\n\n  // Group functions by category\n  const categories = {\n    \"File Operations\": [\n      \"readFile\",\n      \"listFiles\",\n      \"listFilesByPath\",\n      \"httpEndpoint\",\n      \"emailAddress\",\n      \"getValId\",\n      \"fetchTranspiledJavaScript\",\n    ],\n    \"HTTP Utilities\": [\"serveFile\", \"getContentType\", \"staticHTTPServer\", \"hotReload\"],\n    \"Val Metadata\": [\"parseVal\", \"isMain\"],\n    \"Testing\": [\"testServer\"],\n  };\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            \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;","/** @jsxImportSource npm:hono@4.10.4/jsx */\nimport { Hono } from \"npm:hono@4.10.4\";\nimport { readFile } from \"./file.ts\";\nimport testsServer from \"./_tests.ts\";\nimport ts from \"npm:typescript@5.9.3\";\n\nconst app = new Hono();\n\napp.get(\"/badge.svg\", (c) => testsServer(c.req.raw));\n\n// Helper functions for TypeScript doc extraction\nfunction isExported(node: ts.Node): boolean {\n  const mods = (node as any).modifiers as ts.NodeArray | undefined;\n  return !!(mods && mods.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));\n}\n\nfunction getName(node: ts.Node): string {\n  const anyNode = node as any;\n  const hasDefault = anyNode.modifiers &&\n    anyNode.modifiers.some((m: ts.Modifier) =>\n      m.kind === ts.SyntaxKind.DefaultKeyword\n    );\n\n  // Handle direct name on function/class declarations\n  if (anyNode.name && anyNode.name.escapedText) {\n    return anyNode.name.escapedText;\n  }\n\n  // Handle variable declarations: export const foo = ...\n  if (ts.isVariableStatement(node)) {\n    const decls = node.declarationList.declarations;\n    if (decls.length > 0 && ts.isIdentifier(decls[0].name)) {\n      return decls[0].name.escapedText as string;\n    }\n  }\n\n  return hasDefault ? \"default\" : \"(anonymous)\";\n}\n\nfunction collectJsDoc(node: ts.Node) {\n  const tags = ts.getJSDocTags(node) || [];\n  const docNodes = (node as any).jsDoc as any[] | undefined;\n\n  const descParts = docNodes\n    ? docNodes.map((d: any) => d.comment).filter(Boolean)\n    : [];\n  const description = descParts.length ? descParts.join(\"\\n\") : \"\";\n\n  const byTag: Record = {};\n\n  for (const tag of tags) {\n    const tagName = (tag as any).tagName?.escapedText?.toString() ?? \"\";\n\n    let entry: any = {};\n\n    if (tagName === \"param\") {\n      const paramName = tag.name?.getText?.() ?? tag.name?.escapedText ?? \"\";\n      const comment = tag.comment ||\n        (tag.text ? tag.text.map((x: any) => x.text).join(\"\") : \"\") ||\n        \"\";\n      entry = { name: String(paramName), description: String(comment) };\n    } else {\n      const comment = tag.comment ||\n        (tag.text ? tag.text.map((x: any) => x.text).join(\"\") : \"\") ||\n        \"\";\n      entry = String(comment);\n    }\n\n    if (!byTag[tagName]) byTag[tagName] = [];\n    byTag[tagName].push(entry);\n  }\n\n  return { description, byTag };\n}\n\ninterface TypeInfo {\n  signature: string | null;\n  paramTypes: Record; // paramName -> TS type string\n  returnType: string | null;\n}\n\nfunction extractTypeInfo(node: ts.Node, checker: ts.TypeChecker): TypeInfo {\n  const paramTypes: Record = {};\n\n  // Handle variable statements with arrow functions: export const foo = (...) => ...\n  if (ts.isVariableStatement(node)) {\n    const decl = node.declarationList.declarations[0];\n    if (decl && decl.initializer) {\n      const name = ts.isIdentifier(decl.name) ? decl.name.escapedText as string : \"(anonymous)\";\n      const type = checker.getTypeAtLocation(decl);\n      const callSigs = type.getCallSignatures();\n      if (callSigs.length > 0) {\n        const sig = callSigs[0];\n        const params = sig.getParameters().map((p) => {\n          const paramType = checker.getTypeOfSymbolAtLocation(p, decl);\n          const typeStr = checker.typeToString(paramType);\n          const opt = (p.declarations?.[0] as any)?.questionToken ? \"?\" : \"\";\n          paramTypes[p.getName()] = typeStr;\n          return `${p.getName()}${opt}: ${typeStr}`;\n        }).join(\", \");\n        const ret = checker.getReturnTypeOfSignature(sig);\n        const retStr = checker.typeToString(ret);\n        return {\n          signature: `function ${name}(${params}): ${retStr}`,\n          paramTypes,\n          returnType: retStr,\n        };\n      }\n    }\n    return { signature: null, paramTypes, returnType: null };\n  }\n\n  if (!(\"parameters\" in (node as any))) {\n    return { signature: null, paramTypes, returnType: null };\n  }\n\n  const fn = node as ts.FunctionDeclaration | ts.MethodDeclaration | any;\n  const sig = checker.getSignatureFromDeclaration(fn as any);\n  if (!sig) return { signature: null, paramTypes, returnType: null };\n\n  const ret = checker.getReturnTypeOfSignature(sig);\n  const retStr = checker.typeToString(ret);\n  const params = (fn.parameters || []).map((p: ts.ParameterDeclaration) => {\n    const t = checker.getTypeAtLocation(p);\n    const tStr = checker.typeToString(t);\n    const pn = ((p.name as any).escapedText) ||\n      checker.typeToString(checker.getTypeAtLocation(p.name));\n    const opt = (p as any).questionToken ? \"?\" : \"\";\n    paramTypes[pn] = tStr;\n    return `${pn}${opt}: ${tStr}`;\n  }).join(\", \");\n\n  const name = getName(node);\n  return {\n    signature: `function ${name}(${params}): ${retStr}`,\n    paramTypes,\n    returnType: retStr,\n  };\n}\n\n// Hardcoded return type overrides for functions whose return types the in-memory\n// TS compiler can't resolve (e.g. SDK types like ValTown.Vals.Files.FileRetrieveResponse).\n// These may go stale if the @valtown/sdk return types change — update them if so.\n// See https://sdk.val.town/api/typescript/resources/files/methods/retrieve for the current shape.\nconst FILE_METADATA_TYPE = `{\n  name: string;\n  id: string;\n  path: string;\n  version: number;\n  updatedAt: string;\n  type: \"directory\" | \"file\" | \"interval\" | \"http\" | \"email\" | \"script\";\n  links: {\n    self: string;\n    html: string;\n    module: string;\n    endpoint?: string;\n    email?: string;\n  };\n}`;\n\nconst VAL_TYPE = `{\n  username: string;\n  name: string;\n  version: string;\n  branch: string;\n  path: string;\n  links: {\n    self: {\n      latest: string;\n      pinned: string;\n      val: string;\n    };\n    module: {\n      latest: string;\n      pinned: string;\n      val: string;\n      valPinned: string;\n    };\n  };\n}`;\n\nconst RETURN_TYPE_OVERRIDES: Record = {\n  listFiles: `Promise<${FILE_METADATA_TYPE}[]>`,\n  listFilesByPath: `Promise<${FILE_METADATA_TYPE}[]>`,\n  parseVal: VAL_TYPE,\n  testServer: `(req: Request) => Promise`,\n  staticHTTPServer: `(request: Request) => Response | Promise`,\n};\n\nasync function extractDocs(filePath: string) {\n  const sourceText = await readFile(filePath);\n\n  const fileName = `/${filePath}`;\n  const compilerOptions: ts.CompilerOptions = {\n    target: ts.ScriptTarget.ES2022,\n    module: ts.ModuleKind.ESNext,\n  };\n  const host: ts.CompilerHost = {\n    getSourceFile: (fn, lv) =>\n      ts.createSourceFile(\n        fn,\n        fn === fileName ? sourceText : \"\",\n        lv,\n        true,\n        ts.ScriptKind.TS,\n      ),\n    writeFile: () => {},\n    getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),\n    useCaseSensitiveFileNames: () => true,\n    getCanonicalFileName: (f) => f,\n    getCurrentDirectory: () => \"/\",\n    getNewLine: () => \"\\n\",\n    fileExists: (fn) => fn === fileName,\n    readFile: (fn) => fn === fileName ? sourceText : undefined,\n    getDirectories: () => [],\n  };\n\n  const program = ts.createProgram([fileName], compilerOptions, host);\n  const checker = program.getTypeChecker();\n  const sf = program.getSourceFile(fileName)!;\n\n  const items: any[] = [];\n  sf.forEachChild(function walk(node) {\n    if (isExported(node)) {\n      const { line: startLine } = sf.getLineAndCharacterOfPosition(\n        node.getStart(sf),\n      );\n      const { line: endLine } = sf.getLineAndCharacterOfPosition(node.getEnd());\n      const { description, byTag } = collectJsDoc(node);\n      const name = getName(node);\n      const typeInfo = extractTypeInfo(node, checker);\n\n      let { signature, returnType } = typeInfo;\n      const { paramTypes } = typeInfo;\n\n      // Apply hardcoded return type overrides for unresolvable SDK types\n      if (RETURN_TYPE_OVERRIDES[name]) {\n        returnType = RETURN_TYPE_OVERRIDES[name];\n        if (signature) {\n          const lastParen = signature.lastIndexOf(\")\");\n          if (lastParen !== -1) {\n            signature = signature.slice(0, lastParen + 1) + \": \" + returnType;\n          }\n        }\n      }\n\n      items.push({\n        name,\n        filePath,\n        start: startLine + 1,\n        end: endLine + 1,\n        description,\n        tags: byTag,\n        signature,\n        paramTypes,\n        returnType,\n      });\n    }\n    ts.forEachChild(node, walk);\n  });\n\n  return items;\n}\n\n/** Render inline backtick text as  elements, and linkify VALTOWN_ENTRYPOINT references */\nfunction renderDescription(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/** Strip leading dash and render with inline code */\nfunction renderParamDescription(text: string) {\n  const cleaned = text.replace(/^ *-\\s*/, \"\").replace(/^Optional\\.\\s*/, \"\").replace(/^The\\s+/, \"the \");\n  return renderDescription(cleaned);\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      \n        {renderDescription(doc.description)}\n      
\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                  {renderDescription(returnsDesc)}
\n                )}\n              
\n            ) : (\n              \n                ({doc.returnType})\n                {returnsDesc ? \": \" : \"\"}\n                {returnsDesc && (\n                  {renderDescription(returnsDesc)}\n                )}\n              
\n            )}\n          
\n        );\n      })()}\n\n      {doc.tags.example && doc.tags.example.length > 0 && (\n        \n          Example
\n          \n            \n            {doc.tags.example.join('\\n\\n').replace(\"```ts\\n\", \"\").replace(\"```\", \"\")}\n          
\n        
\n      )}\n    
\n  );\n}\n\nconst DOC_FILES = [\n  \"file.ts\",\n  \"serve-file.ts\",\n  \"parseImportMeta.ts\",\n  \"is-main.ts\",\n  \"test.tsx\",\n  \"static.tsx\",\n  \"hot-reload.ts\",\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\", \"hotReload\"],\n  \"Val Metadata\": [\"parseVal\", \"isMain\"],\n  \"Testing\": [\"testServer\"],\n};\n\nasync function getDocumentedFunctions() {\n  const allDocs = await Promise.all(DOC_FILES.map((file) => extractDocs(file)));\n  const docs = allDocs.flat();\n  return docs.filter((d) => d.description);\n}\n\n/** Strip backtick-wrapped code in descriptions for plain text / markdown output */\nfunction stripBackticks(text: string): string {\n  return text.replace(/`([^`]+)`/g, \"`$1`\");\n}\n\nfunction renderDocsMarkdown(documentedFunctions: any[]): string {\n  const lines: string[] = [];\n\n  lines.push(\"# Val Town Utils Documentation\\n\");\n  lines.push(\"[View val on Val Town](https://www.val.town/x/std/utils)\\n\");\n  lines.push(\n    \"@std/utils is a collection of utilities for Val Town, including \" +\n    \"reading files, serving static content, getting Val Town metadata, \" +\n    \"and more.\\n\",\n  );\n\n  lines.push(\"## What is the entrypoint?\\n\");\n  lines.push(\n    \"Many functions below accept an optional `metaImportUrl` parameter \" +\n    \"that defaults to the entrypoint. \" +\n    \"The entrypoint is the `import.meta.url` of the file that Val Town executed — \" +\n    \"the HTTP handler that received a request, the cron job that fired, the email handler that received a message, or the script you clicked \\\"Run\\\" on. \" +\n    \"Val Town sets this automatically via `Deno.env.get(\\\"VALTOWN_ENTRYPOINT\\\")`, \" +\n    \"so you almost never need to pass it yourself. The main reason to pass `import.meta.url` explicitly \" +\n    \"is when you're calling these functions from a different val than the one that was triggered.\\n\",\n  );\n\n  lines.push(\"---\\n\");\n\n  // Table of contents\n  lines.push(\"## Table of Contents\\n\");\n  for (const [category, funcs] of Object.entries(CATEGORIES)) {\n    const items = funcs.filter((name) =>\n      documentedFunctions.some((d: any) => d.name === name)\n    );\n    if (items.length === 0) continue;\n    lines.push(`### ${category}\\n`);\n    for (const name of items) {\n      lines.push(`- [${name}](#${name.toLowerCase()})`);\n    }\n    lines.push(\"\");\n  }\n\n  lines.push(\"---\\n\");\n\n  // Function docs\n  for (const doc of documentedFunctions) {\n    const sourceUrl = `https://www.val.town/x/std/utils/code/${doc.filePath}#L${doc.start}-${doc.end}`;\n\n    lines.push(`## ${doc.name}\\n`);\n    lines.push(`[source](${sourceUrl})\\n`);\n\n    if (doc.description) {\n      lines.push(`${stripBackticks(doc.description)}\\n`);\n    }\n\n    if (doc.signature) {\n      lines.push(\"```ts\");\n      lines.push(doc.signature);\n      lines.push(\"```\\n\");\n    }\n\n    if (doc.tags.param && doc.tags.param.length > 0) {\n      lines.push(\"### Arguments\\n\");\n      for (const param of doc.tags.param) {\n        const typeStr = doc.paramTypes?.[param.name];\n        const desc = param.description\n          ? param.description.replace(/^ *-\\s*/, \"\").replace(/^Optional\\.\\s*/, \"\").replace(/^The\\s+/, \"the \")\n          : \"\";\n        const typePart = typeStr ? ` (\\`${typeStr}\\`)` : \"\";\n        const descPart = desc ? `: ${stripBackticks(desc)}` : \"\";\n        lines.push(`- **${param.name}**${typePart}${descPart}`);\n      }\n      lines.push(\"\");\n    }\n\n    if (doc.returnType) {\n      lines.push(\"### Returns\\n\");\n      const isMultiline = doc.returnType.includes(\"\\n\");\n      const returnsDesc = doc.tags.returns && doc.tags.returns.length > 0 ? doc.tags.returns[0] : null;\n      if (isMultiline) {\n        lines.push(\"```ts\");\n        lines.push(doc.returnType);\n        lines.push(\"```\");\n        if (returnsDesc) lines.push(`\\n${stripBackticks(returnsDesc)}`);\n      } else {\n        const descPart = returnsDesc ? `: ${stripBackticks(returnsDesc)}` : \"\";\n        lines.push(`\\`${doc.returnType}\\`${descPart}`);\n      }\n      lines.push(\"\");\n    }\n\n    if (doc.tags.example && doc.tags.example.length > 0) {\n      lines.push(\"### Example\\n\");\n      lines.push(\"```ts\");\n      lines.push(doc.tags.example.join(\"\\n\\n\").replace(\"```ts\\n\", \"\").replace(\"```\", \"\"));\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            \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;","createdAt",["D",1775852488004],"branchVersion","branchId","bb8fa1c2-f528-11ef-b06d-569c3dd06744","id","bb8f592e-f528-11ef-b06d-569c3dd06744","utils",["D",1740674076598],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Val Town Utilities","imageUrl","c9143560-63b6-444f-8f9f-e2647fabe09f","pinnedFileId","pinPreview",true,"pinMigrated","screenshotVersion",90,"likeCount",6,"orgId","c606f87f-4d7e-48c8-9c39-ef5ab94aec49","tursoName","bb8f592ef52811efb06d569c3dd06744","tursoHostname","bb8f592ef52811efb06d569c3dd06744-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789508444194],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_106":105,"_113":109},"org",{"_106":105,"_107":-5,"_108":109,"_19":-5,"_110":111,"_112":31},"branch",{"_13":95,"_38":96,"_49":48,"_97":50,"_98":-5,"_99":-5,"_100":-5,"_101":-5,"_102":-5,"_103":51,"_104":105},"isOwned",285,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","std","handle","displayName","avatar","https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvdXBsb2FkZWQvaW1nXzJVaVhpQ1BId3dscVpBbkdZVWlMNjJtcjkxWS5wbmcifQ","tier","pro","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_49":50,"_38":51,"_44":381,"_53":-5,"_54":31,"_55":56,"_57":56,"_58":59,"_60":-5,"_19":61,"_62":37,"_63":64,"_65":-5,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":382,"_78":-5,"_79":80,"_81":80,"_82":83,"_84":83,"_85":83,"_86":80,"_87":80,"_88":383,"_90":384,"_92":385,"_94":31},"tree",[304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322],"files",[304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322],"counts",{"_293":278,"_294":69,"_295":296,"_297":298,"_299":300},"contents",[136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_49":286,"_38":287,"_36":288,"_158":-5,"_47":48,"_46":159,"_160":31,"_44":289,"_13":290,"_39":26,"_41":291,"_30":31,"_165":-5,"_33":292},{"_49":281,"_38":34,"_36":37,"_158":-5,"_47":48,"_46":14,"_160":31,"_44":282,"_13":283,"_39":40,"_41":43,"_30":31,"_165":284,"_33":285},{"_49":273,"_38":274,"_36":275,"_158":-5,"_47":48,"_46":276,"_160":31,"_44":277,"_13":278,"_39":40,"_41":279,"_30":31,"_165":-5,"_33":280},{"_49":267,"_38":268,"_36":269,"_158":-5,"_47":48,"_46":206,"_160":64,"_44":270,"_13":208,"_39":40,"_41":271,"_30":31,"_165":-5,"_33":272},{"_49":259,"_38":260,"_36":261,"_158":-5,"_47":48,"_46":262,"_160":64,"_44":263,"_13":264,"_39":40,"_41":265,"_30":31,"_165":-5,"_33":266},{"_49":252,"_38":253,"_36":254,"_158":-5,"_47":48,"_46":159,"_160":31,"_44":255,"_13":256,"_39":163,"_41":257,"_30":31,"_165":-5,"_33":258},{"_49":246,"_38":247,"_36":248,"_158":-5,"_47":48,"_46":228,"_160":64,"_44":249,"_13":208,"_39":40,"_41":250,"_30":31,"_165":-5,"_33":251},{"_49":240,"_38":241,"_36":242,"_158":-5,"_47":48,"_46":228,"_160":64,"_44":243,"_13":208,"_39":163,"_41":244,"_30":31,"_165":-5,"_33":245},{"_49":233,"_38":234,"_36":235,"_158":-5,"_47":48,"_46":236,"_160":64,"_44":237,"_13":222,"_39":163,"_41":238,"_30":31,"_165":-5,"_33":239},{"_49":225,"_38":226,"_36":227,"_158":-5,"_47":48,"_46":228,"_160":31,"_44":229,"_13":230,"_39":163,"_41":231,"_30":31,"_165":-5,"_33":232},{"_49":217,"_38":218,"_36":219,"_158":-5,"_47":48,"_46":220,"_160":64,"_44":221,"_13":222,"_39":40,"_41":223,"_30":31,"_165":-5,"_33":224},{"_49":211,"_38":212,"_36":213,"_158":-5,"_47":48,"_46":159,"_160":64,"_44":214,"_13":186,"_39":163,"_41":215,"_30":31,"_165":-5,"_33":216},{"_49":203,"_38":204,"_36":205,"_158":-5,"_47":48,"_46":206,"_160":64,"_44":207,"_13":208,"_39":40,"_41":209,"_30":31,"_165":-5,"_33":210},{"_49":197,"_38":198,"_36":199,"_158":-5,"_47":48,"_46":159,"_160":64,"_44":200,"_13":194,"_39":163,"_41":201,"_30":31,"_165":-5,"_33":202},{"_49":189,"_38":190,"_36":191,"_158":-5,"_47":48,"_46":192,"_160":64,"_44":193,"_13":194,"_39":40,"_41":195,"_30":31,"_165":-5,"_33":196},{"_49":181,"_38":182,"_36":183,"_158":-5,"_47":48,"_46":184,"_160":64,"_44":185,"_13":186,"_39":163,"_41":187,"_30":31,"_165":-5,"_33":188},{"_49":174,"_38":175,"_36":176,"_158":-5,"_47":48,"_46":177,"_160":31,"_44":178,"_13":162,"_39":40,"_41":179,"_30":31,"_165":-5,"_33":180},{"_49":167,"_38":168,"_36":169,"_158":-5,"_47":48,"_46":159,"_160":31,"_44":170,"_13":171,"_39":163,"_41":172,"_30":31,"_165":-5,"_33":173},{"_49":155,"_38":156,"_36":157,"_158":-5,"_47":48,"_46":159,"_160":64,"_44":161,"_13":162,"_39":163,"_41":164,"_30":31,"_165":-5,"_33":166},"7ac8c19a-3065-11f1-b279-42dde27851f2","test.tsx","3746bd4e-73bb-11f0-bdd9-0224a6c84d84","parentId",253,"latest",["D",1775334783470],18,"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};","label",[156],"7ac8ac3c-3065-11f1-b279-42dde27851f2","static.tsx","3746bace-73bb-11f0-bdd9-0224a6c84d84",["D",1775334783470],12,"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 metaImportUrl - 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 `(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\n * export default staticHTTPServer();\n *\n * // Explicit val specification\n * export default staticHTTPServer(import.meta.url);\n * ```\n */\nexport function staticHTTPServer(\n  metaImportUrl: 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, 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  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}",[168],"41891bf8-0768-11f1-91f9-42dde27851f2","static.test.ts","3746b5ce-73bb-11f0-bdd9-0224a6c84d84",245,["D",1770827978247],"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);",[175],"a9f877e2-0768-11f1-bb6e-42dde27851f2","serve-file.ts","3746b452-73bb-11f0-bdd9-0224a6c84d84",250,["D",1770828153464],3,"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",[182],"99aa23d8-b82e-11f0-9e55-0224a6c84d84","serve-file.test.ts","3746add6-73bb-11f0-bdd9-0224a6c84d84",209,["D",1762117073435],4,"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);",[190],"7ac89a4e-3065-11f1-b279-42dde27851f2","parseImportMeta.ts","3746ab42-73bb-11f0-bdd9-0224a6c84d84",["D",1775334783470],"interface Val {\n  username: string;\n  name: string;\n  version: string;\n  branch: string;\n  path: string;\n  links: {\n    self: {\n      latest: string;\n      pinned: string;\n      val: string;\n    };\n    module: {\n      latest: string;\n      pinned: string;\n      val: string;\n      valPinned: string;\n    };\n  };\n}\n\n/**\n * Parses Val Town metadata from an import.meta.url.\n *\n * @param metaImportUrl - Optional. The import.meta.url to parse. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns A `Val` object with `username`, `name`, `version`, `branch`, `path`, and `links` (containing `self` and `module` URL variants)\n *\n * @example\n * ```ts\n * import { parseVal } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * const val = parseVal(import.meta.url);\n * console.log(val);\n * // Output: { username: \"username\", name: \"valname\", version: \"1\", branch: \"main\", path: \"\", links: {...} }\n * ```\n */\nexport function parseVal(metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\"): Val {\n  // Updated pattern to capture the prefix (v or p) and handle URL format variations\n  const pattern =\n    /^https:\\/\\/esm\\.town\\/(v|p)\\/([^/]+)\\/([^@]+)@(\\d+)-(.+?)(\\/.*)?$/;\n  const match = metaImportUrl.match(pattern);\n\n  if (!match) {\n    throw new Error(`Invalid ESM Town URL format: ${metaImportUrl}`);\n  }\n\n  let [, prefix, username, name, version, branch, path = \"\"] = match;\n  // Remove leading slash if present\n  path = path && path.startsWith(\"/\") ? path.substring(1) : path;\n\n  const branchPath = branch === \"main\" ? \"\" : `/branch/${branch}`;\n\n  const valURL = `https://www.val.town/x/${username}/${name}`;\n\n  return {\n    username,\n    name,\n    version,\n    branch,\n    path,\n    links: {\n      self: {\n        latest: `${valURL}${branchPath}/code/${path}`,\n        pinned: `${valURL}/branch/${branch}/version/${version}/code/${path}`,\n        val: valURL,\n      },\n      module: {\n        latest:\n          `https://esm.town/${prefix}/${username}/${name}${branchPath}/${path}`,\n        pinned:\n          `https://esm.town/${prefix}/${username}/${name}@${version}-${branch}/${path}`,\n        val: `https://esm.town/${prefix}/${username}/${name}/`,\n        valPinned:\n          `https://esm.town/${prefix}/${username}/${name}@${version}-${branch}/`,\n      },\n    },\n  };\n}\n",[198],"3746a6ce-73bb-11f0-bdd9-0224a6c84d84","parseImportMeta.test.ts","3746a732-73bb-11f0-bdd9-0224a6c84d84",116,["D",1754590837179],0,"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);",[204],"7ac891b6-3065-11f1-b279-42dde27851f2","is-main.ts","5bbcab98-7a0a-11f0-a022-0224a6c84d84",["D",1775334783470],"/**\n * Checks if the current file is the main entry point of the val.\n *\n * This is a replacement for `import.meta.main` which is not available in Val Town's environment.\n *\n * @param metaImportUrl - The `import.meta.url` of the current file\n * @returns `true` if the file is the main entry point, `false` otherwise\n *\n * @example\n * ```ts\n * import { isMain } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * if (isMain(import.meta.url)) {\n *   // Code that doesn't run if this file is imported\n *   // Useful for testing functions near their definitions\n * }\n * ```\n */\nexport function isMain(metaImportUrl: string): boolean {\n  return metaImportUrl === Deno.env.get(\"VALTOWN_ENTRYPOINT\");\n}",[212],"5e155cfa-7e1a-11f0-bfa8-0224a6c84d84","is-main.test.ts","5bbca5c6-7a0a-11f0-a022-0224a6c84d84",192,["D",1755731216104],1,"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);",[218],"aa2bc66c-3065-11f1-a524-42dde27851f2","index.ts","dc1b4790-f52b-11ef-9ee4-569c3dd06744",254,["D",1775334862977],19,"export {\n  emailAddress,\n  fetchTranspiledJavaScript,\n  getValId,\n  httpEndpoint,\n  listFiles,\n  listFilesByPath,\n  readFile,\n  readFileTranspiled,\n} from \"./file.ts\";\nexport { parseVal } from \"./parseImportMeta.ts\";\nexport { getContentType, serveFile } from \"./serve-file.ts\";\nexport { testServer } from \"./test.tsx\";\nexport { staticHTTPServer } from \"./static.tsx\";\nexport { isMain } from \"./is-main.ts\";\nexport { hotReload } from \"./hot-reload.ts\";\n\n// for backwards compatibility\nexport { parseProject } from \"https://esm.town/v/std/utils@105-main/parseImportMeta/project.ts\";",[226],"52113748-337e-11f1-a3f0-42b51c65c3df","hot-reload.ts","aa2b45de-3065-11f1-a524-42dde27851f2",255,["D",1775675306082],"import ValTown from \"npm:@valtown/sdk@1.9.0\";\nimport { parseVal } from \"./parseImportMeta.ts\";\nimport { API_URL } from \"https://esm.town/v/std/API_URL\";\n\nconst POLL_PATH = \"/__vt_hot_reload\";\nconst HOLD_DURATION_MS = 30_000;\nconst CHECK_INTERVAL_MS = 500;\n\n/**\n * Wraps an HTTP handler to enable hot reload during development.\n *\n * When a val is served on a `.val.run` domain, this wrapper:\n * 1. Injects a small script into HTML responses that long-polls for version changes\n * 2. Handles the long-poll endpoint (`/__vt_hot_reload`)\n * 3. Actively checks the Val Town API for new versions of the current branch\n * 4. When a new version is deployed, the client detects the change and reloads the page\n *\n * On custom domains (non `.val.run`), the handler passes through unmodified.\n *\n * @param handler - Your HTTP fetch handler\n * @returns A wrapped handler with hot reload support\n *\n * @example\n * ```ts\n * import { hotReload } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * export default hotReload(async (req: Request) => {\n *   return new Response(\"Hello!
\", {\n *     headers: { \"Content-Type\": \"text/html\" },\n *   });\n * });\n * ```\n */\nexport function hotReload(\n  handler: (req: Request) => Response | Promise,\n): (req: Request) => Promise {\n  const val = parseVal();\n  const startVersion = parseInt(val.version, 10);\n\n  // Lazily initialize the SDK and val/branch IDs on first poll request\n  let pollContext:\n    | Promise<{ vt: ValTown; valId: string; branchName: string }>\n    | null = null;\n\n  function getPollContext() {\n    if (!pollContext) {\n      pollContext = (async () => {\n        const vt = new ValTown({ baseURL: API_URL });\n        const { id: valId } = await vt.alias.username.valName.retrieve(\n          val.username,\n          val.name,\n        );\n        return { vt, valId, branchName: val.branch };\n      })();\n    }\n    return pollContext;\n  }\n\n  return async (req: Request): Promise => {\n    const url = new URL(req.url);\n\n    // Only activate on val.run domains\n    if (!url.hostname.endsWith(\".val.run\")) {\n      return handler(req);\n    }\n\n    // Handle long-poll endpoint\n    if (url.pathname === POLL_PATH) {\n      return handlePoll(getPollContext, startVersion);\n    }\n\n    // Normal request — call user handler, maybe inject script\n    const res = await handler(req);\n\n    // Don't inject into iframe responses — Sec-Fetch-Dest is \"iframe\" for\n    // iframe loads and \"document\" for top-level navigations.\n    const fetchDest = req.headers.get(\"sec-fetch-dest\");\n    if (fetchDest && fetchDest !== \"document\") {\n      return res;\n    }\n\n    return maybeInjectScript(res, startVersion);\n  };\n}\n\n/**\n * Handles the long-poll request from the client.\n *\n * Actively polls the Val Town API for branch version changes.\n * If the branch version has increased, respond immediately (triggering reload).\n * Otherwise, keep checking every ~1s for up to ~30s, then respond 304.\n */\nasync function handlePoll(\n  getPollContext: () => Promise<\n    { vt: ValTown; valId: string; branchName: string }\n  >,\n  startVersion: number,\n): Promise {\n  const { vt, valId, branchName } = await getPollContext();\n  const deadline = Date.now() + HOLD_DURATION_MS;\n\n  while (Date.now() < deadline) {\n    try {\n      const latestVersion = await getBranchVersion(vt, valId, branchName);\n      if (latestVersion !== null && latestVersion > startVersion) {\n        return Response.json({ version: latestVersion });\n      }\n    } catch {\n      // API error — don't crash, just retry next interval\n    }\n    // Wait before next check (but don't overshoot the deadline)\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) break;\n    await new Promise((resolve) =>\n      setTimeout(resolve, Math.min(CHECK_INTERVAL_MS, remaining))\n    );\n  }\n\n  return new Response(null, { status: 304 });\n}\n\n/**\n * Gets the current version of a branch from the Val Town API.\n */\nasync function getBranchVersion(\n  vt: ValTown,\n  valId: string,\n  branchName: string,\n): Promise {\n  const branches = await Array.fromAsync(vt.vals.branches.list(valId, {}));\n  const branch = branches.find((b) => b.name === branchName);\n  return branch ? branch.version : null;\n}\n\n/**\n * If the response is HTML, inject the hot-reload client script before  or .\n * Otherwise, return the response unmodified.\n */\nasync function maybeInjectScript(\n  res: Response,\n  version: number,\n): Promise {\n  const contentType = res.headers.get(\"content-type\") || \"\";\n  if (!contentType.includes(\"text/html\")) {\n    return res;\n  }\n\n  const script = clientScript(version);\n\n  // If the response body is a ReadableStream, use the streaming injector\n  if (res.body) {\n    const injected = res.body\n      .pipeThrough(new TextDecoderStream())\n      .pipeThrough(new InjectBeforeCloseStream(script))\n      .pipeThrough(new TextEncoderStream());\n\n    return new Response(injected, {\n      status: res.status,\n      statusText: res.statusText,\n      headers: res.headers,\n    });\n  }\n\n  // Fallback for bodyless responses\n  return res;\n}\n\n/**\n * Generates the inline client-side script that long-polls for version changes.\n */\nfunction clientScript(version: number): string {\n  return ``;\n}\n\n/**\n * A TransformStream that injects a string before  or  in an HTML stream.\n * If neither tag is found, appends at the end.\n */\nclass InjectBeforeCloseStream extends TransformStream {\n  constructor(content: string) {\n    const state = { injected: false, buffer: \"\" };\n\n    super({\n      transform(chunk, controller) {\n        if (state.injected) {\n          controller.enqueue(chunk);\n          return;\n        }\n\n        const combined = state.buffer + chunk;\n        state.buffer = \"\";\n\n        // Try to inject before  or \n        const bodyMatch = combined.match(/(<\\/body[\\s>])/i);\n        const htmlMatch = combined.match(/(<\\/html[\\s>])/i);\n        const match = bodyMatch || htmlMatch;\n\n        if (match && match.index !== undefined) {\n          const before = combined.slice(0, match.index);\n          const after = combined.slice(match.index);\n          controller.enqueue(before + content + after);\n          state.injected = true;\n          return;\n        }\n\n        // Buffer the tail in case = 1; i--) {\n          const slice = combined.slice(-i);\n          if (\"\".startsWith(slice) || \"\".startsWith(slice)) {\n            state.buffer = slice;\n            controller.enqueue(combined.slice(0, -i));\n            return;\n          }\n        }\n\n        controller.enqueue(combined);\n      },\n      flush(controller) {\n        if (state.buffer) {\n          controller.enqueue(state.buffer);\n        }\n        if (!state.injected) {\n          controller.enqueue(content);\n        }\n      },\n    });\n  }\n}",[234],"aa2b2fcc-3065-11f1-a524-42dde27851f2","hot-reload.test.ts","aa2b3058-3065-11f1-a524-42dde27851f2",["D",1775334862977],"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",[241],"aa2b093e-3065-11f1-a524-42dde27851f2","hot-reload.example.tsx","aa2b0a06-3065-11f1-a524-42dde27851f2",["D",1775334862977],"/** @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);",[247],"7ac84c6a-3065-11f1-b279-42dde27851f2","file.ts","3746a5a2-73bb-11f0-bdd9-0224a6c84d84",["D",1775334783470],28,"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  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 metadata objects — see the signature above for the full type\n *\n * @example\n * ```ts\n * import { listFiles } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // Most common usage - lists files from current val\n * const files = await listFiles();\n * files.forEach((file) => console.log(file.path));\n *\n * // Explicit val specification\n * const files2 = await listFiles(import.meta.url);\n * files2.forEach((file) => console.log(file.path));\n * ```\n */\nexport function listFiles(\n  metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n  return listFilesByPath(\"\", metaImportUrl);\n}\n\n/**\n * Gets the ID of a val.\n *\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to get the ID for. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to the val ID as a string\n *\n * @example\n * ```ts\n * import { getValId } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // Get the val id for the val this code is in\n * const id = await getValId();\n * console.log(id); // Returns: \"bb8f592e-f528-11ef-b06d-569c3dd06744\"\n * ```\n */\nexport async function getValId(\n  metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n  const val = parseVal(metaImportUrl);\n  const { id } = await vt.alias.username.valName.retrieve(\n    val.username,\n    val.name,\n  );\n  return id;\n}\n\n/**\n * Lists files in a specific directory path within the current val.\n *\n * @param path - The directory path to list files from\n * @param metaImportUrl - Optional. The import.meta.url to determine which val to list files from. Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n * @returns Promise that resolves to an array of file metadata objects (same shape as `listFiles`)\n *\n * @example\n * ```ts\n * import { listFilesByPath } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * // List files in a specific directory\n * const frontendFiles = await listFilesByPath(\"frontend/\");\n * frontendFiles.forEach((file) => console.log(file.path));\n * ```\n */\nexport async function listFilesByPath(\n  path: string,\n  metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\",\n): Promise {\n  const val = parseVal(metaImportUrl);\n  const valId = await getValId(metaImportUrl);\n\n  const params: {\n    path: string;\n    recursive: boolean;\n    branch_id?: string;\n  } = {\n    path,\n    recursive: true,\n  };\n\n  if (val.branch !== \"main\") {\n    const branches = await Array.fromAsync(vt.vals.branches.list(valId, {}));\n    const branch = branches.find((b) => b.name === val.branch);\n    if (!branch) {\n      throw new Error(\"Failed to find branch \" + val.branch);\n    }\n    params.branch_id = branch.id; // set like this because of a stainless bug\n  }\n\n  const files = await Array.fromAsync(vt.vals.files.retrieve(valId, params));\n  return files;\n}\n\n/**\n * Fetches and transpiles TypeScript/JavaScript code from esm.town URLs.\n *\n * @param url - The esm.town URL to fetch (e.g., \"https://esm.town/v/username/valname@version-branch/file.ts\")\n * @returns Promise that resolves to the transpiled JavaScript code as a string\n *\n * @example\n * ```ts\n * import { fetchTranspiledJavaScript } from \"https://esm.town/v/std/utils/index.ts\";\n *\n * const code = await fetchTranspiledJavaScript(\n *   \"https://esm.town/v/std/utils@85-main/index.ts\"\n * );\n * console.log(code);\n * ```\n */\nexport async function fetchTranspiledJavaScript(url: string): Promise {\n  return await fetchFile(url, true);\n}\n\nasync function fetchFile(url: string, isTranspiled: boolean): Promise {\n  if (!url.startsWith(\"https://esm.town\")) {\n    throw Error(\"Can only fetch from https://esm.town\");\n  }\n  const res = await fetch(url, {\n    headers: {\n      // Always transpile TS to JS\n      // Learn more: https://www.val.town/v/stevekrouse/esmTownTranspileDemo\n      \"User-Agent\": isTranspiled ? \"\" : \"Deno\",\n      \"Authorization\": \"Bearer \" + Deno.env.get(\"valtown\"),\n    },\n  });\n  if (res.status === 404) {\n    throw new Error(\"File not found\");\n  }\n  if (!res.ok) {\n    throw new Error(\"Failed to fetch \" + url + res.status);\n  }\n  return await res.text();\n}",[253],"2f394918-0ff2-11f1-adb6-42dde27851f2","file.test.ts","37469ecc-73bb-11f0-bdd9-0224a6c84d84",252,["D",1771766827384],14,"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);",[260],"3746999a-73bb-11f0-bdd9-0224a6c84d84","example.test.ts","37469a44-73bb-11f0-bdd9-0224a6c84d84",["D",1754590837179],"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);",[268],"5bbcb980-7a0a-11f0-a022-0224a6c84d84","_tests.ts","3746c686-73bb-11f0-bdd9-0224a6c84d84",156,["D",1755284535560],2,"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]);",[274],"dab90d12-351a-11f1-96bc-42b51c65c3df",["D",1775852488004],22,"utilities",[34],"7ac79e64-3065-11f1-b279-42dde27851f2","README.md","d8b972ae-f529-11ef-8863-569c3dd06744",["D",1775334783470],45,"# @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```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| `readFile` | Read raw file contents from your val |\n| `readFileTranspiled` | Read transpiled JS (types stripped) for browser use |\n| `listFiles` | List all files in the current val with metadata |\n| `listFilesByPath` | List files in a specific directory |\n| `httpEndpoint` | Get the live HTTP URL for a file |\n| `emailAddress` | Get the email address for an email-trigger file |\n| `getValId` | Get the current val's UUID |\n| `fetchTranspiledJavaScript` | Fetch transpiled JS from any esm.town URL |\n| `serveFile` | Serve a file as an HTTP Response with correct Content-Type |\n| `getContentType` | Get MIME type for a file path |\n| `staticHTTPServer` | Create a static file server (serves `/index.html` at root) |\n| `parseVal` | Parse val metadata (username, name, version, branch, links) from `import.meta.url` |\n| `isMain` | Check if the current file is the entrypoint |\n| `testServer` | Create an HTML test runner with pass/fail badges |\n\n## Architecture\n\n```mermaid\ngraph TD\n    index[index.ts
re-exports everything]\n\n    index --> file[file.ts
readFile, listFiles, httpEndpoint,
emailAddress, getValId, etc.]\n    index --> serveFile[serve-file.ts
serveFile, getContentType]\n    index --> parseVal[parseImportMeta.ts
parseVal]\n    index --> isMain[is-main.ts
isMain]\n    index --> testServer[test.tsx
testServer]\n    index --> staticServer[static.tsx
staticHTTPServer]\n\n    file --> parseVal\n    serveFile --> file\n    staticServer --> serveFile\n\n    docs[_docs.tsx
auto-generated API docs site]\n    tests[_tests.ts
test runner endpoint]\n\n    style docs fill:#e8f4fd,stroke:#4a90d9\n    style tests fill:#e8f4fd,stroke:#4a90d9\n    style index fill:#f0f9e8,stroke:#5cb85c\n```\n\n## File overview\n\n| File | Type | Purpose |\n|---|---|---|\n| `index.ts` | script | Public entry point — re-exports all utilities |\n| `file.ts` | script | File I/O: read, list, transpile, endpoints, email addresses |\n| `serve-file.ts` | script | HTTP file serving with MIME type detection |\n| `parseImportMeta.ts` | script | Parse `import.meta.url` into val metadata |\n| `is-main.ts` | script | Entrypoint detection (`import.meta.main` replacement) |\n| `test.tsx` | script | Test runner with HTML output and SVG badges |\n| `static.tsx` | script | Hono-based static file server |\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",[287],"pulls","branches","forks",9,"envVars",{"_301":208,"_303":208},"connections",{"_301":208,"_302":208},"count","unfilledCount","emptyCount",{"_49":286,"_38":287,"_36":288,"_158":-5,"_47":48,"_46":159,"_160":31,"_44":378,"_13":290,"_39":26,"_41":291,"_30":31,"_165":-5,"_324":379,"_33":380},{"_49":281,"_38":34,"_36":37,"_158":-5,"_47":48,"_46":14,"_160":31,"_44":375,"_13":283,"_39":40,"_41":43,"_30":31,"_165":284,"_324":376,"_33":377},{"_49":273,"_38":274,"_36":275,"_158":-5,"_47":48,"_46":276,"_160":31,"_44":372,"_13":278,"_39":40,"_41":279,"_30":31,"_165":-5,"_324":373,"_33":374},{"_49":267,"_38":268,"_36":269,"_158":-5,"_47":48,"_46":206,"_160":64,"_44":369,"_13":208,"_39":40,"_41":271,"_30":31,"_165":-5,"_324":370,"_33":371},{"_49":259,"_38":260,"_36":261,"_158":-5,"_47":48,"_46":262,"_160":64,"_44":366,"_13":264,"_39":40,"_41":265,"_30":31,"_165":-5,"_324":367,"_33":368},{"_49":252,"_38":253,"_36":254,"_158":-5,"_47":48,"_46":159,"_160":31,"_44":363,"_13":256,"_39":163,"_41":257,"_30":31,"_165":-5,"_324":364,"_33":365},{"_49":246,"_38":247,"_36":248,"_158":-5,"_47":48,"_46":228,"_160":64,"_44":360,"_13":208,"_39":40,"_41":250,"_30":31,"_165":-5,"_324":361,"_33":362},{"_49":240,"_38":241,"_36":242,"_158":-5,"_47":48,"_46":228,"_160":64,"_44":357,"_13":208,"_39":163,"_41":244,"_30":31,"_165":-5,"_324":358,"_33":359},{"_49":233,"_38":234,"_36":235,"_158":-5,"_47":48,"_46":236,"_160":64,"_44":354,"_13":222,"_39":163,"_41":238,"_30":31,"_165":-5,"_324":355,"_33":356},{"_49":225,"_38":226,"_36":227,"_158":-5,"_47":48,"_46":228,"_160":31,"_44":351,"_13":230,"_39":163,"_41":231,"_30":31,"_165":-5,"_324":352,"_33":353},{"_49":217,"_38":218,"_36":219,"_158":-5,"_47":48,"_46":220,"_160":64,"_44":348,"_13":222,"_39":40,"_41":223,"_30":31,"_165":-5,"_324":349,"_33":350},{"_49":211,"_38":212,"_36":213,"_158":-5,"_47":48,"_46":159,"_160":64,"_44":345,"_13":186,"_39":163,"_41":215,"_30":31,"_165":-5,"_324":346,"_33":347},{"_49":203,"_38":204,"_36":205,"_158":-5,"_47":48,"_46":206,"_160":64,"_44":342,"_13":208,"_39":40,"_41":209,"_30":31,"_165":-5,"_324":343,"_33":344},{"_49":197,"_38":198,"_36":199,"_158":-5,"_47":48,"_46":159,"_160":64,"_44":339,"_13":194,"_39":163,"_41":201,"_30":31,"_165":-5,"_324":340,"_33":341},{"_49":189,"_38":190,"_36":191,"_158":-5,"_47":48,"_46":192,"_160":64,"_44":336,"_13":194,"_39":40,"_41":195,"_30":31,"_165":-5,"_324":337,"_33":338},{"_49":181,"_38":182,"_36":183,"_158":-5,"_47":48,"_46":184,"_160":64,"_44":333,"_13":186,"_39":163,"_41":187,"_30":31,"_165":-5,"_324":334,"_33":335},{"_49":174,"_38":175,"_36":176,"_158":-5,"_47":48,"_46":177,"_160":31,"_44":330,"_13":162,"_39":40,"_41":179,"_30":31,"_165":-5,"_324":331,"_33":332},{"_49":167,"_38":168,"_36":169,"_158":-5,"_47":48,"_46":159,"_160":31,"_44":327,"_13":171,"_39":163,"_41":172,"_30":31,"_165":-5,"_324":328,"_33":329},{"_49":155,"_38":156,"_36":157,"_158":-5,"_47":48,"_46":159,"_160":64,"_44":323,"_13":162,"_39":163,"_41":164,"_30":31,"_165":-5,"_324":325,"_33":326},["D",1775334783470],"children",[],[156],["D",1775334783470],[],[168],["D",1770827978247],[],[175],["D",1770828153464],[],[182],["D",1762117073435],[],[190],["D",1775334783470],[],[198],["D",1754590837179],[],[204],["D",1775334783470],[],[212],["D",1755731216104],[],[218],["D",1775334862977],[],[226],["D",1775675306082],[],[234],["D",1775334862977],[],[241],["D",1775334862977],[],[247],["D",1775334783470],[],[253],["D",1771766827384],[],[260],["D",1754590837179],[],[268],["D",1755284535560],[],[274],["D",1775852488004],[],[34],["D",1775334783470],[],[287],["D",1740674076598],["D",1789508444194],{"_106":105,"_113":109},{"_106":105,"_107":-5,"_108":109,"_19":-5,"_110":111,"_112":31},{"_13":95,"_38":96,"_49":48,"_97":50,"_98":-5,"_99":-5,"_100":-5,"_101":-5,"_102":-5,"_103":51,"_104":105},"ctx",{"_88":-5,"_133":419,"_420":421,"_422":423,"_424":31,"_425":31,"_426":31,"_427":64,"_428":-5,"_429":-7,"_430":-7,"_431":208,"_432":31,"_433":31,"_434":-5,"_435":31,"_436":31,"_437":31,"_438":-5},"ENV",{"_390":391,"_392":393,"_394":96,"_395":396,"_397":398,"_399":400,"_401":402,"_403":404,"_405":406,"_407":408,"_409":410,"_411":412,"_413":414,"_415":416,"_417":418},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","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"]
Diff · v256
