Skip to content

feat(municipalities): add getCodeByMunicipalityName - #610

Merged
hyanmandian merged 6 commits into
claude/license-plate-formatfrom
claude/municipality-code-by-name
Sep 29, 2026
Merged

hyanmandian merged 6 commits into
claude/license-plate-formatfrom
claude/municipality-code-by-name

Conversation

@hyanmandian

Copy link
Copy Markdown
Member

What does this PR do?

Adds getCodeByMunicipalityName, the offline, synchronous counterpart of the Python library's get_code_by_municipality_name: the 7-digit IBGE code of a municipality from its name and state code.

getCodeByMunicipalityName({ municipalityName: "São Paulo", stateCode: "SP" });   // "3550308"
getCodeByMunicipalityName({ municipalityName: "sao paulo", stateCode: "sp" });   // "3550308"
getCodeByMunicipalityName({ municipalityName: "Não Existe", stateCode: "SP" }); // null
  • Both fields are required, so they come in one params object, as isValidIe's { value, stateCode } does. The type is exported as GetCodeByMunicipalityNameParams.
  • The match ignores accents, cedilla and casing, and the state code is case-insensitive.
  • An unknown state, an unknown name, or a missing or malformed argument returns null.
  • The deprecated getMunicipality name query now delegates to it, and its deprecation note points here. getMunicipality keeps its uf field for compatibility.
  • Docs (EN/PT), migration guides, context7.json and the getting-started bundle size are updated.

Stacked on the license-plate PR.

Checklist

  • My commit/PR title follows Conventional Commits.
  • I added or updated tests covering this change (npm test).
  • I updated the documentation in both docs/utilities.md and docs/pt-br/utilities.md.
  • npm run check passes locally (format, lint, types).
  • I ran npm run build:llms.
  • This change does not introduce a breaking change.
  • This change does not add any runtime dependency.

Additional context

It uses the municipality table already shipped in the package, so there is no new data. getMunicipality behaves as before.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RLkm9YrtAifc6XCLFVEsdH


Generated by Claude Code

@vercel

vercel Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
brazilian-utils Ready Ready Preview Sep 29, 2026 4:30am UTC

@coderabbitai

coderabbitai Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 52484957-7f5c-4061-8f6a-2874422c2c95

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@pkg-pr-new

pkg-pr-new Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@brazilian-utils/brazilian-utils@610

commit: af4c390

@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Tree-shaking report

✅ No size regression. 1 grew, 1 new out of 195 exports.

Base Head Δ
Pre-existing exports, all imported 1845.2 KB 1845.3 KB (gzip 327.3 KB) +53 B (+0.0%)
Full import 1845.2 KB 1845.3 KB (gzip 327.3 KB) +56 B (+0.0%)
Exports 194 195 +1

What changed (2)

