Parameter Management

/**
 * Creates a new parameters wrapper around a Map instance
 * @param {Map} map - Internal Map instance for parameter storage
 */
class MIMETypeParameters {
  constructor(map);
}

/**
 * Gets the number of parameters
 * @returns {number} The number of parameter key-value pairs
 */
get size();

const MIMEType = require("whatwg-mimetype");

const mimeType = new MIMEType("text/html;charset=utf-8;boundary=something");
console.log(mimeType.parameters.size); // 2

/**
 * Gets a parameter value by name (case-insensitive)
 * @param {string} name - Parameter name to look up
 * @returns {string|undefined} Parameter value or undefined if not found
 */
get(name);

const mimeType = new MIMEType("text/html;charset=utf-8;Boundary=abc123");

console.log(mimeType.parameters.get("charset")); // "utf-8"
console.log(mimeType.parameters.get("CHARSET")); // "utf-8" (case-insensitive)
console.log(mimeType.parameters.get("boundary")); // "abc123"
console.log(mimeType.parameters.get("missing")); // undefined

/**
 * Checks if a parameter exists (case-insensitive)
 * @param {string} name - Parameter name to check
 * @returns {boolean} True if the parameter exists
 */
has(name);

const mimeType = new MIMEType("text/html;charset=utf-8");

console.log(mimeType.parameters.has("charset")); // true
console.log(mimeType.parameters.has("CHARSET")); // true (case-insensitive)
console.log(mimeType.parameters.has("boundary")); // false

/**
 * Sets a parameter value with validation
 * @param {string} name - Parameter name (will be normalized to lowercase)
 * @param {string} value - Parameter value
 * @returns {Map} The underlying Map instance (for chaining)
 * @throws {Error} If name contains invalid characters
 * @throws {Error} If value contains invalid characters
 */
set(name, value);

const mimeType = new MIMEType("text/html");

// Set new parameter
mimeType.parameters.set("charset", "utf-8");
console.log(mimeType.toString()); // "text/html;charset=utf-8"

// Update existing parameter
mimeType.parameters.set("CHARSET", "iso-8859-1"); // case-insensitive
console.log(mimeType.parameters.get("charset")); // "iso-8859-1"

// Parameter names are normalized to lowercase
mimeType.parameters.set("Boundary", "abc123");
console.log(mimeType.parameters.get("boundary")); // "abc123"

// Invalid parameter names throw errors
try {
  mimeType.parameters.set("invalid@name", "value");
} catch (error) {
  console.log(error.message); // 'Invalid MIME type parameter name "invalid@name": only HTTP token code points are valid.'
}

// Invalid parameter values throw errors
try {
  mimeType.parameters.set("charset", "invalid\x00value");
} catch (error) {
  console.log(error.message); // 'Invalid MIME type parameter value "invalid\x00value": only HTTP quoted-string token code points are valid.'
}

/**
 * Removes a parameter by name (case-insensitive)
 * @param {string} name - Parameter name to remove
 * @returns {boolean} True if the parameter existed and was removed
 */
delete(name);

const mimeType = new MIMEType("text/html;charset=utf-8;boundary=abc123");

console.log(mimeType.parameters.delete("charset")); // true
console.log(mimeType.parameters.has("charset")); // false
console.log(mimeType.toString()); // "text/html;boundary=abc123"

console.log(mimeType.parameters.delete("BOUNDARY")); // true (case-insensitive)
console.log(mimeType.parameters.delete("missing")); // false

/**
 * Removes all parameters
 */
clear();

const mimeType = new MIMEType("text/html;charset=utf-8;boundary=abc123");

console.log(mimeType.parameters.size); // 2
mimeType.parameters.clear();
console.log(mimeType.parameters.size); // 0
console.log(mimeType.toString()); // "text/html"

/**
 * Executes a callback for each parameter
 * @param {function} callbackFn - Function to execute for each parameter
 * @param {*} [thisArg] - Value to use as 'this' when executing callback
 */
forEach(callbackFn, thisArg);

/**
 * Returns an iterator for parameter names
 * @returns {Iterator<string>} Iterator for parameter names
 */
keys();

/**
 * Returns an iterator for parameter values
 * @returns {Iterator<string>} Iterator for parameter values
 */
values();

/**
 * Returns an iterator for [name, value] pairs
 * @returns {Iterator<[string, string]>} Iterator for parameter entries
 */
entries();

/**
 * Makes the parameters object iterable (same as entries())
 * @returns {Iterator<[string, string]>} Iterator for parameter entries
 */
[Symbol.iterator]();

const mimeType = new MIMEType("text/html;charset=utf-8;boundary=abc123");

// forEach iteration
mimeType.parameters.forEach((value, name) => {
  console.log(`${name}: ${value}`);
});
// Output:
// charset: utf-8
// boundary: abc123

// for...of iteration (uses Symbol.iterator)
for (const [name, value] of mimeType.parameters) {
  console.log(`${name} = ${value}`);
}
// Output:
// charset = utf-8
// boundary = abc123

// Individual iterators
for (const name of mimeType.parameters.keys()) {
  console.log(`Parameter: ${name}`);
}

for (const value of mimeType.parameters.values()) {
  console.log(`Value: ${value}`);
}

for (const [name, value] of mimeType.parameters.entries()) {
  console.log(`${name}: ${value}`);
}

const mimeType = new MIMEType("text/html;charset=utf-8");

// Size property
console.log(mimeType.parameters.size); // 1

// Standard Map methods work as expected
console.log(mimeType.parameters.has("charset")); // true
console.log(mimeType.parameters.get("charset")); // "utf-8"

// Iteration works like Map
const params = Array.from(mimeType.parameters);
console.log(params); // [["charset", "utf-8"]]

// Convert to plain object
const paramsObj = Object.fromEntries(mimeType.parameters);
console.log(paramsObj); // { charset: "utf-8" }

const mimeType = new MIMEType("text/html");

// Valid parameter names: HTTP token characters
mimeType.parameters.set("charset", "utf-8"); // ✓ Valid
mimeType.parameters.set("my-param", "value"); // ✓ Valid (hyphens allowed)
mimeType.parameters.set("param123", "value"); // ✓ Valid (numbers allowed)

// Invalid parameter names
try {
  mimeType.parameters.set("param with spaces", "value");
} catch (error) {
  // ✗ Spaces not allowed in parameter names
}

try {
  mimeType.parameters.set("param@invalid", "value");
} catch (error) {
  // ✗ @ symbol not allowed in parameter names
}

// Valid parameter values: HTTP quoted-string characters
mimeType.parameters.set("param", "simple-value"); // ✓ Valid
mimeType.parameters.set("param", "value with spaces"); // ✓ Valid
mimeType.parameters.set("param", "value/with/slashes"); // ✓ Valid

// Invalid parameter values (control characters)
try {
  mimeType.parameters.set("param", "value\x00with\x01control");
} catch (error) {
  // ✗ Control characters not allowed
}