best-practices-for-writing-deno-based-application

AI Coding with Deno: Best Practices

This document summarizes the best practices for writing code using Deno and AI. It is designed not only for human readers but also as a prompt for coding agents.

This project assumes two modes of operation: Script Mode and Module Mode. The details are explained below.

Coding Policy

• First, define the types and the interface for the functions that process them.
• Clearly document the specifications of each file in comments whenever possible.
• If an implementation does not require maintaining internal state, prefer functions over classes.
• Use the Adapter Pattern to abstract external dependencies, allowing in-memory adapters to be used in tests.

Type Definition Guidelines

• Use the most specific types possible and avoid using any.
• Utilize Utility Types for common type patterns.
• Use meaningful type aliases to clarify intent.

// Good Example
type UserId = string;
type UserData = {
  id: UserId;
  createdAt: Date;
};

// Avoid this
type Data = any;

Writing Tests

Use @std/expect and @std/testing/bdd. Avoid nested describe blocks unless there is a strong reason.

import { expect } from "@std/expect";
import { test } from "@std/testing/bdd";

test("2+3=5", () => {
  expect(add(2, 3)).toBe(5);
});

Implementation Mode: Script Mode

• Minimize external dependencies and keep all logic within a single file.
• Include test code within the same file.
• A script is identified if it contains @script in the code or is located under scripts/* or script/*.

Example of Script Mode

/* @script */
/**
A simple module for addition
 */
function add(a: number, b: number): number {
  return a + b;
}

// Entry point for execution via `deno run add.ts`
if (import.meta.main) {
  console.log(add(1, 2));
}

/// test
import { expect } from "@std/expect";
import { test } from "@std/testing/bdd";

test("add(1, 2) = 3", () => {
  expect(add(1, 2)).toBe(3);
});

Coding agents like CLINE/Roo should first execute deno run add.ts, then expand tests to be runnable with deno test -A <filename> as needed.