DEV Community: Mohamed Fadlalla

The Evil of Optional Parameters: When Having too Many Options is Self Destructing

Mohamed Fadlalla — Sat, 10 Oct 2026 01:22:04 +0000

You are the main developer of agents.com, an app that lets an organization manage an army of AI agents. You’re designing an admin page where an admin within an org can see each agent and the skills associated with them. You write this beautiful, simple function that takes an orgId and agentId and returns a list of skills:

function getAgentSkills(orgId: string, agentId: string): AgentSkill[] {
  // fetches all of the skills from the server
}

The skills page needs to show some metadata along with the list of skills. For example, we need to show the name of the agent, the date they were created, and their specialties. Because of this, we make a small change to the return type of this function:

interface AgentSkillsResponse {
  agent: Agent;
  skills: Skill[];
}

function getAgentSkills(orgId: string, agentId: string): AgentSkillsResponse {
  // Some API calls
}

So far, so good! The page looks great, and admins are happy tracking their agents' contributions.

The Original Sin of Convenience

The agent section contains more than just a list of skills. You have independent pages for tasks, relations, and a high-level overview page. On the overview page, you want to show the top five agent skills.

However, you really don't want to return the agent object with the response here because you already have the agent information handy in the state, and you want to save yourself a heavy database join in your backend.

So, what do you do? You commit the first sin. You add a boolean optional parameter includeAgent. It defaults to true, and the overview page caller can just set it to false. Here is how your function looks now:

function getAgentSkills(
  orgId: string,
  agentId: string,
  includeAgent?: boolean = true
): AgentSkillsResponse {
  // fetches skills and includes agent conditionally
}

But wait, you also need to update the function return type because the agent is now optional:

interface AgentSkillsResponse {
  agent?: Agent;
  skills: Skill[];
}

Not bad, right? We'll see.

Descending Deeper: The Second Offense

Months later, your app is doing great. You are getting feature requests left and right. You need help, so you hire a new developer.

The first feature they work on is the UI for "deleted" agents. When an agent is deleted, you free up their username so new agents can use it. But new agents can be deleted as well! Your backend has a clever solution for this: you store a deletionTimeStamp to identify multiple agents deleted with the exact same username.

Your new developer wants to support showing skills for deleted agents on the skills page. What do they do? They pass a deletedAt param into your existing function. Because of data retention regulations, you don't store a lot of information about deleted agents, so the response shape is a bit different.

interface AgentSkillsResponse {
  agent?: Agent;
  deletedAgent?: DeletedAgent;
  skills: Skill[];
}

function getAgentSkills(
  orgId: string,
  agentId: string,
  includeAgent?: boolean = true,
  deletedAt?: DateTime,
): AgentSkillsResponse {
  // fetches skills and includes agent conditionally
}

Look closely at this function. The good news is that it returns a list of skills. But does it include an active agent or a deleted agent? Only God knows. Even worse, an agent cannot be active and deleted at the same time. What happens when someone passes includeAgent=true and deletedAt=Date(SOME_DATE) ? The function signature allows an impossible state.

Knocking on Hell's Door

As your business grows, you start allowing users to have more control over agents. However, this feature is only rolled out to an allowlisted set of users for A/B testing. You call this feature AgentControl.

When this feature is enabled, you expect the agent object to include more attributes—for example, allowed_tools, memory_config, and guardrail_profile_id. So, you add another optional parameter.

function getAgentSkills(
  orgId: string,
  agentId: string,
  includeAgent?: boolean = true,
  deletedAt?: DateTime,
  isAgentControlEnabled: boolean = false,
): AgentSkillsResponse {
  // fetches skills and includes agent conditionally
}

Keep in mind, the isAgentControlEnabled param is only relevant when fetching active agents. Deleted agents will always return the minimum response. This function already looks terrible, but there's no turning back now.

If You're Going Through Hell, Keep Going

Believe it or not, there are cases where optional parameters actually seem completely justified. Your skills service is heavily cached. When a new skill is added in the UI, or when the user clicks a manual refresh button, you want to invalidate the cache and force loading fresh data.

What do you do to our function? I think you know the answer by now.

