us-ssn-tools 1.0.0 → 2.0.0

package/README.md

@@ -4,16 +4,18 @@ A small, well-tested TypeScript library for **working with U.S. Social Security
 
 It provides:
 
-* ✅ **Validation** (strict + typing-as-you-go)
-* 🔁 **Normalization** (canonical `###-##-####` formatting)
-* 🎭 **Masking** (UI-safe, best-effort, privacy-first)
+* ✅ **Validation** (strict + typing-as-you-go, boolean API)
+* 🔁 **Normalization** (deterministic, UI-friendly formatting)
+* 🎭 **Masking** (privacy-first, best-effort, never validates)
 * 🎲 **Generation** (pre-2011, post-2011, random, and publicly advertised SSNs)
 * 🧩 **Zod & Yup adapters** for form validation
 
-> **Design principle:**
-> Validation enforces rules.
-> Masking never leaks data.
-> Normalization is deterministic and UI-friendly.
+> **Design principles**
+>
+> * Validation answers *“is this valid?”* — nothing more.
+> * Normalization formats input for display and typing UX.
+> * Masking never leaks digits and never enforces validity.
+> * Public safety beats convenience.
 
 ---
 
@@ -35,8 +37,8 @@ yarn add us-ssn-tools
 
 ```ts
 import {
-  validateSsn,
-  normalizeSsnInput,
+  isValidSsn,
+  normaliseSsn,
   formatSsnFromDigits,
   maskSsn,
   generateSsn,
@@ -50,81 +52,86 @@ import { yupSsnTyping, yupSsnSubmit } from "us-ssn-tools/yup";
 
 ## Validation
 
-### `validateSsn(input, options)`
+### `isValidSsn(input, options): boolean`
 
-Validates an SSN according to U.S. rules.
+Checks whether an SSN is valid according to U.S. rules.
+
+* Returns **`true` or `false` only**
+* Does **not** normalize
+* Can validate *partial input* (“valid so far”)
 
 ```ts
-const result = validateSsn("123-45-6789");
-
-if (result.ok) {
-  console.log(result.normalized); // "123-45-6789"
-} else {
-  console.log(result.error);   // e.g. "INVALID_AREA"
-  console.log(result.message); // human-readable explanation
-}
+isValidSsn("123-45-6789"); // true
+isValidSsn("123456789");  // false (dashes required by default)
 ```
 
 ### Options
 
 ```ts
 type ValidateSsnOptions = {
-  allowNoDashes?: boolean; // default true
-  allowPartial?: boolean; // default false
-  ruleMode?: "pre2011" | "post2011" | "both"; // default "both"
+  requireDashes?: boolean;   // default: true
+  allowPartial?: boolean;    // default: false
+  ruleMode?: "pre2011" | "post2011"; // default: "post2011"
 };
 ```
 
-#### Examples
+### Examples
 
 ```ts
-validateSsn("123456789"); // ok (normalized to "123-45-6789")
+isValidSsn("9", { allowPartial: true });
+// true (still potentially valid)
 
-validateSsn("9", { allowPartial: true }); 
-// ❌ INVALID_AREA (impossible prefix)
+isValidSsn("900", { allowPartial: true });
+// false (invalid area)
 
-validateSsn("773-12-3456", { ruleMode: "pre2011" });
-// ❌ INVALID_AREA
+isValidSsn("773-12-3456", { ruleMode: "pre2011" });
+// false
 
-validateSsn("773-12-3456", { ruleMode: "post2011" });
-// ✅ ok
+isValidSsn("773-12-3456", { ruleMode: "post2011" });
+// true
 ```
 
 ---
 
 ## Normalization
 
-### `normalizeSsnInput(input, options)`
+### `normaliseSsn(input, options): string`
 
-Parses and formats SSNs **without enforcing full validity**.
-Ideal for **typing-as-you-go**.
+Formats input for **UI display**.
+It does **not validate** and never throws.
 
-```ts
-const res = normalizeSsnInput("1234", { allowPartial: true });
+* Extracts digits
+* Optionally inserts dashes
+* Supports typing-as-you-go
+* Allows overflow digits if desired
 