Export Base Head Δ gzip
🆕 getCodeByMunicipalityName — 153.6 KB new 49.4 KB
🟡 getMunicipality 154.1 KB 154.2 KB +57 B (+0.0%) 49.8 KB
All exports (195)
Export Base Head Δ gzip
⚪ GetAddressInfoByCepError 112 B 112 B 0 B 124 B
⚪ GetAddressInfoByCepNotFoundError 205 B 205 B 0 B 145 B
⚪ GetAddressInfoByCepServiceError 204 B 204 B 0 B 143 B
⚪ GetAddressInfoByCepValidationError 203 B 203 B 0 B 144 B
⚪ GetCepInfoByAddressError 112 B 112 B 0 B 124 B
⚪ GetCepInfoByAddressNotFoundError 205 B 205 B 0 B 145 B
⚪ GetCepInfoByAddressValidationError 203 B 203 B 0 B 144 B
⚪ addBusinessDays 9.5 KB 9.5 KB 0 B 3.3 KB
⚪ capitalize 2.4 KB 2.4 KB 0 B 1.2 KB
⚪ convertCurrencyToWords 2.0 KB 2.0 KB 0 B 1.0 KB
⚪ convertDateToWords 2.4 KB 2.4 KB 0 B 1.2 KB
⚪ convertLicensePlateToMercosul 573 B 573 B 0 B 387 B
⚪ convertNumberToWords 1.6 KB 1.6 KB 0 B 819 B
⚪ differenceInBusinessDays 9.3 KB 9.3 KB 0 B 3.3 KB
⚪ formatBoleto 649 B 649 B 0 B 402 B
⚪ formatCEP 470 B 470 B 0 B 334 B
⚪ formatCNPJ 620 B 620 B 0 B 420 B
⚪ formatCPF 521 B 521 B 0 B 365 B
⚪ formatCaepf 487 B 487 B 0 B 344 B
⚪ formatCei 484 B 484 B 0 B 343 B
⚪ formatCep 470 B 470 B 0 B 334 B
⚪ formatCertidao 513 B 513 B 0 B 350 B
⚪ formatCest 474 B 474 B 0 B 337 B
⚪ formatCid10 459 B 459 B 0 B 330 B
⚪ formatCnae 474 B 474 B 0 B 340 B
⚪ formatCnh 517 B 517 B 0 B 361 B
⚪ formatCno 488 B 488 B 0 B 344 B
⚪ formatCnpj 620 B 620 B 0 B 420 B
⚪ formatCns 483 B 483 B 0 B 340 B
⚪ formatCpf 521 B 521 B 0 B 365 B
⚪ formatCurrency 985 B 985 B 0 B 592 B
⚪ formatIban 267 B 267 B 0 B 228 B
⚪ formatIsbn 27.0 KB 27.0 KB 0 B 6.2 KB
⚪ formatLegalNature 470 B 470 B 0 B 337 B
⚪ formatLicensePlate 361 B 361 B 0 B 270 B
⚪ formatNbs 462 B 462 B 0 B 334 B
⚪ formatNcm 475 B 475 B 0 B 338 B
⚪ formatNfeKey 601 B 601 B 0 B 383 B
⚪ formatPassport 187 B 187 B 0 B 174 B
⚪ formatPhone 2.6 KB 2.6 KB 0 B 1.2 KB
⚪ formatPis 521 B 521 B 0 B 365 B
⚪ formatProcessoJuridico 490 B 490 B 0 B 344 B
⚪ formatSuframa 476 B 476 B 0 B 338 B
⚪ formatVoterId 523 B 523 B 0 B 365 B
⚪ generateBoleto 1.4 KB 1.4 KB 0 B 779 B
⚪ generateCNPJ 843 B 843 B 0 B 523 B
⚪ generateCPF 702 B 702 B 0 B 458 B
⚪ generateCep 130 B 130 B 0 B 136 B
⚪ generateCnh 565 B 565 B 0 B 343 B
⚪ generateCnpj 843 B 843 B 0 B 523 B
⚪ generateCpf 702 B 702 B 0 B 458 B
⚪ generateLegalNature 5.0 KB 5.0 KB 0 B 1.6 KB
⚪ generateLicensePlate 266 B 266 B 0 B 227 B
⚪ generatePassport 226 B 226 B 0 B 191 B
⚪ generatePhone 670 B 670 B 0 B 419 B
⚪ generatePis 357 B 357 B 0 B 272 B
⚪ generatePixPayload 4.5 KB 4.5 KB 0 B 2.0 KB
⚪ generateProcessoJuridico 821 B 821 B 0 B 523 B
⚪ generateRenavam 378 B 378 B 0 B 284 B
⚪ generateSuframa 451 B 451 B 0 B 335 B
⚪ generateVoterId 926 B 926 B 0 B 587 B
⚪ getAddressInfoByCep 3.9 KB 3.9 KB 0 B 1.7 KB
⚪ getAreaCodeByMunicipalityCode 165.0 KB 165.0 KB 0 B 52.2 KB
⚪ getAreaCodeInfo 3.1 KB 3.1 KB 0 B 989 B
⚪ getAreaCodesByState 814 B 814 B 0 B 463 B
⚪ getBankByCode 37.8 KB 37.8 KB 0 B 9.2 KB
⚪ getBankByIspb 37.8 KB 37.8 KB 0 B 9.2 KB
⚪ getBanks 37.6 KB 37.6 KB 0 B 9.0 KB
⚪ getBoletoInfo 2.4 KB 2.4 KB 0 B 1.2 KB
⚪ getCbo 107.6 KB 107.6 KB 0 B 24.8 KB
⚪ getCepInfoByAddress 2.0 KB 2.0 KB 0 B 1.0 KB
⚪ getCertidaoInfo 1.0 KB 1.0 KB 0 B 594 B
⚪ getCest 111.6 KB 111.6 KB 0 B 24.1 KB
⚪ getCfop 66.8 KB 66.8 KB 0 B 5.3 KB
⚪ getCid10 988.3 KB 988.3 KB 0 B 123.6 KB
⚪ getCities 153.5 KB 153.5 KB 0 B 49.3 KB
⚪ getClassTrib 50.0 KB 50.0 KB 0 B 9.0 KB
⚪ getCnae 86.6 KB 86.6 KB 0 B 18.0 KB
⚪ getCnpjInfo 964 B 964 B 0 B 542 B
🆕 getCodeByMunicipalityName — 153.6 KB new 49.4 KB
⚪ getCpfInfo 994 B 994 B 0 B 614 B
⚪ getCstIbsCbs 967 B 967 B 0 B 534 B
⚪ getFormatLicensePlate 361 B 361 B 0 B 268 B
⚪ getGtinInfo 821 B 821 B 0 B 558 B
⚪ getHolidays 8.4 KB 8.4 KB 0 B 2.9 KB
⚪ getIbanInfo 752 B 752 B 0 B 492 B
⚪ getIsbnInfo 26.9 KB 26.9 KB 0 B 6.1 KB
⚪ getLegalNature 5.6 KB 5.6 KB 0 B 1.8 KB
⚪ getLegalNatures 5.1 KB 5.1 KB 0 B 1.6 KB
⚪ getLegalNaturesByCategory 5.6 KB 5.6 KB 0 B 1.9 KB
⚪ getMunicipalities 153.7 KB 153.7 KB 0 B 49.5 KB
⚪ getMunicipalitiesByAreaCode 167.8 KB 167.8 KB 0 B 52.8 KB
🟡 getMunicipality 154.1 KB 154.2 KB +57 B (+0.0%) 49.8 KB
⚪ getMunicipalityByCode 153.8 KB 153.8 KB 0 B 49.5 KB
⚪ getNbs 75.6 KB 75.6 KB 0 B 11.6 KB
⚪ getNfeKeyInfo 2.2 KB 2.2 KB 0 B 1.2 KB
⚪ getNfseKeyInfo 2.4 KB 2.4 KB 0 B 1.2 KB
⚪ getPixKeyInfo 2.5 KB 2.5 KB 0 B 1.2 KB
⚪ getPixPayloadInfo 4.6 KB 4.6 KB 0 B 2.1 KB
⚪ getRegions 255 B 255 B 0 B 165 B
⚪ getServiceItem 26.1 KB 26.1 KB 0 B 8.1 KB
⚪ getStateByCep 3.6 KB 3.6 KB 0 B 1.0 KB
⚪ getStateByIbgeCode 2.4 KB 2.4 KB 0 B 700 B
⚪ getStateCapital 959 B 959 B 0 B 638 B
⚪ getStateCodeByName 2.3 KB 2.3 KB 0 B 649 B
⚪ getStateNameByCode 2.2 KB 2.2 KB 0 B 594 B
⚪ getStates 2.2 KB 2.2 KB 0 B 539 B
⚪ getStatesByRegion 2.3 KB 2.3 KB 0 B 602 B
⚪ getTimezoneByState 759 B 759 B 0 B 344 B
⚪ isBusinessDay 8.8 KB 8.8 KB 0 B 3.1 KB
⚪ isHoliday 8.7 KB 8.7 KB 0 B 3.0 KB
⚪ isValidBankAccount 5.1 KB 5.1 KB 0 B 1.9 KB
⚪ isValidBoleto 1.6 KB 1.6 KB 0 B 892 B
⚪ isValidCEP 163 B 163 B 0 B 163 B
⚪ isValidCNPJ 796 B 796 B 0 B 447 B
⚪ isValidCPF 500 B 500 B 0 B 334 B
⚪ isValidCaepf 782 B 782 B 0 B 479 B
⚪ isValidCbo 6.7 KB 6.7 KB 0 B 1.7 KB
⚪ isValidCei 714 B 714 B 0 B 472 B
⚪ isValidCep 163 B 163 B 0 B 163 B
⚪ isValidCertidao 758 B 758 B 0 B 462 B
⚪ isValidCest 3.6 KB 3.6 KB 0 B 848 B
⚪ isValidCfop 1.9 KB 1.9 KB 0 B 689 B
⚪ isValidCid10 26.2 KB 26.2 KB 0 B 6.8 KB
⚪ isValidClassTrib 1.8 KB 1.8 KB 0 B 639 B
⚪ isValidCnae 4.6 KB 4.6 KB 0 B 1.9 KB
⚪ isValidCnh 610 B 610 B 0 B 370 B
⚪ isValidCno 718 B 718 B 0 B 474 B
⚪ isValidCnpj 796 B 796 B 0 B 447 B
⚪ isValidCns 746 B 746 B 0 B 475 B
⚪ isValidCpf 500 B 500 B 0 B 334 B
⚪ isValidCreditCard 555 B 555 B 0 B 389 B
⚪ isValidCsosn 330 B 330 B 0 B 262 B
⚪ isValidCst 995 B 995 B 0 B 569 B
⚪ isValidCstIbsCbs 894 B 894 B 0 B 505 B
⚪ isValidEmail 171 B 171 B 0 B 157 B
⚪ isValidGtin 432 B 432 B 0 B 316 B
⚪ isValidIE 5.2 KB 5.2 KB 0 B 1.8 KB
⚪ isValidIban 531 B 531 B 0 B 376 B
⚪ isValidIe 5.2 KB 5.2 KB 0 B 1.8 KB
⚪ isValidIsbn 413 B 413 B 0 B 325 B
⚪ isValidLandlinePhone 717 B 717 B 0 B 463 B
⚪ isValidLegalNature 739 B 739 B 0 B 450 B
⚪ isValidLicensePlate 313 B 313 B 0 B 248 B
⚪ isValidMobilePhone 758 B 758 B 0 B 496 B
⚪ isValidNbs 3.5 KB 3.5 KB 0 B 1.3 KB
⚪ isValidNcm 29.6 KB 29.6 KB 0 B 9.0 KB
⚪ isValidNfeKey 1.6 KB 1.6 KB 0 B 954 B
⚪ isValidNfseKey 2.1 KB 2.1 KB 0 B 1.1 KB
⚪ isValidPIS 418 B 418 B 0 B 316 B
⚪ isValidPassport 197 B 197 B 0 B 186 B
⚪ isValidPhone 1.8 KB 1.8 KB 0 B 909 B
⚪ isValidPis 418 B 418 B 0 B 316 B
⚪ isValidPixKey 2.3 KB 2.3 KB 0 B 1.1 KB
⚪ isValidPixPayload 4.2 KB 4.2 KB 0 B 1.9 KB
⚪ isValidProcessoJuridico 699 B 699 B 0 B 429 B
⚪ isValidRegistroProfissional 1.3 KB 1.3 KB 0 B 758 B
⚪ isValidRenavam 516 B 516 B 0 B 356 B
⚪ isValidServiceItem 1.1 KB 1.1 KB 0 B 554 B
⚪ isValidServicePhone 706 B 706 B 0 B 372 B
⚪ isValidSuframa 590 B 590 B 0 B 411 B
⚪ isValidVin 848 B 848 B 0 B 572 B
⚪ isValidVoterId 706 B 706 B 0 B 427 B
⚪ parseBoleto 247 B 247 B 0 B 215 B
⚪ parseCaepf 199 B 199 B 0 B 183 B
⚪ parseCbo 198 B 198 B 0 B 182 B
⚪ parseCei 199 B 199 B 0 B 183 B
⚪ parseCep 198 B 198 B 0 B 182 B
⚪ parseCertidao 199 B 199 B 0 B 183 B
⚪ parseCest 198 B 198 B 0 B 182 B
⚪ parseCfop 198 B 198 B 0 B 182 B
⚪ parseCid10 177 B 177 B 0 B 170 B
⚪ parseCnae 198 B 198 B 0 B 182 B
⚪ parseCnh 199 B 199 B 0 B 183 B
⚪ parseCno 199 B 199 B 0 B 183 B
⚪ parseCnpj 298 B 298 B 0 B 240 B
⚪ parseCns 199 B 199 B 0 B 184 B
⚪ parseCpf 199 B 199 B 0 B 183 B
⚪ parseCurrency 610 B 610 B 0 B 409 B
⚪ parseIban 227 B 227 B 0 B 202 B
⚪ parseIsbn 150 B 150 B 0 B 150 B
⚪ parseLegalNature 198 B 198 B 0 B 182 B
⚪ parseLicensePlate 177 B 177 B 0 B 170 B
⚪ parseNcm 198 B 198 B 0 B 182 B
⚪ parseNfeKey 412 B 412 B 0 B 312 B
⚪ parseNfseKey 253 B 253 B 0 B 219 B
⚪ parsePassport 177 B 177 B 0 B 169 B
⚪ parsePhone 370 B 370 B 0 B 281 B
⚪ parsePis 199 B 199 B 0 B 183 B
⚪ parseProcessoJuridico 199 B 199 B 0 B 182 B
⚪ parseSuframa 198 B 198 B 0 B 181 B
⚪ parseVoterId 199 B 199 B 0 B 183 B
⚪ removeAccents 99 B 99 B 0 B 119 B
⚪ subBusinessDays 9.6 KB 9.6 KB 0 B 3.4 KB
⚪ toStandardSchema 284 B 284 B 0 B 233 B
How this is measured

