qbo4.Permutator.Web

ASP.NET Core class library that exposes name permutation and parsing as a REST API and ships a Lit-based web component (<qbo-permutator>) for interactive use.

What it does

Contact and company name data is often entered inconsistently — nicknames, hyphenated last names, middle initials, entity suffixes like "LLC", and so on. The Permutator solves this by taking a raw name, parsing it into structured parts, and generating every reasonable variation so that downstream search and matching operations can work against a complete alias set rather than just what was typed.

This project is the hosting layer. It wires the parsing and permutation engines to HTTP endpoints and provides a browser UI for testing and inspection.

REST API

All endpoints are under the /permutator route prefix.

POST /permutator/parse-permutate

Parses a contact name into structured parts and then generates all permutations in one call.

Request

{
  "contact": {
    "firstName": "John",
    "middleName": "Allen",
    "lastName": "Smith-Jones",
    "suffix": "Jr"
  },
  "options": {
    "transpose": true,
    "toggleMiddleName": true,
    "forceHyphen": false
  }
}

Response — flat array of Contact objects. Each item includes a source field indicating which option produced it (e.g. "Transpose", "ToggleMiddleName", "ForceHyphen", "MixedCaseSplit", "IncludeSuffix", or null for base variations). Multi-source items are comma-separated (e.g. "Transpose,ToggleMiddleName").

POST /permutator/permutate

Generates permutations from an already-parsed contact (skips the parse step).

Same request/response shape as parse-permutate.

POST /permutator/parse-company

Parses a raw company name string into distinct variations, splitting on common delimiters (dba, aka, fka, /) and recognising entity types (LLC, Inc, Corp, LLP, etc.).

Request

{
  "company": "Acme Corp dba The Rocket Company, LLC",
  "options": {
    "includeEntity": "OriginalOnly"
  }
}

Response — array of CompanyVariation objects (name, entity, contactTemplate).

Parse options (ParsePermutateOptions)

| Option | Type | Default | Effect | |---|---|---|---| | parseModel | enum | NameSegmentParse | Selects the parser/permutator implementation (NameSegmentParse, None, AI) | | keepOriginal | bool | true | Include the original unparsed name in results | | parsePrefix | bool | true | Extract titles (Mr, Dr, etc.) from the first-name field | | parseSuffix | bool | true | Extract suffixes (Jr, Sr, Esq, etc.) from the last-name field | | middleNameParse | enum | None | How to handle middle names: None, Share, ShareMerge, AppendMiddleInitial, AppendMiddleInitialAll | | toggleMiddleName | bool | false | Generate variations both with and without the middle name | | togglePrimaryName | bool | false | Generate variations with only the last name (no first/middle) | | transpose | bool | false | Swap the order of compound last-name parts (e.g. "Smith Jones" → "Jones Smith") | | mergeNameParts | bool | false | Generate merged forms of compound names (e.g. "Smith Jones" → "SmithJones") | | forceHyphen | bool | false | For two-part space-separated last names, also generate a hyphenated form | | suppressHyphenParse | enum | Never | Control whether existing hyphens in a last name are split: Never, MultipleOnly, Always | | mixedCaseSplit | bool | false | Split camelCase last names into separate parts | | includeSuffix | enum | None | Append the name suffix to variations: None, OriginalOnly, All | | removeNobiliaryParticiple | bool | false | Strip nobiliary particles (von, de, van, etc.) when splitting compound names | | maxPermutationCount | int | 50 | Hard limit on the number of permutations returned |

Web component

The project ships a Lit custom element for browser-based testing and inspection. Register the script and use the element:

<script type="module" src="/permutator/js/Program.js"></script>

<qbo-permutator base-url="/"></qbo-permutator>

Features

• Contact / Company mode toggle — switch between person name and company name workflows
• Options panel — collapsible panel exposing every ParsePermutateOptions and ParseCompanyOptions field
• Results table — displays parsed and permutated variations with columns for Full Name, Prefix, First, Middle, Last, Suffix, Template, Type, and Source
• Source filter chips — after a result is returned, clickable chips appear for each distinct source value (e.g. Transpose, ToggleMiddleName). Selecting a chip filters the table to show only variations produced by that option. Multiple chips can be active at once; a Clear button resets the filter
• Export Results — downloads the currently displayed (filtered) results as a JSON file named permutator-results-{lastName}.json
• Export Settings — downloads the full request payload (contact/company input + options) as permutator-settings.json, ready to replay directly against the API

Dependency injection

Register via AddPermutatorUI along with the parser and permutator implementations:

services.AddNameSegmentParser(configuration);   // registers IParser + ICompanyParser
services.AddAdvancedPermutator(configuration);  // registers IPermutator
services.AddPermutatorUI(configuration.GetSection(PermutatorWebOptions.SectionName));

The convention-based ConfigureProject() host builder extension will discover and call these automatically when the assemblies are referenced.

Project structure

Controllers/
  PermutatorController.cs     REST endpoints
Extensions/
  ServiceCollectionExtensions.cs   AddPermutatorUI registration
src/
  qbo-permutator.ts           Lit web component
  styles.ts                   Component CSS (generated — edit scss/qbo-permutator.scss)
scss/
  qbo-permutator.scss         Source styles
wwwroot/
  js/                         Compiled TypeScript output
  css/                        Compiled and purged CSS output

Note: src/styles.ts is generated by the build pipeline (npm run sass). Always edit scss/qbo-permutator.scss — do not edit styles.ts directly.