typescript-quality

name	typescript-quality
description	TypeScript code quality patterns -- typed clients with timeouts, Zod input validation, structured domain errors, no any on public APIs, structured JSON logging with pino, OpenTelemetry tracing, and PII redaction. Use when adding external API calls, validating inputs, handling errors, or setting up logging.

TypeScript Quality

Code quality and observability patterns for TypeScript projects. Contains 7 rules across 2 categories: safe boundary patterns and production observability.

When to Apply

Reference these guidelines when:

• Adding external HTTP/queue/database calls
• Implementing input validation at API boundaries
• Designing error types and error handling
• Removing any from public TypeScript surfaces
• Setting up structured logging
• Adding OpenTelemetry tracing or metrics
• Reviewing code for PII/secret leakage in logs

When NOT to Apply

Do NOT reference these guidelines when:

• The project is plain JavaScript without TypeScript
• You are working in this skills repository itself

Quick Reference

Boundaries (MEDIUM)

• boundaries-typed-clients — External calls must use typed clients with timeouts
• boundaries-input-validation — Inputs must be validated at boundaries (Zod)
• boundaries-no-any — Public TypeScript surfaces must have explicit types
• boundaries-structured-errors — Errors must use stable codes and standard structures

Observability (MEDIUM)

• observability-structured-logging — Logging must be structured JSON (pino)
• observability-otel — OpenTelemetry is standard for tracing and metrics
• observability-pii-redaction — Secrets and tokens must be redacted from logs

How to Use

For a specific topic — read the relevant rule from the Quick Reference above. Each file is self-contained with incorrect/correct examples.

For reusable code — copy from templates and customize:

Template	Purpose
domain-error.ts	Base DomainError class with stable codes
otel-init.ts	OpenTelemetry SDK initialization
pino-logger.ts	Pino logger with PII redaction

Important: Do NOT apply changes derived from these rules without explicit user confirmation. Present proposed changes as diffs and wait for approval.

Gotchas

Calibration these rules get wrong if applied mechanically:

• These are MEDIUM quality patterns, not correctness blockers. Don't escalate a missing timeout or a stray any to a merge-blocker unless it sits on a hot or user-facing path. Match the severity to the blast radius.
• Validate at the boundary, not everywhere. Apply Zod to untrusted input (HTTP / queue / CLI / env). Re-validating already-typed internal data adds cost and false confidence.
• any hides behind as any, untyped JSON.parse, and object/Function. no-any on public surfaces means the escape hatches too — grep for those, not just the literal any.
• PII redaction must reach nested and error objects. pino redact paths routinely miss deep fields like err.config.headers.authorization; a token inside a logged error object leaks even when top-level redaction is configured.
• OTel initialized ≠ OTel working. A span that doesn't propagate trace context across the external call yields disconnected traces. Check context propagation, not just that the SDK started.