Programming advice that still matters when the tools change

Reject ambiguous input once

The exact module and companion test file below were executed together under Node.js 22.20.0, using its built-in test runner and no external packages. The parser validates the entire trimmed string before converting it. It deliberately avoids parseInt: ECMAScript specifies that parseInt can consume an initial integer portion and ignore later characters, so parseInt("12boxes", 10) is not full-field validation.

The order of checks is part of this example contract. A non-string returns quantity_must_be_text. A string that fails the one-to-four-digit format returns quantity_must_be_integer, including 99999 even though its numeric interpretation exceeds the limit. Only a format-valid value such as 1001 reaches quantity_out_of_range. Each failure object omits quantity. If your API needs every oversized decimal string classified as a range error, change that rule and its tests deliberately.

export function parseQuantity(input) {
  if (typeof input !== 'string') {
    return { ok: false, error: 'quantity_must_be_text' };
  }

  const text = input.trim();
  if (!/^[1-9][0-9]{0,3}$/.test(text)) {
    return { ok: false, error: 'quantity_must_be_integer' };
  }

  const quantity = Number(text);
  if (quantity > 1000) {
    return { ok: false, error: 'quantity_out_of_range' };
  }

  return { ok: true, quantity };
}

Use tests to preserve decisions

Save quantity.mjs and quantity.test.mjs in the same directory, then run node --test quantity.test.mjs with Node.js 22.20.0. The observed normal run passes four tests containing 29 strict result-object assertions. The cases specify accepted inputs and exact errors, without asserting which regular expression or helper structure implements them.

The whitespace samples include ordinary spaces, a tab with a newline, and non-breaking spaces. An embedded newline and a zero-width space are rejected. Full-width and Arabic-Indic digits are rejected because the product contract uses ASCII digits; these are not tests of every Unicode code point. Node documents that a synchronous test fails when it throws, and strict deep equality compares the complete expected result.

The download also runs four altered parsers: removing trim, accepting non-string input through numeric coercion, accepting a numeric prefix and removing the upper bound. Each run exits with a failed assertion in its intended test and input case; every other test must pass. The reporter records the actual Node version and hashes of the mounted module, tests and reporter. An unrelated exception or syntax error does not satisfy these negative controls.

import test from 'node:test';
import assert from 'node:assert/strict';
import { parseQuantity } from './quantity.mjs';

test('accepted values and ECMAScript surrounding whitespace', () => {
  for (const [input, quantity] of [
    ['1', 1], ['12', 12], ['1000', 1000], [' 12 ', 12],
    ['\t12\n', 12], ['\u00a012\u00a0', 12],
  ]) {
    assert.deepEqual(parseQuantity(input), { ok: true, quantity }, `accept:${JSON.stringify(input)}`);
  }
});

test('non-string inputs keep the type error', () => {
  for (const input of [null, undefined, 12, true, {}, ['12']]) {
    assert.deepEqual(parseQuantity(input), {
      ok: false, error: 'quantity_must_be_text',
    }, `type:${JSON.stringify(input)}`);
  }
});

test('malformed strings keep the format error', () => {
  for (const input of [
    '', ' ', '0', '-1', '+1', '01', '1.0', '1.5', '12boxes',
    '99999', '1 2', '1\n2', '\u200b12', '１２', '١٢',
  ]) {
    assert.deepEqual(parseQuantity(input), {
      ok: false, error: 'quantity_must_be_integer',
    }, `reject:${JSON.stringify(input)}`);
  }
});

test('four-digit values above the product limit keep the range error', () => {
  for (const input of ['1001', '9999']) {
    assert.deepEqual(parseQuantity(input), {
      ok: false, error: 'quantity_out_of_range',
    }, `range:${JSON.stringify(input)}`);
  }
});

Keep the next boundary explicit too

Validation does not establish stock availability. Two valid requests can race for the same remaining item. The reservation operation still needs an atomic consistency rule in its persistence layer, and a retried request needs defined duplicate behavior. Do not add those concerns to the parser just because they share the word quantity.

At the request boundary, map the parser's error to the application's documented client-error response. Log an appropriate error category and request identifier if needed, rather than indiscriminately logging the incoming body. Unexpected database failures belong to a different error path.

This separation is useful because each decision can change independently. A future API might accept JSON numbers instead of form strings. Add a boundary adapter and tests for that contract rather than quietly broadening every caller's accepted input.

The fixture proves only this synchronous value contract under one pinned Node version. It does not parse an HTTP request, check permissions, reserve stock, execute a transaction or make retries safe. The HTTP caller still needs a documented response mapping, and the reservation operation needs its own consistency and duplicate-request tests. No production performance result is claimed.

Name the decision and keep feedback close

Names such as parseQuantity and quantity_out_of_range explain the rule more directly than processValue or invalid. If a new requirement changes the limit, a reviewer can find the implementation and examples without tracing a generic validation pipeline.

Extract a shared abstraction when multiple callers truly share the contract, including their failure behavior. Two fields with similar syntax may still represent different business rules. A little duplication can be cheaper than a shared helper whose flags describe unrelated exceptions.

The durable habit is to make one decision visible, check it quickly, and keep its side effects bounded. Frameworks can change around that work without erasing the reasoning behind it.