{"id":15664704,"url":"https://github.com/alexandre-fernandez/tzlocator","last_synced_at":"2025-05-06T19:14:05.256Z","repository":{"id":55183816,"uuid":"522918837","full_name":"Alexandre-Fernandez/tzlocator","owner":"Alexandre-Fernandez","description":"Lightweight privacy respecting geolocation library with no dependencies.","archived":false,"fork":false,"pushed_at":"2022-12-05T15:53:42.000Z","size":152,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-06T19:13:58.432Z","etag":null,"topics":["geolocation","timezone"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/tzlocator","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Alexandre-Fernandez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-09T11:22:34.000Z","updated_at":"2024-09-18T11:28:21.000Z","dependencies_parsed_at":"2023-01-23T02:50:13.225Z","dependency_job_id":null,"html_url":"https://github.com/Alexandre-Fernandez/tzlocator","commit_stats":null,"previous_names":["tzlocator/tzlocator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alexandre-Fernandez%2Ftzlocator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alexandre-Fernandez%2Ftzlocator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alexandre-Fernandez%2Ftzlocator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alexandre-Fernandez%2Ftzlocator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Alexandre-Fernandez","download_url":"https://codeload.github.com/Alexandre-Fernandez/tzlocator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252752059,"owners_count":21798723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geolocation","timezone"],"created_at":"2024-10-03T13:43:56.166Z","updated_at":"2025-05-06T19:14:05.231Z","avatar_url":"https://github.com/Alexandre-Fernandez.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tzlocator\n\n\u003e Lightweight privacy respecting geolocation library with no dependencies.\n\n## Key features\n\n-   🥂 No third-party API calls\n-   👀 Works without browser prompt\n-   🪙 No reverse IP lookups\n-   🌏 Country and currency data\n-   🔒 Privacy respecting\n-   🪶 Lightweight with no dependencies\n-   🎓 Fully typed\n\n## Installation\n\n```ts\n// npm\nnpm install tzlocator\n// yarn\nyarn add tzlocator\n// pnpm\npnpm add tzlocator\n```\n\n## Usage\n\n-   Star the [github repo](https://github.com/alexandre-fernandez/tzlocator) 😎\n\n### Browser\n\n#### Single page application\n\n```ts\nimport { Tzlocator, getBrowserTimezone } from \"tzlocator\"\n\nconst tzlocator = new TzLocator()\nconst location = tzlocator.get(getBrowserTimezone())\n```\n\n#### Server side rendering\n\n```ts\nimport { getBrowserTimezone } from \"tzlocator\"\n\nconst timezone = getBrowserTimezone()\n// send the timezone to the server\ndocument.cookie = `timezone=${timezone};`\n```\n\n### Server\n\n```ts\nimport { getRequestCookies } from \"my-project\"\nimport { Tzlocator } from \"tzlocator\"\n\nconst tzlocator = new TzLocator()\n\nfunction getLocation(request: Request) {\n\t// retrieves the browser's timezone from a cookie\n\tconst cookies = getRequestCookies(request)\n\treturn tzlocator.get(cookies.timezone)\n}\n```\n\n## Configuration\n\nYou can modify tzlocator's configuration by passing an object to its class constructor (e.g. `new Tzlocator({})`).\n\n```ts\n{\n\tinclude, /*\n\tAn array of functions that take the Tzlocator's `get` method result as a\n\tparameter and return true if it should be included or false otherwise.\n\t*/\n\texclude, /*\n\tAn array of functions that take the Tzlocator's `get` method result as a\n\tparameter and return true if it should be excluded or false otherwise\n\t*/\n\tfallback, /*\n\tA string indicating the timezone when the Tzlocator's `get` method can't\n\tfind the given timezone, either because it's not included/excluded or\n\tbecause it doesn't exist.\n\t*/\n}\n```\n\n## Tzlocator\n\nUsed to get the location information ([Locator](#locator)) using a timezone.\nCan be instanciated with or without a [configuration](#configuration) object.\n\n```ts\nclass Tzlocator {\n\t/**\n\t * Returns a boolean indicating if the `timezone` has an assigned\n\t * CountryCode.\n\t */\n\tstatic exists(timezone: string): timezone is Timezone {}\n\n\t/**\n\t * Returns the Locator corresponding to the `timezone`.\n\t * If `useFallback` is true and the `timezone` cannot be found in the\n\t * included Locator pool it will return the set config fallback.\n\t * Else if there's no set fallback or if `useFallback` is false it will\n\t * return undefined.\n\t */\n\tget(timezone: string, useFallback = true) {}\n\n\t/**\n\t * Returns a boolean indicating if the `timezone` has a valid assigned\n\t * Locator.\n\t */\n\thas() {}\n\n\t/**\n\t * Returns an array of all the valid timezones for the current instance.\n\t */\n\ttimezones() {}\n\n\t/**\n\t * Returns an array of all the valid currencies for the current instance.\n\t */\n\tcurrencies() {}\n\n\t/**\n\t * Returns an array of all the valid languages for the current instance.\n\t */\n\tlanguages() {}\n\n\t/**\n\t * Returns an array of all the valid locators for the current instance.\n\t */\n\tlocators() {}\n}\n```\n\n## Locator\n\nLocation information class.\nCan be instanciated using a country code (e.g. `DE`).\n\n```ts\nclass Locator {\n\tcode // country's code\n\tname: // country's name\n\tnative: // country's native name\n\tprefix: // country's phone code\n\tcontinent: // continent\n\tmeasurement: // country's measurement system\n\tcurrency: // country's currency information\n\tlocales: // country's locales\n\n\t/**\n\t * Returns a boolean indicating if the `countryCode` has an assigned\n\t * Locator.\n\t */\n\tstatic exists(countryCode: string): countryCode is CountryCode {}\n\n\t/**\n\t * Returns the languages corresponding to each locale.\n\t */\n\tgetLanguages() {}\n\n\t/**\n\t * Returns the main locale for this country.\n\t */\n\tgetMainLocale() {}\n\n\t/**\n\t * Returns the main language for this country.\n\t */\n\tgetMainLanguage() {}\n}\n```\n\n## Currency\n\nCurrency information class.\nCan be instanciated using a currency code (e.g. `EUR`).\n\n```ts\nclass Currency {\n\tcode:  // currency's code\n\tsymbol: // currency's symbol\n\tname: // currency's name\n\n\t/**\n\t * Returns a boolean indicating if the `currencyCode` has an assigned\n\t * Currency.\n\t */\n\tstatic exists(currencyCode: string): currencyCode is CurrencyCode {}\n}\n```\n\n## Language\n\nLanguage information class.\nCan be instanciated using a language code (e.g. `en`).\n\n```ts\nclass Language {\n\tcode: // language's code\n\tname: // language's name\n\tnative: // language's native name\n\tscripts: // language's scripts\n\n\t/**\n\t * Returns a boolean indicating if the `languageCode` has an assigned\n\t * Language.\n\t */\n\tstatic exists(languageCode: string): languageCode is LanguageCode {}\n}\n```\n\n## Thanks\n\n-   [IANA](https://data.iana.org/time-zones/releases/)\n-   [Wikipedia](https://www.wikipedia.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexandre-fernandez%2Ftzlocator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexandre-fernandez%2Ftzlocator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexandre-fernandez%2Ftzlocator/lists"}