nodejs-coding

Node.js / TypeScript Coding Standards

TypeScript Configuration

• "strict": true always — no exceptions
• "noUncheckedIndexedAccess": true for array safety
• "exactOptionalPropertyTypes": true to distinguish undefined from missing
• Target: ES2022 minimum, module: NodeNext

Naming Conventions

Element	Convention	Example
File	kebab-case	order-service.ts, create-order.handler.ts
Class	PascalCase	OrderService, CreateOrderHandler
Interface/Type	PascalCase	OrderResponse, CreateOrderInput
Function	camelCase	createOrder, findById
Constant	UPPER_SNAKE or camelCase	MAX_RETRIES, defaultConfig
Enum	PascalCase members	OrderStatus.Pending

Async/Await

// Good — explicit error handling
async function createOrder(input: CreateOrderInput): Promise<Result<Order>> {
  try {
    const order = Order.create(input);
    await repository.save(order);
    return Result.ok(order);
  } catch (error) {
    if (error instanceof ValidationError) {
      return Result.fail(error.message);
    }
    throw error; // re-throw unexpected errors
  }
}

// Bad — unhandled promise
function createOrder(input: CreateOrderInput) {
  repository.save(Order.create(input)); // floating promise!
}

• Always await promises — never leave floating promises
• Use Promise.all() for parallel operations, Promise.allSettled() when partial failures are OK
• Never use callbacks — always async/await

Error Handling

• Use typed Result pattern or throw custom error classes
• Define error hierarchy: AppError → ValidationError, NotFoundError, AuthorizationError
• Always include error context: new NotFoundError(\Order ${id} not found`)`
• Use cause for error chaining: new AppError("failed", { cause: originalError })

Types

• Prefer interface for object shapes, type for unions/intersections
• Use unknown over any — always narrow before use
• Use discriminated unions for state machines
• Avoid type assertions (as) — use type guards instead

// Discriminated union
type OrderResult =
  | { status: "success"; order: Order }
  | { status: "validation_error"; errors: string[] }
  | { status: "not_found" };

Modules (ESM)

• Use ESM (import/export) — never CommonJS (require)
• Use .js extension in imports (TypeScript resolves .ts → .js)
• Barrel exports (index.ts) only at module boundaries, not within