logistics.hs-code-validate

export function validateHsCode(value: string): HsCodeCheck

/** The result of checking a commodity code. Every string but reason is null when valid is false; reason is null when it is true. */
export interface HsCodeCheck {
  readonly valid: boolean;
  /** the digits only */
  readonly normalised: string | null;
  /** hs (6 digits), cn (8) or taric (10, also the UK's commodity code length) */
  readonly kind: string | null;
  /** first two digits, leading zero kept: "01" */
  readonly chapter: string | null;
  /** first four digits */
  readonly heading: string | null;
  /** first six digits, the internationally shared HS subheading */
  readonly subheading: string | null;
  /** empty, bad-character, bad-length, bad-chapter, reserved-chapter, national-chapter or bad-heading */
  readonly reason: string | null;
}

import { validateHsCode } from "#fune/logistics.hs-code-validate@^1";

import { type HsCodeCheck } from "./logistics_hs_code_validate_types.ts";

const KINDS: { readonly [length: number]: string } = { 6: "hs", 8: "cn", 10: "taric" };

function invalid(reason: string): HsCodeCheck {
  return { valid: false, normalised: null, kind: null, chapter: null, heading: null, subheading: null, reason };
}

/**
 * Check the format of a 6-digit HS, 8-digit CN or 10-digit TARIC/UK commodity
 * code. Validators answer rather than throw: a malformed code is the answer "no".
 */
export function validateHsCode(value: string): HsCodeCheck {
  if (typeof value !== "string") return invalid("empty");
  let digits = "";
  for (const ch of value) {
    if (ch === " " || ch === ".") continue;
    if (ch < "0" || ch > "9") return invalid("bad-character");
    digits += ch;
  }
  if (digits.length === 0) return invalid("empty");
  const kind = KINDS[digits.length];
  if (kind === undefined) return invalid("bad-length");

  // Text, not a number: chapter "01" must keep its zero.
  const chapter = digits.slice(0, 2);
  if (chapter === "00") return invalid("bad-chapter");
  if (chapter === "77") return invalid("reserved-chapter");
  // 98 and 99 are left to national tariffs, so only a national-length code may use them.
  if ((chapter === "98" || chapter === "99") && kind === "hs") return invalid("national-chapter");
  if (digits.slice(2, 4) === "00") return invalid("bad-heading");

  return {
    valid: true,
    normalised: digits,
    kind,
    chapter,
    heading: digits.slice(0, 4),
    subheading: digits.slice(0, 6),
    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 logistics.hs-code-validate

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./logistics.hs-code-validate-1.0.0-typescript.fune, or fetch it from a terminal with fune pull logistics.hs-code-validate@1.0.0:typescript.

The whole function, every language, is one file too: logistics.hs-code-validate-1.0.0.fune, 15,709 bytes, sha256 eddcf67d1fabf3fa292b04fa0eebf29864dfac042423cc3aa270daf774f60579. It installs into a project of any language.

// fune: before logistics.hs-code-validate

// fune: after logistics.hs-code-validate

// fune: step logistics.hs-code-validate after <n|label>

More from the author

| digits | kind | what it is | |---|---|---| | 6 | `hs` | the HS subheading, shared by every country that uses the Harmonized System (WCO) | | 8 | `cn` | the EU Combined Nomenclature, and the export commodity code in the UK tariff | | 10 | `taric` | the EU TARIC code, and the UK's 10-digit import commodity code |

Four digits (a heading) is not a commodity code and fails as `bad-length`, as do 7 and 9. Spaces and dots are ignored anywhere, because codes are written `8471.30.00` and `0101 21 00 00`; nothing else is tidied away.

The code is text, never a number: chapter `01` (live animals) loses its leading zero as an integer, which is the classic bug this catches in spreadsheets. The result keeps it: `chapter` is `"01"`.

## Chapter and heading checks

The HS has 97 chapters, 01 to 97, with chapter 77 reserved for future use. Chapters 98 and 99 are not part of the HS; the HS Convention leaves them for each country's national use (the EU CN uses both, for example, and the UK tariff uses 99 for special codes).

| chapter | 6 digits | 8 or 10 digits | |---|---|---| | 00 | `bad-chapter` | `bad-chapter` | | 01-76, 78-97 | valid | valid | | 77 | `reserved-chapter` | `reserved-chapter` | | 98, 99 | `national-chapter` | valid, as a national code |

Headings are numbered from 01 within each chapter, so a heading of `00` (`840012`) is `bad-heading`. The check stops there.

## What a pass means

A valid result means the code is well formed, not that it exists in any particular tariff or in force on any date: codes are added and retired every year, and the HS itself is revised every five years or so (HS 2022 is the current edition). Look the code up in the UK Trade Tariff or EU TARIC for that.

## Sources

- World Customs Organization, Harmonized System nomenclature, 2022 edition, https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools/hs-nomenclature-2022-edition.aspx ; "Chapter 77 (Reserved for possible future use in the Harmonized System)", https://www.wcoomd.org/-/media/wco/public/global/pdf/topics/nomenclature/instruments-and-tools/hs-nomenclature-older-edition/2007/hs-2007/1577_2007e.pdf - U.S. Customs and Border Protection, "What Every Member of the Trade Community Should Know About: Tariff Classification" (chapters 98 and 99 reserved for special uses by contracting parties), https://www.cbp.gov/sites/default/files/documents/icp017r2_3.pdf - HMRC, "Finding commodity codes for imports into or exports out of the UK" (only the first 6 digits are used worldwide), https://www.gov.uk/guidance/finding-commodity-codes-for-imports-or-exports - European Commission, customs tariff (CN and TARIC), https://taxation-customs.ec.europa.eu/customs-4/calculation-customs-duties/customs-tariff_en

Files