Skip to content

coding-style.md

Latest commit

 

History

History
353 lines (260 loc) · 8.06 KB

coding-style.md

File metadata and controls

353 lines (260 loc) · 8.06 KB

Coding Style

Overview

High-level constraints that govern all TypeScript in the monorepo. These rules are enforced by OXLint and OXFmt — code that violates them will not pass CI. The goal is a strict functional style: pure, immutable, declarative, with side effects pushed to the edges.

Rules

No let — Use const Only

All bindings must be const. No reassignment, no mutation. Mutable state inside closures (factory internals) is the one accepted exception.

Correct

const timeout = 5000
const scripts = config.scripts.filter(isEnabled)

Incorrect

let timeout = 5000
timeout = 10000

let scripts: Script[] = []
scripts.push(newScript)

No Loops

Use map, filter, reduce, flatMap, and es-toolkit utilities instead of for, while, do...while, for...in, or for...of.

Correct

const names = scripts.map((s) => s.name)
const enabled = scripts.filter((s) => s.enabled)
const total = items.reduce((sum, item) => sum + item.count, 0)

Incorrect

const names: string[] = []
for (const script of scripts) {
  names.push(script.name)
}

No Classes

Use plain objects, closures, and factory functions. Classes are permitted only when wrapping an external SDK that requires instantiation.

Anti-pattern Use Instead
Utility classes Module with functions
Static method collections Module with functions
Data containers Plain objects / interfaces
Singletons Module-level constants

Correct

export function capitalize(s: string) {
  return s.charAt(0).toUpperCase() + s.slice(1)
}

Incorrect

class StringUtils {
  static capitalize(s: string) {
    return s.charAt(0).toUpperCase() + s.slice(1)
  }
}

No this

Never reference this. Factory closures and plain functions eliminate the need.

No throw

Return errors as values using the Result tuple type. No throw statements or throw expressions.

Correct

function parseConfig(raw: string): Result<Config, ParseError> {
  if (!raw) {
    return [{ type: 'parse_error', message: 'Empty input' }, null]
  }
  return [null, JSON.parse(raw)]
}

Incorrect

function parseConfig(raw: string): Config {
  if (!raw) {
    throw new Error('Empty input')
  }
  return JSON.parse(raw)
}

Immutable Data

Do not mutate objects or arrays after creation. Return new values from every transformation.

Correct

function addScript(scripts: readonly Script[], script: Script): readonly Script[] {
  return [...scripts, script]
}

Incorrect

function addScript(scripts: Script[], script: Script) {
  scripts.push(script)
}

No Ternaries

Use if/else or match expressions. Ternaries are banned by the linter.

Correct

if (isVerbose) {
  log.info(details)
} else {
  log.info(summary)
}

Incorrect

const message = isVerbose ? details : summary

No any

Use unknown, generics, or proper types. Narrow with type guards when needed.

Correct

function parse(data: unknown): Result<Config, ParseError> {
  if (!isPlainObject(data)) {
    return [{ type: 'parse_error', message: 'Expected object' }, null]
  }
  return [null, validateConfig(data)]
}

Incorrect

function parse(data: any): Config {
  return data
}

Prefer Point-Free Style

When passing a named function to a higher-order function, pass it directly instead of wrapping in an arrow.

Correct

const valid = scripts.filter(isEnabled)
const names = items.map(getName)

Incorrect

const valid = scripts.filter((s) => isEnabled(s))
const names = items.map((item) => getName(item))

ESM Only

Use ES module syntax with verbatimModuleSyntax. Use import type for type-only imports. Prefer the node: protocol for Node.js builtins.

Correct

import type { Config } from './types'
import { readFile } from 'node:fs/promises'
import { loadConfig } from './lib/config'

Incorrect

const fs = require('fs')
import { Config } from './types' // should use import type
import { readFile } from 'fs' // should use node: protocol

No IIFEs

Do not use immediately invoked function expressions. Extract the logic into a named function and call it explicitly. This applies to both sync and async IIFEs.

Correct

/**
 * @private
 */
async function execute(options: Options): Promise<void> {
  // ...
}

function start(options: Options): void {
  void execute(options)
}

Incorrect

function start(options: Options): void {
  void (async () => {
    // ...
  })()
}

Import Ordering

Organize imports into three groups separated by blank lines, sorted alphabetically within each group. Use top-level import type statements — do not use inline type specifiers.

  1. Node builtins — node: protocol imports
  2. External packages — third-party dependencies
  3. Internal imports — project-relative paths, ordered farthest-to-closest (../ before ./), then alphabetically within the same depth

Correct

import { readdir } from 'node:fs/promises'
import { basename, resolve } from 'node:path'

import { isPlainObject } from 'es-toolkit'
import { match } from 'ts-pattern'

import type { Command } from '../types.js'
import { createLogger } from '../lib/logger.js'
import { registerCommandArgs } from './args.js'
import type { ResolvedRef } from './register.js'

Incorrect

import { match } from 'ts-pattern'
import { readdir } from 'node:fs/promises' // node: should be first
import { registerCommandArgs } from './args.js'
import type { Command } from '../types.js' // ../ should come before ./
import { isPlainObject } from 'es-toolkit'
import { createLogger, type Logger } from '../lib/logger.js' // no inline type specifiers

File Structure

Organize each source file in this order:

  1. Imports — ordered per import rules above
  2. Module-level constants — const bindings used throughout the file
  3. Exported functions — the public API, each with full JSDoc
  4. Section separator — // ---------------------------------------------------------------------------
  5. Private helpers — non-exported functions, each with JSDoc including @private

Exported functions appear first so readers see the public API without scrolling. Private helpers are implementation details pushed to the bottom. Function declarations are hoisted, so calling order does not matter.

Correct

import type { Config } from '../types.js'

const DEFAULT_NAME = 'untitled'

/**
 * Load and validate a configuration file.
 *
 * @param path - Absolute path to the config file.
 * @returns The validated configuration record.
 */
export function loadConfig(path: string): Config {
  const raw = readRawConfig(path)
  return validateConfig(raw)
}

// ---------------------------------------------------------------------------
// Private
// ---------------------------------------------------------------------------

/**
 * Read the raw config file from disk.
 *
 * @private
 * @param path - Absolute path to read.
 * @returns The raw config string.
 */
function readRawConfig(path: string): string {
  // ...
}

/**
 * Validate a raw config string against the schema.
 *
 * @private
 * @param raw - Unvalidated config string.
 * @returns A validated Config object.
 */
function validateConfig(raw: string): Config {
  // ...
}

Incorrect

// Private helper defined before exports — reader must scroll to find the API
function readRawConfig(path: string): string {
  /* ... */
}
function validateConfig(raw: string): Config {
  /* ... */
}

export function loadConfig(path: string): Config {
  const raw = readRawConfig(path)
  return validateConfig(raw)
}

References

  • Design Patterns -- Factories, pipelines, composition
  • Errors -- Result type for error handling
  • State -- Immutable state management
  • Functions -- Pure functions and composition