> TypeScript > TypeScript Type System > Forge Type Predicates: Master TypeScript 'is' Functions

Forge Type Predicates: Master TypeScript 'is' Functions

We navigate the complex interplay between runtime dynamics and compile-time assurances in software development. Ever faced the frustration of a TypeError at runtime, despite your TypeScript code compiling without a hitch? This ubiquitous challenge often stems from discrepancies between what TypeScript infers statically and the actual state of data during execution. To bridge this critical gap, TypeScript arms us with a potent tool: Custom Type Predicates. These specialized functions empower us to declare explicit type relationships, enabling the compiler to narrow types with precision based on runtime checks. Imagine crafting reusable validation logic that not only confirms data integrity but also immediately informs the TypeScript compiler about the exact type of your variables within specific code blocks. This article illuminates the path to engineering powerful 'is' functions, transforming your approach to type safety and code reusability. We shall decode the core mechanics, advanced strategies, and architectural integration of type predicates, activating a new frontier in our journey toward mastering static typing and type inference in TypeScript. Prepare to elevate your codebase from reactive error handling to proactive type enforcement, forging a robust foundation for scalable and maintainable applications.

Published on: 18 October 2026

Deconstruct Custom Type Predicates: The Core Concept

We embark on a crucial exploration, decoding the fundamental architecture of Custom Type Predicates in TypeScript. At their core, these are specialized functions engineered to perform a runtime check and, crucially, to communicate the outcome of that check back to the TypeScript compiler. This communication happens through a unique return type signature: parameterName is Type. This isn't merely a boolean declaration; it's a compiler directive. When such a function returns true, TypeScript automatically narrows the type of parameterName to Type for the remainder of the current scope, or until a contradictory condition is met. This mechanism represents a powerful bridge, connecting dynamic runtime validations with static type safety, a critical leverage point in robust software engineering.

Consider the inherent challenge: JavaScript, and by extension TypeScript at runtime, operates on a dynamic type system. We frequently encounter scenarios where a variable's type might be a union (e.g., string | number | undefined) or an any, and we need to ascertain its specific type at runtime to perform type-specific operations. Without type predicates, our options are limited: either cumbersome type assertions (as Type), which bypass type safety and introduce potential runtime errors, or manual type guards (typeof x === 'string'), which, while effective, often lack reusability for complex object structures. Type predicates elevate these individual guards into encapsulated, reusable functions.

We activate this mechanism to achieve superior code clarity and maintainability. Instead of repeating if ('property' in obj && typeof obj.property === 'string') throughout our codebase, we encapsulate this logic within a single, descriptive predicate function like isSpecificObject(obj): obj is SpecificObject. This not only streamlines our code but also centralizes type-checking logic, making future modifications surgical and less error-prone. This foundational understanding empowers us to proactively sculpt our type system, transforming ambiguous data flows into precisely typed pathways, thereby enforcing compile-time guarantees that resonate through our entire application.

interface Car {
    make: string;
    model: string;
}

interface Bike {
    type: string;
    wheels: number;
}

type Vehicle = Car | Bike;

// A standard boolean function does NOT narrow the type. The compiler won't know 'vehicle' is a Car.
function isCarOld(vehicle: Vehicle): boolean {
    return 'make' in vehicle; // This check happens at runtime.
}

// A type predicate function DOES narrow the type. The 'vehicle is Car' signature is key.
function isCar(vehicle: Vehicle): vehicle is Car {
    // We perform a runtime check to determine if 'vehicle' possesses 'Car' properties.
    // A common way is to check for a distinguishing property.
    return (vehicle as Car).make !== undefined; 
}

// Example of usage demonstrating type narrowing
function processVehicle(vehicle: Vehicle) {
    if (isCar(vehicle)) {
        // Inside this block, TypeScript has narrowed 'vehicle' to 'Car'.
        // We can now safely access 'make' and 'model' without type assertions.
        console.log(`Processing car: ${vehicle.make} ${vehicle.model}`);
    } else {
        // In the 'else' block, TypeScript knows 'vehicle' must be 'Bike'.
        console.log(`Processing bike: ${vehicle.type} with ${vehicle.wheels} wheels`);
    }
}

// Test cases
const myCar: Vehicle = { make: "Toyota", model: "Camry" };
const myBike: Vehicle = { type: "Mountain", wheels: 2 };

