@types/convict
Version:
TypeScript definitions for convict
211 lines (180 loc) • 7.18 kB
TypeScript
/// <reference types="node" />
declare namespace convict {
// Taken from https://github.com/Microsoft/TypeScript/issues/12215#issuecomment-307871458
type Overwrite<T, U> = { [P in Exclude<keyof T, keyof U>]: T[P] } & U;
type ValidationMethod = "strict" | "warn";
interface ValidateOptions {
/**
* If set to warn, any properties specified in config files that are not declared in
* the schema will print a warning. This is the default behavior. If set to strict,
* any properties specified in config files that are not declared in the schema will
* throw errors. This is to ensure that the schema and the config files are in sync.
*/
allowed?: ValidationMethod | undefined;
/** @deprecated use allowed instead */
strict?: boolean | undefined;
/**
* If specified, possible warnings will be passed to this function instead of being
* outputted to console.log, which would be the default behaviour.
*/
output?: ((message: string) => void) | undefined;
}
interface Format {
name?: string | undefined;
validate?(val: any, schema: SchemaObj): void;
coerce?(val: any): any;
}
interface Parser {
extension: string | string[];
parse: (content: string) => any;
}
type PredefinedFormat =
| "*"
| "int"
| "port"
| "windows_named_pipe"
| "port_or_windows_named_pipe"
| "url"
| "email"
| "ipaddress"
| "duration"
| "timestamp"
| "nat"
| String
| Object
| Number
| RegExp
| Boolean;
interface SchemaObj<T = any> {
/**
* You can define a configuration property as "required" without providing a default value.
* Set its default to null and if your format doesn't accept null it will throw an error.
*/
default: T | null;
doc?: string | undefined;
/**
* From the implementation:
*
* format can be a:
* - predefined type, as seen below
* - an array of enumerated values, e.g. ["production", "development", "testing"]
* - built-in JavaScript type, i.e. Object, Array, String, Number, Boolean
* - function that performs validation and throws an Error on failure
*
* If omitted, format will be set to the value of Object.prototype.toString.call
* for the default value
*/
format?: PredefinedFormat | any[] | ((val: any) => asserts val is T) | ((val: any) => void) | undefined;
env?: string | undefined;
arg?: string | undefined;
sensitive?: boolean | undefined;
nullable?: boolean | undefined;
[key: string]: any;
}
type Schema<T> = {
[P in keyof T]: Schema<T[P]> | SchemaObj<T[P]>;
};
interface InternalSchema<T> {
_cvtProperties: {
[K in keyof T]: T[K] extends object ? InternalSchema<T[K]> : { default: T[K] };
};
}
interface Options {
env?: NodeJS.ProcessEnv | undefined;
args?: string[] | undefined;
}
// Taken from https://twitter.com/diegohaz/status/1309489079378219009
type PathImpl<T, K extends keyof T> = K extends string
? T[K] extends Record<string, any>
? T[K] extends ArrayLike<any> ? K | `${K}.${PathImpl<T[K], Exclude<keyof T[K], keyof any[]>>}`
: K | `${K}.${PathImpl<T[K], keyof T[K]>}`
: K
: never;
type Path<T> = PathImpl<T, keyof T> | keyof T;
type PathValue<T, P extends Path<T>> = P extends `${infer K}.${infer Rest}`
? K extends keyof T ? Rest extends Path<T[K]> ? PathValue<T[K], Rest>
: never
: never
: P extends keyof T ? T[P]
: never;
interface Config<T> {
/**
* @returns the current value of the name property. name can use dot
* notation to reference nested values
*/
get<K extends Path<T> | null | undefined = undefined>(
name?: K,
): K extends null | undefined ? T : K extends Path<T> ? PathValue<T, K> : never;
/**
* @returns the default value of the name property. name can use dot
* notation to reference nested values
*/
default<K extends Path<T> | null | undefined = undefined>(
name?: K,
): K extends null | undefined ? T : K extends Path<T> ? PathValue<T, K> : never;
/**
* @returns true if the property name is defined, or false otherwise
*/
has<K extends Path<T>>(name: K): boolean;
/**
* Resets a property to its default value as defined in the schema
*/
reset<K extends Path<T>>(name: K): void;
/**
* Sets the value of name to value. name can use dot notation to reference
* nested values, e.g. "database.port". If objects in the chain don't yet
* exist, they will be initialized to empty objects
*/
set<K extends Path<T> | string>(name: K, value: K extends Path<T> ? PathValue<T, K> : any): Config<T>;
/**
* Loads and merges a JavaScript object into config
*/
load<U>(conf: U): Config<Overwrite<T, U>>;
/**
* Loads and merges JSON configuration file(s) into config
*/
loadFile<U>(files: string | string[]): Config<Overwrite<T, U>>;
/**
* Validates config against the schema used to initialize it
*/
validate(options?: ValidateOptions): Config<T>;
/**
* Exports all the properties (that is the keys and their current values) as a {JSON} {Object}
* @returns A {JSON} compliant {Object}
*/
getProperties(): T;
/**
* Exports the schema as a {JSON} {Object}
* @returns A {JSON} compliant {Object}
*/
getSchema(): InternalSchema<T>;
/**
* Exports all the properties (that is the keys and their current values) as a JSON string.
* @returns A string representing this object
*/
toString(): string;
/**
* Exports the schema as a JSON string.
* @returns A string representing the schema of this {Config}
*/
getSchemaString(): string;
/**
* Gets the environment variable map, using the override passed to the
* convict function or process.env if no override was passed.
*/
getEnv(): string[];
/**
* Gets the array of process arguments, using the override passed to the
* convict function or process.argv if no override was passed.
*/
getArgs(): string[];
}
}
interface convict {
addFormat(format: convict.Format): void;
addFormats(formats: { [name: string]: convict.Format }): void;
addParser(parsers: convict.Parser | convict.Parser[]): void;
<T>(config: convict.Schema<T> | string, opts?: convict.Options): convict.Config<T>;
}
declare var convict: convict;
export = convict;