Static Data Kit

A TypeScript-first utility library for accessing and using high-quality static reference data in SaaS, B2B, and analytics applications.

---

✨ Why Static Data Kit?

When building SaaS platforms, you often need consistent, high-quality static data for:

• Countries
• Currencies
• States or provinces
• Job roles and industries
• Regional formats

But existing datasets are often:

• Incomplete or poorly structured
• Behind paywalls or APIs
• Unreliable or inconsistently formatted

Static Data Kit solves this by offering a clean, typed, offline-friendly dataset with standardized fields — perfect for use in onboarding flows, settings screens, or seed data in any modern app.

---

📦 Installation

1npm install @financially/static-data-kit
2# or
3yarn add @financially/static-data-kit
4# or
5pnpm add @financially/static-data-kit

---

🌍 Countries

✅ Methods

1getAllCountries(): Country[]
2getCountryByAlpha2Code(code: string): Country | undefined
3getCountryByAlpha3Code(code: string): Country | undefined

🔍 Example

1import {
2  getAllCountries,
3  getCountryByAlpha2Code,
4} from '@financially/static-data-kit';
5
6const countries = getAllCountries();
7const india = getCountryByAlpha2Code('IN');
8console.log(india?.flagFile); // "IN.svg" - you can append this to your S3 bucket domain and use it

📘 Interface

1interface Country {
2  commonName: string;
3  officialName: string;
4  isoAlpha2Code: string;
5  isoAlpha3Code: string;
6  countryNumericCode: string;
7  isoAlpha2SubDivisionCode: string;
8  region: string;
9  subRegion: string;
10  regionCode: string;
11  subRegionCode: string;
12  flagUnicode: string;
13  flagFile: string;
14  phonePrefix: string;
15}

---

💱 Currencies

✅ Methods

1getAllCurrencies(): Currency[]
2getCurrencyByAlpha3Code(code: string): Currency | undefined
3getCurrenciesByCountryCode(countryCode: string): Currency[]

🔍 Example

1import {
2  getCurrencyByAlpha3Code,
3  getCurrenciesByCountryCode,
4} from '@financially/static-data-kit';
5
6const usd = getCurrencyByAlpha3Code('USD');
7const swiss = getCurrenciesByCountryCode('CH');

📘 Interface

1interface Currency {
2  name: string;
3  isoAlpha3Code: string;
4  symbol: string;
5  isoNumericCode: string;
6  minorUnit: string;
7  supportedCountryCodes: string[];
8}

---

🗺️ States / Provinces

✅ Methods

1getAllStates(): State[]
2getStateByCode(code: string): State | undefined
3getStatesByCountryCode(countryCode: string): State[]

🔍 Example

1import { getStatesByCountryCode } from '@financially/static-data-kit';
2
3const usStates = getStatesByCountryCode('US');

📘 Interface

1interface State {
2  name: string;
3  code: string;
4  countryCode: string;
5  type: string;
6}

---

🏭 Industries

✅ Methods

1getAllIndustries(): Industry[]
2getIndustryBySlug(slug: string): Industry | undefined

🔍 Example

1import { getAllIndustries } from '@financially/static-data-kit';
2
3const industries = getAllIndustries();

📘 Interface

1interface Industry {
2  name: string;
3  slug: string;
4}

---

👨‍💼 Job Roles

✅ Methods

1getAllJobRoles(): JobRole[]
2getJobRoleBySlug(slug: string): JobRole | undefined
3getJobRolesByCategorySlug(slug: string): JobRole[]

🔍 Example

1import { getJobRolesByCategorySlug } from '@financially/static-data-kit';
2
3const execRoles = getJobRolesByCategorySlug('executive-leadership');

📘 Interface

1interface JobRole {
2  title: string;
3  slug: string;
4  category: string;
5  categorySlug: string;
6}

---

🌐 Regional Settings

✅ Methods

1getAllRegionalSettings(): RegionalSetting[]
2getRegionalSettingByCountryCode(code: string): RegionalSetting | undefined

🔍 Example

1import {
2  getRegionalSettingByCountryCode,
3  getAllRegionalSettings,
4} from '@financially/static-data-kit';
5
6const usSettings = getRegionalSettingByCountryCode('US');
7const all = getAllRegionalSettings();

📘 Interface

1export interface RegionalSetting {
2  countryCode: string;
3  dateFormat: DateFormat;
4  timeFormat: TimeFormat;
5  weekStartsOn: WeekStart;
6  defaultTimeZone: string; // e.g. "Asia/Phnom_Penh"
7  numberFormat: {
8    format: string; // e.g. "comma-thousand-dot-decimal"
9    example: string; // e.g. "1,234.56"
10    groupingStyle: number[]; // e.g. [3]
11    decimalSeparator: string; // e.g. "."
12    thousandSeparator: string; // e.g. ","
13  };
14}

All the timezone values are used according to proper ISO format. We use the package: https://github.com/vvo/tzdb/

---

🧪 Type Safety

All datasets are fully typed with TypeScript. You get complete IntelliSense, validation, and autocomplete support out-of-the-box.

---

📁 Asset Access (Flags)

All country flags are stored as SVGs with filenames like:

IN.svg
US.svg
...

Each country object includes a flagFile field:

1"flagFile": "IN.svg"

You can use this to construct the full flag URL using your own asset CDN or static hosting service.

✅ Usage Example

1import { getCountryByAlpha2Code } from '@financially/static-data-kit';
2
3const CDN_BASE_URL = 'https://assets.your-domain.com/countries/';
4const country = getCountryByAlpha2Code('IN');
5
6const flagFile = `${CDN_BASE_URL}${country.flagFile}`;
7console.log(flagFile);
8// Output: https://assets.your-domain.com/countries/IN.svg

---

🤝 Contributing

PRs are welcome! Please follow these guidelines:

• Keep entries alphabetically sorted where appropriate
• Ensure field consistency and valid JSON
• Add new types to src/types/index.ts
• Store new country flags in src/assets/countries/XX.svg

See CONTRIBUTING.md for more details.

---

👤 Author

Suprith Reddy – Creator & Maintainer github.com/suprith-s-reddy

Built with ❤️ at Financially modern SaaS products.

---

📄 License

MIT