processVehicle(myCar); // Output: Processing car: Toyota Camry
processVehicle(myBike); // Output: Processing bike: Mountain with 2 wheels

Engineering 'is' Functions: Syntactic Blueprint and Implementation

We now delve into the surgical precision required to Engineer 'is' Functions, decoding their syntactic blueprint and crafting practical implementations. The core signature for any type predicate function is function name(parameter: TypeA): parameter is TypeB. The initial type of the parameter (TypeA) often defaults to unknown or a wider union type if the possibilities are constrained. Employing unknown is a proactive choice, enforcing type safety within the predicate's body itself, demanding explicit checks before accessing properties, thereby preventing premature assumptions.

Within the function's body, we deploy JavaScript's intrinsic type-checking operators: typeof for primitives ('string', 'number', 'boolean', 'symbol', 'bigint', 'undefined') and the in operator for checking property existence on objects. For robust object validation, we frequently combine typeof and in checks. We first verify that the input is indeed an object and not null, then proceed to validate the presence and types of its expected properties. This multi-stage validation ensures comprehensive type safety and robustness.

For example, to assert that an unknown value is a specific interface MyInterface, we must check that it's an object, not null, and that all required properties exist and possess their correct types. We can strategically cast obj as Record<string, any> inside the predicate to facilitate property access, understanding this assertion is localized and part of the overall runtime validation process. This disciplined approach ensures that our predicates provide reliable assertions to the TypeScript compiler. By mastering this blueprint, we activate the capability to build highly accurate and reusable type guards, significantly strengthening the compile-time guarantees across our entire development ecosystem.

// 1. Basic predicate for a primitive type (less common but illustrates principle)
function isString(value: unknown): value is string {
    return typeof value === 'string';
}

// 2. Predicate for an object with a specific interface
interface User {
    id: number;
    name: string;
    email?: string; // Optional property
}

function isUser(obj: unknown): obj is User {
    // We activate a series of checks to ensure the object conforms to the 'User' interface.
    // First, ensure it's an object and not null, as 'typeof null' is 'object'.
    if (typeof obj !== 'object' || obj === null) {
        return false;
    }

    // Then, cast to a generic record type to safely access properties for runtime checks.
    const potentialUser = obj as Record<string, any>;

    // We verify the presence and type of mandatory properties.
    // For 'id', it must be a number.
    // For 'name', it must be a string.
    return (
        typeof potentialUser.id === 'number' &&
        typeof potentialUser.name === 'string' &&
        // Optionally, check for other properties if strictly required or if they have specific types.
        // If 'email' exists, it must be a string.
        (potentialUser.email === undefined || typeof potentialUser.email === 'string')
    );
}

// 3. Demonstrating usage of the engineered predicates
function processInput(input: unknown) {
    if (isString(input)) {
        // 'input' is narrowed to 'string' here.
        console.log(`Input is a string: ${input.toUpperCase()}`);
    } else if (isUser(input)) {
        // 'input' is narrowed to 'User' here.
        console.log(`Input is a user: ID=${input.id}, Name=${input.name}`);
    } else {
        console.log(`Input type not recognized: ${JSON.stringify(input)}`);
    }
}

// Test cases for our predicates
processInput("hello world"); // Output: Input is a string: HELLO WORLD
processInput({ id: 1, name: "Alice" }); // Output: Input is a user: ID=1, Name=Alice
processInput({ id: 2, name: "Bob", email: "bob@example.com" }); // Output: Input is a user: ID=2, Name=Bob
processInput(123); // Output: Input type not recognized: 123
processInput(null); // Output: Input type not recognized: null
processInput({}); // Output: Input type not recognized: {}

Advanced Predicate Strategies: Crafting Robust Type Guards

We now elevate our capabilities, delving into Advanced Predicate Strategies to craft truly robust type guards. One potent technique involves leveraging Discriminant Unions. When a union type has a common property (the 'discriminant') whose literal string value uniquely identifies the union member, type predicates become remarkably efficient. We engineer specific 'is' functions, like isCircle(shape): shape is Circle, where the check simply verifies shape.kind === "circle". This approach dramatically simplifies type narrowing for complex data structures, ensuring compile-time safety across intricate branching logic.

