TypeScript Builder Pattern for Conditional Validation in SaaS

How Did the TypeScript Builder Pattern Challenge Surface in a Real SaaS Project?

While working on a core access management module for a large-scale enterprise SaaS platform, we needed a robust way to construct complex domain objects before passing them down to the repository layer. To handle the object instantiation cleanly in our Node.js and TypeScript environment, the team implemented the Builder pattern. However, during the development of an AccessPolicy entity, we encountered a nuanced architectural challenge.

We realized that our data layer required dynamic validation rules depending on whether the incoming payload was intended for a “Create” or an “Update” operation. For a Create operation, the database primary key (ID) is inherently missing, making all other fields strictly mandatory. Conversely, for an Update operation, the ID is strictly mandatory to locate the record, but the other payload fields become optional—provided that at least one field is supplied to avoid executing empty database queries. Failing to enforce these mutually exclusive states at runtime would result in either data corruption or overwriting existing database columns with null values.

This situation sparked a deep dive into how builders handle dynamic state variations. We are sharing this engineering experience so other teams can avoid writing fragmented object states and implement conditional runtime validations gracefully.

Why Do Conditional Runtime Validations Matter in Backend Architecture?

In modern backend systems, the transition of data between the controller, the business logic layer and the repository layer must be heavily guarded. When a repository layer executes an operation, it blindly trusts the domain entity or Data Transfer Object (DTO) it receives. In our use case, the rules were strict but contextual:

• For Creation: The id attribute must not exist. The policyName and resourceModule attributes are strictly mandatory to create a valid record.
• For Update: The id attribute is strictly mandatory. The policyName and resourceModule become optional, but at least one must be provided. Unprovided fields must remain undefined so the repository’s Query Builder knows to ignore them and not overwrite existing database columns.

If the application cannot safely differentiate between these two contexts during object construction, it risks passing incomplete models to the database, resulting in failed constraints or silent data loss.

What Went Wrong With the Initial Builder Implementation?

Our initial implementation correctly applied the Builder pattern for fluent method chaining, but it failed to support the conditional optionality of the fields. The individual setter methods were immediately validating their inputs, assuming all fields were always required. Here is a sanitized representation of the bottleneck:

export class AccessPolicyBuilder {
    private id?: string;
    private policyName?: string;
    private resourceModule?: string;
    setId(id: string): AccessPolicyBuilder {
        if (!id || !id.trim()) throw new Error('ID cannot be empty');
        this.id = id;
        return this;
    }
    setPolicyName(name: string): AccessPolicyBuilder {
        if (!name || !name.trim()) throw new Error('Policy Name cannot be empty');
        this.policyName = name;
        return this;
    }
    // Similar setter for resourceModule...
    build() {
        // The builder lacked the context to enforce conditional rules here
        return {
            id: this.id,
            policyName: this.policyName,
            resourceModule: this.resourceModule,
        };
    }
}

The symptom was immediate: Update operations failed because the setters threw errors on missing fields and Create operations were occasionally passing without necessary attributes if the developer forgot to call a specific setter. The builder lacked contextual awareness of its final state.

How Did We Approach Solving the Conditional Validation Dilemma?

When you hire backend developers for system design, evaluating tradeoffs between strictness and flexibility is crucial. We debated multiple approaches to solve this without creating a bloated or fragmented codebase.

Did We Consider Using Two Separate Builders?

Our first thought was to split the logic into a CreateAccessPolicyBuilder and an UpdateAccessPolicyBuilder. This would provide absolute type safety at compile time. However, this approach would lead to significant code duplication, especially as the entity scales to include dozens of fields. Maintaining two separate builders for a single domain entity violates the DRY (Don’t Repeat Yourself) principle in this context.

Did We Consider Explicit Build Methods?

We also evaluated keeping a single builder but exposing two distinct build methods: buildForCreate() and buildForUpdate(). While this cleanly separates the validation logic, it forces the consuming service to know exactly which method to invoke, bypassing the generic polymorphic nature of a standard build() method. If a generic factory class was utilizing this builder, it would require ugly switch statements to determine the right method.

Did We Consider A State Machine Approach?

