code-patterns

Code Patterns

Purpose

This skill is a genome of common code patterns — reference implementations that teach agents how we prefer utility code to be written. Each pattern demonstrates:

• Pure functions with no side effects
• Arrow function style with const declarations
• Proper TypeScript typing (no any, use unknown with type guards)
• Comprehensive test coverage (happy path, edge cases, falsey values)

Use this when:

• Writing standalone utility functions
• Implementing deep comparison, async helpers, or similar patterns
• Needing a reference for our preferred coding conventions
• Writing tests for utility-style code

Shared Utilities (plaited/utils)

Before writing any custom utility, check if plaited/utils already provides it. Import from 'plaited/utils' instead of reimplementing:

Import	Purpose	Example
keyMirror	Self-referential constant objects (event names, enums)	keyMirror('evt_a', 'evt_b') → { evt_a: 'evt_a', evt_b: 'evt_b' }
isTypeOf	TypeScript type guard	isTypeOf<MyType>(val, 'object')
trueTypeOf	Precise runtime type string	trueTypeOf([]) → 'array'
ueid	Unique-enough IDs (not crypto-safe)	ueid('msg-') → 'msg-lxz3f8a'
camelCase / kebabCase / pascalCase	String case conversion	camelCase('hello-world') → 'helloWorld'
htmlEscape / htmlUnescape	XSS-safe HTML escaping	htmlEscape('<script>') → '&lt;script&gt;'
deepEqual	Deep equality comparison	deepEqual({ a: 1 }, { a: 1 }) → true

These are pure, tested, and framework-agnostic. Reimplementing them wastes tokens and risks subtle bugs (edge cases in deep comparison, escaped character handling, ID collision probability).

Type Boundaries — Parse, Don't Cast

When data crosses into your type system from an untyped boundary (JSON.parse, SQL results, API responses, event detail payloads, file reads), use Zod .parse() instead of as casts.

// BAD — cast asserts without checking
const user = JSON.parse(raw) as User

// GOOD — parse validates and types in one step
const user = UserSchema.parse(JSON.parse(raw))

as casts suppress the type checker without runtime validation. If the actual shape diverges from the expected type, a cast silently passes bad data into your system. Zod .parse() catches mismatches at the boundary immediately and produces a correctly typed value. z.output<typeof MySchema> gives you the static type for free — no separate type declaration needed.

Every external boundary (network, storage, file system, serialization) is a point where unknown enters. Parse at the boundary, trust the parsed value everywhere else.

Patterns

Deep Equal

deep-equal.ts — Deep equality comparison for any JavaScript values

A recursive comparator that handles all built-in types including circular references. Demonstrates:

• Object.is() for primitive comparison (correct NaN and +0/-0 handling)
• instanceof checks for Date, RegExp, Map, Set, TypedArrays
• WeakMap for circular reference detection (no memory leaks)
• Reflect.ownKeys() for thorough object comparison (includes symbols)
• Early exit optimizations (length/size checks before iteration)

deep-equal.spec.ts — Test coverage

Shows testing conventions: flat test() blocks (not it()), comment-separated sections for each type category, no conditional assertions.

Wait

wait.ts — Promise-based delay utility

A minimal async helper showing our conventions for:

• Type-first design (type Wait declared separately from implementation)
• Single-expression arrow functions
• Promise wrapping of callback APIs (setTimeout → Promise)

Conventions Demonstrated

Convention	Pattern
Arrow functions	const fn = () => not function fn()
Type over interface	type Wait = ... not interface Wait
No any	Use unknown with type guards
Pure functions	No side effects, deterministic output
test() not it()	Bun test convention
No conditional assertions	Assert condition first, then assert value

Related Skills

• plaited-runtime — Event-driven coordination and runtime doctrine
• code-documentation — TSDoc standards for documenting these patterns