While direct generic type predicates like is<T>(item: unknown): item is T are inherently complex due to JavaScript's lack of runtime type information for arbitrary T, we can strategically employ generics to enforce structural constraints on the input parameter. For instance, a predicate like hasProperty<K extends string>(obj: object, prop: K): obj is Record<K, unknown> dynamically asserts the presence of a property K on an object. This empowers us to create highly flexible and reusable checks that adapt to varying data shapes, without requiring runtime reflection on the generic type T itself.

To avoid common pitfalls, we must adhere to disciplined practices. First, ensure the predicate's return logic is surgically precise: returning true unequivocally means the parameter matches the asserted type. Incomplete property checks are a primary source of false positives and runtime errors. Second, strictly enforce pure function principles; type predicates must not introduce side effects. Their sole purpose is to perform a type assertion. Third, adopt descriptive naming conventions (e.g., isUser, hasStringProperty) to clearly communicate intent. Finally, centralize your predicate definitions. This engineering practice transforms scattered type-checking logic into a cohesive, maintainable module, facilitating easier audits and updates. We activate these strategies to forge a codebase with unparalleled type integrity and architectural clarity.

// 1. Predicates for a Discriminant Union: The 'kind' property distinguishes between types.
interface Circle {
    kind: "circle";
    radius: number;
}

interface Square {
    kind: "square";
    sideLength: number;
}

type Shape = Circle | Square;

function isCircle(shape: Shape): shape is Circle {
    // We leverage the 'kind' property as a discriminant to surgically narrow the type.
    return shape.kind === "circle";
}

function isSquare(shape: Shape): shape is Square {
    return shape.kind === "square";
}

// Usage for discriminant unions: 'getArea' leverages predicates for safe type-specific logic.
function getArea(shape: Shape): number {
    if (isCircle(shape)) {
        // 'shape' is now a Circle object; TypeScript knows 'radius' exists.
        return Math.PI * shape.radius ** 2;
    } else if (isSquare(shape)) {
        // 'shape' is now a Square object; TypeScript knows 'sideLength' exists.
        return shape.sideLength ** 2;
    }
    // A robust system accounts for all possibilities, though TS helps here to ensure exhaustive checks.
    throw new Error("Unknown shape type");
}

console.log(`Area of circle: ${getArea({ kind: "circle", radius: 10 })}`); // Output: Area of circle: 314.159...
console.log(`Area of square: ${getArea({ kind: "square", sideLength: 5 })}`); // Output: Area of square: 25


// 2. Conceptualizing Generics with Type Predicates for structural constraints
// Direct 'is T' for arbitrary T at runtime is problematic, but generics can constrain parameters.

interface HasId {
    id: string;
}

// This predicate ensures the input is an object with a string 'id' property.
// It uses a generic 'T' to ensure the input 'obj' is an object.
// The return type 'obj is T & HasId' correctly narrows 'obj' to include the 'HasId' properties
// while preserving 'T's original properties.
function hasStringId<T extends object>(obj: T): obj is T & HasId {
    // Validate that 'obj' is an object, not null, and has a string 'id' property.
    return typeof obj === 'object' && obj !== null && typeof (obj as HasId).id === 'string';
}

// Usage example for hasStringId with union types
interface ItemA {
    name: string;
    id: string;
}

interface ItemB {
    value: number;
}

type MixedItem = ItemA | ItemB;

function processItem(item: MixedItem) {
    if (hasStringId(item)) {
        // 'item' is narrowed to ItemA because ItemA is the only union member satisfying 'HasId'.
        console.log(`Processing item with ID: ${item.id} and name: ${item.name}`);
    } else {
        // 'item' is narrowed to ItemB.
        console.log(`Processing item without string ID: ${item.value}`);
    }
}

processItem({ name: "Widget", id: "abc-123" }); // Output: Processing item with ID: abc-123 and name: Widget
processItem({ value: 42 }); // Output: Processing item without string ID: 42

Activating Predicates for Enhanced Code Architectures

We extend our strategic reach, focusing on Activating Predicates for Enhanced Code Architectures, transforming how we structure and validate our applications. Custom type predicates transcend simple type narrowing; they become foundational elements for constructing robust, maintainable, and scalable systems. We leverage them to solidify the boundaries between trusted internal logic and unpredictable external data, particularly when interfacing with APIs or processing user inputs. By defining clear is functions for expected data structures—like isApiResponseSuccess(response): response is ApiResponseSuccess—we gain immediate compile-time assurances that allow us to process complex API responses with absolute type safety.

