@cityssm/mpac-tools 0.1.0

package/rollNumbers/lookups.ts

@@ -0,0 +1,525 @@
+// eslint-disable-next-line @eslint-community/eslint-comments/disable-enable-pair
+/* eslint-disable @cspell/spellchecker, max-lines, sonarjs/no-duplicate-string */
+
+export const rollNumberMunicipalities = Object.freeze({
+  // Prescott, Russell, Stormont Dundas & Glengarry Counties
+  '0101': 'South Glengarry Township',
+  '0111': 'North Glengarry Township',
+  '0201': 'East Hawkesbury Township',
+  '0208': 'Hawkesbury Town',
+  '0209': 'Champlain Township',
+  '0212': 'The Nation Municipality',
+  '0231': 'Alfred and Plantagenet Township',
+  '0302': 'Casselman Village',
+  '0306': 'Russell Township',
+  '0316': 'Clarence-Rockland City',
+  '0402': 'Cornwall City',
+  '0406': 'South Stormont Township',
+  '0411': 'North Stormont Township',
+  '0506': 'South Dundas Township',
+  '0511': 'North Dundas Township',
+
+  // Lanark, Leeds & Grenville Counties
+  '0701': 'Edwardsburgh/Cardinal Township',
+  '0706': 'Augusta Township',
+  '0708': 'Prescott Town',
+  '0714': 'Merrickville-wolford Village',
+  '0719': 'North Grenville Township',
+  '0801': 'Elizabethtown-kitley Township',
+  '0802': 'Brockville City',
+  '0806': 'Front Yonge Township',
+  '0812': 'Leeds & Thousand Islands Township',
+  '0814': 'Gananoque Town',
+  '0819': 'Athens Township',
+  '0831': 'Rideau Lakes Township',
+  '0841': 'Westport Village',
+  '0901': 'Montague Township',
+  '0904': 'Smiths Falls Town',
+  '0911': 'Tay Valley Township',
+  '0919': 'Drummond/North Elmsley Township',
+  '0921': 'Perth Town',
+  '0924': 'Beckwith Township',
+  '0928': 'Carleton Place Town',
+  '0931': 'Mississippi Mills Town',
+  '0940': 'Lanark Highlands Township',
+
+  // Regional Municipality of the City of Ottawa
+  '0614': 'Ottawa City',
+
+  // Renfrew County
+  '4701': 'Mcnab/Braeside Township',
+  '4702': 'Arnprior Town',
+  '4706': 'Greater Madawaska Township',
+  '4719': 'Brudenell Lyndoch Raglan Township',
+  '4726': 'Madawaska Valley Township',
+  '4731': 'Killaloe, Hagarty & Richards Township',
+  '4738': 'Bonnechere Valley Township',
+  '4742': 'Admaston/Bromley Township',
+  '4746': 'Horton Township',
+  '4748': 'Renfrew Town',
+  '4758': 'Whitewater Region Township',
+  '4764': 'Pembroke City',
+  '4766': 'Laurentian Valley Township',
+  '4769': 'North Algona Wilberforce Township',
+  '4779': 'Petawawa Town',
+  '4792': 'Laurentian Hills Town',
+  '4796': 'Deep River Town',
+  '4798': 'Head Clara Maria Township',
+
+  // Frontenac, Lennox & Addington Counties
+  '1001': 'Frontenac Islands Township',
+  '1011': 'Corporation Of The City Of Kingston',
+  '1029': 'South Frontenac Township',
+  '1039': 'Central Frontenac Township',
+  '1042': 'North Frontenac Township',
+  '1104': 'Loyalist Township',
+  '1121': 'Greater Napanee Town',
+  '1124': 'Stone Mills Township',
+  '1134': 'Addington Highlands Township',
+
+  // Hastings, Northumberland, City of Prince Edward Counties
+  '1201': 'Tyendinaga Township',
+  '1202': 'Deseronto Town',
+  '1204': 'Quinte West City',
+  '1208': 'Belleville City',
+  '1220': 'Stirling-Rawdon Township',
+  '1230': 'Centre Hastings Municipality',
+  '1231': 'Tweed Municipality',
+  '1236': 'Madoc Township',
+  '1241': 'Marmora And Lake Municipality',
+  '1248': 'Tudor Cashel Township',
+  '1251': 'Limerick Township',
+  '1254': 'Wollaston Township',
+  '1258': 'Faraday Township',
+  '1262': 'Bancroft Town',
+  '1270': 'Carlow/Mayo Township',
+  '1290': 'Hastings Highlands Municipality',
+  '1350': 'Prince Edward County',
+  '1408': 'Brighton Municipality',
+  '1411': 'Cramahe Township',
+  '1419': 'Hamilton Township',
+  '1421': 'Cobourg Town',
+  '1423': 'Port Hope Municipality',
+  '1435': 'Trent Hills Municipality',
+  '1450': 'Alnwick/Haldimand Township',
+
+  // Peterborough County, Kawartha Lakes County, Haliburton County
+  '1501': 'Asphodel-norwood Township',
+  '1506': 'Otonabee-south Monaghan Township',
+  '1509': 'Cavan Monaghan Township',
+  '1514': 'Peterborough City',
+  '1516': 'Selwyn Township',
+  '1522': 'Douro-dummer Township',
+  '1531': 'Havelock-belmont-methuen Township',
+  '1536': 'North Kawartha Township',
+  '1542': 'Trent Lakes Municipality',
+  '1651': 'Kawartha Lakes City',
+  '4601': 'Highlands East Municipality',
+  '4616': 'Minden Hills Township',
+  '4621': 'Algonquin Highlands Township',
+  '4624': 'Dysart Et Al Municipality',
+
+  // City of Toronto
+  '1900': 'City Of Toronto',
+
+  // Regional Municipality of Durham
+  '1801': 'Pickering City',
+  '1805': 'Ajax Town',
+  '1809': 'Whitby Town',
+  '1813': 'Oshawa City',
+  '1817': 'Clarington Municipality',
+  '1820': 'Scugog Township',
+  '1829': 'Uxbridge Township',
+  '1839': 'Brock Township',
+
+  // Regional Municipality of York
+  '1928': 'Vaughan City',
+  '1936': 'Markham City',
+  '1938': 'Richmond Hill Town',
+  '1944': 'Whitchurch-stouffville Town',
+  '1946': 'Aurora Town',
+  '1948': 'Newmarket Town',
+  '1949': 'King Township',
+  '1954': 'East Gwillimbury Town',
+  '1970': 'Georgina Town',
+
+  // Regional Municipalities of Halton and Peel
+  '2105': 'Mississauga City',
+  '2110': 'Brampton City',
+  '2124': 'Caledon Town',
+  '2401': 'Oakville Town',
+  '2402': 'Burlington City',
+  '2409': 'Milton Town',
+  '2415': 'Halton Hills Town',
+
+  // Simcoe County
+  '4301': 'Adjala-tosorontio Township',
+  '4312': 'Bradford West Gwillimbury Town',
+  '4316': 'Innisfil Town',
+  '4321': 'Essa Township',
+  '4324': 'New Tecumseth Town',
+  '4329': 'Clearview Township',
+  '4331': 'Collingwood Town',
+  '4341': 'Springwater Township',
+  '4342': 'Barrie City',
+  '4346': 'Oro-medonte Township',
+  '4348': 'Ramara Township',
+  '4351': 'Severn Township',
+  '4352': 'Orillia City',
+  '4353': 'Tay Township',
+  '4364': 'Wasaga Beach Town',
+  '4368': 'Tiny Township',
+  '4372': 'Penetanguishene Town',
+  '4374': 'Midland Town',
+
+  // District Municipality of Muskoka
+  '4402': 'Gravenhurst Town',
+  '4418': 'Bracebridge Town',
+  '4427': 'Lake Of Bays Township',
+  '4442': 'Huntsville Town',
+  '4453': 'Muskoka Lakes Township',
+  '4465': 'Georgian Bay Township',
+
+  // Regional Municipality of Niagara
+  '2602': 'West Lincoln Township',
+  '2615': 'Grimsby Town',
+  '2622': 'Lincoln Town',
+  '2627': 'Niagara-on-the-lake Town',
+  '2629': 'St Catharines City',
+  '2703': 'Fort Erie Town',
+  '2711': 'Port Colborne City',
+  '2714': 'Wainfleet Township',
+  '2719': 'Welland City',
+  '2725': 'Niagara Falls City',
+  '2731': 'Thorold City',
+  '2732': 'Pelham Town',
+
+  // Regional Municipality of Hamilton
+  '2518': 'Hamilton City',
+
+  // City of Brantford, Brant, Haldimand County and Norfolk Counties
+  '2810': 'Haldimand County',
+  '2906': 'Brantford City',
+  '2920': 'County Of Brant',
+  '3310': 'Norfolk County',
+
+  // Regional Municipality of Waterloo, the Counties of Dufferin and Wellington, and the City of Guelph
+  '2201': 'East Garafraxa Township',
+  '2204': 'Grand Valley Town',
+  '2208': 'Amaranth Township',
+  '2212': 'Mono Town',
+  '2214': 'Orangeville Town',
+  '2216': 'Mulmur Township',
+  '2219': 'Melancthon Township',
+  '2221': 'Shelburne Town',
+  '2301': 'Puslinch Township',
+  '2308': 'Guelph City',
+  '2311': 'Guelph Eramosa Township',
+  '2316': 'Erin Town',
+  '2326': 'Centre Wellington Township',
+  '2332': 'Mapleton Township',
+  '2341': 'Minto Town',
+  '2349': 'Wellington North Township',
+  '3001': 'North Dumfries Township',
+  '3006': 'Cambridge City',
+  '3012': 'Kitchener City',
+  '3016': 'Waterloo City',
+  '3018': 'Wilmot Township',
+  '3024': 'Wellesley Township',
+  '3029': 'Woolwich Township',
+
+  // Elgin, Middlesex and Oxford Counties
+  '3202': 'Norwich Township',
+  '3204': 'Tillsonburg Town',
+  '3211': 'South-west Oxford Township',
+  '3218': 'Ingersoll Town',
+  '3227': 'Zorra Township',
+  '3238': 'East Zorra-tavistock Township',
+  '3242': 'Woodstock City',
+  '3245': 'Blandford Blenheim Township',
+  '3401': 'Bayham Municipality',
+  '3408': 'Malahide Township',
+  '3411': 'Aylmer Town',
+  '3418': 'Central Elgin Municipality',
+  '3421': 'St Thomas City',
+  '3424': 'Southwold Township',
+  '3429': 'Dutton/Dunwich Municipality',
+  '3434': 'West Elgin Municipality',
+  '3902': 'Newbury Village',
+  '3906': 'Southwest Middlesex Municipality',
+  '3916': 'Strathroy-caradoc Municipality',
+  '3926': 'Thames Centre Municipality',
+  '3936': 'London City',
+  '3939': 'Middlesex Centre Municipality',
+  '3946': 'Adelaide Metcalfe Township',
+  '3954': 'North Middlesex Municipality',
+  '3958': 'Lucan Biddulph Township',
+
+  // Huron and Perth Counties
+  '3110': 'Perth East Township',
+  '3111': 'Stratford City',
+  '3116': 'St Marys Town',
+  '3120': 'Perth South Township',
+  '3130': 'West Perth Municipality',
+  '3140': 'North Perth Municipality',
+  '4010': 'South Huron Municipality',
+  '4020': 'Bluewater Municipality',
+  '4028': 'Goderich Town',
+  '4030': 'Central Huron Municipality',
+  '4040': 'Huron East Municipality',
+  '4046': 'Howick Township',
+  '4050': 'North Huron Township',
+  '4060': 'Morris-turnberry Municipality',
+  '4070': 'Ashfield-colborne-wawanosh Township',
+
+  // Bruce and Grey Counties
+  '4102': 'South Bruce Peninsula Town',
+  '4103': 'Arran-elderslie Municipality',
+  '4104': 'Brockton Municipality',
+  '4105': 'South Bruce Municipality',
+  '4107': 'Huron-kinloss Township',
+  '4108': 'Kincardine Municipality',
+  '4109': 'Northern Bruce Peninsula Municipality',
+  '4110': 'Saugeen Shores Town',
+  '4203': 'Georgian Bluffs Township',
+  '4204': 'Chatsworth Township',
+  '4205': 'West Grey Municipality',
+  '4207': 'Southgate Township',
+  '4208': 'Grey Highlands Municipality',
+  '4210': 'Meaford Municipality',
+  '4229': 'Hanover Town',
+  '4242': 'Blue Mountains Town',
+  '4259': 'Owen Sound City',
+
+  // Municipality of Chatham-Kent, Lambton County
+  '3650': 'Chatham-kent Municipality',
+  '3805': 'St Clair Township',
+  '3806': 'Dawn-euphemia Township',
+  '3815': 'Brooke-alvinston Municipality',
+  '3816': 'Enniskillen Township',
+  '3818': 'Oil Springs Village',
+  '3819': 'Petrolia Town',
+  '3829': 'Sarnia City',
+  '3831': 'Point Edward Village',
+  '3835': 'Plympton-wyoming Town',
+  '3841': 'Warwick Township',
+  '3845': 'Lambton Shores Municipality',
+
+  // Essex County
+  '3701': 'Peele Township',
+  '3706': 'Leamington Municipality',
+  '3711': 'Kingsville Town',
+  '3729': 'Amherstburg Town',
+  '3734': 'Lasalle Town',
+  '3739': 'Windsor City',
+  '3744': 'Tecumseh Town',
+  '3751': 'Lakeshore Town',
+  '3754': 'Essex Town',
+
+  // Territorial Districts of Nipissing and Parry Sound
+  '4801': 'South Algonquin Township',
+  '4803': 'Province Of Ontario',
+  '4816': 'Papineau-cameron Township',
+  '4819': 'Mattawan Township',
+  '4821': 'Mattawa Town',
+  '4822': 'Calvin Municipality',
+  '4826': 'Bonfield Township',
+  '4831': 'Chisholm Township',
+  '4834': 'East Ferris Municipality',
+  '4844': 'Corporation Of The City Of North Bay',
+  '4852': 'West Nipissing Municipality',
+  '4869': 'Temagami Municipality',
+  '4898': 'Province Of Ontario',
+  '4899': 'Province Of Ontario',
+  '4903': 'Seguin Township',
+  '4905': 'The Archipelago Township',
+  '4912': 'McMurrich/Monteith Township',
+  '4914': 'Perry Township',
+  '4918': 'Kearney Town',
+  '4919': 'Armour Township',
+  '4922': 'Burks Falls Village',
+  '4924': 'Ryerson Township',
+  '4928': 'McKellar Township',
+  '4931': 'McDougall Municipality',
+  '4932': 'Parry Sound Town',
+  '4936': 'Carling Township',
+  '4939': 'Whitestone Municipality',
+  '4944': 'Magnetawan Municipality',
+  '4948': 'Sundridge Village',
+  '4951': 'Joly Township',
+  '4954': 'Machar Township',
+  '4956': 'South River Village',
+  '4959': 'Powassan Municipality',
+  '4966': 'Callander Municipality',
+  '4971': 'Nipissing Township',
+  '4995': 'Province Of Ontario',
+  '4998': 'Province Of Ontario',
+  '4999': 'Province Of Ontario',
+
+  // Territorial Districts of Cochrane and Timiskaming
+  '5401': 'Coleman Township',
+  '5406': 'Latchford Town',
+  '5408': 'Cobalt Town',
+  '5414': 'Harris Township',
+  '5418': 'Temiskaming Shores City',
+  '5421': 'Hudson Township',
+  '5424': 'Kerns Township',
+  '5426': 'Harley Township',
+  '5429': 'Casey Township',
+  '5432': 'Brethour Township',
+  '5434': 'Hilliard Township',
+  '5436': 'Armstrong Township',
+  '5438': 'Thornloe Village',
+  '5442': 'James Township',
+  '5446': 'Charlton And Dack Municipality',
+  '5449': 'Evanturel Township',
+  '5452': 'Englehart Town',
+  '5454': 'Chamberlain Township',
+  '5456': 'Matachewan Township',
+  '5458': 'McGarry Township',
+  '5462': 'Larder Lake Township',
+  '5466': 'Gauthier Township',
+  '5468': 'Kirkland Lake Town',
+  '5480': 'Province Of Ontario',
+  '5490': 'Province Of Ontario',
+  '5499': 'Province Of Ontario',
+  '5602': 'Province Of Ontario',
+  '5614': 'Black River-matheson Township',
+  '5620': 'Province Of Ontario',
+  '5627': 'Timmins City',
+  '5630': 'Province Of Ontario',
+  '5631': 'Iroquois Falls Town',
+  '5639': 'Cochrane Town',
+  '5640': 'Province Of Ontario',
+  '5648': 'Smooth Rock Falls Town',
+  '5652': 'Fauquier-strickland Township',
+  '5656': 'Moonbeam Township',
+  '5665': 'Moosonee Town',
+  '5666': 'Kapuskasing Town',
+  '5670': 'Val Rita-harty Township',
+  '5673': 'Opasatika Township',
+  '5676': 'Hearst Town',
+  '5677': 'Mattice-val Cote Township',
+  '5699': 'Province Of Ontario',
+
+  // Regional Municipality of Sudbury and the Territorial Districts of Sudbury and Manitoulin
+  '5101': 'Tehkummah Township',
+  '5102': 'Province Of Ontario',
+  '5104': 'Central Manitoulin Municipality',
+  '5111': 'Assiginack Township',
+  '5119': 'Northeastern Manitoulin & The Islands',
+  '5121': 'Billings Township',
+  '5124': 'Gordon/Barrie Island Municipality',
+  '5126': 'Gore Bay Town',
+  '5128': 'Burpee And Mills Township',
+  '5134': 'Cockburn Island Township',
+  '5136': 'Killarney Municipality',
+  '5201': 'French River Municipality',
+  '5202': 'Province Of Ontario',
+  '5204': 'St. Charles Municipality',
+  '5208': 'Markstay-warren Municipality',
+  '5218': 'Sables - Spanish Rivers Township',
+  '5226': 'Espanola Town',
+  '5228': 'Baldwin Township',
+  '5231': 'Nairn And Hyman Township',
+  '5283': 'Province Of Ontario',
+  '5289': 'Province Of Ontario',
+  '5292': 'Chapleau Township',
+  '5293': 'Province Of Ontario',
+  '5295': 'Province Of Ontario',
+  '5297': 'Province Of Ontario',
+  '5298': 'Province Of Ontario',
+  '5299': 'Province Of Ontario',
+  '5307': 'Greater Sudbury City',
+
+  // Territorial District of Algoma
+  '5701': 'Jocelyn Township',
+  '5704': 'Hilton Township',
+  '5706': 'Hilton Beach Village',
+  '5708': 'St Joseph Township',
+  '5711': 'Laird Township',
+  '5714': 'Tarbutt Tarbutt Addl Township',
+  '5716': 'Johnson Township',
+  '5719': 'Plummer Additional Township',
+  '5721': 'Bruce Mines Town',
+  '5724': 'Huron Shores Municipality',
+  '5727': 'Province Of Ontario',
+  '5728': 'Thessalon Town',
+  '5738': 'Blind River Town',
+  '5739': 'Spanish Town',
+  '5740': 'North Shore Township',
+  '5741': 'Elliot Lake City',
+  '5751': 'MacDonald Meredith Et Al Township',
+  '5761': 'Sault Ste Marie City',
+  '5766': 'Prince Township',
+  '5776': 'Wawa Municipality',
+  '5779': 'Dubreuilville Township',
+  '5791': 'White River Township',
+  '5796': 'Hornepayne Township',
+  '5799': 'Province Of Ontario',
+
+  // Territorials District of Kenora, Rainy River and Thunder Bay
+  '5801': 'Neebing Municipality',
+  '5803': 'Province Of Ontario',
+  '5804': 'Thunder Bay City',
+  '5805': 'Province Of Ontario',
+  '5808': 'Oliver Paipoonge Municipality',
+  '5810': 'Province Of Ontario',
+  '5811': 'Province Of Ontario',
+  '5812': 'Gillies Township',
+  '5815': 'Province Of Ontario',
+  '5816': "O'connor Township",
+  '5819': 'Conmee Township',
+  '5828': 'Shuniah Municipality',
+  '5834': 'Dorion Township',
+  '5841': 'Red Rock Township',
+  '5844': 'Nipigon Township',
+  '5851': 'Schreiber Township',
+  '5854': 'Terrace Bay Township',
+  '5859': 'Marathon Town',
+  '5866': 'Manitouwadge Township',
+  '5876': 'Greenstone Municipality',
+  '5883': 'Province Of Ontario',
+  '5884': 'Province Of Ontario',
+  '5885': 'Province Of Ontario',
+  '5895': 'Province Of Ontario',
+  '5897': 'Province Of Ontario',
+  '5898': 'Province Of Ontario',
+  '5899': 'Province Of Ontario',
+  '5901': 'Atikokan Town',
+  '5902': 'Province Of Ontario',
+  '5903': 'Province Of Ontario',
+  '5911': 'Alberton Township',
+  '5912': 'Fort Frances Town',
+  '5916': 'La Vallee Township',
+  '5919': 'Emo Township',
+  '5924': 'Chapple Township',
+  '5931': 'Morley Township',
+  '5934': 'Dawson Township',
+  '5942': 'Rainy River Town',
+  '5946': 'Lake Of The Woods Township',
+  '5973': 'Province Of Ontario',
+  '5974': 'Province Of Ontario',
+  '5998': 'Province Of Ontario',
+  '5999': 'Province Of Ontario',
+  '6001': 'Ignace Township',
+  '6007': 'Province Of Ontario',
+  '6008': 'Sioux Narrows-nestor Falls Twp',
+  '6016': 'Kenora City',
+  '6021': 'Machin Municipality',
+  '6026': 'Dryden City',
+  '6034': 'Sioux Lookout Municipality',
+  '6041': 'Red Lake Municipality',
+  '6042': 'Ear Falls Township',
+  '6049': 'Pickle Lake Township',
+  '6060': 'Province Of Ontario',
+  '6088': 'Province Of Ontario',
+  '6089': 'Province Of Ontario',
+  '6091': 'Province Of Ontario',
+  '6093': 'Province Of Ontario',
+  '6095': 'Province Of Ontario',
+  '6096': 'Province Of Ontario',
+  '6097': 'Province Of Ontario',
+  '6098': 'Province Of Ontario',
+  '6099': 'Province Of Ontario'
+})

package/rollNumbers/utilities.d.ts

@@ -0,0 +1,12 @@
+export declare function validateRollNumber(rollNumber: string): boolean;
+export interface ParsedRollNumber {
+    county?: string;
+    municipality?: string;
+    mapArea: string;
+    mapDivision: string;
+    mapSubdivision: string;
+    parcel: string;
+    parcelSub: string;
+    primarySubordinate: string;
+}
+export declare function parseRollNumber(rollNumber: string): ParsedRollNumber;

package/rollNumbers/utilities.js

@@ -0,0 +1,24 @@
+import { rollNumberMunicipalities } from './lookups.js';
+export function validateRollNumber(rollNumber) {
+    return (/^\d{15}$/.test(rollNumber) ||
+        (/^\d{19}$/.test(rollNumber) &&
+            Object.keys(rollNumberMunicipalities).includes(rollNumber.slice(0, 4))));
+}
+export function parseRollNumber(rollNumber) {
+    if (!validateRollNumber(rollNumber)) {
+        throw new Error(`Invalid roll number: ${rollNumber}`);
+    }
+    const is19Digit = rollNumber.length === 19;
+    const countyMunicipalityDigits = is19Digit ? rollNumber.slice(0, 4) : '';
+    const shortRollNumber = is19Digit ? rollNumber.slice(4) : rollNumber;
+    return {
+        county: is19Digit ? countyMunicipalityDigits.slice(0, 2) : undefined,
+        municipality: is19Digit ? countyMunicipalityDigits.slice(2, 4) : undefined,
+        mapArea: shortRollNumber.slice(0, 2),
+        mapDivision: shortRollNumber.slice(2, 3),
+        mapSubdivision: shortRollNumber.slice(3, 6),
+        parcel: shortRollNumber.slice(6, 9),
+        parcelSub: shortRollNumber.slice(9, 11),
+        primarySubordinate: shortRollNumber.slice(11, 15)
+    };
+}

package/rollNumbers/utilities.ts

@@ -0,0 +1,57 @@
+// eslint-disable-next-line @eslint-community/eslint-comments/disable-enable-pair
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+
+import { rollNumberMunicipalities } from './lookups.js'
+
+/**
+ * Validates a roll number.
+ * @param rollNumber - The roll number to validate
+ * @returns True if the roll number is valid, false otherwise
+ */
+export function validateRollNumber(rollNumber: string): boolean {
+  return (
+    /^\d{15}$/.test(rollNumber) ||
+    (/^\d{19}$/.test(rollNumber) &&
+      Object.keys(rollNumberMunicipalities).includes(rollNumber.slice(0, 4)))
+  )
+}
+
+export interface ParsedRollNumber {
+  county?: string
+  municipality?: string
+  mapArea: string
+  mapDivision: string
+  mapSubdivision: string
+  parcel: string
+  parcelSub: string
+  primarySubordinate: string
+}
+
+/**
+ * Parses a roll number into its component parts.
+ * @param rollNumber - The roll number to parse
+ * @returns An object containing the parsed roll number components
+ */
+export function parseRollNumber(rollNumber: string): ParsedRollNumber {
+  if (!validateRollNumber(rollNumber)) {
+    throw new Error(`Invalid roll number: ${rollNumber}`)
+  }
+
+  const is19Digit = rollNumber.length === 19
+
+  const countyMunicipalityDigits = is19Digit ? rollNumber.slice(0, 4) : ''
+  const shortRollNumber = is19Digit ? rollNumber.slice(4) : rollNumber
+
+  return {
+    county: is19Digit ? countyMunicipalityDigits.slice(0, 2) : undefined,
+    municipality: is19Digit ? countyMunicipalityDigits.slice(2, 4) : undefined,
+
+    mapArea: shortRollNumber.slice(0, 2),
+    mapDivision: shortRollNumber.slice(2, 3),
+    mapSubdivision: shortRollNumber.slice(3, 6),
+
+    parcel: shortRollNumber.slice(6, 9),
+    parcelSub: shortRollNumber.slice(9, 11),
+    primarySubordinate: shortRollNumber.slice(11, 15)
+  }
+}