TypeScript

TypeScript-specific guidelines for type safety and code organization.

Quick Reference

Do

• Use import type for type-only imports
• Use { cause } when re-throwing errors
• Let TypeScript infer types when obvious
• Create factory functions with create* prefix
• Prefer factory functions over classes
• Return null from handlers when request doesn't match
• Use a logger instead of console.log
• Validate external data at runtime (fetch, filesystem, env vars, user input) with an existing validation library

Don't

• Use default exports
• Use any type (use unknown and narrow)
• Use type assertions (as Type) - they indicate interface problems
• Use non-null assertions (x!) - they hide nullability bugs
• Assume type assertions provide runtime safety - they don't
• Over-type code with explicit annotations the compiler can infer
• Include file extensions in imports (unless required by runtime)

Naming Conventions

Files

Types and Interfaces

Functions

Variables

Acronyms in Names

Preserve acronym capitalization based on position:

// Good - acronyms stay capitalized when starting uppercase
getURLFromRequest
requestURL
parseHTTPHeaders

// Good - lowercase-starting acronyms stay lowercase
url
json

// Bad - don't mix case within acronyms
getUrlFromRequest  // Should be getURLFromRequest
requestUrl         // Should be requestURL

Common acronyms: URL, HTTP, HTTPS, JSON, API, RPC, HTML, XML

Note: "ID" is an abbreviation, so use standard camelCase: userId, requestId, getId().

Type System Patterns

Runtime Validation

Use a validation library (e.g., arktype, zod, typebox) for runtime type validation. Define the validator and TypeScript type together:

import { type } from "arktype";

// Define runtime validator
export const PaymentRequest = type({
  scheme: "string",
  network: "string",
  amount: "string.numeric",
  resource: "string.url",
});

// Derive TypeScript type from validator
export type PaymentRequest = typeof PaymentRequest.infer;

If no existing validation library is installed, install arktype and use it.

This pattern should be used for all external data: API responses from fetch, file system reads, environment variables, user input, and third-party API responses.

Type Guards

Create type guards using validation functions:

export function isAddress(maybe: unknown): maybe is Address {
  return !isValidationError(Address(maybe));
}

export function isKnownNetwork(n: string): n is KnownNetwork {
  return knownNetworks.includes(n as KnownNetwork);
}

Interfaces vs Types

• type: Use for data structures, unions, and validator-derived types
• interface: Use for behavioral contracts (objects with methods)

// Type for data structure
export type RequestContext = {
  request: RequestInfo | URL;
};

// Interface for behavioral contract
export interface PaymentHandler {
  getSupported?: () => Promise<SupportedKind>[];
  handleSettle: (requirements, payment) => Promise<SettleResponse | null>;
}

Const Assertions for Exhaustive Types

Use as const for exhaustive literal types:

const PaymentMode = {
  Direct: "direct",
  Deferred: "deferred",
} as const;

type PaymentMode = (typeof PaymentMode)[keyof typeof PaymentMode];

// TypeScript ensures all cases handled in switch
switch (mode) {
  case PaymentMode.Direct:
    // ...
    break;
  case PaymentMode.Deferred:
    // ...
    break;
}

Type-Only Imports

Use import type for type-only imports:

import type { PaymentRequest } from "./types";
import type { Hex, Account } from "viem";

// Mixed imports
import {
  type Transaction,
  createTransaction, // value import
} from "./transactions";

Avoid Over-Typing

Let TypeScript infer types when obvious:

// Good - return type is obvious
const createHandler = async (network: string) => {
  const config = { network, enabled: true };
  return {
    getConfig: () => config,
    isEnabled: () => config.enabled,
  };
};

// Unnecessary - the return type is obvious
const createHandler = async (network: string): Promise<{
  getConfig: () => { network: string; enabled: boolean };
  isEnabled: () => boolean;
}> => { ... };

When to add explicit types:

• Public API boundaries where the type serves as documentation
• When the inferred type would be too wide
• When TypeScript cannot infer the type correctly
• Complex return types that benefit from explicit documentation

