Code-level performance tips

Koa2 is a lightweight Node.js web framework designed around an asynchronous middleware mechanism. When developing high-performance applications, code-level optimization is particularly crucial. From middleware execution to route handling and response generation, every step can become a performance bottleneck. Below are specific optimization techniques and practical methods.

Middleware Simplification and Asynchronous Optimization

Middleware is the core of Koa2, but misuse or inefficient implementation can slow down the application. Prioritize using asynchronous functions (async/await) over generator functions (generator), as the former aligns better with modern JavaScript runtime optimizations. For example:

// Inefficient approach (legacy generator)
app.use(function *(next) {
  yield next;
});

// Efficient approach (async/await)
app.use(async (ctx, next) => {
  await next();
});

Avoid unnecessary blocking operations in middleware. For instance, when reading files, use fs.promises instead of callbacks or synchronous methods:

const fs = require('fs/promises');

app.use(async (ctx, next) => {
  // Blocking (avoid)
  // const data = fs.readFileSync('./large.json');
  
  // Non-blocking (recommended)
  const data = await fs.readFile('./large.json');
  ctx.body = data;
});

Route Matching Optimization

Route matching logic directly impacts request processing speed. When using koa-router, static paths are faster than dynamic ones. For example:

const Router = require('koa-router');
const router = new Router();

// Static route (efficient)
router.get('/api/users', (ctx) => {
  ctx.body = 'User list';
});

// Dynamic route (slower)
router.get('/api/users/:id', (ctx) => {
  ctx.body = `User ${ctx.params.id}`;
});

For high-frequency dynamic routes, cache parameter parsing results to improve performance. For example, pre-validate whether :id is a number:

router.get('/api/users/:id', (ctx, next) => {
  const id = parseInt(ctx.params.id);
  if (isNaN(id)) return ctx.status = 400;
  ctx.state.userId = id; // Cache to context
  return next();
});

Response Generation and Stream Handling

When directly manipulating ctx.body, avoid concatenating large strings. For JSON responses, serialize early and set the correct Content-Type:

app.use(async (ctx) => {
  const data = { users: [{ id: 1, name: 'Alice' }] };
  // Inefficient: Implicitly calls JSON.stringify
  // ctx.body = data;
  
  // Efficient: Explicit serialization + type setting
  ctx.type = 'application/json';
  ctx.body = JSON.stringify(data);
});

For large file responses, use streams instead of buffers. Here’s an example of streaming a file:

const fs = require('fs');
const { pipeline } = require('stream/promises');

app.use(async (ctx) => {
  ctx.type = 'application/pdf';
  const fileStream = fs.createReadStream('./large.pdf');
  ctx.body = fileStream;
  // Error handling
  fileStream.on('error', (err) => ctx.throw(500, err));
});

Dependency and Startup Optimization

Minimize synchronous operations during application startup. For example, lazy-load non-essential modules:

// Don't load immediately on startup
let heavyModule;
app.use(async (ctx, next) => {
  if (!heavyModule) {
    heavyModule = require('./heavy-module');
  }
  ctx.heavy = heavyModule.process(ctx.query.input);
  await next();
});

Leverage require caching to avoid reloading the same module. Enable V8 compilation optimizations with NODE_ENV=production:

NODE_ENV=production node app.js

Memory Management and Garbage Collection

Avoid creating large temporary objects in middleware. For example, reuse regex instances:

const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

app.use(async (ctx, next) => {
  // Avoid recreating regex per request
  // const emailRegex = new RegExp('^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$');
  if (emailRegex.test(ctx.query.email)) {
    await next();
  }
});

For frequently manipulated large objects, use WeakMap or WeakSet to reduce memory leak risks:

const userSessions = new WeakMap();

app.use(async (ctx, next) => {
  const user = await getUserFromDB(ctx.headers.token);
  userSessions.set(ctx, user); // Won't prevent GC from reclaiming ctx
  await next();
});

Error Handling and Logging

Poor error handling can degrade performance. Avoid try/catch in hot paths:

// Not recommended: Using try/catch in frequently called middleware
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = 500;
  }
});

// Recommended: Global error handling + specific middleware catching
app.on('error', (err) => {
  console.error('Server error', err);
});

app.use(rateLimit()); // High-frequency middleware without try/catch

Use efficient logging transports. For example, pino over console.log:

const pino = require('pino');
const logger = pino();

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  logger.info({
    duration: Date.now() - start,
    path: ctx.path
  });
});

Concurrency and Event Loop

Koa2 relies on the Node.js event loop, and long synchronous tasks can block other requests. Break CPU-intensive tasks into smaller chunks:

const { setImmediate } = require('timers/promises');

app.use(async (ctx) => {
  const results = [];
  for (const item of largeArray) {
    results.push(compute(item)); // Assume compute is synchronous
    if (results.length % 100 === 0) {
      await setImmediate(); // Release the event loop
    }
  }
  ctx.body = results;
});

Use worker_threads for truly high CPU loads:

const { Worker } = require('worker_threads');

app.use(async (ctx) => {
  const data = await new Promise((resolve) => {
    const worker = new Worker('./heavy-task.js', {
      workerData: ctx.query.input
    });
    worker.on('message', resolve);
  });
  ctx.body = data;
});

Performance Trade-offs in Real-world Scenarios

Some optimizations require balancing readability and performance. For example, precompiling templates:

const ejs = require('ejs');
const template = ejs.compile('<%= user.name %>');

app.use(async (ctx) => {
  // Recompile on every request (slow)
  // const html = ejs.render('<%= user.name %>', { user: ctx.state.user });
  
  // Precompiled template (fast)
  const html = template({ user: ctx.state.user });
  ctx.body = html;
});

For high-frequency APIs, sacrifice real-time responsiveness for throughput. For example, cache database query results for 5 seconds:

const cache = new Map();

app.use(async (ctx) => {
  if (cache.has(ctx.path)) {
    const { data, expires } = cache.get(ctx.path);
    if (Date.now() < expires) {
      ctx.body = data;
      return;
    }
  }
  
  const data = await fetchFromDB(ctx.query);
  cache.set(ctx.path, {
    data,
    expires: Date.now() + 5000
  });
  ctx.body = data;
});