@samatawy/rules-world

World and geography-oriented function providers for @samatawy/rules.

This package is designed as an optional plugin. It keeps geography and country-data helpers outside the core rules engine package while still integrating through the same FunctionFactory.registerProvider(...) API.

It currently exposes 42 country-related functions (2 of which are aliases). Data is available for 250 countries.

To report incorrect data or behaviour, or to request additional features, use the Github issue tracker.

This package can be used by:

• Node.js and browser runtimes
• ESM and CommonJS consumers

Installation

npm install @samatawy/rules @samatawy/rules-world

@samatawy/rules is a peer dependency, so your application provides the core engine version.

Usage

import { FunctionFactory, Workspace } from '@samatawy/rules';
import { CommonGeographyFunctionsProvider } from '@samatawy/rules-world';

FunctionFactory.registerProvider(CommonGeographyFunctionsProvider);

const workspace = new Workspace();

workspace.addRule('SET applicant.country_code = country_code(applicant.country)');

workspace.addRule('IF applicant.country_code != "Unknown" THEN country_known = true');

workspace.addRule('IF country_known THEN email_is_ok = country_has_tld(applicant.country_code, applicant.email_tld)');

workspace.addRule('IF country_known THEN currency_is_ok = country_uses_currency(applicant.country_code, applicant.currency)');

This is especially useful for input validation and fraud screening cases where upstream services have already extracted values such as an email TLD, phone calling code, claimed country, or transaction currency.

For example, after extracting .ca from an email domain and CAD from a payment payload, your rules can validate whether those values are plausible for the claimed country.

const context = workspace.loadContext({
	applicant: {
		country: 'Canada',
		email_tld: '.ca',
		currency: 'CAD',
	},
});

workspace.process(context);

console.log(context.getOutput('applicant.country_code'));         // CA
console.log(context.getOutput('email_is_ok'));          // true
console.log(context.getOutput('currency_is_ok'));       // true

You can also register the provider through the package helper:

import { registerWorldProviders } from '@samatawy/rules-world';

registerWorldProviders();

The same package entry works in both Node.js and browser builds, with ESM and CommonJS output generated from the same source.

Included Provider

• CommonGeographyFunctionsProvider

Included Data

• Countries
• CountryCodes
• CurrencyCodes
• Languages
• Continents
• Timezones

Included Geography Functions

The provider includes lookup, metadata, reverse-lookup, and validation helpers built on the packaged world dataset.

Core Lookup and Metadata

Use these to normalize a country code first, then read related metadata.

• country_code(value) resolves a 2-letter country code from a country name, alias, or ISO code when the input is uniquely identifiable.

This allows you to use the other functions that expect a valid 2-letter code.

• country_name(code) and official_country_name(code) return human-readable country names.
• capital_of(code), continent_of(code), and country_subregion(code) return broad location metadata.
• three_letter_code(code) return ISO-style code forms from a two-letter code.

Example:

set country_code = country_code(applicant.country)

set official = official_country_name(country_code)

set continent = continent_of(country_code)

Currency, TLD, Calling Code, and Language Checks

These are the most useful validation-oriented helpers when checking whether user-supplied values fit the claimed country.

• country_uses_currency(code, currency) checks a currency code, currency symbol, or currency name against a country.
• country_has_tld(code, tld) checks whether a country includes the given top-level domain.
• country_has_calling_code(code, callingCode) checks whether a country includes a phone calling code.
• country_speaks_language(code, language) checks whether a language is listed for a country.

Example:

IF applicant.country_code != "Unknown" THEN currency_is_ok = country_uses_currency(applicant.country_code, applicant.currency)

IF applicant.country_code != "Unknown" THEN email_is_ok = country_has_tld(applicant.country_code, applicant.email_tld)

IF applicant.country_code != "Unknown" THEN calling_code_is_ok = country_has_calling_code(applicant.country_code, applicant.phone_calling_code)

Country Property Lists

These return arrays of values associated with a country.

• country_calling_codes(code)
• country_tlds(code) and country_top_level_domains(code)
• country_languages(code)
• country_timezones(code)
• country_member_of(code)
• country_part_of(code)

Example:

set allowed_tlds = country_top_level_domains(applicant.country_code)

set languages = country_languages(applicant.country_code)

Global Lists and Reverse Group Lookups

These are helpful for building dropdowns, admin tools, filters, or reporting views.

• country_codes(), currency_codes(), languages(), continents(), timezones()
• countries_in_continent(continent)
• countries_in_subregion(subregion)
• countries_in_timezone(timezone)
• countries_speaking_language(language)
• countries_using_currency(currency)
• member_countries(group)
• countries_part_of(group)

Example:

set euro_countries = countries_using_currency("EUR")

set eu_timezones = countries_in_timezone("UTC+01:00")

Membership and Boolean Country Facts

These answer yes/no questions directly.

• country_is_member_of(code, group)
• country_is_part_of(code, group)
• country_in_continent(code, continent)
• country_in_timezone(code, timezone)
• country_is_independent(code)
• country_is_un_member(code)

Example:

IF country_is_un_member(applicant.country_code) THEN applicant.recognized_state = true

IF country_in_continent(applicant.country_code, "Europe") THEN applicant.region = "EMEA"

Additional Metadata Helpers

• currency_of(code), currency_name_of(code), currency_symbol_of(code)
• driving_side(code)
• system_of_government(code)

These are useful when rules need world metadata for routing, enrichment, or display, not only validation.