Typescript declarations (#26)

* Add typings

* Add more comments

* Fix CleanOptions typings

* Typescript declaration tests and improvements

* Fix tests and lint

* Minor styling improvements

envalid.d.ts

@@ -0,0 +1,116 @@
+interface Spec<T> {
+    /**
+     * An Array that lists the admissable parsed values for the env var.
+     */
+    choices?: T[];
+    /**
+     * A fallback value, which will be used if the env var wasn't specified. Providing a default effectively makes the env var optional.
+     */
+    default?: T;
+    /**
+     * A fallback value to use only when NODE_ENV is not 'production'. 
+     * This is handy for env vars that are required for production environments, but optional for development and testing.
+     */
+    devDefault?: T;
+    /**
+     * A string that describes the env var.
+     */
+    desc?: string;
+    /**
+     * An example value for the env var.
+     */
+    example?: string;
+    /**
+     * A url that leads to more detailed documentation about the env var.
+     */
+    docs?: string;
+}
+
+interface ValidatorSpec<T> extends Spec<T> {
+    type: string;
+    _parse: (input: string) => T;
+}
+
+interface Specs {
+    [key: string]: ValidatorSpec<any>;
+}
+
+interface CleanEnv {
+    /** true if NODE_ENV === 'development' */
+    readonly isDev: boolean;
+
+    /** true if NODE_ENV === 'test' */
+    readonly isTest: boolean;
+
+    /** true if NODE_ENV === 'production' */
+    readonly isProduction: boolean;
+}
+
+interface CleanOptions {
+    /**
+     * If true, the output of cleanEnv will only contain the env vars that were specified in the validators argument.
+     * @default false
+     */
+    strict?: boolean;
+
+    /**
+     * Pass in a function to override the default error handling and console output.
+     * See lib/reporter.js for the default implementation.
+     */
+    reporter?: (errors: { [key: string]: Error }, env: any) => void;
+
+    /**
+     * A function used to transform the cleaned environment object before it is returned from cleanEnv.
+     */
+    transformer?: (env: any) => any;
+
+    /**
+     * Path to the file that is parsed by dotenv to optionally load more env vars at runtime.
+     * Pass null if you want to skip dotenv processing entirely and only load from process.env.
+     * @default ".env"
+     */
+    dotEnvPath?: string;
+}
+
+/**
+ * Returns a sanitized, immutable environment object.
+ * @param environment An object containing your env vars (eg. process.env).
+ * @param validators An object that specifies the format of required vars.
+ */
+export function cleanEnv(environment: any, validators?: Specs, options?: CleanOptions): any;
+/**
+ * Returns a sanitized, immutable environment object.
+ * @param environment An object containing your env vars (eg. process.env).
+ * @param validators An object that specifies the format of required vars.
+ */
+export function cleanEnv<T>(environment: any, validators?: Specs, options?: CleanOptions): T & CleanEnv;
+
+/**
+ * Create your own validator functions.
+ */
+export function makeValidator<T>(parser: (input: string) => any, type?: string): (spec?: Spec<T>) => ValidatorSpec<T>;
+
+/**
+ * Parses env var string "0", "1", "true", "false", "t", "f" into Boolean.
+ */
+export function bool(spec?: Spec<boolean>): ValidatorSpec<boolean>;
+/**
+ * Parses an env var (eg. "42", "0.23", "1e5") into a Number.
+ */
+export function num(spec?: Spec<number>): ValidatorSpec<number>;
+/**
+ * Passes string values through, will ensure an value is present unless a default value is given.
+ */
+export function str(spec?: Spec<string>): ValidatorSpec<string>;
+/**
+ * Parses an env var with JSON.parse.
+ */
+export function json(spec?: Spec<any>): ValidatorSpec<any>;
+/**
+ * Ensures an env var is a url with a protocol and hostname
+ */
+export function url(spec?: Spec<string>): ValidatorSpec<string>;
+/**
+ * Ensures an env var is an email address
+ */
+export function email(spec?: Spec<string>): ValidatorSpec<string>;

package.json

@@ -29,7 +29,9 @@
     "eslint": "2.10.2",
     "ghooks": "1.2.1",
     "istanbul": "0.4.3",
-    "painless": "0.9.5"
+    "painless": "0.9.5",
+    "typescript": "2.1.6",
+    "typescript-definition-tester": "0.0.5"
   },
   "author": "Aaron Franks",
   "license": "MIT",
@@ -41,5 +43,6 @@
     "ghooks": {
       "pre-push": "npm run lint && npm test"
     }
-  }
+  },
+  "typings": "envalid.d.ts"
 }

tests/envalid.ts

@@ -0,0 +1,52 @@
+import { cleanEnv, makeValidator, str, bool, num, json, url, email, Spec, Specs } from '..';
+
+interface Env {
+    foo: string;
+}
+
+// Test cleanEnv
+cleanEnv({});
+const env = cleanEnv<Env>({});
+env.foo = '';
+const isDev: Boolean = env.isDev;
+const isProduction: Boolean = env.isProduction;
+const isTest: Boolean = env.isTest;
+cleanEnv({}, {}, {
+    dotEnvPath: null,
+    reporter: (errors, e) => {
+        const errorMessage: string = errors[0].message;
+        const errorName: string = errors[0].name;
+    },
+    strict: false,
+    transformer: (envToTransform) => { }
+})
+
+// Test validator specs
+const spec: Specs = {
+    foo: str({
+        desc: 'description',
+        default: ''
+    }),
+    bool: bool({}),
+    num: num({
+        choices: [1, 2, 3]
+    }),
+    json: json({
+        devDefault: { foo: 'bar' },
+    }),
+    url: url(),
+    email: email({
+        example: 'example',
+        docs: 'http://example.com'
+    })
+}
+spec[0]._parse('test');
+spec[0].type === 'test';
+cleanEnv({}, spec);
+
+// Custom validator
+const validator = makeValidator<Number>((input: string) => 3.33, 'CUSTOM_TYPE');
+validator({
+    default: 3.33,
+    desc: 'Test Validator'
+})

tests/test_typescript.js

@@ -0,0 +1,11 @@
+const { createGroup } = require('painless')
+const tt = require('typescript-definition-tester')
+const test = createGroup()
+
+test('Typescript declaration', (done) => {
+    tt.compileDirectory(
+        __dirname,
+        (fileName) => fileName.indexOf('.ts') > -1,
+        () => done()
+    )
+})