typescript-patterns

TypeScript Patterns

Comprehensive patterns for TypeScript code organization, classes, types, and symbols.

Code Style Conventions

Syntax & Formatting

• Newline after function declaration and opening blocks
• Prefer vertical space over horizontal when functions are long
• Group functions: Declaration → Validation → Business Logic → Commit

Naming Philosophy

• Use meaningful names that explain what the thing is
  • ✅ userExists, fetchInvoiceTotal
  • ❌ x, data, handleIt
• Functions should read like English

Comments & JSDoc

• JSDoc all functions and classes
• Explain WHY something exists — not how or what
• Always provide usage examples

Function Structure

Use our 4-block structure for complex functions:

/**
 * Updates the email address for a given user.
 *
 * @example
 * const user = await updateUserEmail(userID, newEmail);
 */
async function updateUserEmail(userID: UUID, newEmail: EmailAddress): Promise<User> {

    let retryCount = 0;

    if (!isValidEmail(newEmail)) {

        throw new InvalidEmailError();
    }

    const [user, err] = await attempt(() => fetchUser(userID));

    if (err || !user) {

        throw new UserNotFoundError();
    }
    else if (user.email === newEmail) { // notice that else is not on the same line as the closing if

        return user;
    }

    const modifiedUser = modifyUserEmail(user, newEmail);

    const [ok, saveErr] = await attempt(() => saveUser(modifiedUser));

    if (saveErr) {

        throw saveErr;
    }

    return modifiedUser;
}

Where the "declaration" block is:

Declare places in a single, predictable place.

function updateUserEmail(userID: UUID, newEmail: EmailAddress): Promise<User> {

    let retryCount = 0; // <-- declare vars first
    // ...
}

"Validation" block is:

We validate inputs whenever appropriate to have as much predictability as possible

    if (!isValidEmail(newEmail)) {

        throw new InvalidEmailError();
    }

    const [user, err] = await attempt(() => fetchUser(userID));

    if (err || !user) {

        throw new UserNotFoundError();
    }
    else if (user.email === newEmail) { // notice that else is not on the same line as the closing if

        return user;
    }