feat: add BIC/SWIFT parser (ISO 9362)

Author: ClaudiuCeia

README.md

@@ -110,7 +110,7 @@ npx jsr add @claudiu-ceia/ts-duckling
 
 ### Extract entities
 
-Call `Duckling()` with no arguments to use **all 19 built-in parsers**:
+Call `Duckling()` with no arguments to use **all 20 built-in parsers**:
 
 ```ts
 import { Duckling } from "@claudiu-ceia/ts-duckling";
@@ -161,7 +161,7 @@ Use `.redact()` to replace matched entity spans with a mask character:
 ```ts
 import { Duckling, PIIParsers } from "@claudiu-ceia/ts-duckling";
 
-// Redact all PII (email, phone, IP, SSN, credit card, UUID, API key, IBAN, MAC, JWT)
+// Redact all PII (email, phone, IP, SSN, credit card, UUID, API key, IBAN, MAC, JWT, BIC)
 Duckling(PIIParsers).redact(
   "Patient email: john.doe@clinic.org, SSN 078-05-1120, phone +14155552671",
 );
@@ -391,6 +391,7 @@ Available via `PIIParsers` for targeted redaction with
 | **MAC address** | `mac_address`    | `00:1A:2B:3C:4D:5E`, `001A.2B3C.4D5E`                   |
 | **JWT**         | `jwt`            | `eyJhbGciOiJIUzI1NiIs…`                                 |
 | **Crypto**      | `crypto_address` | `0x742d35Cc…f2bD18`, `bc1qar0srrr…`, `1BvBMSEY…`        |
+| **BIC/SWIFT**   | `bic`            | `DEUTDEFF`, `BOFAUS3NXXX`, `COBADEFF100`                 |
 
 ## API reference
 
@@ -417,7 +418,7 @@ function Duckling<T>(parsers: ParserTuple<T>): {
 };
 ```
 
-Creates an extractor/renderer/redactor. Without arguments, uses all 19 built-in
+Creates an extractor/renderer/redactor. Without arguments, uses all 20 built-in
 parsers and returns `AnyEntity[]`. When given an explicit parser array, the
 return type narrows to the union of those entity types.
 
@@ -523,6 +524,7 @@ const PIIParsers: [
   MACAddressParser,
   JWTParser,
   CryptoAddressParser,
+  BICParser,
 ];
 ```
 
@@ -566,13 +568,13 @@ replace the span.
 
 ### `AnyEntity`
 
-Union of all 19 built-in entity types. This is the return element type of
+Union of all 20 built-in entity types. This is the return element type of
 `Duckling().extract(...)`.
 
 ### `PIIEntity`
 
-Union of the 11 PII entity types:
-`EmailEntity | PhoneEntity | IPAddressEntity | SSNEntity | CreditCardEntity | UUIDEntity | ApiKeyEntity | IBANEntity | MACAddressEntity | JWTEntity | CryptoAddressEntity`.
+Union of the 12 PII entity types:
+`EmailEntity | PhoneEntity | IPAddressEntity | SSNEntity | CreditCardEntity | UUIDEntity | ApiKeyEntity | IBANEntity | MACAddressEntity | JWTEntity | CryptoAddressEntity | BICEntity`.
 
 ## Caveats
 

mod.ts

@@ -39,6 +39,7 @@ import {
   CryptoAddress,
   type CryptoAddressEntity,
 } from "./src/CryptoAddress.ts";
+import { BIC, type BICEntity } from "./src/BIC.ts";
 
 /**
  * Union of all entity types produced by the built-in parsers.
@@ -66,7 +67,8 @@ export type AnyEntity =
   | IBANEntity
   | MACAddressEntity
   | JWTEntity
-  | CryptoAddressEntity;
+  | CryptoAddressEntity
+  | BICEntity;
 
 const DefaultParsers: [Parser<AnyEntity>, ...Parser<AnyEntity>[]] = [
   Range.parser,
@@ -88,6 +90,7 @@ const DefaultParsers: [Parser<AnyEntity>, ...Parser<AnyEntity>[]] = [
   MACAddress.parser,
   JWT.parser,
   CryptoAddress.parser,
+  BIC.parser,
 ];
 
 /**
@@ -108,7 +111,8 @@ export type PIIEntity =
   | IBANEntity
   | MACAddressEntity
   | JWTEntity
-  | CryptoAddressEntity;
+  | CryptoAddressEntity
+  | BICEntity;
 
 /**
  * Pre-built parser tuple targeting PII entities.
@@ -136,6 +140,7 @@ export const PIIParsers: ParserTuple<
     MACAddressEntity,
     JWTEntity,
     CryptoAddressEntity,
+    BICEntity,
   ]
 > = [
   Email.parser,
@@ -149,6 +154,7 @@ export const PIIParsers: ParserTuple<
   MACAddress.parser,
   JWT.parser,
   CryptoAddress.parser,
+  BIC.parser,
 ];
 
 type NonEmptyArray<T> = [T, ...T[]];
@@ -515,3 +521,4 @@ export * from "./src/IBAN.ts";
 export * from "./src/MACAddress.ts";
 export * from "./src/JWT.ts";
 export * from "./src/CryptoAddress.ts";
+export * from "./src/BIC.ts";

src/BIC.ts

@@ -0,0 +1,88 @@
+import {
+  type Context,
+  createLanguage,
+  map,
+  optional,
+  regex,
+  seq,
+} from "@claudiu-ceia/combine";
+import type { Parser } from "@claudiu-ceia/combine";
+import { dot } from "./common.ts";
+import { ent, type Entity } from "./Entity.ts";
+import { guard } from "./guard.ts";
+import countries from "@data/countries-en-us" with { type: "json" };
+
+const countryCodes = new Set(Object.keys(countries as Record<string, string>));
+
+/**
+ * BIC/SWIFT entity (Business Identifier Code — ISO 9362).
+ *
+ * Format: `BBBBCCLL(BBB)?`
+ * - BBBB: 4-letter bank/institution code
+ * - CC:   2-letter ISO 3166-1 country code
+ * - LL:   2-character location code (letters or digits)
+ * - BBB:  optional 3-character branch code (letters or digits, "XXX" = head office)
+ */
+export type BICEntity = Entity<
+  "bic",
+  {
+    bic: string;
+    bank: string;
+    country: string;
+    location: string;
+    branch: string | null;
+  }
+>;
+
+/**
+ * Helper for constructing a `BICEntity`.
+ */
+export const bic = (
+  value: BICEntity["value"],
+  before: Context,
+  after: Context,
+): BICEntity => {
+  return ent(value, "bic", before, after);
+};
+
+// Leaf tokens — regex only for character classes
+const bankCode = regex(/[A-Z]{4}/, "bank code");
+const countryChars = regex(/[A-Z]{2}/, "country code");
+const locationCode = regex(/[A-Z0-9]{2}/, "location code");
+const branchCode = regex(/[A-Z0-9]{3}/, "branch code");
+
+type BICLanguage = {
+  /** Full BIC: bank + country + location + optional branch, validated */
+  Full: Parser<BICEntity>;
+  parser: Parser<BICEntity>;
+};
+
+/**
+ * BIC/SWIFT parser language.
+ *
+ * Matches 8- or 11-character SWIFT/BIC codes with a valid ISO 3166-1 country
+ * code at positions 5–6. Uses combinators for structure; regex only for leaf
+ * character classes.
+ */
+export const BIC: BICLanguage = createLanguage<BICLanguage>({
+  Full: () =>
+    guard(
+      map(
+        seq(bankCode, countryChars, locationCode, optional(branchCode)),
+        ([bank, country, location, branch], b, a) =>
+          bic(
+            {
+              bic: `${bank}${country}${location}${branch ?? ""}`,
+              bank,
+              country,
+              location,
+              branch: branch ?? null,
+            },
+            b,
+            a,
+          ),
+      ),
+      (entity) => countryCodes.has(entity.value.country),
+    ),
+  parser: (s) => dot(s.Full),
+});