This architectural integration minimizes the pervasive boilerplate often associated with runtime validation. Instead of ad-hoc checks spread throughout our application, we centralize this logic within reusable predicates. This significantly reduces the likelihood of type-related runtime errors, as the compiler becomes an active partner in validating our data flows. Consider scenarios involving factory functions that return union types: createShape(config): Circle | Square. Type predicates empower us to immediately determine the exact type of the created object, activating specific processing logic without resorting to dangerous type assertions.

Furthermore, predicates enhance established design patterns. In a Strategy pattern, where different algorithms operate on varying data types, type guards allow us to dynamically select and execute the correct strategy, ensuring type correctness at each step. This approach transforms conditional logic from error-prone guesswork into precise, type-safe decision-making. The cumulative effect is a codebase that is not only more resilient to change but also inherently more readable and understandable. We proactively optimize our code flow, reducing verbose if/else chains and the need for repetitive type assertions, thereby forging a development environment where type safety is an inherent property, not an afterthought.

// Define interfaces for API response types, demonstrating a discriminant union pattern.
interface ApiResponseSuccess {
    status: "success";
    data: any; // 'any' here for simplicity, but could be specific type 'T' if API is generic.
}

interface ApiResponseError {
    status: "error";
    message: string;
    code: number;
}

type ApiResponse = ApiResponseSuccess | ApiResponseError;

// Type Predicate to check for a success response, using 'status' as the discriminant.
function isSuccessResponse(response: ApiResponse): response is ApiResponseSuccess {
    return response.status === "success";
}

// Type Predicate to check for an error response.
function isErrorResponse(response: ApiResponse): response is ApiResponseError {
    return response.status === "error";
}

// Simulate an API call function that returns a union type based on logic.
function fetchUserData(id: string): ApiResponse {
    if (id === "user-123") {
        return {
            status: "success",
            data: { id: "user-123", name: "Jane Doe", email: "jane@example.com" } // Example user data
        };
    } else {
        return {
            status: "error",
            message: "User not found",
            code: 404
        };
    }
}

// Define a UserData interface to further narrow the 'data' field in success responses.
interface UserData { id: string; name: string; email: string; }

// Reuse an 'isUser' predicate, adapted for UserData, to validate nested data structure.
function isUserData(data: unknown): data is UserData {
    if (typeof data !== 'object' || data === null) {
        return false;
    }
    const potentialUserData = data as Record<string, any>;
    return (
        typeof potentialUserData.id === 'string' &&
        typeof potentialUserData.name === 'string' &&
        typeof potentialUserData.email === 'string'
    );
}

// Process the API response using predicates to safely handle different outcomes.
function handleApiResponse(response: ApiResponse) {
    if (isSuccessResponse(response)) {
        // TypeScript has narrowed 'response' to 'ApiResponseSuccess'.
        console.log("API Call Success:");
        // We can now safely access 'response.data'. Further validation with 'isUserData'.
        if (isUserData(response.data)) {
            console.log(`  User: ${response.data.name}, Email: ${response.data.email}`);
        } else {
            console.log("  Success, but received unexpected data structure.");
            console.log(response.data); // Log for inspection
        }
    } else if (isErrorResponse(response)) {
        // TypeScript has narrowed 'response' to 'ApiResponseError'.
        console.error(`API Call Error: ${response.message} (Code: ${response.code})`);
    } else {
        // Fallback for unexpected response types (should ideally not happen with strict unions).
        console.error("Received an unknown API response type.");
    }
}

// Example usage for both success and error scenarios.
const successfulResponse = fetchUserData("user-123");
handleApiResponse(successfulResponse); // Processes success with user data.

const failedResponse = fetchUserData("user-456");
handleApiResponse(failedResponse); // Processes error with message and code.

Optimizing Development with Type Predicates: Best Practices and Pitfalls

We conclude our journey by optimizing our development workflow through a set of refined practices and a clear understanding of common pitfalls when deploying type predicates. To truly Optimize Development with Type Predicates, we forge them with precision and discipline. A key principle is to keep predicates focused and atomic. Each predicate should surgically verify one specific type condition, avoiding the temptation to embed complex business logic within its body. This ensures reusability and simplifies debugging. For instance, isAdminUser should only check if a user is an admin, not whether they can perform a specific action, which can be handled by combining predicates or separate functions that consume the narrowed type.

