@alterior/logging 3.5.3 → 3.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alterior/logging",
-  "version": "3.5.3",
+  "version": "3.5.6",
   "description": "Configurable context-aware logging",
   "author": "The Alterior Project (https://github.com/alterior-mvc)",
   "license": "MIT",
@@ -38,11 +38,11 @@
     "docs": "typedoc ."
   },
   "dependencies": {
-    "@alterior/annotations": "^3.4.0",
+    "@alterior/annotations": "^3.5.6",
     "@alterior/common": "^3.4.0",
-    "@alterior/di": "^3.5.3",
-    "@alterior/runtime": "^3.5.3",
+    "@alterior/di": "^3.5.6",
+    "@alterior/runtime": "^3.5.6",
     "rxjs": "^7.8.0"
   },
-  "gitHead": "808d85ec078d91261d8388c717d77c02aefc568a"
+  "gitHead": "220e169fc8c855dc0935620bdb5efb1e9a2b86a7"
 }

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './inspect';
+export * from './logger';
+export * from './trace';
+
+export * from './logging.module';

package/src/inspect.ts

@@ -0,0 +1,386 @@
+/**
+ * Module exports.
+ */
+
+import { ConsoleColors } from '@alterior/common';
+
+export interface InspectOptions {
+    stylize: (str, styleType) => any;
+    depth?: number;
+    colors?: boolean;
+    showHidden?: boolean;
+    customInspect?: boolean;
+}
+
+/**
+ * Echos the value of a value. Trys to print the value out
+ * in the best way possible given the different types.
+ *
+ * @param {Object} obj The object to print out.
+ * @param {Object} opts Optional options object that alters the output.
+ * @license MIT (© Joyent)
+ */
+/* legacy: obj, showHidden, depth, colors*/
+
+export function inspect(obj : any, opts? : InspectOptions): string {
+    // default options
+    interface Context extends InspectOptions {
+        seen: any[];
+    }
+
+    var ctx: Context = {
+        seen: [],
+        stylize: stylizeNothing
+    };
+
+    if (opts)
+        Object.assign(ctx, opts);
+
+    // set default options
+    if (isUndefined(ctx.showHidden)) ctx.showHidden = false;
+    if (isUndefined(ctx.depth)) ctx.depth = 2;
+    if (isUndefined(ctx.colors)) ctx.colors = false;
+    if (isUndefined(ctx.customInspect)) ctx.customInspect = true;
+    if (ctx.colors) ctx.stylize = stylizeWithConsoleColors;
+
+    return formatValue(ctx, obj, ctx.depth);
+}
+
+// Don't use 'blue' not visible on cmd.exe
+const CONSOLE_COLOR_STYLES = {
+    'special': 'cyan',
+    'number': 'yellow',
+    'boolean': 'yellow',
+    'undefined': 'grey',
+    'null': 'bold',
+    'string': 'green',
+    'date': 'magenta',
+    // "name": intentionally not styling
+    'regexp': 'red'
+};
+
+/**
+ * Pass the string through with no stylization.
+ */
+export function stylizeNothing(str, styleType) {
+    return str;
+}
+
+function isBoolean(arg) {
+    return typeof arg === 'boolean';
+}
+
+function isUndefined(arg) {
+    return arg === void 0;
+}
+
+/**
+ * Use console colors to style the string. Suitable for output to
+ * terminals with ANSI color support.
+ */
+export function stylizeWithConsoleColors(str, styleType) {
+    var style = CONSOLE_COLOR_STYLES[styleType];
+    return style ? ConsoleColors[style](str) : str;
+}
+
+function isFunction(arg) {
+    return typeof arg === 'function';
+}
+
+function isString(arg) {
+    return typeof arg === 'string';
+}
+
+function isNumber(arg) {
+    return typeof arg === 'number';
+}
+
+function isNull(arg) {
+    return arg === null;
+}
+
+function hasOwn(obj, prop) {
+    return Object.prototype.hasOwnProperty.call(obj, prop);
+}
+
+function isRegExp(re) {
+    return isObject(re) && objectToString(re) === '[object RegExp]';
+}
+
+function isObject(arg) {
+    return typeof arg === 'object' && arg !== null;
+}
+
+function isError(e) {
+    return isObject(e) &&
+        (objectToString(e) === '[object Error]' || e instanceof Error);
+}
+
+function isDate(d) {
+    return isObject(d) && objectToString(d) === '[object Date]';
+}
+
+function objectToString(o) {
+    return Object.prototype.toString.call(o);
+}
+
+function arrayToHash(array) {
+    var hash = {};
+
+    array.forEach(function (val, idx) {
+        hash[val] = true;
+    });
+
+    return hash;
+}
+
+function formatArray(ctx, value, recurseTimes, visibleKeys, keys) {
+    var output = [];
+    for (var i = 0, l = value.length; i < l; ++i) {
+        if (hasOwn(value, String(i))) {
+            output.push(formatProperty(ctx, value, recurseTimes, visibleKeys,
+                String(i), true));
+        } else {
+            output.push('');
+        }
+    }
+    keys.forEach(function (key) {
+        if (!key.match(/^\d+$/)) {
+            output.push(formatProperty(ctx, value, recurseTimes, visibleKeys,
+                key, true));
+        }
+    });
+    return output;
+}
+
+function formatError(value) {
+    return '[' + Error.prototype.toString.call(value) + ']';
+}
+
+function formatValue(ctx, value, recurseTimes) {
+    // Provide a hook for user-specified inspect functions.
+    // Check that value is an object with an inspect function on it
+    if (ctx.customInspect &&
+        value &&
+        isFunction(value.inspect) &&
+        // Filter out the util module, it's inspect function is special
+        value.inspect !== inspect &&
+        // Also filter out any prototype objects using the circular check.
+        !(value.constructor && value.constructor.prototype === value)) {
+        var ret = value.inspect(recurseTimes, ctx);
+        if (!isString(ret)) {
+            ret = formatValue(ctx, ret, recurseTimes);
+        }
+        return ret;
+    }
+
+    // Primitive types cannot have properties
+    var primitive = formatPrimitive(ctx, value);
+    if (primitive) {
+        return primitive;
+    }
+
+    // Look up the keys of the object.
+    var keys = Object.keys(value);
+    var visibleKeys = arrayToHash(keys);
+
+    try {
+        if (ctx.showHidden && Object.getOwnPropertyNames) {
+            keys = Object.getOwnPropertyNames(value);
+        }
+    } catch (e) {
+        // ignore
+    }
+
+    // IE doesn't make error fields non-enumerable
+    // http://msdn.microsoft.com/en-us/library/ie/dww52sbt(v=vs.94).aspx
+    if (isError(value)
+        && (keys.indexOf('message') >= 0 || keys.indexOf('description') >= 0)) {
+        return formatError(value);
+    }
+
+    // Some type of object without properties can be shortcutted.
+    if (keys.length === 0) {
+        if (isFunction(value)) {
+            var name = value.name ? ': ' + value.name : '';
+            return ctx.stylize('[Function' + name + ']', 'special');
+        }
+        if (isRegExp(value)) {
+            return ctx.stylize(RegExp.prototype.toString.call(value), 'regexp');
+        }
+        if (isDate(value)) {
+            return ctx.stylize(Date.prototype.toString.call(value), 'date');
+        }
+        if (isError(value)) {
+            return formatError(value);
+        }
+    }
+
+    var base = '', array = false, braces = ['{', '}'];
+
+    // Make Array say that they are Array
+    if (Array.isArray(value)) {
+        array = true;
+        braces = ['[', ']'];
+    }
+
+    // Make functions say that they are functions
+    if (isFunction(value)) {
+        var n = value.name ? ': ' + value.name : '';
+        base = ' [Function' + n + ']';
+    }
+
+    // Make RegExps say that they are RegExps
+    if (isRegExp(value)) {
+        base = ' ' + RegExp.prototype.toString.call(value);
+    }
+
+    // Make dates with properties first say the date
+    if (isDate(value)) {
+        base = ' ' + Date.prototype.toUTCString.call(value);
+    }
+
+    // Make error with message first say the error
+    if (isError(value)) {
+        base = ' ' + formatError(value);
+    }
+
+    if (keys.length === 0 && (!array || value.length == 0)) {
+        return braces[0] + base + braces[1];
+    }
+
+    if (recurseTimes < 0) {
+        if (isRegExp(value)) {
+            return ctx.stylize(RegExp.prototype.toString.call(value), 'regexp');
+        } else {
+            return ctx.stylize('[Object]', 'special');
+        }
+    }
+
+    ctx.seen.push(value);
+
+    var output;
+    if (array) {
+        output = formatArray(ctx, value, recurseTimes, visibleKeys, keys);
+    } else {
+        output = keys.map(function (key) {
+            return formatProperty(ctx, value, recurseTimes, visibleKeys, key, array);
+        });
+    }
+
+    ctx.seen.pop();
+
+    return reduceToSingleString(output, base, braces);
+}
+
+function formatProperty(ctx, value, recurseTimes, visibleKeys, key, array) {
+    var name, str, desc;
+    desc = { value: void 0 };
+    try {
+        // ie6 › navigator.toString
+        // throws Error: Object doesn't support this property or method
+        desc.value = value[key];
+    } catch (e) {
+        // ignore
+    }
+    try {
+        // ie10 › Object.getOwnPropertyDescriptor(window.location, 'hash')
+        // throws TypeError: Object doesn't support this action
+        if (Object.getOwnPropertyDescriptor) {
+            desc = Object.getOwnPropertyDescriptor(value, key) || desc;
+        }
+    } catch (e) {
+        // ignore
+    }
+    if (desc.get) {
+        if (desc.set) {
+            str = ctx.stylize('[Getter/Setter]', 'special');
+        } else {
+            str = ctx.stylize('[Getter]', 'special');
+        }
+    } else {
+        if (desc.set) {
+            str = ctx.stylize('[Setter]', 'special');
+        }
+    }
+    if (!hasOwn(visibleKeys, key)) {
+        name = '[' + key + ']';
+    }
+    if (!str) {
+        if (ctx.seen.indexOf(desc.value) < 0) {
+            if (isNull(recurseTimes)) {
+                str = formatValue(ctx, desc.value, null);
+            } else {
+                str = formatValue(ctx, desc.value, recurseTimes - 1);
+            }
+            if (str.indexOf('\n') > -1) {
+                if (array) {
+                    str = str.split('\n').map(function (line) {
+                        return '    ' + line;
+                    }).join('\n').substr(2);
+                } else {
+                    str = '\n' + str.split('\n').map(function (line) {
+                        return '     ' + line;
+                    }).join('\n');
+                }
+            }
+        } else {
+            str = ctx.stylize('[Circular]', 'special');
+        }
+    }
+    if (isUndefined(name)) {
+        if (array && key.match(/^\d+$/)) {
+            return str;
+        }
+        name = JSON.stringify('' + key);
+        if (name.match(/^"([a-zA-Z_][a-zA-Z_0-9]*)"$/)) {
+            name = name.substr(1, name.length - 2);
+            name = ctx.stylize(name, 'name');
+        } else {
+            name = name.replace(/'/g, "\\'")
+                .replace(/\\"/g, '"')
+                .replace(/(^"|"$)/g, "'");
+            name = ctx.stylize(name, 'string');
+        }
+    }
+
+    return name + ': ' + str;
+}
+
+function formatPrimitive(ctx, value) {
+    if (isUndefined(value))
+        return ctx.stylize('undefined', 'undefined');
+    if (isString(value)) {
+        var simple = '\'' + JSON.stringify(value).replace(/^"|"$/g, '')
+            .replace(/'/g, "\\'")
+            .replace(/\\"/g, '"') + '\'';
+        return ctx.stylize(simple, 'string');
+    }
+    if (isNumber(value))
+        return ctx.stylize('' + value, 'number');
+    if (isBoolean(value))
+        return ctx.stylize('' + value, 'boolean');
+    // For some reason typeof null is "object", so special case here.
+    if (isNull(value))
+        return ctx.stylize('null', 'null');
+}
+
+function reduceToSingleString(output, base, braces) {
+    var numLinesEst = 0;
+    var length = output.reduce(function (prev, cur) {
+        numLinesEst++;
+        if (cur.indexOf('\n') >= 0) numLinesEst++;
+        return prev + cur.replace(/\u001b\[\d\d?m/g, '').length + 1;
+    }, 0);
+
+    if (length > 60) {
+        return braces[0] +
+            (base === '' ? '' : base + '\n ') +
+            ' ' +
+            output.join(',\n    ') +
+            ' ' +
+            braces[1];
+    }
+
+    return braces[0] + base + ' ' + output.join(', ') + ' ' + braces[1];
+}

package/src/logger.ts

@@ -0,0 +1,417 @@
+import { Injectable, Optional } from '@alterior/di';
+import { ExecutionContext, Application } from '@alterior/runtime';
+
+export type LogSeverity = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+
+import * as fs from 'fs';
+import { inspect, stylizeWithConsoleColors } from './inspect';
+
+export class LoggingOptionsRef {
+    constructor(readonly options : LoggingOptions) {
+    }
+
+    public static get currentRef(): LoggingOptionsRef {
+        if (!ExecutionContext.current || !ExecutionContext.current.application)
+           return null;
+
+        return ExecutionContext.current.application.inject(LoggingOptionsRef, null);
+    }
+
+    public static get current(): LoggingOptions {
+        let ref = this.currentRef;
+        return ref ? ref.options : {};
+    }
+}
+
+export interface LogOptions {
+    severity : LogSeverity;
+}
+
+export interface LogEvent {
+    type : 'message' | 'inspect';
+    message : string;
+
+    /**
+     * Subject being inspected. Defined
+     * only for `type == 'inspect'`
+     */
+    subject? : any;
+
+    /**
+     * Context data, if any
+     */
+    context? : any;
+
+    /**
+     * Context label, if set
+     */
+    contextLabel? : string;
+
+    /**
+     * Source label, if set.
+     */
+    sourceLabel? : string;
+
+    /**
+     * Context summary
+     */
+    contextSummary? : string;
+
+    /**
+     * Severity of the log event.
+     */
+    severity : LogSeverity;
+
+    /**
+     * The date when the log event was recorded.
+     */
+    date : Date;
+}
+
+export interface LogListener {
+    log(message : LogEvent) : Promise<void>;
+}
+
+export interface FormatSegment {
+    type : "raw" | "parameter";
+    value : string;
+}
+
+export class LogFormatter {
+    constructor(readonly logFormat : LogFormat) {
+        this.compile();
+    }
+
+    private compile() {
+        if (typeof this.logFormat === 'function')
+            return;
+
+        let segment = '';
+        let segments : FormatSegment[] = [];
+
+        for (let i = 0, max = this.logFormat.length; i < max; ++i) {
+            let char = this.logFormat[i];
+
+            if (char == '%') {
+                let lookAhead = this.logFormat.substr(i + 1);
+
+                if (lookAhead.includes('%')) {
+
+                    if (segment != '') {
+                        segments.push({ type: 'raw', value: segment });
+                        segment = '';
+                    }
+
+                    let parameterName = lookAhead.replace(/%.*$/, '');
+                    i += parameterName.length + 1;
+
+                    segments.push({ type: 'parameter', value: parameterName });
+
+                } else {
+                    segment += char;
+                }
+            } else {
+                segment += char;
+            }
+        }
+
+        if (segment !== '') {
+            segments.push({ type: 'raw', value: segment });
+        }
+
+        this.segments = segments;
+    }
+
+    segments : FormatSegment[] = [];
+
+    private formatParameter(name : string, value : Object) {
+        if (value === true || value === false)
+            return value ? '«true»' : '«false»';
+        
+        if (value === null)
+            return '«null»';
+            
+        if (value === undefined)
+            return '«undefined»';
+
+        if (value instanceof Date)
+            return value.toISOString();
+
+        return value.toString();
+    }
+
+    public format(message : LogEvent) : string {
+        if (typeof this.logFormat === 'function')
+            return this.logFormat(message);
+           
+        return this.segments.map(x => x.type == 'parameter' ? this.formatParameter(x.value, message[x.value]) : x.value).join('');
+    }
+}
+
+export class ConsoleLogger implements LogListener {
+    constructor(
+        readonly format : LogFormat
+    ) {
+        this.formatter = new LogFormatter(format);
+    }
+
+    private formatter : LogFormatter;
+
+    async log(message : LogEvent) {
+        let messageText = message.message;
+
+        if (message.type === 'inspect') {
+
+            // On the web, take advantage of the interactive
+            // inspection facilities
+
+            if (typeof document !== 'undefined') {
+                console.dir(message.subject);
+                return;
+            } 
+
+            // Inspect
+
+            messageText = inspect(message.subject, {
+                stylize: stylizeWithConsoleColors
+            });
+        }
+
+        let finalMessage = Object.assign({}, message, { message: messageText });
+        let finalMessageStr = this.formatter.format(finalMessage);
+        console.log(finalMessageStr);
+    }
+}
+
+export type LogFormat = string | ((event : LogEvent) => string);
+
+export class FileLogger implements LogListener {
+    constructor(
+        readonly format : LogFormat,
+        readonly filename : string
+    ) {
+        this.formatter = new LogFormatter(format);
+    }
+
+    private formatter : LogFormatter;
+    private _fdReady : Promise<number>;
+
+    get ready() {
+        return this._fdReady;
+    }
+
+    async open() {
+        if (this._fdReady)
+            return await this._fdReady;
+
+        return await (this._fdReady = new Promise((res, rej) => {
+            fs.open(this.filename, 'a', (err, fd) => {
+                if (err)
+                    rej(err);
+                else
+                    res(fd);
+            });
+        }));
+    }
+
+    async write(str : string) {
+        let fd = await this.open();
+        await new Promise<void>((res, rej) => {
+            fs.write(fd, Buffer.from(str), (err, written, buffer) => {
+                if (err) {
+                    rej(err);
+                    return;
+                }
+                
+                // sync to flush this to disk right away
+                fs.fdatasync(fd, (err) => err ? rej(err) : res());
+            });
+        });
+    }
+
+    async log(message : LogEvent) {
+        let formattedMessage = this.formatter.format(message);
+        await this.write(`${formattedMessage}\n`);
+    }
+}
+
+export interface LoggingOptions {
+    /**
+     * Specify functions which listen to and in some way handle
+     * emitted log messages.
+     */
+    listeners? : LogListener[];
+
+    /**
+     * Whether to enable tracing as provided by @ConsoleTrace.
+     */
+    tracing?: boolean;
+}
+
+export class ZonedLogger {
+    constructor(
+        @Optional() protected optionsRef : LoggingOptionsRef,
+        protected app? : Application,
+        sourceLabel? : string
+    ) {
+        this._sourceLabel = sourceLabel;
+    }
+    
+    clone() {
+        let logger = new ZonedLogger(this.optionsRef, this.app, this._sourceLabel);
+        Object.keys(this).filter(x => typeof this[x] !== 'function').forEach(key => logger[key] = this[key]);
+        return logger;
+    }
+
+    protected _sourceLabel : string = undefined;
+
+    get sourceLabel() {
+        return this._sourceLabel;
+    }
+
+    static readonly ZONE_LOCAL_NAME = '@alterior/logger:Logger.current';
+
+    public static get current(): ZonedLogger {
+        return Zone.current.get(Logger.ZONE_LOCAL_NAME) 
+            ?? ExecutionContext.current?.application?.inject(Logger)
+            ?? new ZonedLogger(null, null)
+        ;
+    }
+
+    get listeners() {
+        if (this.optionsRef?.options?.listeners) {
+            return this.optionsRef.options.listeners;
+        }
+
+        if (this.app?.options?.silent)
+            return [];
+        
+        return DEFAULT_LISTENERS;
+    }
+
+    /**
+     * Run the given function with this logger as the current logger. 
+     * Calls to Logger.current will yield the logger for this execution
+     * context.
+     */
+    run(func : Function): any {
+        return Zone.current.fork({
+            name: `LoggerContext`,
+            properties: {
+                [Logger.ZONE_LOCAL_NAME]: this
+            }
+        }).run(func);
+    }
+
+    protected createMessage(message : Partial<LogEvent>): LogEvent {
+        let contextSummary = this.contextLabel || '';
+
+        if (this._sourceLabel)
+            contextSummary = `${contextSummary} » ${this._sourceLabel}`;
+
+        return <LogEvent>Object.assign(<Partial<LogEvent>>{
+            type: 'message',
+            context: this.context,
+            date: new Date(),
+            message,
+            contextLabel: this.contextLabel,
+            sourceLabel: this._sourceLabel,
+            contextSummary: contextSummary
+        }, message);
+    }
+    
+    log(message : string, options? : LogOptions) {
+        this.emitLog(this.createMessage({
+            message,
+            severity: (options ? options.severity : undefined) || 'info'
+        }));
+    }
+
+    info(message : string, options? : LogOptions) {
+        this.log(message, Object.assign({}, options, { severity: 'info' }));
+    }
+
+    debug(message : string, options? : LogOptions) {
+        this.log(message, Object.assign({}, options, { severity: 'debug' }));
+    }
+    
+    warning(message : string, options? : LogOptions) {
+        this.log(message, Object.assign({}, options, { severity: 'warning' }));
+    }
+    
+    error(message : string, options? : LogOptions) {
+        this.log(message, Object.assign({}, options, { severity: 'error' }));
+    }
+
+    inspect(object : any, options? : LogOptions) {
+        this.emitLog(this.createMessage({
+            type: 'inspect',
+            severity: (options ? options.severity : undefined) || 'info',
+            subject: object,
+            message: '' + object
+        }))
+    }
+
+    private emitLog(message : LogEvent) {
+        this.listeners.forEach(listener => listener.log(message));
+    }
+
+    get context() {
+        return Zone.current.get('logContext');
+    }
+
+    get contextLabel() {
+        return Zone.current.get('logContextLabel');
+    }
+
+    async withContext<T = any>(context : any, label : string, callback : () => T): Promise<T> {
+        let zone = Zone.current.fork({
+            name: `LogContextZone: ${label}`,
+            properties: {
+                logContext: context,
+                logContextLabel: label
+            }
+        });
+
+        return await zone.run<T>(() => callback());
+    }
+}
+
+@Injectable()
+export class Logger extends ZonedLogger {
+    constructor(
+        @Optional() optionsRef : LoggingOptionsRef,
+        app? : Application
+    ) {
+        super(optionsRef, app);
+    }
+    
+    clone() {
+        let logger = new Logger(this.optionsRef);
+        Object.keys(this).filter(x => typeof this[x] !== 'function').forEach(key => logger[key] = this[key]);
+        return logger;
+    }
+
+    withSource(sourceLabel : string | Object) {
+        let logger = this.clone();
+
+        if (typeof sourceLabel === 'string') {
+            logger._sourceLabel = sourceLabel;    
+        } else if (typeof sourceLabel === 'object') {
+            logger._sourceLabel = sourceLabel.constructor.name;
+        } else {
+            logger._sourceLabel = `${sourceLabel}`;
+        }
+
+        return logger;
+    }
+}
+
+export const DEFAULT_FORMAT : LogFormat = (event : LogEvent) => {
+    if (event.contextSummary)
+        return `${event.date.toISOString()} [${event.contextSummary}] ${event.severity}: ${event.message}`;
+    else
+        return `${event.date.toISOString()} ${event.severity}: ${event.message}`;
+};
+
+export const DEFAULT_LISTENERS : LogListener[] = [ new ConsoleLogger(DEFAULT_FORMAT) ];

package/src/logging.module.ts

@@ -0,0 +1,22 @@
+import { Module } from "@alterior/di";
+import { Logger, LoggingOptions, LoggingOptionsRef } from "./logger";
+
+@Module({
+    providers: [
+        Logger
+    ]
+})
+export class LoggingModule {
+    static configure(options : LoggingOptions = {}) {
+        return LoggingModule.forRoot(options);
+    }
+
+    static forRoot(options : LoggingOptions = {}) {
+        return { 
+            $module: LoggingModule, 
+            providers: [
+                { provide: LoggingOptionsRef, useValue: new LoggingOptionsRef(options) }
+            ]
+        }
+    }
+}

package/src/trace.ts

@@ -0,0 +1,236 @@
+/**
+ * (C) 2017-2019 William Lahti
+ */
+
+import { Mutator } from "@alterior/annotations";
+import { ConsoleColors, indentConsole, coalesce } from '@alterior/common';
+import { LoggingOptionsRef, DEFAULT_LISTENERS, Logger } from "./logger";
+
+let ENABLED : boolean = false;
+
+export function getTracingEnabled() {
+    return ENABLED;
+}
+
+export function setTracingEnabled(enabled : boolean) {
+    ENABLED = enabled;
+}
+
+/**
+ * Prints messages related to the execution of the decorated method
+ * to the console. 
+ * 
+ * - When multiple traced functions are involved, the output is indented 
+ *   appropriately. 
+ * - Intercepts console messages from within the function to add 
+ *   appropriate indentation.
+ * - Records (and rethrows) exceptions thrown from within the function.
+ * - For methods returning promises, the promise itself is traced,
+ *   printing a "Resolved" message upon completion or a "Rejected"
+ *   message upon rejection.
+ * 
+ * Note that this functionality can be enabled and disabled by configuring
+ * the `tracing` option when configuring this module for your application. 
+ * When @Trace() is used outside of an Alterior execution context, the trace 
+ * logs are always enabled, and the default log listeners are used.
+ * 
+ * For example, given a class:
+ * 
+```
+class Thing {
+    @ConsoleTrace()
+    static doSomething(data : any, stuff : number) {
+        console.log("ALMOST...");
+        try {
+            this.anotherSomething(stuff);
+        } catch (e) {
+
+        }
+    }
+    @ConsoleTrace()
+    static anotherSomething(stuff : number) {
+        console.log("NAH...");
+        throw new Error('Uh oh');
+    }
+}
+```
+ * When executed, one may see:
+```sh
+Thing#doSomething({"stuff":321,"other":"nice"}, 12333) {
+ALMOST...
+Thing#anotherSomething(12333) {
+   NAH...
+   (!!) Exception:
+        Error: Uh oh
+} // [Exception] Thing#anotherSomething(12333)
+} // [Done, 6ms] Thing#doSomething({"stuff":321,"other":"nice"}, 12333)
+ * ```
+ */
+export function Trace() {
+    return Mutator.define({
+        options: { 
+            validTargets: ['method'] 
+        },
+
+        invoke(site) {
+
+            // - When used outside of Alterior, we will *always trace*.
+            // - When used inside an Alterior app, we will not trace by default.
+            // - If optionsRef.options.tracing is set to true, we trace.
+
+            let optionsRef = LoggingOptionsRef.currentRef;
+            let options = optionsRef ? (optionsRef.options || {}) : null;
+            let enabled = options ? coalesce(options.tracing, false) : true;
+            let logger = Logger.current;
+
+            if (!enabled)
+                return;
+
+            if (!ENABLED)
+                return;
+            
+            let originalMethod : Function = site.propertyDescriptor.value;
+            site.propertyDescriptor.value = function (...args) {
+                let type : Function;
+                let isStatic : boolean = false;
+
+                if (typeof site.target === 'function') {
+                    type = site.target;
+                    isStatic = true;
+                } else {
+                    type = site.target.constructor;
+                    isStatic = false;
+                }
+                
+                let typeName : string;
+                let sep : string = '.';
+
+                if (isStatic)
+                    sep = '#';
+
+                typeName = type.name;
+
+                let startedAt = Date.now();
+
+                let argStrings = [];
+
+                for (let arg of args) {
+                    if (arg === null)
+                        argStrings.push('null');
+                    else if (arg === undefined)
+                        argStrings.push('undefined');
+                    else if (arg === true)
+                        argStrings.push('true');
+                    else if (arg === false)
+                        argStrings.push('false');
+                    else if (typeof arg === 'string') 
+                        argStrings.push(JSON.stringify(arg));
+                    else if (typeof arg === 'function')
+                        argStrings.push(arg.name);
+                    else if (typeof arg === 'object')
+                        argStrings.push(JSON.stringify(arg))
+                    else 
+                        argStrings.push(''+arg);
+                }
+
+                let methodSpec = `${ConsoleColors.cyan(`${typeName}${sep}${site.propertyKey}`)}(${argStrings.join(', ')})`;
+                logger.debug(`${methodSpec} {`);
+                let value;
+
+                let finish = (message?) => {
+                    let time = Date.now() - startedAt;
+                    let components = [message || ConsoleColors.green(`Done`)];
+                    let timingColor = m => m;
+                    let showTiming = time > 3;
+
+                    if (time > 20) {
+                        timingColor = ConsoleColors.red;
+                    } else if (time > 5) {
+                        timingColor = ConsoleColors.yellow;
+                    }
+                    
+                    if (showTiming) {
+                        components.push(timingColor(`${time}ms`));
+                    }
+
+                    logger.debug(`} // [${components.join(', ')}] ${methodSpec}`);
+                };
+
+                let status = undefined;
+
+                try {
+                    indentConsole(4, () => {
+                        try {
+                            value = originalMethod.apply(this, args); 
+                        } catch (e) {
+                            console.error(`${ConsoleColors.red(`(!!)`)} Exception:`);
+                            indentConsole(6, () => console.error(e));
+                            
+                            throw e;
+                        }
+                    });
+                } catch (e) {
+                    finish(ConsoleColors.red(`Exception`));
+                    throw e;
+                }
+                
+                if (value && value.then) {
+                    let promise : Promise<any> = value;
+                    value = promise.then(() => {
+                        finish(ConsoleColors.green(`Resolved`));
+                    }).catch(e => {
+                        finish(ConsoleColors.red(`Rejected (${e})`));
+                        throw e;
+                    });
+                } else {
+                    finish();
+                }
+
+                return value;
+            };
+        }
+    });
+}
+
+/**
+ * If an exception occurs within the target method, report that exception to the console and rethrow.
+ */
+export function ReportExceptionsToConsole() {
+    return Mutator.define({
+        options: { 
+            validTargets: ['method'] 
+        },
+
+        invoke(site) {
+            let originalMethod : Function = site.propertyDescriptor.value;
+            site.propertyDescriptor.value = function (...args) {
+                let type : Function;
+                let isStatic : boolean = false;
+
+                if (typeof site.target === 'function') {
+                    type = site.target;
+                    isStatic = true;
+                } else {
+                    type = site.target.constructor;
+                    isStatic = false;
+                }
+                
+                let typeName : string;
+                let sep : string = '.';
+
+                if (isStatic)
+                    sep = '#';
+
+                typeName = type.name;
+
+                try {
+                    return originalMethod.apply(this, args);
+                } catch (e) {
+                    console.error(`Error occurred during ${typeName}${sep}${site.propertyKey}():`);
+                    console.error(e);
+                    throw e;
+                }
+            };
+        }
+    });
+}

package/dist.esm/inspect.test.js

@@ -1,18 +0,0 @@
-import { suite } from 'razmin';
-import { inspect } from './inspect';
-import { expect } from 'chai';
-suite(describe => {
-    describe('inspect', it => {
-        it('directly stringifies numbers', () => expect(inspect(123)).to.equal('123'));
-        it('quotes strings', () => expect(inspect('hello')).to.equal("'hello'"));
-        it('knows false', () => expect(inspect(false)).to.equal("false"));
-        it('knows true', () => expect(inspect(true)).to.equal("true"));
-        it('knows null', () => expect(inspect(null)).to.equal("null"));
-        it('knows undefined', () => expect(inspect(undefined)).to.equal("undefined"));
-        it('digs into objects', () => expect(inspect({ abc: 123 })).to.equal("{ abc: 123 }"));
-        it('presents functions', () => expect(inspect(() => 123)).to.equal("[Function]"));
-        function namedTest() { }
-        it('presents named functions', () => expect(inspect(namedTest)).to.equal("[Function: namedTest]"));
-    });
-});
-//# sourceMappingURL=inspect.test.js.map

package/dist.esm/logger.test.js

@@ -1,204 +0,0 @@
-import { __awaiter } from "tslib";
-import { suite } from 'razmin';
-import { Logger, LoggingOptionsRef, ConsoleLogger, FileLogger, LogFormatter } from './logger';
-import { expect } from 'chai';
-import * as os from 'os';
-import * as path from 'path';
-import * as fs from 'fs';
-const SAMPLE_LOG_MESSAGE_1 = { type: 'message', message: 'ABCDEF', date: new Date(), severity: 'info', context: null, contextLabel: null, sourceLabel: null };
-const SAMPLE_LOG_MESSAGE_2 = { type: 'message', message: '123456', date: new Date(), severity: 'info', context: null, contextLabel: null, sourceLabel: null };
-const SAMPLE_LOG_MESSAGE_3 = { type: 'message', message: 'TUVXYZ', date: new Date(), severity: 'info', context: null, contextLabel: null, sourceLabel: null };
-function SAMPLE_LOG_MESSAGE(message) {
-    return {
-        type: 'message',
-        message,
-        date: new Date(),
-        severity: 'info',
-        context: null,
-        contextLabel: null,
-        sourceLabel: null
-    };
-}
-function SAMPLE_LOG_MESSAGE_FATAL(message) {
-    return {
-        type: 'message',
-        message,
-        date: new Date(),
-        severity: 'fatal',
-        context: null,
-        contextLabel: null,
-        sourceLabel: null
-    };
-}
-suite(describe => {
-    describe('Logger', it => {
-        it('calls each listener', () => __awaiter(void 0, void 0, void 0, function* () {
-            let result = '';
-            let logger = new Logger(new LoggingOptionsRef({
-                listeners: [
-                    { log(message) {
-                            return __awaiter(this, void 0, void 0, function* () { result += `a${message.message}`; });
-                        } },
-                    { log(message) {
-                            return __awaiter(this, void 0, void 0, function* () { result += `b${message.message}`; });
-                        } }
-                ]
-            }));
-            yield logger.log('X');
-            yield logger.log('Y');
-            expect(result).to.eq('aXbXaYbY');
-        }));
-        it('defaults to ConsoleLogger', () => __awaiter(void 0, void 0, void 0, function* () {
-            let logger = new Logger(undefined);
-            let logger2 = new Logger(new LoggingOptionsRef({}));
-            expect(logger.listeners.length).to.eq(1);
-            expect(logger.listeners[0].constructor).to.equal(ConsoleLogger);
-            expect(logger2.listeners.length).to.eq(1);
-            expect(logger2.listeners[0].constructor).to.equal(ConsoleLogger);
-        }));
-        it('supports execution-based context', () => __awaiter(void 0, void 0, void 0, function* () {
-            let logger = new Logger(new LoggingOptionsRef({ listeners: [] }));
-            expect(logger.context).to.not.exist;
-            expect(logger.contextLabel).to.not.exist;
-            logger.withContext({ abc: 123 }, 'contextlabel', () => {
-                expect(logger.context.abc).to.eq(123);
-                expect(logger.contextLabel).to.eq('contextlabel');
-                setTimeout(() => {
-                    expect(logger.context.abc).to.eq(123);
-                    expect(logger.contextLabel).to.eq('contextlabel');
-                }, 10);
-            });
-            expect(logger.context).to.not.exist;
-            expect(logger.contextLabel).to.not.exist;
-            logger.withContext({ abc: 321 }, 'contextlabel2', () => {
-                expect(logger.context.abc).to.eq(321);
-                expect(logger.contextLabel).to.eq('contextlabel2');
-                setTimeout(() => {
-                    expect(logger.context.abc).to.eq(321);
-                    expect(logger.contextLabel).to.eq('contextlabel2');
-                }, 10);
-            });
-            expect(logger.context).to.not.exist;
-            expect(logger.contextLabel).to.not.exist;
-        }));
-        it('supports child loggers with a specific source', () => __awaiter(void 0, void 0, void 0, function* () {
-            let logger = new Logger(new LoggingOptionsRef({ listeners: [] }));
-            expect(logger.sourceLabel).to.not.exist;
-            let sublogger = logger.withSource('athing');
-            expect(sublogger.sourceLabel).to.eq('athing');
-            expect(logger.sourceLabel).to.not.exist;
-        }));
-    });
-    describe('FileLogger', it => {
-        it('basically works', () => __awaiter(void 0, void 0, void 0, function* () {
-            let filename = path.join(os.tmpdir(), `file-logger-test-${Math.floor(Math.random() * 100000)}.txt`);
-            if (fs.existsSync(filename))
-                fs.unlinkSync(filename);
-            let logger = new FileLogger('%severity%|%message%', filename);
-            yield logger.open();
-            yield logger.log({
-                type: 'message',
-                message: 'TUVXYZ',
-                date: new Date(),
-                severity: 'info'
-            });
-            let contents2 = fs.readFileSync(filename).toString().split(/\n/g);
-            yield logger.log({
-                type: 'message',
-                message: '123456',
-                date: new Date(),
-                severity: 'info'
-            });
-            let contents3 = fs.readFileSync(filename).toString().split(/\n/g);
-            if (fs.existsSync(filename))
-                fs.unlinkSync(filename);
-            expect(contents2[0]).to.eq('info|TUVXYZ');
-            expect(contents3[0]).to.eq('info|TUVXYZ');
-            expect(contents3[1]).to.eq('info|123456');
-            // make sure there's nothing extra
-            expect(contents2.length).to.eq(2);
-            expect(contents3.length).to.eq(3);
-        }));
-    });
-    describe('LogFormatter', it => {
-        it('parses an empty string, ergo always produces empty strings', () => {
-            let formatter = new LogFormatter('');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE(''))).to.equal('');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE('abcdef'))).to.equal('');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE('stuff!'))).to.equal('');
-        });
-        it('parses a literal string, ergo always produces the literal string', () => {
-            let formatter = new LogFormatter('a silly format');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE(''))).to.equal('a silly format');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE('abcdef'))).to.equal('a silly format');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE('stuff!'))).to.equal('a silly format');
-        });
-        it('parses variables and substitutes message fields', () => {
-            let formatter = new LogFormatter('-%severity%- -%message%-');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE('one silly message'))).to.equal('-info- -one silly message-');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE_FATAL('another silly message'))).to.equal('-fatal- -another silly message-');
-            expect(formatter.format(SAMPLE_LOG_MESSAGE(''))).to.equal('-info- --');
-        });
-    });
-    describe('ConsoleLogger', it => {
-        function patchConsole(buffer) {
-            let originalLog;
-            function patch() {
-                originalLog = console.log;
-                console.log = message => {
-                    buffer.push(message);
-                };
-            }
-            function unpatch() {
-                console.log = originalLog;
-            }
-            let zone = Zone.current.fork({
-                name: 'ConsoleLoggerTestZone',
-                onInvoke(parent, current, target, callback, applyThis, applyArgs, source) {
-                    try {
-                        patch();
-                        parent.invoke(target, callback, applyThis, applyArgs, source);
-                    }
-                    finally {
-                        unpatch();
-                    }
-                },
-                onInvokeTask(parent, current, target, task, applyThis, applyArgs) {
-                    try {
-                        patch();
-                        parent.invokeTask(target, task, applyThis, applyArgs);
-                    }
-                    finally {
-                        unpatch();
-                    }
-                }
-            });
-            return zone;
-        }
-        it('should obey silly formats', () => {
-            let buffer = [];
-            patchConsole(buffer)
-                .run(() => {
-                let logger = new ConsoleLogger('ABCDEF');
-                logger.log(SAMPLE_LOG_MESSAGE_3);
-                logger.log(SAMPLE_LOG_MESSAGE_2);
-            });
-            expect(buffer.length).to.eq(2);
-            expect(buffer[0]).to.eq('ABCDEF');
-            expect(buffer[1]).to.eq('ABCDEF');
-        });
-        it('should understand format variable substitution', () => {
-            let buffer = [];
-            patchConsole(buffer)
-                .run(() => {
-                let logger = new ConsoleLogger('%severity%|%message%');
-                logger.log(SAMPLE_LOG_MESSAGE_3);
-                logger.log(SAMPLE_LOG_MESSAGE_2);
-            });
-            expect(buffer.length).to.eq(2);
-            expect(buffer[0]).to.eq('info|TUVXYZ');
-            expect(buffer[1]).to.eq('info|123456');
-        });
-    });
-});
-//# sourceMappingURL=logger.test.js.map