function getAgentSkills(
  orgId: string,
  agentId: string,
  includeAgent?: boolean = true,
  deletedAt?: DateTime,
  isAgentControlEnabled?: boolean = false,
  invalidateCache?: boolean = false
): AgentSkillsResponse {
  // fetches skills and includes agent conditionally
}

Dragging the Rest of the Team Down With You

This is one of the worst functions I have ever seen in my life. Look at what we have done to the developers consuming this API. To simply fetch a fresh list of skills for an active agent with the control features turned on, this is what the call site looks like:

getAgentSkills('org1', 'agent1', true, undefined, true, false)

A string of random booleans and an undefined placeholder just to satisfy the TypeScript compiler.

It gets worse. Because our API is lying about its domain, consumers are forced to write defensive garbage code just to figure out what response they actually got back:

const response = getAgentSkills(...);

if (response.agent) {
  // render active agent UI
} else if (response.deletedAgent) {
  // render deleted agent UI
} else {
  // Wait, what does this even mean? Did includeAgent fail? 
}

Optional parameters didn't remove complexity; they just pushed the cognitive load onto everyone else.

The Path to Redemption (And How Rust Forces It)

When a function accumulates optional parameters like this, it’s a massive red flag that your domain model is muddy. The function is doing too much.

Do we even need optional parameters at the language level? The creators of Rust didn't think so. In Rust, there is no such thing as an optional function argument. If you tried to write our getAgentSkills function in Rust, the compiler would force you to design a strictly typed struct for your configuration, or force you to pass an explicit Option type.

Instead of passing random booleans, Rust forces you to encapsulate the behavior. Applied to our TypeScript codebase, the virtuous approach looks like this:

Split the Execution Threads
Fetching an active agent and fetching a deleted agent are fundamentally different operations. They deserve distinct functions: getActiveAgentSkills() and getDeletedAgentSkills().
Use an Options Object for Modifiers
For genuine behavioral modifiers, pass a single, strongly-typed configuration object instead of positional arguments.

interface FetchSkillOptions {
  includeAgentMetadata?: boolean;
  invalidateCache?: boolean;
  enableAgentControl?: boolean;
}

function getActiveAgentSkills(
  orgId: string, 
  agentId: string, 
  options?: FetchSkillOptions
): ActiveAgentResponse { ... }

Now, calling it is self-documenting:

getActiveAgentSkills('org1', 'agent1', { invalidateCache: true }).

The Two Golden Commandments of Optional Parameters

This isn't to say optional parameters are fundamentally evil everywhere. But if you want to keep your codebase clean, you should strictly limit them to two scenarios:

1. Enriching or Formatting the Response

Use optional parameters when the core operation remains exactly the same, but the shape of the output changes. Think of CLI commands like docker ps --format json. The system is still listing containers; it's just handing you the data differently.

2. Overriding Function Defaults

Use them to expose underlying knobs that usually don't need to be touched, like timeout=30ms or retries=3.

The Unforgivable Sin: You should never use an optional parameter to change the execution thread. If passing true makes your function hit a different database table, execute a different business rule, or return a fundamentally different entity (like switching from an Active Agent to a Deleted Agent), you don't need an optional parameter. You need a new function.

Conclusion: Escaping the Inferno

Optional parameters almost always start as a harmless convenience. But a parameter is rarely truly "optional"—it is a branching path in your logic. When you pile them up to control the flow of your program, you aren't making your function more flexible; you are creating a combinatorial explosion of states that you, and your team, will eventually have to debug.

Repent for your muddy domains. Write dumb functions. Keep your signatures strict. Your future self will thank you.

Thanks for reading! I'm Mohamed Fadlalla, a software engineer passionate about systems architecture, API design, and building developer tools. I share in-depth technical breakdowns on my personal site at mofadlalla.io and share builds and experiments on Twitter/X and LinkedIn.

What's the worst optional parameter disaster you've had to debug in production? Drop your horror stories in the comments below!

The Ultimate Guide to Generating PDFs from HTML with Node.js and Puppeteer

Mohamed Fadlalla — Thu, 21 Aug 2025 04:08:00 +0000

The Ultimate Guide to Generating PDFs from HTML with Node.js and Puppeteer

Posted on: August 20, 2025