We organize our predicates strategically, often placing them in dedicated utility files or modules. This centralizes type-guarding logic, transforming it into a first-class architectural component. Activating compositional strategies, we combine simpler predicates to construct more elaborate type checks. For example, isLoggedInAndAdmin(user) might internally call isLoggedIn(user) and isAdmin(user), leveraging the power of cascading type narrowing. This approach promotes modularity and enhances the maintainability of complex validation flows.

We must navigate common pitfalls with vigilance. A prevalent error is mistaking a simple boolean return for type narrowing. Remember, only the is keyword in the return signature activates the compiler's type-narrowing capabilities. Over-reliance on any within a predicate's implementation defeats its purpose; proactively use unknown to enforce rigorous checks. While performance impacts are generally negligible for type predicates, prioritizing clarity and correctness always outweighs micro-optimizations. By adhering to these best practices, we engineer a codebase that is not only robust and scalable but also intrinsically easier to understand and evolve. We solidify our understanding of the is keyword's power, transforming it from a mere keyword into a cornerstone of intelligent, type-safe software architecture, future-proofing our applications against the complexities of dynamic data.

// Define more specific interfaces for user roles, forming a discriminant union.
interface AdminUser {
    id: string;
    username: string;
    role: "admin";
    permissions: string[];
}

interface EditorUser {
    id: string;
    username: string;
    role: "editor";
    lastEditDate: Date; // Using Date object
}

type AuthenticatedUser = AdminUser | EditorUser;

// Predicate to check for a generic authenticated user structure.
// This is a refined 'isUser' adapted for the AuthenticatedUser union.
function isAuthenticatedUser(obj: unknown): obj is AuthenticatedUser {
    if (typeof obj !== 'object' || obj === null) {
        return false;
    }
    const potentialUser = obj as Record<string, any>;
    // Ensure mandatory properties exist and 'role' is one of the valid discriminant values.
    return (
        typeof potentialUser.id === 'string' &&
        typeof potentialUser.username === 'string' &&
        (potentialUser.role === "admin" || potentialUser.role === "editor")
    );
}

// Predicates for specific roles, leveraging the 'role' discriminant.
function isAdminUser(user: AuthenticatedUser): user is AdminUser {
    return user.role === "admin";
}

function isEditorUser(user: AuthenticatedUser): user is EditorUser {
    return user.role === "editor";
}

// Combine predicates for complex authorization logic, demonstrating reusability.
function canDeleteContent(user: AuthenticatedUser): boolean {
    // We combine predicates to build a complex authorization check.
    // Only administrators possess the general ability to delete content.
    if (isAdminUser(user)) {
        return true; // Admins can always delete.
    }
    return false; // Editors (or other roles) cannot delete content in this simplified model.
}

// Example usage demonstrating predicate chaining and type narrowing in action.
const admin: AuthenticatedUser = {
    id: "a1",
    username: "AdminUser",
    role: "admin",
    permissions: ["manage_users", "delete_content"]
};

const editor: AuthenticatedUser = {
    id: "e1",
    username: "EditorUser",
    role: "editor",
    lastEditDate: new Date()
};

const guest = { id: "g1", username: "Guest", role: "guest" }; // Not an AuthenticatedUser by our predicate

function processUserAction(user: unknown) {
    if (isAuthenticatedUser(user)) {
        console.log(`Processing authenticated user: ${user.username} (Role: ${user.role})`);
        if (canDeleteContent(user)) {
            console.log(`  -> User '${user.username}' CAN delete content.`);
        } else {
            console.log(`  -> User '${user.username}' CANNOT delete content.`);
        }

        // Further specific narrowing for role-based actions
        if (isAdminUser(user)) {
            // 'user' is now AdminUser; access admin-specific properties.
            console.log(`  -> Admin Permissions: ${user.permissions.join(", ")}`);
        } else if (isEditorUser(user)) {
            // 'user' is now EditorUser; access editor-specific properties.
            console.log(`  -> Editor Last Edit: ${user.lastEditDate.toLocaleDateString()}`);
        }
    } else {
        console.log(`Processing unauthenticated entity: ${JSON.stringify(user)}`);
    }
}

processUserAction(admin);
/* Output:
Processing authenticated user: AdminUser (Role: admin)
  -> User 'AdminUser' CAN delete content.
  -> Admin Permissions: manage_users, delete_content
*/

