@samatawy/rules-world 0.1.0 → 0.1.1

package/README.md

@@ -30,8 +30,34 @@ import { CommonGeographyFunctionsProvider } from '@samatawy/rules-world';
 FunctionFactory.registerProvider(CommonGeographyFunctionsProvider);
 
 const workspace = new Workspace();
-workspace.addRule('if country_name("CA") = "Canada" then result.country = true');
-workspace.addRule('if country_has_tld("CA", ".ca") then result.local = true');
+
+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.
+
+```ts
+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:
@@ -57,20 +83,114 @@ The same package entry works in both Node.js and browser builds, with ESM and Co
 - `Continents`
 - `Timezones`
 
-## Example Geography Functions
+## 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:
+
+```ts
+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:
+
+```ts
+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_codes()`
-- `country_code(value)`
-- `country_name(code)`
-- `official_country_name(code)`
 - `country_calling_codes(code)`
-- `country_top_level_domains(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:
+
+```ts
+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)`
-- `country_has_tld(code, tld)`
-- `country_has_calling_code(code, callingCode)`
-- `country_speaks_language(code, language)`
+- `member_countries(group)`
+- `countries_part_of(group)`
+
+Example:
+
+```ts
+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:
+
+```ts
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@samatawy/rules-world",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "World and geography-oriented function providers for @samatawy/rules, including country metadata and lookup helpers.",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -35,6 +35,7 @@
         "prepublishOnly": "npm run lint && npm run test && npm run build"
     },
     "keywords": [
+        "@samatawy/rules",
         "rules-engine",
         "plugin",
         "world",
@@ -57,7 +58,7 @@
     },
     "homepage": "https://samatawy.github.io/rules-world/",
     "peerDependencies": {
-        "@samatawy/rules": "^0.3.5"
+        "@samatawy/rules": "^0.4.0"
     },
     "devDependencies": {
         "@samatawy/rules": "file:../rules",