defensive-programming

name	defensive-programming
description	Defensive programming guidelines for TypeScript/JavaScript projects using jty for runtime type validation. Use this skill when you want to ensure your code is robust and fails gracefully with meaningful errors when it encounters unexpected input or conditions.
license	MIT

Defensive Programming with jty

These guidelines apply to any TypeScript/JavaScript project that depends on jty for runtime type checking.

Core Principles

1. Never Trust External Boundaries

Never assume the type of variables or shape of objects coming from outside your code base: user input, dependencies, databases, AI-generated content, external APIs, parsed JSON/YAML, query parameters, etc. Just because there's a typescript interface or type declaration doesn't mean that those external systems respect that.

So assume the type is unknown and always verify using jty before accessing properties or performing operations.

import { isPOJO, isStr, isNum, hasProp } from 'jty'

function processAPIResponse(data: unknown) {
    if (!isPOJO(data)) {
        throw new TypeError(`Expected a plain object. Got ${data} (${typeof data})`)
    }
    if (!hasProp(data, 'name', 'age')) {
        throw new ReferenceError('Response is missing required properties "name" and/or "age"')
    }
    if (!isStr(data.name)) {
        throw new TypeError(`"name" must be a string. Got ${data.name} (${typeof data.name})`)
    }
    if (!isNum(data.age)) {
        throw new TypeError(`"age" must be a number. Got ${data.age} (${typeof data.age})`)
    }
    // Safe to use data.name and data.age here
}

If the validation code is repeated, create a guard:

import { isPOJO, isStr, isNum, hasProp } from 'jty'

interface APIResponse {
    name: string
    age: number
}

function isValidAPIResponse(data: unknown): data is APIResponse {
    return isPOJO(data) && hasProp(data, 'name', 'age') && isStr(data.name) && isNum(data.age)
}

function processAPIResponse(data: unknown) {
    if (!isValidAPIResponse(data)) {
        throw new TypeError(`Unexpected API response: ${JSON.stringify(data)}`)
    }
    // Safe to use data.name and data.age here
}

Use the provided guards to narrow down a type to expected ranges.

For example:

import { isStr, isStrLen } from 'jty'

const id: unknown = 'sk_0123456789'

// Returns true as long as id is a string
isStr(id)
// Checks that id is a string between 10-64 character long (inclusive)
isStrLen(id, 10, 64)

The validation is not limited to TypeScript types. In combination with JavaScript functions, we can narrow down the expectations.

For example:

import { isStrLen } from 'jty'

const id: unknown = 'sk-abc123'

// Checks that id is less than 256 characters, starts with a specific prefix, and contains only alphanumeric characters and hyphens
isStrLen(id, undefined, 256) && id.startsWith('sk-') && /^[A-Za-z0-9-]+$/.test(id)

2. Verify Close to Usage

Validate parameters inside the function that actually depends on them, not in a distant caller. This produces clearer stack traces and keeps type requirements co-located with the logic that needs them.

import { isArr } from 'jty'

// BAD: caller validates, callee assumes
function caller(items: unknown) {
    if (!isArr(items)) throw new TypeError('...')
    process(items) // process() blindly trusts the caller
}

// GOOD: callee validates what it needs
function process(items: unknown) {
    if (!isArr(items)) {
        throw new TypeError(`process(): "items" must be an array. Got ${items} (${typeof items})`)
    }
    // ...
}

There are exceptions for performance reasons. For example, if a function is called in a tight loop and the caller already validates the input, it may be acceptable to skip validation in the callee. But this should be the exception, not the norm, and should be clearly documented.

import { isArr } from 'jty'
// Acceptable if process() is called in a tight loop and caller already validates
function caller(items: unknown, options: { id: string }) {
    if (!isArr(items)) throw new TypeError('...')
    if (!isPOJO(options) || !hasProp(options, 'id')) throw new TypeError('...')
    for (let i = 0; i < items.length; i++) {
        process(items[i], options) // process() trusts the caller for performance reasons
    }
}
function process(item: unknown, options: { id: string }) {
    if (!isNum(item)) {
        throw new TypeError(`process(): "item" must be a number. Got ${item} (${typeof item})`)
    }
    // don't validate options
}

