TypeScript Deno Agent Rules
Project Context
- Use Deno 2+ with TypeScript — no `tsconfig.json` required, Deno handles type checking natively.
- Format with `deno fmt` and lint with `deno lint` before every commit.
- Define all dependencies in the `imports` field of `deno.json` — avoid bare URL imports in source files.
- Use the `jsr:` specifier for JSR packages and `npm:` for Node.js compatibility packages.
Code Style & Structure
- Use explicit return types on exported functions. Rely on inference for local closures.
- Prefer `const` over `let`. Never use `var`.
- Use `interface` for object shapes and `type` for unions and intersections.
- Avoid enums — use `as const` objects with derived union types: `type Status = typeof STATUS[keyof typeof STATUS]`.
- Place entry points in the project root (`main.ts`, `dev.ts`). Group source by domain: `routes/`, `lib/`, `utils/`.
- Co-locate tests with source files using `_test.ts` suffix: `user.ts` alongside `user_test.ts`.
- Commit `deno.lock` to version control for dependency integrity.
Web Standard APIs
- Use `fetch`, `Request`, `Response`, `URL`, `URLPattern`, and `Headers` over Deno-specific equivalents.
- Use `Deno.serve()` for HTTP servers — it handles graceful shutdown and connection pooling automatically.
- Use `ReadableStream` and `WritableStream` for streaming data processing.
- Use `crypto.subtle` for all cryptographic operations — no third-party crypto libraries needed.
- Use `AbortController` and `AbortSignal` for cancellation of async fetch operations and timeouts.
Module Management
- Run `deno add jsr:@std/assert` to install dependencies — it updates `deno.json` imports automatically.
- Pin all dependency versions explicitly in `deno.json` imports — never use unversioned `@latest` specifiers.
- Prefer the Deno Standard Library (`@std/`) for common utilities: `@std/path`, `@std/fs`, `@std/assert`.
- Run `deno outdated` regularly to check for dependency updates.
- Never import directly from `https://` URLs without mapping them through `deno.json` import aliases.
Deno KV
- Use `const kv = await Deno.openKv()` for built-in key-value storage — no external database required for small apps.
- Design keys as hierarchical arrays: `["users", userId]` and `["users", userId, "sessions", sessionId]`.
- Use `kv.atomic()` for multi-key transactions that require consistency guarantees.
- Set `expireIn` (in milliseconds) on cache entries and temporary data like session tokens.
- Use secondary index keys to enable queries by non-primary attributes.
Permissions
- Run with the minimum required permissions — enumerate each needed permission explicitly.
- Scope `--allow-net` to specific domains: `--allow-net=api.example.com,cdn.example.com`.
- Scope `--allow-read` and `--allow-write` to specific directory paths.
- Never use `--allow-all` (`-A`) in production deployments or CI pipelines.
- Document all required permissions in `deno.json` task definitions so they are self-documenting.
Error Handling
- Use explicit try/catch blocks. Never leave promise rejections unhandled.
- Define custom error classes extending `Error` for domain-specific failures: `class NotFoundError extends Error {}`.
- Use `Result<T, E>` discriminated unions for recoverable errors in library code.
- Return proper HTTP status codes from request handlers: 400 for validation, 401 for auth, 404 for missing.
- Log errors with structured context including request ID, user ID, and timestamp.
Testing
- Write tests with `Deno.test('description', () => { ... })` using descriptive names as full sentences.
- Use `assertEquals`, `assertThrows`, and `assertRejects` from `@std/assert`.
- Use nested test steps with `t.step('sub-task', ...)` to group related assertions.
- Mock functions and objects with `stub()` and `spy()` from `@std/testing/mock`.
- Run tests with `deno test --parallel` for speed. Use `--coverage` to generate coverage reports.
Security
- Validate all external inputs with Zod or manual type guards before processing.
- Store secrets in environment variables — access with `Deno.env.get('SECRET_KEY')`.
- Use `crypto.randomUUID()` for generating IDs — never use predictable sequential IDs for security-sensitive data.
- Hash passwords with `@std/crypto` and a strong algorithm — never store plain text passwords.
TypeScript/
Deno