v3.2.0: Add Typescript definitions

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [3.2.0] - 2021-08-10
+### Added
+- Add TypeScript definitions ([#37](https://github.com/manuelmhtr/countries-and-timezones/pull/37) by [benj-dobs](https://github.com/benj-dobs))
+
 ## [3.1.0] - 2021-08-04
 ### Added
 - Restores `getCountryForTimezone` method to keep compatibility with version 2.

README.md

@@ -24,7 +24,7 @@ Add the following script to your project (only ~9kb):
 <script src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-and-timezones@latest/dist/index.js" type="text/javascript"></script>
 
 <!-- Or specify a version -->
-<script src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-and-timezones@v3.1.0/dist/index.js" type="text/javascript"></script>
+<script src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-and-timezones@v3.2.0/dist/index.js" type="text/javascript"></script>
 
 <!-- This will export a variable named "ct": -->
 <script type="text/javascript">

esm/index.js

@@ -1,4 +1,4 @@
-import ct from '../src/index.js';
+import ct from '../dist/index.js';
 
 export default ct;
 export const getAllCountries = ct.getAllCountries;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "countries-and-timezones",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Minimalistic library to work with countries and timezones data.",
   "main": "./dist/index.js",
   "module": "./esm/index.js",
@@ -13,9 +13,11 @@
     "esm",
     "yarn.lock"
   ],
+  "types": "dist/types.d.ts",
   "scripts": {
     "build": "./node_modules/rollup/dist/bin/rollup -c",
-    "test": "yarn run build && mocha test/"
+    "dtslint": "npx dtslint types",
+    "test": "yarn run build && yarn run dtslint && mocha test/"
   },
   "repository": {
     "type": "git",
@@ -61,7 +63,9 @@
     "mocha": "^8.3.2",
     "proxyquire": "^2.1.3",
     "rollup": "^2.45.2",
+    "rollup-plugin-dts": "^3.0.2",
     "rollup-plugin-uglify": "^6.0.4",
-    "sinon": "^10.0.0"
+    "sinon": "^10.0.0",
+    "typescript": "^4.3.5"
   }
 }

rollup.config.js

@@ -2,6 +2,7 @@ import babel from '@rollup/plugin-babel';
 import commonjs from '@rollup/plugin-commonjs';
 import json from '@rollup/plugin-json';
 import { uglify } from 'rollup-plugin-uglify';
+import dts from 'rollup-plugin-dts';
 
 const plugins = [
   commonjs(),
@@ -23,6 +24,14 @@ export default [
       exports: 'named',
       sourcemap: true,
     },
-    plugins
+    plugins,
+  },
+  {
+    input: 'types/index.d.ts',
+    output: {
+      file: 'dist/types.d.ts',
+      format: 'esm',
+    },
+    plugins: [dts(), json({ preferConst: true, compact: true })],
   },
 ];

types/index.d.ts

@@ -0,0 +1,51 @@
+import data from '../src/data.json';
+
+export {};
+
+export type CountryCode = keyof typeof data['countries'];
+export type TimezoneName = keyof typeof data['timezones'];
+
+export interface Country {
+  id: CountryCode;
+  name: string;
+  timezones: TimezoneName[];
+}
+
+export interface Timezone {
+  name: string;
+  countries: CountryCode[];
+  utcOffset: number;
+  utcOffsetStr: string;
+  dstOffset: number;
+  dstOffsetStr: string;
+  aliasOf: string | null;
+}
+
+type nullish = null | undefined;
+
+export function getCountry(id: CountryCode): Country;
+export function getCountry(id: nullish): null;
+export function getCountry(id: string | nullish): Country | null;
+
+export function getTimezone(name: TimezoneName): Timezone;
+export function getTimezone(name: nullish): null;
+export function getTimezone(name: string | nullish): Timezone | null;
+
+export function getAllCountries(): { [id in CountryCode]: Country };
+
+export function getAllTimezones(): { [name in TimezoneName]: Timezone };
+
+export function getTimezonesForCountry(id: CountryCode): Timezone[];
+export function getTimezonesForCountry(id: nullish): null;
+export function getTimezonesForCountry(id: string | nullish): Timezone[] | null;
+
+export function getCountriesForTimezone(name: TimezoneName): Country[];
+export function getCountriesForTimezone(name: string): Country[];
+export function getCountriesForTimezone(name: nullish): null;
+export function getCountriesForTimezone(
+  name: string | nullish
+): Country[] | null;
+
+export function getCountryForTimezone(name: TimezoneName): Country;
+export function getCountryForTimezone(name: nullish): null;
+export function getCountryForTimezone(name: string | nullish): Country | null;

types/index.test.ts

@@ -0,0 +1,40 @@
+import {
+  getCountriesForTimezone,
+  getCountry,
+  getCountryForTimezone,
+  getTimezone,
+  getTimezonesForCountry,
+} from 'countries-and-timezones';
+
+declare const unknownString: string;
+declare const maybeNull: string | null;
+
+getCountry('GB'); // $ExpectType Country
+getCountry(unknownString); // $ExpectType Country | null
+getCountry(undefined); // $ExpectType null
+getCountry(maybeNull); // $ExpectType Country | null
+getCountry({}); // $ExpectError
+
+getTimezone('America/Cancun'); // $ExpectType Timezone
+getTimezone(unknownString); // $ExpectType Timezone | null
+getTimezone(undefined); // $ExpectType null
+getTimezone(maybeNull); // $ExpectType Timezone | null
+getTimezone(0); // $ExpectError
+
+getTimezonesForCountry('NZ'); // $ExpectType Timezone[]
+getTimezonesForCountry(unknownString); // $ExpectType Timezone[] | null
+getTimezonesForCountry(undefined); // $ExpectType null
+getTimezonesForCountry(maybeNull); // $ExpectType Timezone[] | null
+getTimezonesForCountry(); // $ExpectError
+
+getCountriesForTimezone('Europe/Amsterdam'); // $ExpectType Country[]
+getCountriesForTimezone(unknownString); // $ExpectType Country[]
+getCountriesForTimezone(undefined); // $ExpectType null
+getCountriesForTimezone(maybeNull); // $ExpectType Country[] | null
+getCountriesForTimezone(true); // $ExpectError
+
+getCountryForTimezone('America/Cancun'); // $ExpectType Country
+getCountryForTimezone(unknownString); // $ExpectType Country | null
+getCountryForTimezone(undefined); // $ExpectType null
+getCountryForTimezone(maybeNull); // $ExpectType Country | null
+getCountryForTimezone(getCountryForTimezone); // $ExpectError

types/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["es6"],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": { "countries-and-timezones": ["."] },
+    "resolveJsonModule": true,
+    "esModuleInterop": true
+  }
+}

types/tslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "quotemark": [true, "single", "avoid-escape", "avoid-template"],
+    "unified-signatures": false
+  }
+}