package/dist.esm/test.js

@@ -1,6 +0,0 @@
-import "reflect-metadata";
-import { suite } from 'razmin';
-suite()
-    .include(['./**/*.test.js'])
-    .run();
-//# sourceMappingURL=test.js.map

package/dist.esm/trace.test.js

@@ -1,63 +0,0 @@
-import { __decorate, __metadata } from "tslib";
-import { suite } from "razmin";
-import { Trace, setTracingEnabled, getTracingEnabled } from "./trace";
-import { interceptConsole } from "@alterior/common";
-import { expect } from 'chai';
-suite(describe => {
-    describe('Trace', it => {
-        it('reasonably traces a program', () => {
-            let wasTracingEnabled = getTracingEnabled();
-            setTracingEnabled(true);
-            try {
-                let log = [];
-                interceptConsole((method, original, console, args) => {
-                    log.push({ method, original, console, args });
-                }, () => {
-                    class Thing {
-                        static doSomething(data, stuff) {
-                            console.log("Doing something...");
-                            try {
-                                this.doAnotherThing(stuff);
-                            }
-                            catch (e) {
-                            }
-                        }
-                        static doAnotherThing(stuff) {
-                            console.log("Doing another thing...");
-                            throw new Error('Uh oh');
-                        }
-                    }
-                    __decorate([
-                        Trace(),
-                        __metadata("design:type", Function),
-                        __metadata("design:paramtypes", [Object, Number]),
-                        __metadata("design:returntype", void 0)
-                    ], Thing, "doSomething", null);
-                    __decorate([
-                        Trace(),
-                        __metadata("design:type", Function),
-                        __metadata("design:paramtypes", [Number]),
-                        __metadata("design:returntype", void 0)
-                    ], Thing, "doAnotherThing", null);
-                    let thing = new Thing();
-                    Thing.doSomething({ stuff: 321, other: "nice" }, 12333);
-                });
-                expect(log.length, `Content was: '${log.map(x => x.args.join(' ')).join("\n")}`).to.eq(8);
-                expect(log[0].args[0]).to.contain('Thing#doSomething');
-                expect(log[0].args[0]).to.contain('{');
-                expect(log[1].args[0]).to.contain('Doing something...');
-                expect(log[2].args[0]).to.contain('Thing#doAnotherThing');
-                expect(log[2].args[0]).to.contain('{');
-                expect(log[3].args[0]).to.contain('Doing another thing...');
-                expect(log[4].args[0]).to.contain('Exception');
-                expect(log[5].args[0]).to.contain('Error: Uh oh');
-                expect(log[6].args[0]).to.contain('}');
-                expect(log[7].args[0]).to.contain('}');
-            }
-            finally {
-                setTracingEnabled(wasTracingEnabled);
-            }
-        });
-    });
-});
-//# sourceMappingURL=trace.test.js.map