2.1 Verify when setting state

The only exception to "Verify Close to Usage" is when setting state (e.g. class properties). In those cases, validate the input at the point of setting the state to ensure that the internal state of the system is always valid.

import { isStr } from 'jty'

class User {
    private _name: string
    private readonly _age: number

    constructor(name: unknown, age: unknown) {
        this.name = name
        if (!inRangeInt(age, 0, 150)) {
            throw new TypeError(
                `User.constructor(): "age" must be a number between 0 and 150. Got ${age} (${typeof age})`,
            )
        }
        this._age = age
    }

    set name(name: unknown) {
        if (!isStr(name)) {
            throw new TypeError(`User.name(): "name" must be a string. Got ${name} (${typeof name})`)
        }
        this._name = name
    }

    get name() {
        return this._name
    }
}

3. Don't Double-Verify

If a value is merely passed through to another function, let that function handle validation. Avoid redundant checks in pass-through layers — they hurt performance and create maintenance burden.

import { isStr } from 'jty'

// BAD: both layers check the same thing
function outerFnBad(name: unknown) {
    if (!isStr(name)) throw new TypeError('...')
    innerFnBad(name)
}
function innerFnBad(name: unknown) {
    if (!isStr(name)) throw new TypeError('...')
    // ...
}

// GOOD: only innerFn validates since it uses the value
function outerFn(name: unknown) {
    innerFn(name)
}
function innerFn(name: unknown) {
    if (!isStr(name)) {
        throw new TypeError(`innerFn(): "name" must be a string. Got ${name} (${typeof name})`)
    }
    // ...
}

4. Use The Narrowest and Most Appropriate Error Classes

Throw the appropriate standard JavaScript error subclass because they add extra context about what type of expectation we had and what type of fix applies (e.g. guide the developer or AI agent to diagnose why the received type or reference was wrong):

Error Class	When to Use	jty Example
TypeError	Value has an unexpected type	!isStr(x), !isObj(x)
ReferenceError	Required property is missing	!hasProp(obj, 'key')
RangeError	Value falls outside expected boundary	!inRange(x, 0, 10), !isIdx()
SyntaxError	Malformed structure or failure when validating parsed strings/JSON

5. Emit Meaningful Error Messages

A good error message should answer these questions:

1. What failed? - Which variable, property, or operation was the issue?
2. What was expected? - What type, shape, or value range did we expect?
3. What was actually received? - What value did we get instead, and what type is it?
4. Optional: How to fix it? - Ideally, it should highlight common pitfalls and offer a suggestion for how to fix the issue as well.

// BAD: it misses context
throw new TypeError('Invalid input')

// GOOD: it says where the error happened, what was expected and what was received
throw new TypeError(
    `processId(): "id" must be a string. Got ${id} (${typeof id}).\nDid you forget to encode it from a URL parameter or parse it from JSON?`,
)

6. Use Error Chaining with cause

Exceptions traverse function boundaries, making it hard to understand why an operation failed when the error originates from a deeply nested call. Use cause to add context at intermediate layers:

import { isStr } from 'jty'

async function fetchUserProfile(userId: unknown) {
    if (!isStr(userId)) {
        throw new TypeError(`fetchUserProfile(): "userId" must be a string. Got ${userId} (${typeof userId})`)
    }
    try {
        const response = await fetch(`/api/users/${encodeURIComponent(userId)}`)
        return await response.json()
    } catch (err) {
        throw new Error(`Failed to fetch profile for user "${userId}"`, { cause: err })
    }
}

7. Protect Against Missing TypeScript Guarantees

Although code is written in TypeScript, it may be called from JavaScript where type checking is absent. Also, when working with Small Language Models (SLMs) for code generation, we cannot be sure they follow all type constraints. Always verify and fail with meaningful error messages.

import { isInstance } from 'jty'

