mcpField
Q
quality-code

quality-code

github.com/rhyssullivanDevelopment104235 installsUpdated 16w ago
Repository

About quality-code

A guide for full-stack TypeScript developers writing or reviewing code. It emphasizes type-safe states, end-to-end type flow, realistic tests, and OpenTelemetry instrumentation.

Key features

  1. 01Constrain states with branded and union types
  2. 02Share and derive types end to end
  3. 03Prefer object arguments
  4. 04Use Standard Schema validation
  5. 05Test against real services
  6. 06Instrument with OpenTelemetry

Use cases

  1. 01Design APIs with fewer invalid states
  2. 02Reduce duplicated client and server types
  3. 03Accept reusable schemas for validation
  4. 04Test database and local cloud-service behavior

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/rhyssullivan/skills --skill quality-code

After installing, type/quality-codein Claude Code to confirm it loaded.

Details

From the project README

Writing quality full-stack TypeScript

Apply these principles when writing or reviewing TypeScript code.

Make impossible states unrepresentable

Use the type system to make invalid states fail at compile time. Fewer reachable states = easier code to read and change.

Branded types

Brand primitives so they can't be mixed up. Validate once at the boundary; downstream code trusts the type.

type PhoneNumber = string & { __brand: "PhoneNumber" };

function parsePhone(input: string): PhoneNumber {
  if (!/^\+?\d{10,15}$/.test(input)) throw new Error(`Invalid: ${input}`);
  return input as PhoneNumber;
}

function sendSMS(to: PhoneNumber, body: string) {
  /* input is trusted */
}

If the project already uses a library with native branded-type support (e.g. Effect), use their primitives instead of rolling your own.

Discriminated unions over flag bags
// Don't — invalid combos representable
type State = { loading: boolean; user?: User; error?: string };

// Do — only valid states exist
type State =
  | { status: "loading" }
  | { status: "success"; user: User }
  | { status: "error"; error: string };

Let the types flow end-to-end

DB schema → server → client should share types without manual duplication. Use whatever end-to-end type tool the project already has (tRPC, oRPC, Elysia, TanStack Start). A users.email branded as Email should arrive on the client still branded.

Don't restate types you can derive. Reach for Pick, Omit, Parameters, ReturnType, Awaited, typeof etc. before writing a new interface. For function arguments, infer from the source instead of typing them by hand:

// Don't — duplicate shape, drifts when the row changes
type UserSummary = { id: string; email: Email };
function renderUser(u: UserSummary) {
  /* ... */
}

// Do — derive from the source of truth
type User = Awaited<ReturnType<typeof db.query.users.findFirst>>;
function renderUser(u: Pick<User, "id" | "email">) {
  /* ... */
}

Pass objects, not positional args

// Don't — swap two args, still compiles
sendEmail("Welcome!", "Hi there");
// Do — order-independent, self-documenting
sendEmail({ to: "[email protected]", body: "Hi there" });

Skip on hot perf-critical paths; use elsewhere by default.

Standard Schema for shared validation

For libraries or code that doesn't want to pick a validator, accept StandardSchemaV1<unknown, T>.

Tests as real as possible

Don't mock things you can run. Spin up real services:

  • LocalStack for AWS
  • Miniflare for Cloudflare Workers
  • Real Postgres/SQLite (e.g. bun:sqlite), not a mock DB

Mock only third-party services that have no test environment.

OpenTelemetry, not print logging

When adding observability, instrument with OTel spans. The setup cost pays back the first time a user sends a request ID and you can answer instead of guess.

Comments

Markdown supported