-if (res.ok) {
-  res.digits;     // "1234"
-  res.normalized; // "123-4"
-}
+```ts
+normaliseSsn("1234");        // "123-4"
+normaliseSsn("123456789");  // "123-45-6789"
+normaliseSsn("SSN: 12a3");  // "123"
 ```
 
 ### Options
 
 ```ts
-type NormalizeSsnOptions = {
-  allowPartial?: boolean;
-  allowNoDashes?: boolean;
+type NormaliseSsnOptions = {
+  allowPartial?: boolean;  // default: true
+  digitsOnly?: boolean;    // default: false
+  enforceLength?: boolean; // default: false
 };
 ```
 
 ### Examples
 
 ```ts
-normalizeSsnInput("123456789");
-// → { digits: "123456789", normalized: "123-45-6789" }
+normaliseSsn("123456789", { digitsOnly: true });
+// "123456789"
+
+normaliseSsn("12345678999");
+// "123-45-678999"
 
-normalizeSsnInput("123-45-6", { allowPartial: true });
-// → { digits: "123456", normalized: "123-45-6" }
+normaliseSsn("12345678999", { enforceLength: true });
+// "123-45-6789"
 ```
 
 ---
@@ -134,7 +141,6 @@ normalizeSsnInput("123-45-6", { allowPartial: true });
 ### `formatSsnFromDigits(digits)`
 
 Formats a **digit string** into SSN shape.
-This function **does not validate**.
 
 ```ts
 formatSsnFromDigits("123");       // "123"
@@ -142,16 +148,20 @@ formatSsnFromDigits("1234");      // "123-4"
 formatSsnFromDigits("123456789"); // "123-45-6789"
 ```
 
-Used internally by normalization and masking, but safe to use directly for UI.
+No validation is performed.
 
 ---
 
 ## Masking (UI-safe)
 
-### `maskSsn(input, options)`
+### `maskSsn(input, options): string`
+
+Masks digits after normalization.
 
-Masks digits while **never masking dashes**.
-Designed for **privacy-safe UI rendering**, not validation.
+* Always normalizes first
+* Never validates
+* Never reveals digits unless explicitly allowed
+* Safe for **any** UI context
 
 ```ts
 maskSsn("123-45-6789");
@@ -165,87 +175,80 @@ maskSsn("123-45-6789", { revealLast4: true });
 
 ```ts
 type MaskSsnOptions = {
-  allowPartial?: boolean;      // default false
-  revealLast4?: boolean;       // default false
-  maskChar?: string;           // default "*"
-  dashMode?: "normalize" | "preserve"; // default "normalize"
-  allowNoDashes?: boolean;     // default true
+  allowPartial?: boolean;   // default: true
+  revealLast4?: boolean;    // default: false
+  maskChar?: string;        // default: "*"
+  digitsOnly?: boolean;     // default: false
+  enforceLength?: boolean;  // default: false
 };
 ```
 
-### Partial / typing behavior
+### Typing behavior
 
 ```ts
-maskSsn("123", { allowPartial: true });
+maskSsn("123"); 
 // "***"
 
-maskSsn("123-45-6", { allowPartial: true, revealLast4: true });
+maskSsn("123-45-6", { revealLast4: true });
 // "***-**-6"
 ```
 
-### Important guarantees
+### Guarantees
 
-* ✔️ **Digits are always masked** (even on invalid input)
+* ✔️ Digits are **always masked**
 * ✔️ Dashes are never masked
-* ✔️ No validation required — safe for UI display
+* ✔️ Invalid input is still safely masked
+* ✔️ No validation logic inside masking
 
 ---
 
 ## Generation
 
-### `generateSsn(options)`
-Absolutely — that’s an important point, and it’s worth stating **clearly but professionally**, without sounding alarmist.
+### `generateSsn(options): string`
 
-Here’s a **polished replacement** for the **Generation** section note that you can drop straight into the README.
+Generates SSNs for testing and development.
 
----
-
-## Generation
+```ts
+generateSsn();
+// one of the publicly advertised SSNs
+```
 
-Generates realistic-looking SSNs for testing, demos, and development.
+### Options
 
 ```ts