Ever needed to generate a PDF invoice, a report, or an e-ticket from your web application? It's a common requirement, but turning dynamic HTML into a pixel-perfect PDF can be surprisingly tricky.

In this guide, we'll walk you through the entire process of building a robust PDF generation script using Node.js and Puppeteer, a powerful headless browser tool. We'll cover the basics and also touch on the real-world challenges you might face in a production environment.

Prerequisites

Before we begin, make sure you have Node.js (version 18 or higher) and npm installed on your machine.

Step 1: Setting Up Your Project

First, let's create a new project directory and initialize it with a package.json file.

mkdir pdf-generator
cd pdf-generator
npm init -y

Next, we need to install Puppeteer. This package will download a recent version of Chromium that we can control programmatically.

npm install puppeteer

Step 2: The Core PDF Generation Logic

Now for the fun part. Create a file named generate.js and add the following code. This script defines a function that takes a string of HTML, launches a headless browser, and saves the rendered content as a PDF.

// generate.js
import puppeteer from 'puppeteer';
import fs from 'fs';

// Example HTML content for an invoice
const invoiceHtml = `
<html>
  <head>
    <style>
      body { font-family: Arial, sans-serif; margin: 40px; }
      .invoice-header { text-align: center; margin-bottom: 40px; }
      .invoice-header h1 { margin: 0; }
      .item-table { width: 100%; border-collapse: collapse; }
      .item-table th, .item-table td { border: 1px solid #ddd; padding: 8px; }
      .item-table th { background-color: #f2f2f2; }
      .total { text-align: right; margin-top: 20px; font-weight: bold; }
    </style>
  </head>
  <body>
    <div class="invoice-header">
      <h1>Invoice #123</h1>
      <p>Issued: August 20, 2025</p>
    </div>
    <table class="item-table">
      <thead>
        <tr><th>Item</th><th>Quantity</th><th>Price</th></tr>
      </thead>
      <tbody>
        <tr><td>Web Development Services</td><td>10</td><td>$150.00</td></tr>
        <tr><td>API Consulting</td><td>5</td><td>$200.00</td></tr>
      </tbody>
    </table>
    <div class="total">
      Total: $2500.00
    </div>
  </body>
</html>
`;

async function generatePdfFromHtml(htmlContent) {
  let browser;
  try {
    console.log('Launching browser...');
    browser = await puppeteer.launch();

    console.log('Opening new page...');
    const page = await browser.newPage();

    console.log('Setting page content...');
    await page.setContent(htmlContent, { waitUntil: 'networkidle0' });

    // To ensure all assets like fonts or images are loaded
    await page.emulateMediaType('print');

    console.log('Generating PDF...');
    const pdfBuffer = await page.pdf({
      format: 'A4',
      printBackground: true
    });

    console.log('Saving PDF...');
    fs.writeFileSync('invoice.pdf', pdfBuffer);

    console.log('PDF generated successfully: invoice.pdf');
  } catch (error) {
    console.error('Error generating PDF:', error);
  } finally {
    if (browser) {
      console.log('Closing browser...');
      await browser.close();
    }
  }
}
generatePdfFromHtml(invoiceHtml);

You can run the script from your teminal:

node generate.js

After a few moments, you'll have a beautifully rendered invoice.pdf in your project folder!

Step 3: Optimizing for Performance: From Cold to Warm Starts

Your generate.js script is a great starting point, but it has a major performance bottleneck: it launches a new browser instance for every single PDF. This "cold start" can take several seconds and is very inefficient for a real application like a web server.

Let's refactor our code to use a "warm," singleton browser instance that is launched once and reused for all subsequent requests.

First, let's turn our logic into an Express server. If you haven't already, install Express:

npm install express

Now, create an server.js file:

// server.js
import express from 'express';
import puppeteer from 'puppeteer';

const app = express();
app.use(express.json()); // Middleware to parse JSON bodies

let browser; // We'll hold the browser instance here

// This is an async IIFE (Immediately Invoked Function Expression)
// to launch the browser at the start.
(async () => {
  console.log("Launching a warm browser instance...");
  browser = await puppeteer.launch({
    headless: "new",
    // Important for running in Docker
    args: ['--no-sandbox', '--disable-setuid-sandbox'] 
  });
})();