When NOT to add explicit types:

• Variable assignments with obvious literal values
• Return types that match a simple expression
• Loop variables and intermediate calculations
• Arrow function parameters in callbacks where context provides types

Avoiding any and Type Assertions

Type assertions (as Type) only affect compile-time types. They provide zero runtime safety. A type assertion tells TypeScript "trust me, this is the shape" but does nothing at runtime.

This is especially critical for external data. Data from fetch, the filesystem, environment variables, user input, and third-party APIs always needs runtime validation because:

1. The TypeScript type is just a guess about the actual data shape
2. The network/file/env can return anything, not what you expected
3. External data can be malformed, malicious, or changed without warning

Use unknown instead of any when the type is truly unknown, then narrow with validation:

// Bad
function processData(data: any) {
  return data.value;
}

// Good
function processData(data: unknown) {
  const validated = MyDataType(data);
  if (isValidationError(validated)) {
    throw new Error(`Invalid data: ${validated.summary}`);
  }
  return validated.value;
}

Type assertions bypass type checking and often indicate interface problems. Prefer runtime validation:

// Bad
const data = (await response.json()) as UserData;

// Good
const raw = await response.json();
const data = UserData(raw);
if (isValidationError(data)) {
  throw new Error(`Invalid response: ${data.summary}`);
}

Avoiding Non-Null Assertions

The non-null assertion operator (x!) has the same problem as as Type: it's a compile-time lie. It tells TypeScript "trust me, this isn't null or undefined" when the compiler thinks it could be. If the compiler thinks a value might be null, there's usually a reason.

Instead of silencing the compiler, restructure the code so the value is provably non-null:

// Bad - hiding a potential bug
const user = users.find(u => u.id === id)!;
processUser(user);

// Good - handle the null case
const user = users.find(u => u.id === id);
if (!user) {
  throw new Error(`User not found: ${id}`);
}
processUser(user);

// Bad - asserting map result exists
const handler = handlers.get(name)!;

// Good - check and provide a meaningful error
const handler = handlers.get(name);
if (!handler) {
  throw new Error(`No handler registered for: ${name}`);
}

If you find yourself reaching for !, it means one of:

• The code doesn't properly guarantee the value exists (fix the code)
• The type is too wide for the context (narrow it with a guard or restructure)
• An upstream function returns T | null when it shouldn't (fix the upstream function)

Generic Constraints vs Index Signatures

Prefer generic type parameters with constraints over index signatures:

// Bad - index signature (too permissive)
export interface LoggingBackend {
  configureApp(args: {
    level: LogLevel;
    [key: string]: unknown;
  }): Promise<void>;
}

// Good - generic with constraint (type-safe)
export type BaseConfigArgs = { level: LogLevel };

export interface LoggingBackend<TConfig extends BaseConfigArgs = BaseConfigArgs> {
  configureApp(args: TConfig): Promise<void>;
}

Import/Export Patterns

Barrel Exports

Use index.ts files to re-export from modules:

// packages/types/src/index.ts

// Namespaced exports for grouped functionality
export * as payments from "./payments";
export * as client from "./client";

// Flat exports for utilities
export * from "./validation";
export * from "./helpers";

Named Exports (Preferred)

// Good
export function createMiddleware(args: CreateMiddlewareArgs) { ... }
export const MAX_RETRIES = 3;

// Avoid
export default function createMiddleware(args: CreateMiddlewareArgs) { ... }

Import Ordering

Order imports by category:

1. External library imports
2. Internal package imports
3. Relative imports

// External libraries
import { type } from "arktype";
import { Hono } from "hono";

// Internal packages
import { isValidationError } from "@myorg/types";
import type { Handler } from "@myorg/types/handler";

// Relative imports
import { isValidTransaction } from "./verify";
import { logger } from "./logger";

Import Paths

Omit file extensions in import paths when the module resolver can infer them:

// Good - no extension needed
import { createHandler } from "./handler";
import type { Config } from "../types";