-generateSsn(); 
-// e.g. "509-21-4837"
+type GenerateSsnOptions = {
+  mode?: "public" | "pre2011" | "post2011" | "any"; // default: "public"
+  digitsOnly?: boolean; // default: false
+};
 ```
 
 ### ⚠️ Important note on public usage
 
 > **Only use `mode: "public"` for any SSNs that may be displayed publicly.**
 
-SSNs generated with `"pre2011"`, `"post2011"`, or `"any"` modes are **syntactically valid** and may correspond to **real individuals**.
-
-If such a value is:
+SSNs generated with `"pre2011"`, `"post2011"`, or `"any"` are **syntactically valid** and may correspond to **real individuals**.
 
-* rendered in documentation
-* shown in screenshots
-* logged to public consoles
-* included in sample data or demos
+If such values are:
 
-you risk **exposing a real person to identity theft** if the generated SSN happens to match an existing one.
+* shown in documentation
+* used in screenshots
+* logged publicly
+* included in demos or examples
 
-To prevent this, the library includes a special `"public"` generation mode that returns **historically documented, non-random, publicly advertised SSNs** that are known to be unsafe for real-world use but safe for examples.
+you risk **exposing a real person to identity theft**.
 
-### Recommended usage
+The `"public"` mode returns **historically documented, publicly advertised SSNs** that are known to be unsafe for real-world use but safe for examples.
 
 ```ts
-// ✅ Safe for docs, demos, screenshots, and public output
+// ✅ Safe for docs, demos, screenshots
 generateSsn({ mode: "public" });
 
-// ❌ Do NOT use in any public or user-visible context
+// ❌ Never display publicly
 generateSsn({ mode: "any" });
 generateSsn({ mode: "pre2011" });
 generateSsn({ mode: "post2011" });
 ```
 
-Use non-public modes **only** for:
-
-* internal testing
-* private development environments
-* automated test data that is never exposed
-
-This distinction exists to protect real people, not just to satisfy validation rules.
-
 ---
 
 ## Zod Adapters
@@ -256,7 +259,7 @@ This distinction exists to protect real people, not just to satisfy validation r
 const schema = zodSsnTyping();
 
 schema.parse("1234"); // "123-4"
-schema.parse("9");    // ❌ throws (impossible prefix)
+schema.parse("900");  // ❌ throws
 ```
 
 ### Submit (strict)
@@ -284,14 +287,14 @@ await yupSsnSubmit().validate("123456789");
 
 ## Testing & Guarantees
 
-* ✔️ 100% table-driven Jest tests
-* ✔️ Deterministic RNG support
-* ✔️ Strict separation between:
+* ✔️ Extensive table-driven Jest tests
+* ✔️ Clear separation between:
 
   * validation
-  * formatting
+  * normalization
   * masking
   * generation
+* ✔️ UI-safe defaults everywhere
 
 ---
 
@@ -299,7 +302,7 @@ await yupSsnSubmit().validate("123456789");
 
 * ❌ No storage or encryption
 * ❌ No non-US SSNs (yet)
-* ❌ No implicit trimming or mutation of user input
+* ❌ No mutation of user input beyond formatting
 
 ---
 
@@ -307,13 +310,15 @@ await yupSsnSubmit().validate("123456789");
 
 ISC
 
+---
+
 ## Support This Project
 
-If you find this project useful, consider supporting me to help keep it maintained and improved:
+If you find this project useful, consider supporting it:
 