// Even though TypeScript says `date` is a Date, verify at runtime
// because a JavaScript caller could pass anything
export function formatDate(date: Date): string {
    if (!isInstance(date, Date)) {
        throw new TypeError(`formatDate(): "date" must be a Date. Got ${date} (${typeof date})`)
    }
    return date.toISOString()
}

8. Use Pure Stateless Functions Whenever Possible

Pure functions do not rely on or modify external state, making them easier to test, debug, and reason about. They also work better with AI agents since they don't have side effects that can lead to unexpected behaviors.

// BAD: relies on external state
let config = { maxItems: 10 }
function isValidItemCount(count: unknown) {
    if (!isNum(count)) {
        throw new TypeError(`"count" must be a number. Got ${count} (${typeof count})`)
    }
    return count >= 0 && count <= config.maxItems
}

// GOOD: pure function with explicit parameters
function isValidItemCount(count: unknown, maxItems: number) {
    if (!isNum(count)) {
        throw new TypeError(`"count" must be a number. Got ${count} (${typeof count})`)
    }
    if (!isNum(maxItems)) {
        throw new TypeError(`"maxItems" must be a number. Got ${maxItems} (${typeof maxItems})`)
    }
    return count >= 0 && count <= maxItems
}

If a class method does not rely on instance state, it should be a static method or a standalone function. This makes it clear that the method does not have side effects and can be used without instantiating the class.

8.1 Use Classes When the State is Consistent and Persistent

If a state doesn't change that often, use a class instead of expecting it in every invocation:

import { isStr } from 'jty'

// GOOD: class encapsulates the state and related behavior
class ItemValidator {
    private readonly maxItems: number
    constructor(maxItems: unknown) {
        if (!isNum(maxItems)) {
            throw new TypeError(`"maxItems" must be a number. Got ${maxItems} (${typeof maxItems})`)
        }
        this.maxItems = maxItems
    }
    isValidItemCount(count: unknown) {
        if (!isNum(count)) {
            throw new TypeError(`"count" must be a number. Got ${count} (${typeof count})`)
        }
        return count >= 0 && count <= this.maxItems
    }
}

9. Avoid inheritance and prefer composition

Inheritance can lead to tight coupling and fragile code. Prefer composition of functions and objects to achieve the desired behavior without creating complex class hierarchies.

Composition allows for more testable, flexible, and reusable code, as you can mix and match behaviors without being constrained by an inheritance structure.

A system composed of smaller parts is easier to verify.

10. Test depth first

A system is composed of smaller components. A code base is composed of smaller code constructs (functions, modules, directories, etc.).

Always:

1. Start by unit testing each component first to fail early at a granular level and fix issues in isolation in smaller context.
2. Continue by integration testing the system composed of those components
3. Finish off by smoke testing the most critical or common use cases for the system
4. As a bonus you can continuously run the smoke tests against the production deploy to identify any service degradation or disruption.

10. Don't fight the library, framework or platform

It is tempting to create workarounds when the library, framework or platform doesn't provide a way to address edge cases. But often those workarounds are more complex and less efficient than just rethinking your solution or switching the library or framework to something more fit to purpose, if possible.

11. Prioritize the right trade-offs

Engineering is the art of trade-offs. There are many big or small decisions against a list of alternatives.

In general follow these priorities:

1. Security
2. Reliability (including scalability, correctness, and predictability)
3. Usability (Accessibility & UX)
4. Maintainability (including readability, debuggability, and ease of onboarding new developers or AI agents)
5. Brevity (code length)
6. Affordability (cost of running the code)
7. Performance

The way to use this list is to ask yourself: "Does this make the code more performant at the cost of making it less secure?" You should be able to confidently defend you choices by stating: "This change makes the code shorter but it hurts performance and that's OK".

The priorities are different based on product (e.g. a game may prioritize performance over maintainability and use complex code). The priority can even vary in the same code base (e.g. a piece of code that runs in a sandbox may prioritize maintainability over security).

When unsure, ask the human for help because in all likelihood, they haven't put all the requirements in the words, and not everything they have put in words is available in the context. Err on the side of asking approval instead of going YOLO and guess.