validation.uk-company-number

export function validateUkCompanyNumber(value: string): UkCompanyNumber

/** Everything but valid and reason is null when valid is false. */
export interface UkCompanyNumber {
  readonly valid: boolean;
  /** eight characters, upper case: "SC002180", "02050399" */
  readonly normalised: string | null;
  /** the two-character prefix, or "" for a plain eight-digit number */
  readonly prefix: string | null;
  /** england-wales, scotland, northern-ireland or united-kingdom */
  readonly jurisdiction: string | null;
  /** what the prefix registers, in words */
  readonly companyType: string | null;
  /** null when valid; empty, bad-character, bad-length, bad-format or unknown-prefix */
  readonly reason: string | null;
}

import { validateUkCompanyNumber } from "#fune/validation.uk-company-number@^2";

import { COMPANY_PREFIXES } from "./validation_uk_company_number_data.ts";  ← this capability’s own data, compiled from data/company-prefixes.json into the same file by fune build
import { type UkCompanyNumber } from "./validation_uk_company_number_types.ts";

/** Every company number is eight characters: eight digits, or a two-character prefix and six digits. */
const LENGTH = 8;

function invalid(reason: string): UkCompanyNumber {
  return { valid: false, normalised: null, prefix: null, jurisdiction: null, companyType: null, reason };
}

function isLetter(ch: string): boolean {
  return ch >= "A" && ch <= "Z";
}

function isDigit(ch: string): boolean {
  return ch >= "0" && ch <= "9";
}

/**
 * Check a Companies House company number's shape and prefix.
 *
 * There is no check digit, so a pass means the number is shaped like one
 * Companies House issues under a prefix it uses, not that the company exists:
 * that is a lookup on the register. Checks run in a fixed order (characters,
 * shape, length, prefix) so every language gives the same first reason.
 */
export function validateUkCompanyNumber(value: string): UkCompanyNumber {
  if (typeof value !== "string") return invalid("empty");
  let compact = "";
  for (let ch of value) {
    if (ch === " ") continue;
    // ASCII-only upper-casing, so every language folds identically.
    if (ch >= "a" && ch <= "z") ch = String.fromCharCode(ch.charCodeAt(0) - 32);
    if (!isLetter(ch) && !isDigit(ch)) return invalid("bad-character");
    compact += ch;
  }
  if (compact === "") return invalid("empty");

  // R0 (pre-partition Northern Ireland) is the one prefix containing a digit.
  let prefix: string;
  if (compact.startsWith("R0") || (compact.length >= 2 && isLetter(compact[0]) && isLetter(compact[1]))) {
    prefix = compact.slice(0, 2);
  } else if (isLetter(compact[0])) {
    return invalid("bad-format");
  } else {
    prefix = "";
  }
  const digits = compact.slice(prefix.length);
  for (const ch of digits) {
    if (!isDigit(ch)) return invalid("bad-format");
  }
  const width = LENGTH - prefix.length;
  if (digits.length === 0 || digits.length > width) return invalid("bad-length");
  // Leading zeros are part of the number and are often dropped when typed,
  // so they are put back; a number of nothing but zeros is no company.
  if (/^0+$/.test(digits)) return invalid("bad-format");

  const row = COMPANY_PREFIXES.find((r) => r.prefix === prefix);
  if (row === undefined) return invalid("unknown-prefix");
  return {
    valid: true,
    normalised: prefix + digits.padStart(width, "0"),
    prefix,
    jurisdiction: row.jurisdiction,
    companyType: row.companyType,
    reason: null,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add validation.uk-company-number

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./validation.uk-company-number-2.0.1-typescript.fune, or fetch it from a terminal with fune pull validation.uk-company-number@2.0.1:typescript.

The whole function, every language, is one file too: validation.uk-company-number-2.0.1.fune, 24,336 bytes, sha256 4d2865bda769e6a35cd0e59dded3a4d0bd0bbe286318e4d41df49acf58204951. It installs into a project of any language.

// fune: before validation.uk-company-number

// fune: after validation.uk-company-number

// fune: step validation.uk-company-number after <n|label>

More from the author

## The format

Eight characters: eight digits for a company registered in England and Wales, or a two-character prefix and six digits for everything else (SC Scotland, NI Northern Ireland, OC/SO/NC limited liability partnerships, LP/SL/NL limited partnerships, FC overseas companies, and so on). R0, for pre-partition Northern Ireland companies, is the one prefix with a digit in it.

Leading zeros are part of the number, and dropping them names a different company or none. Because people drop them when typing, a number short of its zeros is padded back: "2050399" becomes "02050399" and "sc 2180" becomes "SC002180". A number of nothing but zeros is refused.

## The prefix table (data)

`data/company-prefixes.json` holds every prefix in Companies House's list of company numbers and prefixes, including the ones for which Companies House holds only the name and number (industrial and provident societies, ICVCs, royal charter companies, credit unions). A prefix not in the table is `unknown-prefix`. Companies House does add prefixes from time to time, so an unknown prefix can be a new one. A prefix added in future is a data release of this capability.

## Input and result

Case is ignored and ASCII spaces are ignored anywhere. Anything else that is not an ASCII letter or digit, hyphens included, is `bad-character`. Validators answer rather than throw.

| reason | meaning (checked in this order) | |---|---| | `empty` | nothing but spaces, or not a string | | `bad-character` | a character other than an ASCII letter, digit or space | | `bad-format` | a single leading letter, letters after the prefix, or all zeros | | `bad-length` | no digits, or more than eight characters in all | | `unknown-prefix` | a prefix not in the table |

## Source

Companies House, "Uniform Resource Identifiers (URI) Customer Guide", version 1.1, section "List of Company Numbers and Prefixes": https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/426891/uniformResourceIdentifiersCustomerGuide.pdf

2.0.0 renames the function from `ukCompanyNumber` to `validateUkCompanyNumber` (`validate_uk_company_number` in Python and Rust), so every validator that returns a result record is `validateX` and every one that returns a bool is `isX`. Nothing else changed; 1.0.0 stays published under the old name.

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

2.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files