-- [Sponsor on GitHub](https://github.com/sponsors/backupbrain)
-- [Buy Me a Coffee](https://www.buymeacoffee.com/backupbrain)
-- [Ko-fi](https://ko-fi.com/backupbrain)
-- [Thanks.dev](https://thanks.dev/u/gh/backupbrain)
+* [Sponsor on GitHub](https://github.com/sponsors/backupbrain)
+* [Buy Me a Coffee](https://www.buymeacoffee.com/backupbrain)
+* [Ko-fi](https://ko-fi.com/backupbrain)
+* [Thanks.dev](https://thanks.dev/u/gh/backupbrain)
 
-Your support is greatly appreciated!
+Your support is greatly appreciated 🙏

package/dist/generate.d.ts

@@ -2,22 +2,18 @@ export type GenerateSsnMode = 'pre2011' | 'post2011' | 'any' | 'public';
 export interface GenerateSsnOptions {
     /**
      * What kind of SSN to generate.
-     * - "any" (default): may produce either pre2011-valid or post2011-valid
+     * - "public" (default): returns one of the publicly-advertised SSNs (intentionally invalid)
+     * - "any": may produce either pre2011-valid or post2011-valid
      * - "pre2011": uses stricter pre-2011 area rules
      * - "post2011": uses post-2011 relaxed area rules
-     * - "public": returns one of the publicly-advertised SSNs (intentionally invalid)
      */
     mode?: GenerateSsnMode;
-    /** Output format (default: "dashed") */
-    format?: 'dashed' | 'digits';
     /**
-     * Optional RNG injection for determinism in tests.
-     * Must return a float in [0, 1).
+     * If true, output is digits-only (#########).
+     * If false, output is dashed (###-##-####).
+     *
+     * Default: false
      */
-    rng?: () => number;
-    /**
-     * For mode="public": choose a specific advertised SSN, otherwise random.
-     */
-    publicValue?: '078-05-1120' | '721-07-4426' | '219-09-9999';
+    digitsOnly?: boolean;
 }
 export declare function generateSsn(opts?: GenerateSsnOptions): string;

package/dist/generate.js

@@ -7,28 +7,27 @@ const PUBLICLY_ADVERTISED = [
     '219-09-9999',
 ];
 function generateSsn(opts = {}) {
-    var _a, _b, _c, _d;
-    const mode = (_a = opts.mode) !== null && _a !== void 0 ? _a : 'any';
-    const format = (_b = opts.format) !== null && _b !== void 0 ? _b : 'dashed';
-    const rng = (_c = opts.rng) !== null && _c !== void 0 ? _c : defaultRng;
+    var _a, _b;
+    const mode = (_a = opts.mode) !== null && _a !== void 0 ? _a : 'public';
+    const digitsOnly = (_b = opts.digitsOnly) !== null && _b !== void 0 ? _b : false;
     if (mode === 'public') {
-        const chosen = (_d = opts.publicValue) !== null && _d !== void 0 ? _d : PUBLICLY_ADVERTISED[randomInt(rng, 0, PUBLICLY_ADVERTISED.length - 1)];
-        return format === 'digits' ? chosen.replace(/-/g, '') : chosen;
+        const chosen = PUBLICLY_ADVERTISED[randomInt(0, PUBLICLY_ADVERTISED.length - 1)];
+        return digitsOnly ? chosen.replace(/-/g, '') : chosen;
     }
-    // "any" => randomly choose pre or post
-    const effectiveMode = mode === 'any' ? (rng() < 0.5 ? 'pre2011' : 'post2011') : mode;
-    const area = generateArea(effectiveMode, rng);
-    const group = generateNonZeroFixedWidth(rng, 2); // 01..99 (not 00)
-    const serial = generateNonZeroFixedWidth(rng, 4); // 0001..9999 (not 0000)
-    const dashed = `${area}-${group}-${serial}`;
-    // Avoid accidentally returning a "publicly advertised" SSN unless explicitly requested.
-    if (PUBLICLY_ADVERTISED.includes(dashed)) {
-        return generateSsn(Object.assign(Object.assign({}, opts), { mode })); // retry (very unlikely)
+    const effectiveMode = mode === 'any' ? (randomFloat() < 0.5 ? 'pre2011' : 'post2011') : mode;
+    while (true) {
+        const area = generateArea(effectiveMode); // "001".."899" with constraints
+        const group = generateNonZeroFixedWidth(2); // "01".."99"
+        const serial = generateNonZeroFixedWidth(4); // "0001".."9999"
+        const dashed = `${area}-${group}-${serial}`;
+        // Avoid returning publicly advertised SSNs unless explicitly requested.
+        if (PUBLICLY_ADVERTISED.includes(dashed))
+            continue;
+        return digitsOnly ? dashed.replace(/-/g, '') : dashed;
     }
-    return format === 'digits' ? dashed.replace(/-/g, '') : dashed;
 }
 /* ---------------------------- helpers ---------------------------- */
-function generateArea(mode, rng) {
+function generateArea(mode) {
     // Base rules always:
     // - not 000
     // - not 666
@@ -40,7 +39,7 @@ function generateArea(mode, rng) {
     //
     // Strategy: generate until it passes constraints (fast, tiny rejection rate).
     while (true) {
-        const n = randomInt(rng, 1, 899); // 001..899
+        const n = randomInt(1, 899); // 001..899
         if (n === 666)
             continue;
         if (mode === 'pre2011') {
@@ -52,28 +51,24 @@ function generateArea(mode, rng) {
         return pad3(n);
     }
 }
-function generateNonZeroFixedWidth(rng, width) {
+function generateNonZeroFixedWidth(width) {
     if (width === 2) {
-        // 01..99
-        const n = randomInt(rng, 1, 99);
+        const n = randomInt(1, 99); // 01..99
         return n.toString().padStart(2, '0');
     }
-    // 0001..9999
-    const n = randomInt(rng, 1, 9999);
+    const n = randomInt(1, 9999); // 0001..9999
     return n.toString().padStart(4, '0');
 }
 function pad3(n) {
     return n.toString().padStart(3, '0');
 }
-function randomInt(rng, min, max) {
+function randomInt(min, max) {
     // inclusive min/max
-    const r = rng();
-    return Math.floor(r * (max - min + 1)) + min;
+    return Math.floor(randomFloat() * (max - min + 1)) + min;
 }
-function defaultRng() {
+function randomFloat() {
     var _a;
     // Prefer crypto when available; fall back to Math.random.
-    // Works in browsers; in Node 19+ crypto.getRandomValues exists on globalThis.crypto.
     const g = globalThis;
     if ((_a = g.crypto) === null || _a === void 0 ? void 0 : _a.getRandomValues) {
         const buf = new Uint32Array(1);

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-export { validateSsn } from './validate';
-export { normalizeSsnInput } from './normalize';
+export { isValidSsn } from './validate';
+export { normalizeSsn } from './normalize';
 export { maskSsn } from './mask';
-export { formatSsnFromDigits } from './utils';
 export { generateSsn } from './generate';

package/dist/index.js

@@ -1,14 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateSsn = exports.formatSsnFromDigits = exports.maskSsn = exports.normalizeSsnInput = exports.validateSsn = void 0;
+exports.generateSsn = exports.maskSsn = exports.normalizeSsn = exports.isValidSsn = void 0;
 // Exporting all functions
 var validate_1 = require("./validate");
-Object.defineProperty(exports, "validateSsn", { enumerable: true, get: function () { return validate_1.validateSsn; } });
+Object.defineProperty(exports, "isValidSsn", { enumerable: true, get: function () { return validate_1.isValidSsn; } });
 var normalize_1 = require("./normalize");
-Object.defineProperty(exports, "normalizeSsnInput", { enumerable: true, get: function () { return normalize_1.normalizeSsnInput; } });
+Object.defineProperty(exports, "normalizeSsn", { enumerable: true, get: function () { return normalize_1.normalizeSsn; } });
 var mask_1 = require("./mask");
 Object.defineProperty(exports, "maskSsn", { enumerable: true, get: function () { return mask_1.maskSsn; } });
-var utils_1 = require("./utils");
-Object.defineProperty(exports, "formatSsnFromDigits", { enumerable: true, get: function () { return utils_1.formatSsnFromDigits; } });
 var generate_1 = require("./generate");
 Object.defineProperty(exports, "generateSsn", { enumerable: true, get: function () { return generate_1.generateSsn; } });

package/dist/mask.d.ts

@@ -1,25 +1,33 @@
 export interface MaskSsnOptions {
-    /** Allow masking partial SSNs (typing-as-you-go). */
+    /**
+     * Allow masking partial SSNs (typing-as-you-go).
+     * Default: true
+     */
     allowPartial?: boolean;
-    /** If true, reveal last 4 digits when present (>= 4 digits typed). */
+    /**
+     * Reveal serial digits as they are typed:
+     * - before serial (<=5 digits): reveal nothing
+     * - serial (6..9 digits): reveal up to 4 digits
+     *
+     * Default: false
+     */
     revealLast4?: boolean;
-    /** Mask character (default: "*"). Only first char is used. */
+    /**
+     * Mask character (default: "*").
+     * Only the first character is used.
+     */
     maskChar?: string;
-    /** Accept digit-only input (default: true). */
-    allowNoDashes?: boolean;
     /**
-     * Controls dash output:
-     * - "preserve": keep dashes only if the input already contains '-'
-     * - "normalize": always insert dashes in ###-##-#### style (even for digits-only)
-     *
-     * Default: "normalize"
+     * Output digits only (no dashes).
+     * Default: false
      */
-    dashMode?: 'preserve' | 'normalize';
+    digitsOnly?: boolean;
     /**
-     * If true (default), and allowPartial=true, invalid partial input will be masked
-     * in a best-effort way (digits masked, dashes preserved).
-     * If false, invalid input is returned unchanged.
+     * If true, cap to 9 digits (SSN length).
+     * If false, allow overflow digits (UI testing / paste scenarios).
+     *
+     * Default: false
      */
-    bestEffortOnInvalidPartial?: boolean;
+    enforceLength?: boolean;
 }
 export declare function maskSsn(input: string, opts?: MaskSsnOptions): string;

package/dist/mask.js

@@ -5,51 +5,26 @@ const normalize_1 = require("./normalize");
 const utils_1 = require("./utils");
 function maskSsn(input, opts = {}) {
     var _a, _b, _c, _d, _e;
-    const allowPartial = (_a = opts.allowPartial) !== null && _a !== void 0 ? _a : false;
+    const allowPartial = (_a = opts.allowPartial) !== null && _a !== void 0 ? _a : true;
     const revealLast4 = (_b = opts.revealLast4) !== null && _b !== void 0 ? _b : false;
-    const maskChar = ((_c = opts.maskChar) !== null && _c !== void 0 ? _c : '*').slice(0, 1) || '*';
-    const allowNoDashes = (_d = opts.allowNoDashes) !== null && _d !== void 0 ? _d : true;
-    const dashMode = (_e = opts.dashMode) !== null && _e !== void 0 ? _e : 'normalize';
-    const hadDashes = input.includes('-');
-    const normalized = (0, normalize_1.normalizeSsnInput)(input, { allowPartial, allowNoDashes });
-    if (!normalized.ok) {
-        // Masking is UI-safety, not validation: never return raw digits.
-        // Best-effort: mask digits, keep '-' unmasked, keep any other characters as-is.
-        const masked = maskBestEffort(input, { maskChar });
-        // If caller wants normalized dashes, we can try to normalize by extracting digits
-        // from the best-effort masked string is not possible (digits are already masked),
-        // so we simply return the best-effort output.
-        return masked;
-    }
-    const digits = normalized.digits; // 0..9 digits (partial) or 9 digits (full)
-    // Determine how many digits to reveal (last 4) if present.
+    const digitsOnly = (_c = opts.digitsOnly) !== null && _c !== void 0 ? _c : false;
+    const enforceLength = (_d = opts.enforceLength) !== null && _d !== void 0 ? _d : false;
+    const maskChar = ((_e = opts.maskChar) !== null && _e !== void 0 ? _e : '*').slice(0, 1) || '*';
+    // 1) Normalize → DIGITS ONLY
+    const digits = (0, normalize_1.normalizeSsn)(input, {
+        allowPartial,
+        digitsOnly: true,
+        enforceLength,
+    });
+    // 2) Mask
     const total = digits.length;
-    // digits.length = total typed digits (0..9)
-    const serialTyped = Math.max(0, total - 5); // digits 6..9 => 1..4
+    // Reveal only serial digits (positions 6–9)
+    const serialTyped = Math.max(0, total - 5);
     const revealCount = revealLast4 ? Math.min(4, serialTyped) : 0;
     const maskedCount = Math.max(0, total - revealCount);
     const maskedDigits = maskChar.repeat(maskedCount) + digits.slice(maskedCount);
-    // Output formatting
-    if (dashMode === 'normalize') {
-        // Insert dashes as ###-##-#### prefix (even while typing).
-        return (0, utils_1.formatSsnFromDigits)(maskedDigits);
-    }
-    // dashMode === "preserve"
-    if (hadDashes) {
-        // Input had dashes -> keep dashed presentation (normalized positions).
-        return (0, utils_1.formatSsnFromDigits)(maskedDigits);
-    }
-    // Input had no dashes -> keep digits-only.
-    return maskedDigits;
-}
-function maskBestEffort(input, opts) {
-    const m = opts.maskChar;
-    let out = '';
-    for (const ch of input) {
-        if (ch >= '0' && ch <= '9')
-            out += m;
-        else
-            out += ch; // dashes and any other characters preserved
-    }
-    return out;
+    // 3) Output formatting
+    if (digitsOnly)
+        return maskedDigits;
+    return (0, utils_1.formatSsnWithOverflow)(maskedDigits);
 }