Data

In this section of the guide we'll take a look at some of the important data structures that exist across the Adze API.

Collections

A Collection is simply an array of Adze log instances that extend from the BaseLog class. There are two types of instances that extend BaseLog, BundledLog and Log. You will never interact with a BaseLog instance directly.

A Log is the instance type that is created whenever you normally terminate a log.

A BundledLog is a log instance that is generated from a bundle factory. These log instances have a getter that allows you to access the log bundle.

Collections are typically used in conjunction with filter functions like filterNamespace, filterLabel, filterLevel, and filterCollection.

Interface

type Collection = BaseLog[];

Bundle Example

import { adze, createShed } from 'adze';

// Let's create a log bundle
const bundled = bundle(adze({ useEmoji: true }));

bundled().label('collect').error('This is an error!');
bundled().label('collect').info('A bundled log with namespaces.');
bundled().label('collect').success('Successfully bundled this log!');
const { log } = bundled().label('collect').log('Another log in the bundle.');

// Let's get our Collection from our bundle
const collection = log.bundle;

Shed Example

import { adze, createShed } from 'adze';

// We'll create a Shed to capture our logs
const shed = createShed();

// Let's get our collection from the Shed
const collection = shed.getCollection();

Label Data Object

A label data object is generated from a label instance. This object contains data that from globally tracked counters, timers, and MDC context.

Interface

interface LabelData {
  name: string | null;
  timeEllapsed: string | null;
  count: number | null;
}

Level Filter

A level filter type is a value that represents one or more log levels. Level Filters are used with any method that allows you to specify a target log level like addListener, filterLevel, or within the filter configurations on Adze logs.

Value	Description
'*'	Target all logs of any level.
[min, '-', max]	Targets logs with levels of min <= level <= max.
[n1, n2, n3, n*]	Array of numbers representing targeted log level numbers.

Example

import { adze, createShed } from 'adze';

// For our example, we'll create a Shed and add some listeners
const shed = createShed();

// Our first listener will target all logs of any level
shed.addListener('*', (data, render, printed) => {
  // do stuff...
});

// Our next listener will target logs with a level within our range
shed.addListener([2, '-', 5], (data, render, printed) => {
  // do stuff...
});

// Our last listener will target logs of specific levels
shed.addListener([2, 3, 6, 8], (data, render, printed) => {
  // do stuff...
});

Output

Log Data

The log data object contains all of the important meta data from a log's instance. The log data object is used throughout the Adze API. For example, when a log listener on a Shed is fired, the callback function will be invoked with two parameters; the log data object and a log render.

A log data object can be manually retrieved from a log instance using the data getter.

A log data object can also be used to create a clone of a log by hydrating a new log instance from the log data object.

Final log data extends log data and changes the possible values of some properties. Certain methods require final log data to be provided to it. Use the isFinalLogData type guard to verify it.

Property showTimestamp available in Version >= 1.1

Interface

// The log data object's interface
interface LogData {
  args: unknown[] | null;
  assertion?: boolean;
  cfg: Defaults;
  context: MetaData;
  definition: LogLevelDefinition | null;
  dumpContext: boolean;
  expression?: boolean;
  isSilent: boolean;
  printed: boolean;
  showTimestamp: boolean;
  label: LabelData;
  level: number | null;
  meta: MetaData;
  modifierQueue: Array<(ctxt: BaseLog) => void>;
  namespace: string[] | null;
  stacktrace: string | null;
  timeNow: string | null;
  timestamp: LogTimestamp | null;
}

// This is the definition for log meta data after termination
interface FinalLogData extends LogData {
  level: number;
  definition: LogLevelDefinition;
  args: unknown[];
  timestamp: LogTimestamp;
}

Property Descriptions

Name	Description	Documentation
args	Arguments provided to the log instance.	-
assertion	The boolean result of the assertion expression on the log instance.	assert
cfg	The configuration of the instance.	Config
context	The context value of an MDC thread.	MDC
definition	Configuration of the log level of the instance.	Log Level Definition
dumpContext	Boolean indicating if the mapped diagnostic context (MDC) should be rendered.	MDC
expression	The boolean result of the test expression on the log instance.	test
isSilent	Boolean value indicating if the log should execute silently.	silent
printed	Boolean value indicating if the log has been printed to the console (versions >= 1.3.0).	Terminated Log Object
showTimestamp	Boolean value indicating that the log should render an ISO 8601 timestamp.	timestamp
label	The values of a label instance attached to the log instance.	Label
level	The log level of the instance.	Log Level Definition
meta	Meta data attached to the instance.	meta
modifierQueue	The queue of modifiers that will be executed against the log instance when it is terminated.	-
namespace	Array of namespaces associate to the log instance.	namespace / ns
stacktrace	A stringified stacktrace that leads up to when the log instance was created.	Config
timeNow	The timestamp from executing a timeNow modifier.	timeNow
timestamp	Object containing time signatures of when the log instance was created.	Log Timestamp

Example

import { adze } from 'adze';

// Let's create a log instance with some various properties
const { log } = adze()
  .ns('foo')
  .label('bar')
  .timeNow.info('Some important information.');

// Let's get the log data by using the data getter on the instance
const data = log.data;

adze().log('Displaying the value of the log data object!', data);

Output

Log Render

A log render is returned as a sub-property of a terminated log object. The log render is a tuple in the form of [method, args] that you can use to re-render your log exactly how the Adze log instance rendered it. Here is an example of how render a log using a log render:

Manual Example

NOTE: This is not the recommended way of doing this. Please refer to render.

import { adze } from 'adze';

// Let's generate a log and get its render
const { render } = adze().info('This is an info log');

// Then we will destructure the log to get the method and arguments
const [method, args] = render;

/* And now we can re-render the log by calling the
   console method and spreading the args */
console[method](...args);

Output

Log Timestamp

The log timestamp data object contains timestamp values in multiple formats from when the log instance was terminated.

utcTimezoneOffset and iso8601 properties: Version >= 1.1

Interface

interface LogTimestamp {
  unixMilli: number;
  utc: string;
  utcTimezoneOffset: string;
  iso8601: string;
}

Example

import { adze, createShed } from 'adze';

// Let's generate a log and get its instance
const { log } = adze().info('This is an info log');

// Now let's export its meta data and select the timestamp data object
const timestamp = log.data.timestamp;
// => { unixMilli: 1617827970649, utc: 'Wed, 07 Apr 2021 20:39:30 GMT', utcTimezoneOffset: '+04:00', iso8601: '2021-04-07T20:39:30+04:00' }

Terminated Log Object

After an Adze log has been terminated a Terminated Log object will be returned (with a couple of exceptions, like clear). A terminated log object consists of three parts, the Log Instance, the Log Render, and the printed value that indicates if the log was printed to the console.

The log instance is the reference to the instance that was terminated. You can use this to get meta data about the Log or get a collection of logs if the log was bundled.

printed property supported in versions >= 1.3.0

Interface

// Versions < 1.3.0
interface TerminatedLog<T extends BaseLog> {
  log: T;
  render: LogRender | null;
}

// Versions >= 1.3.0
interface TerminatedLog<T extends BaseLog> {
  log: T;
  render: LogRender | null;
  printed: boolean;
}