lambda-api

Lambda API uses execution stacks to efficiently process middleware. Stacks are automatically created when you use standard route methods, METHOD(), or use().

Key behaviors:

• Inheritance: Execution stacks inherit middleware from matching routes and methods higher up the stack, building a unique final stack for each route.
• Order Matters: Routes defined before global middleware will not include that middleware in their execution stack. The same applies to wildcard-based routes.
• Path-based Middleware: Middleware attached to parameterized paths (e.g., /users/:userId) creates mount points. This means a middleware defined for /users/:userId will not execute if the request matches a static path like /users/test unless specifically configured.
• Debugging: If you use named functions for your middleware, you can inspect the REQUEST.stack property, which returns an array of function names in the order they are executed.

Sampling allows you to periodically generate log entries for all severities within a request to trace its execution. This is useful for debugging and metrics.

Global Sampling Configuration

Set the sampling property in the logger config.

• target: Minimum number of samples per period.
• rate: Percentage of samples (0 to 1) to take during the period.
• period: Duration of the sampling period in seconds.

Sampling Rules

You can define specific rules to target certain routes or methods. Each rule requires a route (matching the path definition, e.g., /user/:userId).

// Sample 2 requests every 30 seconds + 10% of all other requests
const api = require('lambda-api')({
  logger: {
    sampling: {
      target: 2,
      rate: 0.1,
      period: 30,
    },
  },
});

// Example with rules: disable sampling for /status, enable for /user and /posts/*
const apiWithRules = require('lambda-api')({
  logger: {
    sampling: {
      rules: [
        { route: '/status', target: 0, rate: 0 },
        { route: '/user', target: 1, rate: 0.1 },
        { route: '/posts/*', target: 1, rate: 0.1 },
      ],
      target: 0, // disable default target
      rate: 0,   // disable default rate
    },
  },
});

Lambda API supports multiple ways to send data back to the user.

IMPORTANT: You must either use a callback (like res.send()) OR return a value. If you do neither, the execution will hang. Do not return undefined, as the framework will assume no response was intended.

1. Using Response Callbacks

Use methods on the res object like send(), json(), or html().

2. Using Return Values

Simply return the data from your handler function. The contents will be sent as the body.

3. Async/Await and Promises

You can use async handlers and either return the awaited result or use a callback.

Flow Control Warning

Callbacks like res.error() or res.send() do not terminate the execution of your function. To prevent subsequent code from running (which might override your error/response), you should return the call to the response method.

Correct pattern for errors:

if (condition) {
  return res.error('Error message');
}

// Using res.send()
api.get('/users', (req, res) => {
  res.send({ foo: 'bar' });
});

// Using return
api.get('/users', (req, res) => {
  return { foo: 'bar' };
});

// Using async/await with return
api.get('/users', async (req, res) => {
  let users = await getUsers();
  return users;
});

// Using async/await with callback
api.get('/users', async (req, res) => {
  let users = await getUsers();
  res.send(users);
});

// Using Promises
api.get('/users', (req, res) => {
  getUsers().then((users) => {
    res.send(users);
  });
});

// Correct Flow Control for errors
api.get('/users', (req, res) => {
  if (req.headers.test === 'test') {
    return res.error('Throw an error');
  }

  return { foo: 'bar' };
});

The register() method allows you to load routes from external modules and apply a prefix to all of them. This is useful for versioning APIs (e.g., /v1/, /v2/) without manually rewriting paths.

• register() is recursive: nesting register() calls builds cumulative paths (e.g., /v1/v2/path).
• Prefixed routes are built on top of the instance's base path if one is configured.

Module Structure for Registered Routes: When using register(), the exported module should be a function that receives (api, opts).

// routes/v1/products.js
module.exports = (api, opts) => {
  api.get('/product', handler_v1);
};

// handler.js
const api = require('lambda-api')();

api.register(require('./routes/v1/products'), { prefix: '/v1' });
api.register(require('./routes/v2/products'), { prefix: '/v2' });

module.exports.handler = (event, context, callback) => {
  api.run(event, context, callback);
};