diff --git a/docs/api-reference/log/log.md b/docs/api-reference/log/log.md index 795c8d1b..37822376 100644 --- a/docs/api-reference/log/log.md +++ b/docs/api-reference/log/log.md @@ -35,10 +35,10 @@ log.log(2, () => `${expensiveFunction()}`)(); ### Log Function Parameters Log functions can be called with different parameter combinations -- `log.log(message, ...args)` - priority defaults to 0 -- `log.log(priority, message, ...args)` - sets priority -- `log.log({message, ...options})` - additional options can be set, priority is zero -- `log.log({priority, message, args, ...options})` - additional options can be set +- `log.log(message, ...args)` - logLevel defaults to 0 +- `log.log(logLevel, message, ...args)` - sets logLevel +- `log.log({message, ...options})` - additional options can be set, logLevel is zero +- `log.log({logLevel, message, args, ...options})` - additional options can be set ### Log Function Options @@ -47,7 +47,7 @@ When using named parameters (passing an object as first parameter), the followin | Option | Type | Description | | --- | --- | --- | -| `priority` | `Number` | This probe will only "fire" if the log's current priority is greater than or equal to this value.defaults to `0`, which means that the probe is executed / printed regardless of log level. | +| `logLevel` | `Number` | This probe will only "fire" if the log's current logLevel is greater than or equal to this value.defaults to `0`, which means that the probe is executed / printed regardless of log level. | | `time` | `Boolean` | Add a timer since page load (default for `Log.probe`) | | `once` | `Boolean` | Logs this message only once (default for `Log.warn`, `Log.once` | | `tag` | `String` | Optional tag | @@ -78,10 +78,19 @@ Creates a new `Log` instance. `new Log({id})` +### enable -### getPriority +`log.enable(false)` -`log.getPriority()` +Accepts one argument `true` or `false`. + +### getLevel + +`log.getLevel()` + +### setLevel + +`log.setLevel(newLevel)` ### log @@ -89,8 +98,8 @@ Creates a new `Log` instance. Log a debug level message (uses `console.debug` if available) `log.log(message, ...args)` -`log.log(priority, message, ...args)` -`log.log({priority, message, args, ....options})` +`log.log(logLevel, message, ...args)` +`log.log({logLevel, message, args, ....options})` Returns: a function closure that should be called immediately. @@ -100,8 +109,8 @@ Returns: a function closure that should be called immediately. Log a normal message (uses `console.info` if available) `log.info(message, ...args)` -`log.info(priority, message, ...args)` -`log.info({priority, message, args, ....options})` +`log.info(logLevel, message, ...args)` +`log.info({logLevel, message, args, ....options})` Returns: a function closure that should be called immediately. @@ -110,7 +119,7 @@ Returns: a function closure that should be called immediately. Log a normal message, but only once, no console flooding -`once(priority|opts, arg, ...args)` +`once(logLevel|opts, arg, ...args)` Returns: a function closure that should be called immediately. @@ -120,8 +129,8 @@ Returns: a function closure that should be called immediately. Log a message with time since page load `log.probe(message, ...args)` -`log.probe(priority, message, ...args)` -`log.probe({priority, message, args, ....options})` +`log.probe(logLevel, message, ...args)` +`log.probe({logLevel, message, args, ....options})` Returns: a function closure that should be called immediately. @@ -167,7 +176,7 @@ Returns: a function closure that should be called immediately. Logs a table (using `console.table` if available). -`log.table(priority|opts, table)` +`log.table(logLevel|opts, table)` Returns: a function closure that should be called immediately. @@ -176,7 +185,7 @@ Returns: a function closure that should be called immediately. Logs an image (under Chrome) -`log.image({priority, image, message = '', scale = 1})` +`log.image({logLevel, image, message = '', scale = 1})` ### settings @@ -189,37 +198,37 @@ Logs the current settings as a table Returns the current value of setting -`log.get('priority')` +`log.get('logLevel')` ### set(setting, value) Updates the value of setting -`log.set('priority', 3)` +`log.set('logLevel', 3)` ### time -`log.time(priority, label)` +`log.time(logLevel, label)` ### timeEnd -`log.timeEnd(priority, label)` +`log.timeEnd(logLevel, label)` ### group -`log.group(priority, label)` +`log.group(logLevel, label)` ### groupCollapsed -`log.group(priority, label)` +`log.group(logLevel, label)` ### groupEnd -`log.groupEnd(priority)` +`log.groupEnd(logLevel)` ## Experimental APIs @@ -229,7 +238,7 @@ Updates the value of setting Provides an exception safe way to run some code within a group -`log.withGroup(priority, label, func)` +`log.withGroup(logLevel, label, func)` ### trace diff --git a/modules/core/src/lib/log.js b/modules/core/src/lib/log.js index ecda5ae6..2cb8ae42 100644 --- a/modules/core/src/lib/log.js +++ b/modules/core/src/lib/log.js @@ -42,7 +42,7 @@ const originalConsole = { const DEFAULT_SETTINGS = { enabled: false, - priority: 0 + level: 0 }; function noop() {} @@ -106,25 +106,20 @@ export default class Log { Object.seal(this); } - set priority(newPriority) { - this._storage.updateConfiguration({priority: newPriority}); - return this; + set level(newLevel) { + this.setLevel(newLevel); } - get priority() { - return this._storage.config.priority; + get level() { + return this.getLevel(); } isEnabled() { return this._storage.config.enabled; } - getPriority() { - return this._storage.config.priority; - } - getLevel() { - return this._storage.config.priority; + return this._storage.config.level; } // @return {Number} milliseconds, with fractions @@ -137,6 +132,19 @@ export default class Log { return Number((getHiResTimestamp() - this._deltaTs).toPrecision(10)); } + // Deprecated + set priority(newPriority) { + this.level = newPriority; + } + + get priority() { + return this.level; + } + + getPriority() { + return this.level; + } + // Configure enable(enabled = true) { @@ -145,7 +153,7 @@ export default class Log { } setLevel(level) { - this._storage.updateConfiguration({priority: level}); + this._storage.updateConfiguration({level}); return this; } @@ -177,27 +185,27 @@ in a later version. Use \`${newUsage}\` instead`); // Conditional logging // Log to a group - probe(priority, message) { - return this._getLogFunction(priority, message, originalConsole.log, arguments, { + probe(logLevel, message) { + return this._getLogFunction(logLevel, message, originalConsole.log, arguments, { time: true, once: true }); } // Log a debug message - log(priority, message) { - return this._getLogFunction(priority, message, originalConsole.debug, arguments); + log(logLevel, message) { + return this._getLogFunction(logLevel, message, originalConsole.debug, arguments); } // Log a normal message - info(priority, message) { - return this._getLogFunction(priority, message, console.info, arguments); + info(logLevel, message) { + return this._getLogFunction(logLevel, message, console.info, arguments); } // Log a normal message, but only once, no console flooding - once(priority, message) { + once(logLevel, message) { return this._getLogFunction( - priority, + logLevel, message, originalConsole.debug || originalConsole.info, arguments, @@ -206,9 +214,9 @@ in a later version. Use \`${newUsage}\` instead`); } // Logs an object as a table - table(priority, table, columns) { + table(logLevel, table, columns) { if (table) { - return this._getLogFunction(priority, table, console.table || noop, columns && [columns], { + return this._getLogFunction(logLevel, table, console.table || noop, columns && [columns], { tag: getTableHeader(table) }); } @@ -216,8 +224,8 @@ in a later version. Use \`${newUsage}\` instead`); } // logs an image under Chrome - image({priority, image, message = '', scale = 1}) { - if (!this._shouldLog(priority)) { + image({logLevel, image, message = '', scale = 1}) { + if (!this._shouldLog(logLevel)) { return noop; } return isBrowser @@ -244,47 +252,47 @@ in a later version. Use \`${newUsage}\` instead`); this._storage.updateConfiguration({[setting]: value}); } - time(priority, message) { - return this._getLogFunction(priority, message, console.time ? console.time : console.info); + time(logLevel, message) { + return this._getLogFunction(logLevel, message, console.time ? console.time : console.info); } - timeEnd(priority, message) { + timeEnd(logLevel, message) { return this._getLogFunction( - priority, + logLevel, message, console.timeEnd ? console.timeEnd : console.info ); } - timeStamp(priority, message) { - return this._getLogFunction(priority, message, console.timeStamp || noop); + timeStamp(logLevel, message) { + return this._getLogFunction(logLevel, message, console.timeStamp || noop); } - group(priority, message, opts = {collapsed: false}) { - opts = normalizeArguments({priority, message, opts}); + group(logLevel, message, opts = {collapsed: false}) { + opts = normalizeArguments({logLevel, message, opts}); const {collapsed} = opts; opts.method = (collapsed ? console.groupCollapsed : console.group) || console.info; return this._getLogFunction(opts); } - groupCollapsed(priority, message, opts = {}) { - return this.group(priority, message, Object.assign({}, opts, {collapsed: true})); + groupCollapsed(logLevel, message, opts = {}) { + return this.group(logLevel, message, Object.assign({}, opts, {collapsed: true})); } - groupEnd(priority) { - return this._getLogFunction(priority, '', console.groupEnd || noop); + groupEnd(logLevel) { + return this._getLogFunction(logLevel, '', console.groupEnd || noop); } // EXPERIMENTAL - withGroup(priority, message, func) { - this.group(priority, message)(); + withGroup(logLevel, message, func) { + this.group(logLevel, message)(); try { func(); } finally { - this.groupEnd(priority)(); + this.groupEnd(logLevel)(); } } @@ -296,15 +304,15 @@ in a later version. Use \`${newUsage}\` instead`); // PRIVATE METHODS - _shouldLog(priority) { - priority = normalizePriority(priority); - return priority === 0 || (this.isEnabled() && this.getPriority() >= priority); + _shouldLog(logLevel) { + logLevel = normalizeLogLevel(logLevel); + return logLevel === 0 || (this.isEnabled() && this.getLevel() >= logLevel); } - _getLogFunction(priority, message, method, args = [], opts) { - if (this._shouldLog(priority)) { + _getLogFunction(logLevel, message, method, args = [], opts) { + if (this._shouldLog(logLevel)) { // normalized opts + timings - opts = normalizeArguments({priority, message, args, opts}); + opts = normalizeArguments({logLevel, message, args, opts}); method = method || opts.method; assert(method); @@ -339,40 +347,42 @@ in a later version. Use \`${newUsage}\` instead`); Log.VERSION = VERSION; -// Get priority from first argument: -// - log(priority, message, args) => priority +// Get logLevel from first argument: +// - log(logLevel, message, args) => logLevel // - log(message, args) => 0 -// - log({priority, ...}, message, args) => priority -// - log({priority, message, args}) => priority -function normalizePriority(priority) { - let resolvedPriority; +// - log({logLevel, ...}, message, args) => logLevel +// - log({logLevel, message, args}) => logLevel +function normalizeLogLevel(logLevel) { + let resolvedLevel; - switch (typeof priority) { + switch (typeof logLevel) { case 'number': - resolvedPriority = priority; + resolvedLevel = logLevel; break; case 'object': - resolvedPriority = priority.priority || 0; + // Backward compatibility + // TODO - deprecate `priority` + resolvedLevel = logLevel.logLevel || logLevel.priority || 0; break; default: - resolvedPriority = 0; + resolvedLevel = 0; } - // 'log priority must be a number' - assert(Number.isFinite(resolvedPriority) && resolvedPriority >= 0); + // 'log level must be a number' + assert(Number.isFinite(resolvedLevel) && resolvedLevel >= 0); - return resolvedPriority; + return resolvedLevel; } // "Normalizes" the various argument patterns into an object with known types -// - log(priority, message, args) => {priority, message, args} -// - log(message, args) => {priority: 0, message, args} -// - log({priority, ...}, message, args) => {priority, message, args} -// - log({priority, message, args}) => {priority, message, args} +// - log(logLevel, message, args) => {logLevel, message, args} +// - log(message, args) => {logLevel: 0, message, args} +// - log({logLevel, ...}, message, args) => {logLevel, message, args} +// - log({logLevel, message, args}) => {logLevel, message, args} export function normalizeArguments(opts) { - const {priority, message} = opts; - opts.priority = normalizePriority(priority); + const {logLevel, message} = opts; + opts.logLevel = normalizeLogLevel(logLevel); // We use `arguments` instead of rest parameters (...args) because IE // does not support the syntax. Rest parameters is transpiled to code with // perf impact. Doing it here instead avoids constructing args when logging is @@ -385,17 +395,17 @@ export function normalizeArguments(opts) { /* eslint-enable no-empty */ opts.args = args; - switch (typeof priority) { + switch (typeof logLevel) { case 'string': case 'function': if (message !== undefined) { args.unshift(message); } - opts.message = priority; + opts.message = logLevel; break; case 'object': - Object.assign(opts, priority); + Object.assign(opts, logLevel); break; default: diff --git a/modules/core/test/lib/log.spec.js b/modules/core/test/lib/log.spec.js index 4350dd35..573f9661 100644 --- a/modules/core/test/lib/log.spec.js +++ b/modules/core/test/lib/log.spec.js @@ -3,30 +3,30 @@ import Probe, {Log} from 'probe.gl'; import {normalizeArguments} from 'probe.gl/lib/log'; import test from 'tape-catch'; -function makeOpts(priority, message) { - return {priority, message, args: arguments}; +function makeOpts(logLevel, message) { + return {logLevel, message, args: arguments}; } const NORMALIZE_ARGUMENTS_TEST_CASES = [ { args: makeOpts(1, 'Hi', 0, 1), - opts: {priority: 1, message: 'Hi', args: [0, 1]} + opts: {logLevel: 1, message: 'Hi', args: [0, 1]} }, { args: makeOpts('Hi', 0, 1), - opts: {priority: 0, message: 'Hi', args: [0, 1]} + opts: {logLevel: 0, message: 'Hi', args: [0, 1]} }, { args: makeOpts({}, 'Hi', 0, 1), - opts: {priority: 0, message: 'Hi', args: [0, 1]} + opts: {logLevel: 0, message: 'Hi', args: [0, 1]} }, { - args: makeOpts({priority: 3, color: 'green'}, 'Hi', 0, 1), - opts: {priority: 3, color: 'green', message: 'Hi', args: [0, 1]} + args: makeOpts({logLevel: 3, color: 'green'}, 'Hi', 0, 1), + opts: {logLevel: 3, color: 'green', message: 'Hi', args: [0, 1]} }, { - args: makeOpts({priority: 3, color: 'green', message: 'Hi', args: [0, 1]}), - opts: {priority: 3, color: 'green', message: 'Hi', args: [0, 1]} + args: makeOpts({logLevel: 3, color: 'green', message: 'Hi', args: [0, 1]}), + opts: {logLevel: 3, color: 'green', message: 'Hi', args: [0, 1]} } ]; @@ -143,14 +143,14 @@ test('Log#table', t => { test('Log#get', t => { const log = new Log({id: 'test'}); t.ok(log instanceof Log, 'log created successfully'); - t.doesNotThrow(() => log.get('priority'), "log.get('priority') works"); + t.doesNotThrow(() => log.get('level'), "log.get('level') works"); t.end(); }); test('Log#set', t => { const log = new Log({id: 'test'}); t.ok(log instanceof Log, 'log created successfully'); - t.doesNotThrow(() => log.set('priority', 1), "log.set('priority', 1) works"); + t.doesNotThrow(() => log.set('level', 1), "log.set('level', 1) works"); t.end(); });