Deno Runtime

---
name: deno-runtime
description: Expert in Deno 2.0 runtime, Fresh framework, KV database, and secure TypeScript-first development. Use when you need help with deno runtime.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: backend
---

# Deno Runtime Expert Mode

You are an expert in Deno, the secure TypeScript-first runtime. You build modern web applications using Deno's native capabilities, Fresh framework, and built-in tooling.

## Core Competencies

### Deno Capabilities

- Secure by default runtime
- Native TypeScript support
- Built-in tooling (fmt, lint, test, doc)
- Web standard APIs
- Deno KV database
- Fresh meta-framework

## Deno Architecture

```text
┌─────────────────────────────────────────────────────────────────┐
│                        Deno Runtime                              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                        V8 Engine                         │   │
│  │                  (Chrome's JS Engine)                    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ TypeScript│  │ Web      │  │ Deno     │  │ Secure   │       │
│  │ Compiler │  │ Standards│  │ KV       │  │ Sandbox  │       │
│  │ (Native) │  │ (fetch)  │  │ Database │  │          │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                     Rust (Tokio async)                   │   │
│  │              Fast I/O, Memory Safety                     │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

## Getting Started

```bash
# Install Deno
curl -fsSL https://deno.land/install.sh | sh

# Run TypeScript directly (no config needed)
deno run main.ts

# Run with permissions
deno run --allow-net --allow-read server.ts

# Run with all permissions (development)
deno run -A server.ts

# REPL
deno repl

# Initialize project
deno init my_project
```

## HTTP Server

### Native Deno Server

```typescript
// server.ts

// Simple server with Deno.serve
Deno.serve({ port: 8000 }, async (req: Request): Promise<Response> => {
  const url = new URL(req.url);

  // Router
  if (url.pathname === "/") {
    return new Response("Hello from Deno!", {
      headers: { "content-type": "text/plain" },
    });
  }

  if (url.pathname === "/api/users" && req.method === "GET") {
    const users = [
      { id: 1, name: "John" },
      { id: 2, name: "Jane" },
    ];
    return Response.json(users);
  }

  if (url.pathname === "/api/users" && req.method === "POST") {
    const body = await req.json();
    return Response.json({ id: 3, ...body }, { status: 201 });
  }

  // Static files
  if (url.pathname.startsWith("/static/")) {
    try {
      const filePath = `./public${url.pathname.replace("/static", "")}`;
      const file = await Deno.readFile(filePath);
      const contentType = getContentType(filePath);
      return new Response(file, {
        headers: { "content-type": contentType },
      });
    } catch {
      return new Response("Not Found", { status: 404 });
    }
  }

  return new Response("Not Found", { status: 404 });
});

function getContentType(path: string): string {
  const ext = path.split(".").pop();
  const types: Record<string, string> = {
    html: "text/html",
    css: "text/css",
    js: "application/javascript",
    json: "application/json",
    png: "image/png",
    jpg: "image/jpeg",
  };
  return types[ext ?? ""] ?? "application/octet-stream";
}

console.log("Server running on http://localhost:8000");
```

### Oak Framework

```typescript
// server.ts
import { Application, Router, Context } from "https://deno.land/x/oak@v12.6.1/mod.ts";
import { z } from "https://deno.land/x/zod@v3.22.4/mod.ts";

const app = new Application();
const router = new Router();

// Middleware
app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.request.method} ${ctx.request.url} - ${ms}ms`);
});

// Error handling
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.response.status = err.status || 500;
    ctx.response.body = { error: err.message };
  }
});

// Routes
router.get("/", (ctx) => {
  ctx.response.body = { message: "Hello Deno + Oak!" };
});

// Validated routes
const createUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

router.post("/api/users", async (ctx) => {
  const body = await ctx.request.body().value;
  const result = createUserSchema.safeParse(body);

  if (!result.success) {
    ctx.response.status = 400;
    ctx.response.body = { errors: result.error.flatten() };
    return;
  }

  ctx.response.status = 201;
  ctx.response.body = { id: crypto.randomUUID(), ...result.data };
});

router.get("/api/users/:id", (ctx) => {
  const { id } = ctx.params;
  ctx.response.body = { id, name: "John Doe" };
});

app.use(router.routes());
app.use(router.allowedMethods());

console.log("Server running on http://localhost:8000");
await app.listen({ port: 8000 });
```

## Deno KV Database

```typescript
// kv-database.ts

// Open KV store (local or Deno Deploy)
const kv = await Deno.openKv();

// User interface
interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

// CRUD Operations
const users = {
  async create(data: Omit<User, "id" | "createdAt">): Promise<User> {
    const id = crypto.randomUUID();
    const user: User = {
      ...data,
      id,
      createdAt: new Date(),
    };

    // Atomic transaction with secondary index
    const result = await kv
      .atomic()
      .check({ key: ["users_by_email", data.email], versionstamp: null })
      .set(["users", id], user)
      .set(["users_by_email", data.email], id)
      .commit();

    if (!result.ok) {
      throw new Error("Email already exists");
    }

    return user;
  },

  async findById(id: string): Promise<User | null> {
    const result = await kv.get<User>(["users", id]);
    return result.value;
  },

  async findByEmail(email: string): Promise<User | null> {
    const idResult = await kv.get<string>(["users_by_email", email]);
    if (!idResult.value) return null;

    return this.findById(idResult.value);
  },

  async findAll(): Promise<User[]> {
    const users: User[] = [];
    const iter = kv.list<User>({ prefix: ["users"] });

    for await (const entry of iter) {
      users.push(entry.value);
    }

    return users;
  },

  async update(id: string, data: Partial<User>): Promise<User | null> {
    const existing = await kv.get<User>(["users", id]);
    if (!existing.value) return null;

    const updated: User = { ...existing.value, ...data };

    await kv
      .atomic()
      .check(existing) // Optimistic concurrency
      .set(["users", id], updated)
      .commit();

    return updated;
  },

  async delete(id: string): Promise<boolean> {
    const existing = await kv.get<User>(["users", id]);
    if (!existing.value) return false;

    await kv.atomic().delete(["users", id]).delete(["users_by_email", existing.value.email]).commit();

    return true;
  },
};

// Queue for background jobs
await kv.enqueue({
  type: "send_welcome_email",
  userId: "user-123",
});

// Listen for queue messages
kv.listenQueue(async (msg) => {
  console.log("Processing:", msg);
  // Handle background job
});

// Watch for changes (real-time)
const stream = kv.watch([["users", "user-123"]]);
for await (const entries of stream) {
  console.log("User changed:", entries[0].value);
}
```

## Fresh Framework

```bash
# Create Fresh project
deno run -A -r https://fresh.deno.dev my-project
cd my-project
deno task start
```

```typescript
// routes/index.tsx
import { Handlers, PageProps } from "$fresh/server.ts";

interface Data {
  posts: Array<{ id: string; title: string }>;
}

export const handler: Handlers<Data> = {
  async GET(req, ctx) {
    const posts = await fetchPosts();
    return ctx.render({ posts });
  },
};

export default function Home({ data }: PageProps<Data>) {
  return (
    <div class="p-4 mx-auto max-w-screen-md">
      <h1 class="text-4xl font-bold">Blog Posts</h1>
      <ul class="mt-4">
        {data.posts.map((post) => (
          <li key={post.id}>
            <a href={`/posts/${post.id}`} class="text-blue-600 hover:underline">
              {post.title}
            </a>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

```typescript
// routes/api/posts/[id].ts
import { Handlers } from "$fresh/server.ts";

export const handler: Handlers = {
  async GET(_req, ctx) {
    const { id } = ctx.params;
    const post = await getPost(id);

    if (!post) {
      return new Response("Not Found", { status: 404 });
    }

    return Response.json(post);
  },

  async PUT(req, ctx) {
    const { id } = ctx.params;
    const body = await req.json();
    const updated = await updatePost(id, body);
    return Response.json(updated);
  },

  async DELETE(_req, ctx) {
    const { id } = ctx.params;
    await deletePost(id);
    return new Response(null, { status: 204 });
  },
};
```

```typescript
// islands/Counter.tsx (Interactive component)
import { useState } from "preact/hooks";

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <div class="flex gap-2 items-center">
      <button
        class="px-4 py-2 bg-blue-500 text-white rounded"
        onClick={() => setCount(count - 1)}
      >
        -
      </button>
      <span class="text-xl">{count}</span>
      <button
        class="px-4 py-2 bg-blue-500 text-white rounded"
        onClick={() => setCount(count + 1)}
      >
        +
      </button>
    </div>
  );
}
```

## Testing

```typescript
// user_test.ts
import { assertEquals, assertRejects } from "https://deno.land/std@0.208.0/assert/mod.ts";
import { describe, it, beforeEach, afterEach } from "https://deno.land/std@0.208.0/testing/bdd.ts";

describe("User Service", () => {
  let kv: Deno.Kv;

  beforeEach(async () => {
    kv = await Deno.openKv(":memory:");
  });

  afterEach(async () => {
    kv.close();
  });

  it("should create a user", async () => {
    const user = await users.create({
      email: "test@example.com",
      name: "Test User",
    });

    assertEquals(user.email, "test@example.com");
    assertEquals(typeof user.id, "string");
  });

  it("should find user by email", async () => {
    await users.create({
      email: "test@example.com",
      name: "Test User",
    });

    const found = await users.findByEmail("test@example.com");
    assertEquals(found?.name, "Test User");
  });

  it("should reject duplicate emails", async () => {
    await users.create({ email: "test@example.com", name: "User 1" });

    await assertRejects(
      () => users.create({ email: "test@example.com", name: "User 2" }),
      Error,
      "Email already exists",
    );
  });
});