tests/BIC.test.ts

@@ -0,0 +1,90 @@
+import { assertEquals } from "@std/assert";
+import { BIC } from "../src/BIC.ts";
+import { Duckling } from "../mod.ts";
+
+Deno.test("BIC 8-char (head office)", () => {
+  const res = Duckling([BIC.parser]).extract("Send via DEUTDEFF please");
+  assertEquals(res.length, 1);
+  assertEquals(res[0].kind, "bic");
+  assertEquals(res[0].text, "DEUTDEFF");
+  assertEquals(res[0].value, {
+    bic: "DEUTDEFF",
+    bank: "DEUT",
+    country: "DE",
+    location: "FF",
+    branch: null,
+  });
+});
+
+Deno.test("BIC 11-char (with branch)", () => {
+  const res = Duckling([BIC.parser]).extract("Wire to BOFAUS3NXXX now");
+  assertEquals(res.length, 1);
+  assertEquals(res[0].kind, "bic");
+  assertEquals(res[0].text, "BOFAUS3NXXX");
+  assertEquals(res[0].value, {
+    bic: "BOFAUS3NXXX",
+    bank: "BOFA",
+    country: "US",
+    location: "3N",
+    branch: "XXX",
+  });
+});
+
+Deno.test("BIC HSBC UK", () => {
+  const res = Duckling([BIC.parser]).extract("Use HBUKGB4B for HSBC");
+  assertEquals(res.length, 1);
+  assertEquals(res[0].value.bank, "HBUK");
+  assertEquals(res[0].value.country, "GB");
+});
+
+Deno.test("BIC with numeric location", () => {
+  const res = Duckling([BIC.parser]).extract("Code: BNPAFRPP ok");
+  assertEquals(res.length, 1);
+  assertEquals(res[0].value, {
+    bic: "BNPAFRPP",
+    bank: "BNPA",
+    country: "FR",
+    location: "PP",
+    branch: null,
+  });
+});
+
+Deno.test("BIC invalid country rejected", () => {
+  // ZZ is not a valid ISO 3166-1 country code
+  const res = Duckling([BIC.parser]).extract("code AAAAZZBB ok");
+  assertEquals(res.length, 0);
+});
+
+Deno.test("BIC too short rejected (7 chars)", () => {
+  const res = Duckling([BIC.parser]).extract("code DEUTDEF ok");
+  assertEquals(res.length, 0);
+});
+
+Deno.test("BIC 9 chars rejected (not 8 or 11)", () => {
+  // 9 chars is neither a valid 8-char nor 11-char BIC
+  const res = Duckling([BIC.parser]).extract("code DEUTDEFFA ok");
+  // The parser will match DEUTDEFF (8) and leave the A, which is fine
+  // because dot() requires a non-word boundary after. 'A' is a word char,
+  // so this should NOT match.
+  assertEquals(res.length, 0);
+});
+
+Deno.test("BIC in default parsers", () => {
+  const res = Duckling().extract("Wire to DEUTDEFF please");
+  assertEquals(
+    res.some((e) => e.kind === "bic"),
+    true,
+  );
+});
+
+Deno.test("BIC with branch digits", () => {
+  const res = Duckling([BIC.parser]).extract("SWIFT: COBADEFF100 here");
+  assertEquals(res.length, 1);
+  assertEquals(res[0].value, {
+    bic: "COBADEFF100",
+    bank: "COBA",
+    country: "DE",
+    location: "FF",
+    branch: "100",
+  });
+});