diff --git a/envalid.d.ts b/envalid.d.ts new file mode 100644 index 0000000..bd07a10 --- /dev/null +++ b/envalid.d.ts @@ -0,0 +1,116 @@ +interface Spec { + /** + * 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 extends Spec { + type: string; + _parse: (input: string) => T; +} + +interface Specs { + [key: string]: ValidatorSpec; +} + +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(environment: any, validators?: Specs, options?: CleanOptions): T & CleanEnv; + +/** + * Create your own validator functions. + */ +export function makeValidator(parser: (input: string) => any, type?: string): (spec?: Spec) => ValidatorSpec; + +/** + * Parses env var string "0", "1", "true", "false", "t", "f" into Boolean. + */ +export function bool(spec?: Spec): ValidatorSpec; +/** + * Parses an env var (eg. "42", "0.23", "1e5") into a Number. + */ +export function num(spec?: Spec): ValidatorSpec; +/** + * Passes string values through, will ensure an value is present unless a default value is given. + */ +export function str(spec?: Spec): ValidatorSpec; +/** + * Parses an env var with JSON.parse. + */ +export function json(spec?: Spec): ValidatorSpec; +/** + * Ensures an env var is a url with a protocol and hostname + */ +export function url(spec?: Spec): ValidatorSpec; +/** + * Ensures an env var is an email address + */ +export function email(spec?: Spec): ValidatorSpec; \ No newline at end of file diff --git a/package.json b/package.json index c3baefc..0ede78a 100644 --- a/package.json +++ b/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" } diff --git a/tests/envalid.ts b/tests/envalid.ts new file mode 100644 index 0000000..7786f61 --- /dev/null +++ b/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.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((input: string) => 3.33, 'CUSTOM_TYPE'); +validator({ + default: 3.33, + desc: 'Test Validator' +}) diff --git a/tests/test_typescript.js b/tests/test_typescript.js new file mode 100644 index 0000000..d2fef78 --- /dev/null +++ b/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() + ) +})