URL Encoded Plugin

Parses application/x-www-form-urlencoded request bodies (HTML form submissions) and exposes the parsed data on req.body.

Quick Start

import { Server } from 'balda-js';

const server = new Server({
  plugins: {
    urlencoded: true  // Enable with defaults
  }
});

Configuration

const server = new Server({
  plugins: {
    urlencoded: {
      limit: 2 * 1024 * 1024,  // Maximum body size in bytes (2MB)
      extended: true,           // Parse rich objects and arrays
      charset: 'utf8',          // Character encoding
      allowEmpty: true,         // Allow empty values
      parameterLimit: 1000      // Maximum number of parameters
    }
  }
});

Options

Option	Type	Default	Description
limit	number	1048576 (1MB)	Maximum body size in bytes
extended	boolean	false	Parse rich objects and arrays
charset	string	'utf8'	Character encoding
allowEmpty	boolean	true	Allow empty values
parameterLimit	number	1000	Maximum parameters to parse

Usage

Basic Form Handling

@controller('/api')
export class FormController {
  @post('/submit')
  async handleSubmit(req: Request, res: Response) {
    const { name, email, message } = req.body;

    res.json({
      received: { name, email, message }
    });
  }
}

HTML Form

<form action="/api/submit" method="POST">
  <input type="text" name="name" value="John" />
  <input type="email" name="email" value="john@example.com" />
  <textarea name="message">Hello!</textarea>
  <button type="submit">Submit</button>
</form>

<!-- Body sent: name=John&email=john@example.com&message=Hello! -->

Extended Parsing

With extended: true, parse nested objects and arrays:

<form action="/api/user" method="POST">
  <input name="user[name]" value="John" />
  <input name="user[email]" value="john@example.com" />
  <input name="tags[]" value="developer" />
  <input name="tags[]" value="designer" />
</form>

@post('/user')
async createUser(req: Request, res: Response) {
  console.log(req.body);
  // {
  //   user: { name: 'John', email: 'john@example.com' },
  //   tags: ['developer', 'designer']
  // }
}

Disabling the Plugin

const server = new Server({
  plugins: {
    urlencoded: false
  }
});

Error Handling

Body Too Large

// Response: 413 Payload Too Large
{
  "error": "Request body exceeds limit"
}

Too Many Parameters

// Response: 400 Bad Request
{
  "error": "Too many parameters"
}

Complete Example

const server = new Server({
  port: 3000,
  plugins: {
    urlencoded: {
      limit: 2 * 1024 * 1024,  // 2MB limit
      extended: true            // Support nested objects
    }
  }
});

@controller('/forms')
export class FormsController {
  @post('/contact')
  async contact(req: Request, res: Response) {
    const { name, email, message } = req.body;

    if (!name || !email || !message) {
      return res.badRequest({ error: 'Missing required fields' });
    }

    // Process form submission
    await saveContactForm({ name, email, message });

    res.json({ success: true });
  }
}

Common Patterns

Contact Form

urlencoded: {
  limit: 1 * 1024 * 1024,  // 1MB
  extended: false
}

User Registration

urlencoded: {
  limit: 2 * 1024 * 1024,  // 2MB
  extended: true           // Support nested user data
}

Search Form

urlencoded: {
  limit: 100 * 1024,      // 100KB
  extended: false
}