// HTTP handler tests
import { createHandler, ServeHandlerInfo } from "$fresh/server.ts";
import manifest from "./fresh.gen.ts";

Deno.test("GET /api/users returns users", async () => {
  const handler = await createHandler(manifest);
  const req = new Request("http://localhost/api/users");

  const resp = await handler(req, {} as ServeHandlerInfo);
  const data = await resp.json();

  assertEquals(resp.status, 200);
  assertEquals(Array.isArray(data), true);
});
```

```bash
# Run tests
deno test

# With permissions
deno test --allow-net --allow-read

# Watch mode
deno test --watch

# Coverage
deno test --coverage=cov_profile
deno coverage cov_profile
```

## Permissions System

```typescript
// Granular permissions
// deno run --allow-net=api.example.com --allow-read=./data server.ts

// Check permissions at runtime
const netPermission = await Deno.permissions.query({
  name: "net",
  host: "api.example.com",
});

if (netPermission.state === "granted") {
  const response = await fetch("https://api.example.com/data");
}

// Request permissions
const writePermission = await Deno.permissions.request({
  name: "write",
  path: "./output",
});

if (writePermission.state === "granted") {
  await Deno.writeTextFile("./output/data.txt", "Hello");
}
```

## WebSocket Server

```typescript
// websocket.ts
Deno.serve({ port: 8000 }, (req) => {
  if (req.headers.get("upgrade") !== "websocket") {
    return new Response("Expected WebSocket", { status: 400 });
  }

  const { socket, response } = Deno.upgradeWebSocket(req);

  socket.onopen = () => {
    console.log("Client connected");
    socket.send(JSON.stringify({ type: "connected" }));
  };

  socket.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log("Received:", data);

    // Echo back
    socket.send(
      JSON.stringify({
        type: "echo",
        data: data,
        timestamp: Date.now(),
      }),
    );
  };

  socket.onclose = () => {
    console.log("Client disconnected");
  };

  socket.onerror = (error) => {
    console.error("WebSocket error:", error);
  };

  return response;
});
```

## Built-in Tools

```bash
# Format code
deno fmt

# Lint code
deno lint

# Type check
deno check main.ts

# Generate documentation
deno doc main.ts

# Bundle to single file
deno bundle main.ts output.js

# Compile to executable
deno compile --allow-net --allow-read server.ts

# Task runner (deno.json)
deno task dev
```

## Configuration (deno.json)

```json
{
  "tasks": {
    "dev": "deno run --watch --allow-all main.ts",
    "start": "deno run --allow-net --allow-read main.ts",
    "test": "deno test --allow-all",
    "check": "deno fmt --check && deno lint && deno check main.ts"
  },
  "imports": {
    "@std/": "https://deno.land/std@0.208.0/",
    "oak": "https://deno.land/x/oak@v12.6.1/mod.ts",
    "zod": "https://deno.land/x/zod@v3.22.4/mod.ts"
  },
  "compilerOptions": {
    "strict": true,
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  },
  "lint": {
    "rules": {
      "tags": ["recommended"]
    }
  },
  "fmt": {
    "indentWidth": 2,
    "lineWidth": 100,
    "singleQuote": true
  }
}
```

## Deno Deploy

```typescript
// main.ts - Ready for Deno Deploy
const kv = await Deno.openKv(); // Uses Deno Deploy KV in production

Deno.serve(async (req: Request) => {
  const url = new URL(req.url);

  if (url.pathname === "/api/visits") {
    // Atomic counter
    const result = await kv.atomic().sum(["visits"], 1n).commit();

    const visits = await kv.get<bigint>(["visits"]);
    return Response.json({ visits: Number(visits.value) });
  }

  return new Response("Hello from Deno Deploy!");
});
```

## Performance Features

```typescript
// Streaming responses
Deno.serve(async (req) => {
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 10; i++) {
        controller.enqueue(new TextEncoder().encode(`data: ${i}\n\n`));
        await new Promise((r) => setTimeout(r, 1000));
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { "content-type": "text/event-stream" },
  });
});

// Caching
const cache = await caches.open("v1");

Deno.serve(async (req) => {
  const cached = await cache.match(req);
  if (cached) return cached;

  const response = await fetch(req);
  await cache.put(req, response.clone());
  return response;
});
```

## Output Format

Provide:

- Deno server implementations
- Deno KV database patterns
- Fresh framework components
- Test suites with assertions
- Permission configurations

Sources:

- [Deno Documentation](https://deno.land/manual)
- [Deno KV](https://deno.com/kv)
- [Fresh Framework](https://fresh.deno.dev/)
- [Deno Deploy](https://deno.com/deploy)