Finally, we looked at implementing internal state tracking inside the generic build() method. By deferring the complex, cross-field validation logic until the exact moment build() is invoked, the setter methods remain simple state mutators. The build() method acts as the gatekeeper, evaluating the entirety of the object’s state in one go. We chose this approach as it maintained the standard interface while enforcing our business rules safely.

What Did the Final TypeScript Implementation Look Like?

We refactored the builder to perform conditional evaluation at the final construction step. By inspecting the presence of the id field, the builder dynamically infers the operation type. This is a pattern we highly recommend when clients hire typescript developers for enterprise applications—it balances flexibility with defensive programming.

export class AccessPolicyBuilder {
    private id?: string;
    private policyName?: string;
    private resourceModule?: string;
    setId(id: string): AccessPolicyBuilder {
        this.id = id;
        return this;
    }
    setPolicyName(name: string): AccessPolicyBuilder {
        this.policyName = name;
        return this;
    }
    setResourceModule(module: string): AccessPolicyBuilder {
        this.resourceModule = module;
        return this;
    }
    build() {
        const isUpdate = this.id !== undefined && this.id.trim() !== '';
        if (isUpdate) {
            // Context: UPDATE OPERATION
            const hasPayload = this.policyName !== undefined || this.resourceModule !== undefined;
            if (!hasPayload) {
                throw new Error('Update payload invalid: At least one field must be provided alongside ID.');
            }
        } else {
            // Context: CREATE OPERATION
            if (!this.policyName || !this.policyName.trim()) {
                throw new Error('Create payload invalid: Policy Name is mandatory.');
            }
            if (!this.resourceModule || !this.resourceModule.trim()) {
                throw new Error('Create payload invalid: Resource Module is mandatory.');
            }
        }
        // Return a clean object, omitting undefined properties automatically
        // to ensure the repository layer does not overwrite with nulls
        return {
            ...(this.id && { id: this.id }),
            ...(this.policyName && { policyName: this.policyName }),
            ...(this.resourceModule && { resourceModule: this.resourceModule }),
        };
    }
}

This implementation completely resolves the fragmentation. The setters no longer throw premature errors. The build() method safely distinguishes between the two states, ensures no empty updates are sent to the database and uses the spread operator to construct a pristine object that the repository layer can consume directly.

What Are the Core Lessons for Engineering Teams?

Whether you hire nodejs developers for backend architecture or are training an internal team, standardizing how objects are validated is critical. Here are the actionable insights we extracted from this scenario:

• Defer Complex Validation to the Build Step: Individual setter methods should only validate the format of the specific input (e.g., regex checking an email). Cross-field dependency checks should always reside in the final build() phase.
• Protect Against Empty Updates: A common database anti-pattern is executing an UPDATE query with no altered fields. Enforcing a “minimum one field” rule in the builder prevents redundant database hits.
• Utilize Object Spread for Clean DTOs: By using the spread operator with logical AND (...(condition && { key: value })), you guarantee that unassigned properties are entirely omitted from the resulting object, avoiding unintentional null overwrites in an ORM.
• Keep the API Contract Simple: Resist the urge to create multiple builder classes or multiple build methods unless the domain entities are fundamentally distinct. A single smart build() method reduces cognitive load for the consuming services.
• Centralize Business Rules: Keeping the logic inside the builder prevents the service layer from becoming bloated with conditional if/else statements before saving data.

How Can Teams Standardize Object Creation Patterns?

Scaling a SaaS platform requires consistency in how data moves through the application. By centralizing contextual validation inside the Builder pattern, we prevented invalid states from bleeding into the repository layer. The approach is scalable, strictly typed and protects database integrity without compromising developer experience. If your engineering organization struggles with architectural consistency, it might be time to bring in experienced specialists. Feel free to contact us to explore how to hire software developer experts for your next enterprise build.

Social Hashtags

#TypeScript #TypeScriptTips #NodeJS #SaaS #BackendDevelopment #SoftwareArchitecture #DesignPatterns #BuilderPattern #WebDevelopment #SoftwareEngineering #CleanCode #BackendArchitecture #EnterpriseSoftware #Programming #Developers