// Bad - unnecessary extension
import { createHandler } from "./handler.ts";
import type { Config } from "../types.ts";

Note: Some environments (like Deno or Node.js with "type": "module") require explicit extensions. Follow project conventions when extensions are mandated by the runtime.

Async Patterns

Factory Functions

Use async factory functions that return objects with async methods:

const createHandler = async (network: string, rpc: RpcClient, config?: HandlerOptions) => {
  // Async initialization
  const networkInfo = await fetchNetworkInfo(rpc);

  // Return object with async methods
  return {
    getSupported,
    handleVerify,
    handleSettle,
  };
};

Parallel Execution

Use Promise.all for independent parallel operations:

const [tokenName, tokenVersion] = await Promise.all([
  client.readContract({ functionName: "name" }),
  client.readContract({ functionName: "version" }),
]);

Timeouts

Use Promise.race for operations that need timeouts:

function timeout(timeoutMs: number, msg?: string) {
  return new Promise((_, reject) =>
    setTimeout(() => reject(new Error(msg ?? "timed out")), timeoutMs),
  );
}

const result = await Promise.race([
  fetchData(),
  timeout(5000, "fetch timed out"),
]);

Retry Logic

Implement retries with exponential backoff:

let attempt = (options.retryCount ?? 2) + 1;
let backoff = options.initialRetryDelay ?? 100;
let response;

do {
  response = await makeRequest();

  if (response.ok) {
    return response;
  }

  await new Promise((resolve) => setTimeout(resolve, backoff));
  backoff *= 2;
} while (--attempt > 0);

Error Handling

Validation Errors

Check validation errors before proceeding:

const payload = parsePayload(input);

if (isValidationError(payload)) {
  logger.debug(`couldn't validate payload: ${payload.summary}`);
  return sendBadRequest();
}

// payload is now typed correctly

Local Error Response Factories

Create local helpers for consistent error responses:

const handleSettle = async (requirements, payment) => {
  const errorResponse = (msg: string): SettleResponse => {
    logger.error(msg);
    return {
      success: false,
      error: msg,
      txHash: null,
    };
  };

  if (someConditionFails) {
    return errorResponse("Invalid transaction");
  }
  // ...
};

Error Chaining

Use { cause } when re-throwing errors:

try {
  transaction = parseTransaction(input);
} catch (cause) {
  throw new Error("Failed to parse transaction", { cause });
}

Return null for "Not My Responsibility"

Handlers should return null when a request doesn't match their criteria:

const handleVerify = async (requirements, payment) => {
  if (!isMatchingRequirement(requirements)) {
    return null; // Let another handler try
  }
  // Handle the request...
};

Testing

Philosophy

Focus test coverage on logic specific to your codebase:

• Business logic and domain-specific validation
• Integration points between components
• Error handling paths and edge cases
• Custom algorithms and data transformations

Do not write tests that merely verify functionality provided by external libraries. Trust well-maintained libraries to do their job.

Test Structure

import t from "tap";

await t.test("descriptiveTestName", async (t) => {
  // Setup
  const cache = new Cache({ capacity: 3 });

  // Assertions
  t.equal(cache.size, 0);
  t.matchOnly(cache.get("key"), undefined);

  t.end();
});

Time-Based Testing

Inject time functions for deterministic time-based tests:

let theTime = 0;
const now = () => theTime;

const cache = new Cache({
  maxAge: 1000,
  now, // Inject time function
});

theTime += 500;
t.matchOnly(cache.get("key"), 42); // Still valid

theTime += 1000;
t.matchOnly(cache.get("key"), undefined); // Expired

Documentation

TSDoc Comments

Document public APIs with TSDoc:

/**
 * Creates a handler for the payment scheme.
 *
 * @param network - The network identifier (e.g., "mainnet", "testnet")
 * @param rpc - RPC client
 * @param config - Optional configuration options
 * @returns Promise resolving to a Handler
 */
export const createHandler = async (
  network: string,
  rpc: RpcClient,
  config?: HandlerOptions,
): Promise<Handler> => { ... };