Val Utilities

Utilities for reading files and directories in Val Town Projects.

readFile(path: string, metaImportUrl: string): Promise<string>

Reads a file from the current project.

Create val
import { readFile } from "https://esm.town/v/std/utils/index.ts";

const content = await readFile("/README.md", import.meta.url);
console.log(content);

listFiles(metaImportUrl: string): Promise<File[]>

Lists all files in the current project.

Create val
import { listFiles } from "https://esm.town/v/std/utils/index.ts";

const files = await listFiles(import.meta.url);
console.log(files.map((f) => f.path));

fetchTranspiledJavaScript(url: string): Promise<string>

Fetches and transpiles TypeScript/JavaScript from esm.town URLs.

Create val
import { fetchTranspiledJavaScript } from "https://esm.town/v/std/utils/index.ts";

const code = await fetchTranspiledJavaScript(
  "https://esm.town/v/std/utils@85-main/index.ts",
);
console.log(code);

• All functions require a valid Val Town API token in the valtown environment variable
• Paths can be specified with or without leading slashes
• Files are automatically transpiled from TypeScript to JavaScript when fetched

If you're running code in Val Town, sometimes you want to know information about the val that's running. This module has functions for that.

Create val
import { parseVal } from "https://esm.town/v/std/utils/index.ts";

const val = parseVal(import.meta.url);
console.log(val);

• @pomdtr/extractValInfo
• @easrng/whoami

Utilities for serving project files as HTTP responses with proper content types.

serveFile(path: string, metaImportUrl: string): Promise<Response>

Serves a file from the project as an HTTP Response with the correct Content-Type header.

Create val
import { serveFile } from "https://esm.town/v/std/utils/index.ts";

// In a Hono app
app.get("/assets/*", async (c) => {
  return await serveFile(c.req.path, import.meta.url);
});

getContentType(path: string): string

Determines the appropriate MIME type for a file based on its extension.

Create val
import { getContentType } from "https://esm.town/v/std/utils/index.ts";

console.log(getContentType("index.html")); // "text/html; charset=utf-8"
console.log(getContentType("script.ts")); // "text/javascript"
console.log(getContentType("data.json")); // "application/json; charset=utf-8"

• TypeScript Support: .ts, .tsx, and .jsx files are served as text/javascript
• Automatic MIME Detection: Uses the mime-types library for accurate content type detection
• Fallback Handling: Unknown file types default to application/octet-stream
• Proper Headers: All responses include appropriate Content-Type headers

This module is used internally by the staticHTTPServer function to serve static assets with correct content types.

A simple HTTP server for serving static files from Val Town projects.

staticHTTPServer(importMetaURL: string): (req: Request) => Promise<Response>

Creates a Hono-based HTTP server that serves static files from the project.

Create val
import { staticHTTPServer } from "https://esm.town/v/std/utils/index.ts";

export default staticHTTPServer(import.meta.url);

• Root Path Handling: Requests to / serve /index.html
• Wildcard Routing: All other paths serve the corresponding file from the project
• Content Type Detection: Automatically sets correct MIME types for all file types
• Error Handling: Properly handles missing files and other errors
• TypeScript Support: Serves .ts, .tsx, and .jsx files as JavaScript

The server includes Hono's error unwrapping to provide detailed error messages during development. Missing files will result in appropriate HTTP error responses.

• Serving frontend applications from Val Town projects
• Creating simple static websites
• Hosting documentation sites
• Serving assets for web applications

A lightweight testing framework for Val Town that provides HTML test results and SVG badges.

testServer(testGroups: TestGroup[], metaImportUrl?: string): (req: Request) => Promise<Response>

Creates an HTTP server that runs tests and displays results as HTML or SVG badges.

Create val
import { expect } from "jsr:@std/expect";
import { testServer } from "https://esm.town/v/std/utils/index.ts";

export default testServer([
  {
    name: "My Tests",
    sourceFile: "myModule.ts", // Optional: links to source file
    tests: [
      {
        name: "should work correctly",
        function: () => {
          expect(1 + 1).toBe(2);
        },
      },
    ],
  },
], import.meta.url);

• HTML Test Results: Visit the test endpoint to see detailed test results
• SVG Badges: Access /badge.svg for a status badge showing pass/fail counts
• Test Grouping: Organize tests into logical groups
• Timing Information: Shows execution time for each test
• Error Details: Displays full error messages and stack traces for failing tests
• Before/After Hooks: Optional setup and teardown functions per test group
• Source File Links: Links back to source files in the Val Town editor

Create val
interface TestGroup {
  name: string;
  tests: TestCase[];
  sourceFile?: string; // Optional: filename for source link
  before?: () => void; // Run before all tests in this group
  after?: () => void; // Run after all tests in this group
}

interface TestCase {
  name: string;
  function: () => void | Promise<void>;
}

The framework automatically generates SVG badges that can be embedded in README files:

[![Tests](https://your-test-endpoint.web.val.run/badge.svg)](https://your-test-endpoint.web.val.run)

The framework works with any assertion library. We recommend using jsr:@std/expect for comprehensive assertion capabilities.