processUserAction(editor);
/* Output:
Processing authenticated user: EditorUser (Role: editor)
  -> User 'EditorUser' CANNOT delete content.
  -> Editor Last Edit: [current date in locale format]
*/

processUserAction(guest); // Output: Processing unauthenticated entity: {"id":"g1","username":"Guest","role":"guest"}
processUserAction(null); // Output: Processing unauthenticated entity: null

Key Takeaways

Deciphering Type Predicates' Core

Custom Type Predicates, with their unique parameter is Type signature, bridge runtime checks and compile-time type safety. They empower the TypeScript compiler to precisely narrow types based on dynamic conditions, transforming ambiguous data into strictly typed flows and significantly enhancing code clarity and reusability over manual guards or dangerous assertions.

Blueprint for 'is' Function Engineering

We construct 'is' functions using the unknown type for broad input handling, deploying typeof and in operators for robust runtime validation. Meticulous checks for object presence, null values, and property types are paramount. This disciplined engineering ensures reliable type assertions, strengthening compile-time guarantees across the codebase.

Mastering Advanced Predicate Strategies

Elevate type guarding with Discriminant Unions, where a common property simplifies type narrowing for complex structures. While direct generic type predicates are challenging, generics constrain input parameters effectively. Adhere to pure function principles, precise return logic, comprehensive checks, and descriptive naming to avoid pitfalls and forge robust, centralized type-checking logic.

Architecting with Predicates for Code Enhancement

Type predicates are architectural pillars, crucial for validating external data from APIs and user inputs. They minimize boilerplate, centralize validation logic, and integrate seamlessly into design patterns like factory functions or the Strategy pattern. This approach optimizes code flow, reducing repetitive assertions and forging resilient, maintainable, and scalable applications.

Optimizing & Avoiding Pitfalls

To optimize, design atomic, focused predicates without complex business logic. Organize them in dedicated utilities and combine them for intricate checks. Beware of mistaking boolean returns for type narrowing, and always prefer unknown over any within predicates. This disciplined approach establishes type safety as an intrinsic property of the application's architecture, future-proofing development.

Editorial Team

← Forge Unbreakable Code: Mastering TypeScript's Static Typing and Type Inference Forge Types: Extract Function Return Signatures with ReturnType →

FAQ

What is the fundamental difference between a function returning `boolean` and one returning `parameter is Type`?

A function returning boolean simply indicates whether a condition is true or false. The TypeScript compiler infers no additional type information from it. In contrast, a function returning parameter is Type is a compile-time type assertion. If this function returns true, TypeScript understands that parameter is now of the specified Type within the rest of the conditional code block, and it narrows the type accordingly. This is the key to dynamic type safety.
Can type predicate functions have side effects?

No, type predicate functions must be pure functions. Their sole responsibility is to verify a type condition and communicate it to the compiler via the is Type signature. Introducing side effects (like modifying global state or performing network requests) inside a predicate breaks the predictability and clarity of your codebase, making bugs difficult to trace. We advocate for surgical design where each function has a unique, well-defined role.
When should I use a type predicate versus a type assertion (`as Type`)?

We employ type predicates when we want to perform a dynamic type check (at runtime) and inform the TypeScript compiler of the outcome, enabling safe type narrowing. This is ideal for validating external inputs or polymorphic data. Type assertions (as Type) are direct hints to the compiler that we 'know better' than it, forcing a type without runtime verification. They should be used sparingly and cautiously, primarily when runtime verification is already guaranteed by other means or for specific cases where you are absolutely certain of the type. Predicates are proactive and secure; assertions are more of a manual override.
Can TypeScript type predicates be generic?

Yes, type predicate functions can be generic, but their direct application with is T for an arbitrary T is complex because JavaScript lacks generic type information at runtime. However, we can use generics to constrain the type of the predicate's parameters, or to define predicates that check for generic properties, for example, hasProperty<K extends string>(obj: unknown, prop: K): obj is Record<K, unknown>. This allows us to engineer flexible and reusable type guards that adapt to different structures.
Are type predicates checked at runtime or compile-time?

This is a crucial distinction. The internal logic of a predicate function (the function body) is executed at runtime, as it performs standard JavaScript checks (like typeof or in). However, the type narrowing effect of the parameter is Type signature is a directive exclusively for the TypeScript compiler at compile-time. It uses the runtime function's result to adjust its static type model for subsequent code blocks.