app.post('/convert', async (req, res) => {
  if (!browser) {
    return res.status(503).send('Browser is not ready.');
  }

  const { html } = req.body;
  if (!html) {
    return res.status(400).send('HTML content is required.');
  }

  const page = await browser.newPage();
  try {
    await page.setContent(html, { waitUntil: 'networkidle0' });
    await page.emulateMediaType('print');

    const pdfBuffer = await page.pdf({
      format: 'A4',
      printBackground: true
    });

    res.contentType('application/pdf');
    res.send(pdfBuffer);
  } catch (error) {
    console.error('Error generating PDF:', error);
    res.status(500).send('Failed to generate PDF.');
  } finally {
    await page.close(); // IMPORTANT: Only close the page, not the browser
  }
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`PDF generation server listening on port ${PORT}`);
});

By moving puppeteer.launch() outside the request handler, we've eliminated the cold start. Now, each call to /convert is significantly faster.

Step 4: Advanced Challenges in Production

While our server is now much faster, running Puppeteer in a production environment introduces a new set of challenges:

Server Dependencies: Your server needs all the correct system libraries to run headless Chromium. This can be complex to manage, especially in Docker containers.
Handling Dynamic Content and Authentication: What if the page you need to PDF requires a user to be logged in, or what if it needs to fetch data from an API before rendering? You can't just pass static HTML. You need to manage browser sessions and wait for asynchronous operations.

For example, to handle a page that's behind a login, you would need to:

// This is pseudo-code to illustrate the complexity
const page = await browser.newPage();
// 1. Navigate to the login page
await page.goto('https://myapp.com/login');
// 2. Programmatically fill in username and password
await page.type('#username', 'user');
await page.type('#password', 'pass');
await page.click('#login-button');
// 3. Wait for the redirect after login to complete
await page.waitForNavigation();
// 4. NOW navigate to the page you want to PDF
await page.goto('https://myapp.com/my-report');
// 5. Wait for the data to load on the page (e.g., a chart)
await page.waitForSelector('#chart-container.loaded'); 

const pdf = await page.pdf();

This adds significant complexity around authentication, cookies, and knowing exactly what to wait for on the page.

Performance at Scale: While our singleton pattern solves the "cold start" issue, what happens when you get 100 simultaneous requests? A single browser instance can become a bottleneck. You have to build a pooling mechanism to manage multiple browser instances, distribute the load, and handle queueing.
Maintenance: You're now responsible for keeping the server, Node.js, and Puppeteer updated to patch security vulnerabilities.

The Simpler Way: Using a Dedicated API

Building and maintaining this infrastructure is a lot of work. For most projects, a dedicated API is a more efficient and reliable solution.

That's why I built PageFlow. It's a simple REST API that handles all the browser management, scaling, and maintenance for you.

Here’s how you would accomplish the exact same task using the PageFlow API:

// pageflow-example.js
import fetch from 'node-fetch'; // or native fetch
import fs from 'fs';

const API_KEY = 'YOUR_API_KEY'; // Get yours from app.pageflow.dev
const invoiceHtml = `...`; // The same HTML string from before

async function generateWithPageFlow() {
  try {
    const response = await fetch('https://api.pageflow.dev/convert', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ html: invoiceHtml })
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.statusText}`);
    }

    const pdfBuffer = await response.buffer();
    fs.writeFileSync('invoice-api.pdf', pdfBuffer);
    console.log('PDF generated with PageFlow: invoice-api.pdf');
  } catch (error) {
    console.error(error);
  }
}

generateWithPageFlow();

The result is the samle high-quality PDF, but your code is simpler, and you have zero infrastructure to maintain.

Conclusion

Generating PDFs from HTML doesn’t have to be a headache. By leveraging Puppeteer, you gain the full power of a modern browser to render your documents exactly as they appear on the web. We’ve moved from a basic script to a high-performance Express server, setting a solid foundation for any production environment.

From here, you can explore adding custom headers and footers, handling complex CSS layouts, or even integrating this service into a larger microservices architecture. Happy coding!

I’m Mohamed Fadlalla, a software engineer passionate about developer tooling, systems architecture, and building products in public. If you found this guide helpful or have thoughts on running headless browsers in production, let's connect on Twitter/X and LinkedIn.