First typings

telefonicaid · Aug 21, 2016 · 78223bd · 78223bd
1 parent 5766f0b
commit 78223bd
Show file tree

Hide file tree

Showing 3 changed files with 410 additions and 1 deletion.
diff --git a/lib/logops.d.ts b/lib/logops.d.ts
@@ -0,0 +1,335 @@
+
+declare module "logops" {
+    /**
+     * The stream where the logger will write string traces
+     * Defaults to process.stdout
+     */
+    export let stream: Stream;
+
+    /**
+     * Gets the current log level. The default level is INFO
+     *
+     * @return One of the following values
+     *     ['DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL']
+     */
+    export function getLevel(): string;
+    /**
+     * Sets the enabled logging level.
+     * All the disabled logging methods are replaced by a noop,
+     * so there is not any performance penalty at production using an undesired level
+     * You can also set the logging level using the `LOGOPS_LEVEL` environment variable:
+     * ```
+     * $> LOGOPS_LEVEL=DEBUG node app.js 
+     * ```
+     *
+     * @param level one of 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'
+     */
+    export function setLevel(level: string): void;
+
+    /**
+     * Gets a global context that should be printed and merged with specific
+     * log context props
+     *
+     * @example
+     * ```
+     * logops.getContext = function getContext() {
+     *  return {
+     *    hostname: require('os').hostname,
+     *    pid: process.pid
+     *  };
+     * }
+     * 
+     * logger.info({app: 'server'}, 'Startup');
+     * // {"hostname":"host.local","pid":35502,"app":"server","time":"2015-12-23T11:47:25.862Z","lvl":"INFO","msg":"Startup"}     
+     * ```
+     *  @return The context object
+     */
+    export function getContext(): Context;
+    /**
+     * Specifies the Formatter used for printing traces
+     * @example
+     * ```
+     * logops.format = logops.formatters.dev;
+     * ```
+     * 
+	 * You can also set the format specifying the formatter with `LOGOPS_FORMAT` environment variable:
+     * @example
+     * ```
+     * $> LOGOPS_FORMAT=json node app.js
+     * ```
+     */
+    export let format: Formatter;
+    /**
+     * The available formatters 
+     */
+    export let formatters: Formatters;
+
+    /**
+     * Logs a debug trace with the provided Context
+     * ```
+     * logger.debug({ip: '127.0.0.0'}, 'Something went wrong');
+     * // {"ip":"127.0.0.0","time":"2015-12-22T16:33:17.002Z","lvl":"DEBUG","msg":"Something went wrong"}
+     * ```
+     * 
+     * @param props the Context to print
+     * @param format A printf-like format string as you will use in console.log()
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function debug(props:Context, format?:string, ...params:any[]):void; 
+    /**
+     * Logs an Error as a debug trace. 
+     * See Logops.stacktracesWith to print the stack traces
+     * ```
+     * logger.debug(new Error('Out of memory'), 'SYSTEM UNSTABLE. BYE');
+     * ```
+     * 
+     * @param error the Error to serialize and print
+     * @param format A printf-like format string as you will use in console.log(). 
+     *  If not present, the message will be the Error message itself
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function debug(error:Error, format?:string, ...params:any[]):void;
+
+    /**
+     * Logs a debug trace, as you will do with console.log 
+     * ```
+     * logger.debug('Request %s %d %j', 'is', 5, {key: 'value'}, 'guy');
+     * // {"time":"2015-12-22T16:31:56.184Z","lvl":"DEBUG","msg":"Request is 5 {\"key\":\"value\"} guy"}
+     * ```
+     * 
+     * @param format A printf-like format string as you will use in console.log(). 
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function debug(format:string, ...params:any[]):void;
+
+
+    /**
+     * Logs an info trace with the provided Context
+     * ```
+     * logger.info({ip: '127.0.0.0'}, 'Something went wrong');
+     * // {"ip":"127.0.0.0","time":"2015-12-22T16:33:17.002Z","lvl":"INFO","msg":"Something went wrong"}
+     * ```
+     * 
+     * @param props the Context to print
+     * @param format A printf-like format string as you will use in console.log()
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function info(props:Context, format?:string, ...params:any[]):void; 
+    /**
+     * Logs an Error as a info trace. 
+     * See Logops.stacktracesWith to print the stack traces
+     * ```
+     * logger.info(new Error('Out of memory'), 'SYSTEM UNSTABLE. BYE');
+     * ```
+     * 
+     * @param error the Error to serialize and print
+     * @param format A printf-like format string as you will use in console.log(). 
+     *  If not present, the message will be the Error message itself
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function info(error:Error, format?:string, ...params:any[]):void;
+
+    /**
+     * Logs a info trace, as you will do with console.log 
+     * ```
+     * logger.info('Request %s %d %j', 'is', 5, {key: 'value'}, 'guy');
+     * // {"time":"2015-12-22T16:31:56.184Z","lvl":"INFO","msg":"Request is 5 {\"key\":\"value\"} guy"}
+     * ```
+     * 
+     * @param format A printf-like format string as you will use in console.log(). 
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function info(format:string, ...params:any[]):void;
+
+    /**
+     * Logs a warning trace with the provided Context
+     * ```
+     * logger.warn({ip: '127.0.0.0'}, 'Something went wrong');
+     * // {"ip":"127.0.0.0","time":"2015-12-22T16:33:17.002Z","lvl":"WARN","msg":"Something went wrong"}
+     * ```
+     * 
+     * @param props the Context to print
+     * @param format A printf-like format string as you will use in console.log()
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function warn(props:Context, format?:string, ...params:any[]):void; 
+    /**
+     * Logs an Error as a warn trace. 
+     * See Logops.stacktracesWith to print the stack traces
+     * ```
+     * logger.warn(new Error('Out of memory'), 'SYSTEM UNSTABLE. BYE');
+     * ```
+     * 
+     * @param error the Error to serialize and print
+     * @param format A printf-like format string as you will use in console.log(). 
+     *  If not present, the message will be the Error message itself
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function warn(error:Error, format?:string, ...params:any[]):void;
+
+    /**
+     * Logs a warn trace, as you will do with console.log 
+     * ```
+     * logger.warn('Request %s %d %j', 'is', 5, {key: 'value'}, 'guy');
+     * // {"time":"2015-12-22T16:31:56.184Z","lvl":"WARN","msg":"Request is 5 {\"key\":\"value\"} guy"}
+     * ```
+     * 
+     * @param format A printf-like format string as you will use in console.log(). 
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function warn(format:string, ...params:any[]):void;
+
+
+    /**
+     * Logs an error trace with the provided Context
+     * ```
+     * logger.error({ip: '127.0.0.0'}, 'Something went wrong');
+     * // {"ip":"127.0.0.0","time":"2015-12-22T16:33:17.002Z","lvl":"ERROR","msg":"Something went wrong"}
+     * ```
+     * 
+     * @param props the Context to print
+     * @param format A printf-like format string as you will use in console.log()
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function error(props:Context, format?:string, ...params:any[]):void; 
+    /**
+     * Logs an Error as an error trace. 
+     * See Logops.stacktracesWith to print the stack traces
+     * ```
+     * logger.error(new Error('Out of memory'), 'SYSTEM UNSTABLE. BYE');
+     * ```
+     * 
+     * @param error the Error to serialize and print
+     * @param format A printf-like format string as you will use in console.log(). 
+     *  If not present, the message will be the Error message itself
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function error(error:Error, format?:string, ...params:any[]):void;
+
+    /**
+     * Logs a error trace, as you will do with console.log 
+     * ```
+     * logger.error('Request %s %d %j', 'is', 5, {key: 'value'}, 'guy');
+     * // {"time":"2015-12-22T16:31:56.184Z","lvl":"ERROR","msg":"Request is 5 {\"key\":\"value\"} guy"}
+     * ```
+     * 
+     * @param format A printf-like format string as you will use in console.log(). 
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function error(format:string, ...params:any[]):void;
+
+
+    /**
+     * Logs a fatal trace with the provided Context
+     * ```
+     * logger.fatal({ip: '127.0.0.0'}, 'Something went wrong');
+     * // {"ip":"127.0.0.0","time":"2015-12-22T16:33:17.002Z","lvl":"FATAL","msg":"Something went wrong"}
+     * ```
+     * 
+     * @param props the Context to print
+     * @param format A printf-like format string as you will use in console.log()
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function fatal(props:Context, format?:string, ...params:any[]):void; 
+    /**
+     * Logs an Error as a debug trace. 
+     * See Logops.stacktracesWith to print the stack traces
+     * ```
+     * logger.fatal(new Error('Out of memory'), 'SYSTEM UNSTABLE. BYE');
+     * ```
+     * 
+     * @param error the Error to serialize and print
+     * @param format A printf-like format string as you will use in console.log(). 
+     *  If not present, the message will be the Error message itself
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function fatal(error:Error, format?:string, ...params:any[]):void;
+
+    /**
+     * Logs a fatal trace, as you will do with console.log 
+     * ```
+     * logger.fatal('Request %s %d %j', 'is', 5, {key: 'value'}, 'guy');
+     * // {"time":"2015-12-22T16:31:56.184Z","lvl":"FATAL","msg":"Request is 5 {\"key\":\"value\"} guy"}
+     * ```
+     * 
+     * @param format A printf-like format string as you will use in console.log(). 
+     * @param params Additional properties to be coerced in the format string
+     */
+    export function fatal(format:string, ...params:any[]):void;
+
+    /**
+     *  NodeJS.Stream interface simplification for documentarion purposes 
+     */
+    interface Stream {
+        write(str: string): boolean;
+    }
+
+    /**
+     * A key value map that should be printed and serialized as first class 
+     * citizien in the traces. 
+     */
+    interface Context {
+        [key: string]: any;
+    }
+
+    /**
+     * Interface for a logops formatter, that formats the user input as a readable 
+     * string ready to be written to a Stream
+     */
+    interface Formatter {
+        /**
+         * Format the user input as a readable string ready to be written to a Stream
+         * @param level One of the following values
+         *      ['DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL']
+         * @param context Additional information to add to the trace
+         * @param message The main message to be added to the trace
+         * @param args More arguments provided to the log function
+         * @param err A cause error used to log extra information
+         */
+        format(level: string, context:Context, message:string, args:any[], err?:Error): string;
+    }
+
+    /**
+     * The additional properties in a DevFormatter
+     */
+    interface DevFormatter extends Formatter {
+        /**
+         * Context properties keys that should be skipped from printing in dev format
+         */
+        omit: string[];
+    }
+
+    /**
+     * The formatters interface. All relative to customization of how a trace 
+     * is printed is located here
+     */
+    interface Formatters { 
+        /**
+         *  Formats a trace message in JSON format
+         */       
+        json: Formatter;
+        /**
+         * Formats a trace message with some nice TTY colors
+         */
+        dev: DevFormatter;
+        /**
+         * Formats a trace message with fields separated by pipes.
+         * @deprecated
+         */
+        pipe: Formatter;
+        /**
+         * Array of logger levels that will print error stacktraces 
+         * Defaults to `['ERROR', 'FATAL']
+         */
+        stacktracesWith: string[];
+        /**
+         * Sets a value for those fields that are not available in the context. This field
+         * will only be used in the 'pipes' formatter.
+         *
+         * @param str New value for not available fields.
+         * @deprecated
+         */
+        setNotAvailable(str: string): void;
+    }   
+}
+
diff --git a/package.json b/package.json
@@ -56,5 +56,6 @@
     "Germán Toro del Valle <german.torodelvalle@telefonica.com>",
     "Daniel Morán Jiménez <daniel.moranjimenez@telefonica.com>",
     "Juan de Bravo Diez <juande.bravodiez@telefonica.com>"
-  ]
+  ],
+  "typings": "./lib/logops.d.ts"
 }