{"_id":"@amondar-libs/js-us-flow","_rev":"6-e1f919fc0d35d85e88a3024827c3bc50","name":"@amondar-libs/js-us-flow","dist-tags":{"latest":"1.0.6"},"versions":{"1.0.0":{"name":"@amondar-libs/js-us-flow","version":"1.0.0","keywords":["us-states","state-flow","geography","usa"],"author":{"url":"Amondar","name":"Oleg Sereda"},"license":"MIT","_id":"@amondar-libs/js-us-flow@1.0.0","maintainers":[{"name":"amondar-libs","email":"zaxodu11@gmail.com"}],"dist":{"shasum":"15563b7aee6dd413da6735da535ba4e2243aa3e4","tarball":"https://registry.npmjs.org/@amondar-libs/js-us-flow/-/js-us-flow-1.0.0.tgz","fileCount":15,"integrity":"sha512-sti2iVQAnFwLjPJvrVcue99cBSpYeBffuP4SwxPuczMjuXMc/hgjTpgpPX+Ui4vp2pgZKSDGtvVB+WKVEBb2kQ==","signatures":[{"sig":"MEUCICNqGYW1nEa6anN7iNf8b3+7W92QjdIl1HWfiO7MjHvQAiEAhd0Kwf0ZX8h8bGzMEV165thPxxHpp1zrLNPbofUUj7g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27775},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"942327264c401ed5134be8c097134a335b57ebf5","scripts":{"test":"NODE_OPTIONS='--loader ts-node/esm --no-warnings' node tests/flow.test.ts","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"amondar-libs","email":"zaxodu11@gmail.com"},"_npmVersion":"11.9.0","description":"A utility for working with US States (abbreviations, names, regex patterns). TypeScript/ESM implementation of php-us-flow.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"reflect-metadata":"^0.2.2"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^6.0.2","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/js-us-flow_1.0.0_1776305930735_0.8804444984658795","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@amondar-libs/js-us-flow","version":"1.0.2","keywords":["us-states","state-flow","geography","usa"],"author":{"url":"Amondar","name":"Oleg Sereda"},"license":"MIT","_id":"@amondar-libs/js-us-flow@1.0.2","maintainers":[{"name":"amondar-libs","email":"zaxodu11@gmail.com"}],"dist":{"shasum":"0d5ea46215eb62a34a5bc3e8d9a825f25c712352","tarball":"https://registry.npmjs.org/@amondar-libs/js-us-flow/-/js-us-flow-1.0.2.tgz","fileCount":15,"integrity":"sha512-ymiKRU5IUjl1O8vB4brn24F+WG8OiU+l/sVT7hzXz2vo0Xn1e5+NtnVHcN3UGj1WNjHWNuKbJzK4gOgqXGITpA==","signatures":[{"sig":"MEUCIEMRIg6bp/UeekHLUH+rJvNgoLZf8KgK4DwlmX39CNyuAiEA4l+FWYD+spAJjLRySD6MUCwQxh2nVS9tgY0SJloMKA8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27728},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d26d1a8c34f104190bf6bcc342353c568768e4ec","scripts":{"test":"NODE_OPTIONS='--loader ts-node/esm --no-warnings' node tests/flow.test.ts","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"amondar-libs","email":"zaxodu11@gmail.com"},"_npmVersion":"11.9.0","description":"A utility for working with US States (abbreviations, names, regex patterns). TypeScript/ESM implementation of php-us-flow.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"reflect-metadata":"^0.2.2"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^6.0.2","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/js-us-flow_1.0.2_1776306515141_0.40318404685882947","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@amondar-libs/js-us-flow","version":"1.0.3","keywords":["us-states","state-flow","geography","usa"],"author":{"url":"Amondar","name":"Oleg Sereda"},"license":"MIT","_id":"@amondar-libs/js-us-flow@1.0.3","maintainers":[{"name":"amondar-libs","email":"zaxodu11@gmail.com"}],"dist":{"shasum":"014453fc9d1ba0686698fa1ce006d91295d3c959","tarball":"https://registry.npmjs.org/@amondar-libs/js-us-flow/-/js-us-flow-1.0.3.tgz","fileCount":15,"integrity":"sha512-LDT2tinGwfoju5VFKwwk/faLKri5bgmhujEwmQthL9xR22/uFcxF8kLHrPmT5pm59bBd7AZDyuRSnSg736kg0Q==","signatures":[{"sig":"MEQCIHWy9EzW+kCaPnKyWxOLEXyqbXEJwtT1mh7d7BiVtQasAiB8GTi/3GDP8mDdLhgJgn1UnVGbBZQpvxOLU+AhcIHpgA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28163},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d58dbe29464d1b44a1818508e6267658146bb3f3","scripts":{"test":"NODE_OPTIONS='--loader ts-node/esm --no-warnings' node tests/flow.test.ts","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"amondar-libs","email":"zaxodu11@gmail.com"},"_npmVersion":"11.9.0","description":"A utility for working with US States (abbreviations, names, regex patterns). TypeScript/ESM implementation of php-us-flow.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"reflect-metadata":"^0.2.2"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^6.0.2","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/js-us-flow_1.0.3_1776306715775_0.8666130320781882","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@amondar-libs/js-us-flow","version":"1.0.4","keywords":["us-states","state-flow","geography","usa"],"author":{"url":"Amondar","name":"Oleg Sereda"},"license":"MIT","_id":"@amondar-libs/js-us-flow@1.0.4","maintainers":[{"name":"amondar-libs","email":"zaxodu11@gmail.com"}],"dist":{"shasum":"cff16db8a32c6409434f8f4262aec7fb54482e58","tarball":"https://registry.npmjs.org/@amondar-libs/js-us-flow/-/js-us-flow-1.0.4.tgz","fileCount":15,"integrity":"sha512-jEbB4YontniIXuA7gm0jaUwkuOJTUv6qExawcjGRJXu6vEOchXl33p2OwSHs5qYaVNuedwq5pRI9vTjUE/VqIg==","signatures":[{"sig":"MEYCIQC6FLu2Wwo2cPcThugnOfZ0K8escwOxPOVxKC6DIB4qnQIhAJbus2rDOWUfM1TXvJaOPGDuL/FClGwz47Uzn/3QAcSp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28163},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d58dbe29464d1b44a1818508e6267658146bb3f3","scripts":{"test":"NODE_OPTIONS='--loader ts-node/esm --no-warnings' node tests/flow.test.ts","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"amondar-libs","email":"zaxodu11@gmail.com"},"_npmVersion":"11.9.0","description":"A utility for working with US States (abbreviations, names, regex patterns). TypeScript/ESM implementation of php-us-flow.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"reflect-metadata":"^0.2.2"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^6.0.2","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/js-us-flow_1.0.4_1778527590092_0.055859851478333056","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@amondar-libs/js-us-flow","version":"1.0.5","keywords":["us-states","state-flow","geography","usa"],"author":{"url":"Amondar","name":"Oleg Sereda"},"license":"MIT","_id":"@amondar-libs/js-us-flow@1.0.5","maintainers":[{"name":"amondar-libs","email":"zaxodu11@gmail.com"}],"dist":{"shasum":"34f1a8bc865f9e6705b746aec6820b42b492a948","tarball":"https://registry.npmjs.org/@amondar-libs/js-us-flow/-/js-us-flow-1.0.5.tgz","fileCount":15,"integrity":"sha512-1s4eIfkTNd77I7OCLO4Y4s+IhvZwqn1RnH5/F6EtSYHQO/HjmCWj3zM7jtZLzeP0UmWPYANCXqx8SCtAAL52JA==","signatures":[{"sig":"MEUCIBAnN0Z9gCA/nlGAv6cgLiZ6v++SzxCfclsDVn52NuwJAiEAx8BNqWPkVxYBs9gMqt+fNhfuvXWqHrSK6c6BSzEuUnQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28430},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"253937484f03325fbfbbddd9c6661cea5c05599a","scripts":{"test":"NODE_OPTIONS='--loader ts-node/esm --no-warnings' node tests/flow.test.ts","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"amondar-libs","email":"zaxodu11@gmail.com"},"_npmVersion":"11.9.0","description":"A utility for working with US States (abbreviations, names, regex patterns). TypeScript/ESM implementation of php-us-flow.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"reflect-metadata":"^0.2.2"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^6.0.2","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/js-us-flow_1.0.5_1778541160801_0.5131898184843333","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"name":"@amondar-libs/js-us-flow","version":"1.0.6","description":"A utility for working with US States (abbreviations, names, regex patterns). TypeScript/ESM implementation of php-us-flow.","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"test":"NODE_OPTIONS='--loader ts-node/esm --no-warnings' node tests/flow.test.ts","build":"tsc","prepublishOnly":"npm run build"},"keywords":["us-states","state-flow","geography","usa"],"author":{"name":"Oleg Sereda","url":"Amondar"},"license":"MIT","type":"module","devDependencies":{"@types/node":"^25.6.0","ts-node":"^10.9.2","typescript":"^6.0.2"},"dependencies":{"reflect-metadata":"^0.2.2"},"gitHead":"932a5d1df5d125515b89ca4c0705b87e008d2f08","_id":"@amondar-libs/js-us-flow@1.0.6","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-AeVvGWXNEKyKcSxJp/9FOeJLTq+emhzE8uLlL6Ea8WrFN9p+gnNTHwx1XhGoFdu9GoNjMqvVI0i1xaAm7axGuA==","shasum":"23e21a4f3792839eb55cd0f590a39f98c56f1091","tarball":"https://registry.npmjs.org/@amondar-libs/js-us-flow/-/js-us-flow-1.0.6.tgz","fileCount":15,"unpackedSize":28481,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDlT6um+68CmZtgLigUfLGJnJGYEU7CabKevsHucbXyVAiEA6E9+CaAQQ/+/jgP9YAiTMJR2Ctt+scLJX/IUazG6jQU="}]},"_npmUser":{"name":"amondar-libs","email":"zaxodu11@gmail.com"},"directories":{},"maintainers":[{"name":"amondar-libs","email":"zaxodu11@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/js-us-flow_1.0.6_1778541329803_0.009768931429713357"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-16T02:18:50.620Z","modified":"2026-05-11T23:15:30.115Z","1.0.0":"2026-04-16T02:18:50.902Z","1.0.2":"2026-04-16T02:28:35.289Z","1.0.3":"2026-04-16T02:31:55.941Z","1.0.4":"2026-05-11T19:26:30.241Z","1.0.5":"2026-05-11T23:12:41.011Z","1.0.6":"2026-05-11T23:15:29.984Z"},"author":{"name":"Oleg Sereda","url":"Amondar"},"license":"MIT","keywords":["us-states","state-flow","geography","usa"],"description":"A utility for working with US States (abbreviations, names, regex patterns). TypeScript/ESM implementation of php-us-flow.","maintainers":[{"name":"amondar-libs","email":"zaxodu11@gmail.com"}],"readme":"# amondar-libs/js-state-flow\n\nA lightweight TypeScript package for working with U.S. state codes and names.\n\nIt provides:\n- Fast in-memory lookups for state code/name conversions\n- Prebuilt regex fragments for validation/parsing\n- Support for custom vocabularies via plain objects or enums\n\n## Requirements\n- Node.js `^18.x` or higher (ESM support)\n\n## Installation\n```bash\nnpm install @amondar-libs/js-us-flow\n```\n\n## Quick Start\n```typescript\nimport { StateFlow } from '@amondar-libs/js-us-flow';\n\nStateFlow.getAbbreviation('New York');   // \"NY\"\nStateFlow.getName('ny');          // \"New York\"\n\n// Regex fragments\nconst cityRegex = StateFlow.getCityRegex();\nconst regex = new RegExp('^' + cityRegex + '$');\nregex.test('Los Angeles, CA'); // true\n```\n\n## Core Concepts\n\n### There can be only one\nThis package is developed with one principle in mind:\n- any search/mapping response is based on lowercase keys and normalized values.\n- keys are lowercase for searching, and values are normalized for display.\n\n### Default Vocabulary\nBy default, all methods use the internal `State` enum, which contains 51 U.S. states.\n\n### Custom Vocabulary\nMost methods accept a final argument (`vocabulary`) which can be any object or enum.\nThis allows reuse of the same helpers with your own custom dataset.\n\n## API Reference\n\n### `getAbbreviations(vocabulary = State): string[]`\nReturns all vocabulary keys (state abbreviations by default), e.g. `['AL', 'AZ', ..., 'WY']`.\n```typescript\nconst codes = StateFlow.getAbbreviations();\n```\n\n### `getCount(vocabulary = State): number`\nReturns total number of items in the vocabulary.\n```typescript\nconst count = StateFlow.getCount(); // 51, including Hawaii, Alaska and District of Columbia\n```\n\n### `getNames(vocabulary = State): string[]`\nReturns all vocabulary values (state names by default), e.g. `['Alabama', 'New York', ...]`.\n```typescript\nconst names = StateFlow.getNames();\n```\n\n### `getAbbreviationsRegex(vocabulary = State): string`\nReturns a pipe-separated regex fragment of codes, e.g. `AL|AZ|AR|...`.\n```typescript\nconst codeRegex = StateFlow.getAbbreviationsRegex();\n```\n\n### `getNamesRegex(vocabulary = State): string`\nReturns a pipe-separated regex fragment of names, e.g. `Alabama|Arizona|...`.\n```typescript\nconst labelRegex = StateFlow.getNamesRegex();\n```\n\n### `getAbbreviationByNameMap(vocabulary = State): Record<string, string>`\nReturns a map of normalized snake_case names to abbreviations.\nExamples:\n- `new_york => NY`\n- `west_virginia => WV`\n```typescript\nconst map = StateFlow.getAbbreviationByNameMap();\n```\n\n### `getNameByAbbreviationMap(vocabulary = State): Record<string, string>`\nReturns a map of lowercase abbreviations to human-readable names.\nExamples:\n- `ny => New York`\n- `al => Alabama`\n```typescript\nconst map = StateFlow.getNameByAbbreviationMap();\n```\n\n### `getAbbreviation(name: string, lower: boolean = false, vocabulary = State): string | null`\nConverts a full state name to its short code.\nBehavior:\n- Input is normalized (trimmed, squished, snake_cased)\n- Returns `null` if state name is unknown\n- Optional lowercase output\n```typescript\nStateFlow.getAbbreviation('New York');         // \"NY\"\nStateFlow.getAbbreviation('  New   York  ');   // \"NY\"\nStateFlow.getAbbreviation('New York', true);   // \"ny\"\nStateFlow.getAbbreviation('NY');               // null\n```\n\n### `getName(short: string, lower: boolean = false, vocabulary = State): string | null`\nConverts a short code to full state name.\nBehavior:\n- Code lookup is case-insensitive\n- Returns `null` if code is unknown\n- Optional lowercase output\n```typescript\nStateFlow.getName('NY');        // \"New York\"\nStateFlow.getName('ny');        // \"New York\"\nStateFlow.getName('NY', true);  // \"new york\"\nStateFlow.getName('XX');        // null\n```\n\n### `getCityRegex(maxCityName: number = 30, defaultCity: string | null = null, vocabulary = State): string`\nBuilds a regex fragment for values like:\n- `City, ST` (code)\n- `City, State Name` (label)\nSupports:\n- Optional whitespace after comma\n- Configurable max city length (`maxCityName`)\n- Optional exact fallback city (`defaultCity`)\n```typescript\nconst regex = StateFlow.getCityRegex();\nconst pattern = new RegExp('^' + regex + '$');\npattern.test('New York, NY');       // true\npattern.test('New York, New York'); // true\npattern.test('Invalid City, XX');   // false\n\nconst regexWithDefault = StateFlow.getCityRegex(30, 'Anywhere');\nconst patternWithDefault = new RegExp('^' + regexWithDefault + '$');\npatternWithDefault.test('Anywhere'); // true\n```\n\n### `getOriginRegex(maxCityName: number = 30, vocabulary = State): string`\nBuilds a regex fragment that matches:\n- `City, ST`\n- `City, State Name`\n- Standalone state code\n- Standalone state label\n```typescript\nconst regex = StateFlow.getOriginRegex();\nconst pattern = new RegExp('^' + regex + '$');\npattern.test('NY');            // true\npattern.test('New York, NY');  // true\npattern.test('XX');            // false\n```\n\n### `search(query: string, vocabulary = State): Record<string, string>`\nSearches states by abbreviation fragment and returns matched pairs as:\n- key: lowercase abbreviation\n- value: full state name\nBehavior:\n- Query is normalized (trimmed + lowercased)\n- Empty/whitespace-only query returns an empty object\n- Matches if query is contained in name or equals full abbreviation\n```typescript\n// Search all with \"n\" in name.\nStateFlow.search('n');\n// {\n//   nc: 'North Carolina',\n//   ny: 'New York',\n//   tn: 'Tennessee',\n//   ...\n// }\n\nStateFlow.search('  NY  ');\n// { ny: 'New York' }\n\nStateFlow.search('   ');\n// {}\n```\n\n### `getRandom(vocabulary = State): { abbreviation: string, name: string }`\nReturns one random item from vocabulary as an object:\n- `abbreviation`: uppercase abbreviation\n- `name`: full state name\n```typescript\nconst random = StateFlow.getRandom();\n// {\n//   abbreviation: 'NY',\n//   name: 'New York',\n// }\n```\n\n### `normalizeNameKey(name: string): string`\nNormalizes a name for use as a lookup key.\nBehavior:\n- Trims whitespace\n- Squishes multiple spaces into a single space (handles special whitespace like `\\u3164` and `\\u1160`)\n- Converts to lowercase\n- Replaces spaces and hyphens with underscores\n```typescript\nStateFlow.normalizeNameKey('  New   York  '); // \"new_york\"\nStateFlow.normalizeNameKey('West-Virginia');  // \"west_virginia\"\n```\n\n## Using a Custom Vocabulary\nYou can use any object or enum as a vocabulary.\n```typescript\nenum Region {\n    NORTH = 'N',\n    SOUTH = 'S'\n}\n\nconst codes = StateFlow.getAbbreviations(Region); // ['NORTH', 'SOUTH']\nconst names = StateFlow.getNames(Region);         // ['N', 'S']\nconst name = StateFlow.getName('north', false, Region); // 'N'\n```\n\n## Caching Notes\nThis package caches computed arrays/regex strings in static `Map` properties within the `StateFlow` class.\n- Improves repeated lookup performance.\n- Cache is cleared when the application restarts.\n- Fully compatible with modern JavaScript environments (Node.js, Browser, etc.).\n\n## Testing\nRun tests with npm:\n```bash\nnpm test\n```\n\n## License\nMIT\n","readmeFilename":"README.md"}