Every export is imported alone into an esbuild consumer bundle (minified, tree-shaken) built from the head and from the base of this pull request; the sizes are the resulting bundles, gzip is their gzipped size. 🔴 marks a regression: a pre-existing export that grew more than 20% and more than 256 B, or the bundle importing every pre-existing export growing more than 5%. 🟡 is growth under the threshold, 🟢 a decrease, ⚪ no change, 🆕 an export that does not exist on the base (never a regression), 🗑️ an export that was removed. An intentional increase is accepted with the tree-shaking: accepted label.

@codecov

codecov Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (claude/license-plate-format@bcb55ce). Learn more about missing BASE report.

Additional details and impacted files
@@                       Coverage Diff                       @@
##             claude/license-plate-format      #610   +/-   ##
===============================================================
  Coverage                               ?   100.00%           
===============================================================
  Files                                  ?       238           
  Lines                                  ?      2429           
  Branches                               ?       713           
===============================================================
  Hits                                   ?      2429           
  Misses                                 ?         0           
  Partials                               ?         0           
Flag Coverage Δ
node 100.00% <100.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

The IBGE code of a municipality from its name and state code, accents, cedilla and casing
ignored: the offline, synchronous counterpart of the Python library's
get_code_by_municipality_name. The deprecated getMunicipality name query now calls it, and its
deprecation points to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RLkm9YrtAifc6XCLFVEsdH
…yName as { stateCode }

The second argument is now an options object, GetCodeByMunicipalityNameOptions, exported with
the function. A missing or malformed options object returns null.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RLkm9YrtAifc6XCLFVEsdH
…tate code in one object

getCodeByMunicipalityName({ municipalityName, stateCode }): both fields are
required, so one params object names them at the call site, as isValidIe's
{ value, stateCode } and getMunicipality's { municipalityName, uf } do.
Also list the new type in the public-types test and point the migration
guide and context7 at the new function for a name lookup.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RLkm9YrtAifc6XCLFVEsdH
@hyanmandian
hyanmandian merged commit 1f82b56 into main Sep 29, 2026
36 of 51 checks passed

This branch was successfully deployed

1 active deployment
Preview — af4c3908 Deployed Sep 29, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants