= debugtrace-js

link:README_ja.asciidoc[[Japanese]]

debugtrace-js is a library that outputs trace logs when debugging JavaScript programs. It is available on Node.js 10 or later. + By embedding debugtrace.enter() and debugtrace.leave() at the start and end of functions, you can output the execution status of the JavaScript program under development to the log.

=== 1. Features

• Automatically outputs invoker's function name, source file and line number.
• Automatically indents the log with nesting methods and objects.
• There are no dependent libraries at run time.

=== 2. How to use

Do the following for debug target and related methods.

. Insert debugtrace.enter() at the beginning of functions. . Insert debugtrace.leave() at the end of functions or just before the return statement. . Insert debugtrace.print('foo', foo) to output arguments, local variables and return value to the log if necessary.

The following is an example of JavaScript source used debugtrace-js methods and the log of when it has been executed.

[source,javascript] .ReadmeExample.js

// ReadmeExample.js const debugtrace = require('debugtrace-js') // ToDo: Remove after debugging

class Contact { constructor(id, firstName, lastName, birthday) { this.id = id this.firstName = firstName this.lastName = lastName this.birthday = birthday } }

const func2 = () => { debugtrace.enter() // ToDo: Remove after debugging let contacts = [ new Contact(1, 'Akane' , 'Apple', new Date(Date.UTC(1991, 2, 3))), new Contact(2, 'Yukari', 'Apple', new Date(Date.UTC(1992, 3, 4))) ] debugtrace.print('contacts', contacts) // ToDo: Remove after debugging debugtrace.leave() // ToDo: Remove after debugging }

const func1 = () => { debugtrace.enter() // ToDo: Remove after debugging debugtrace.printMessage('Hello, World!') func2() debugtrace.leave() // ToDo: Remove after debugging }

func1()

.debugtrace.log

2022-03-13 09:29:51.293+09:00 debugtrace-js 2.1.2 (Node.js 16.13.2) 2022-03-13 09:29:51.304+09:00 2022-03-13 09:29:51.305+09:00 Enter func1 (ReadmeExample.js:25) 2022-03-13 09:29:51.305+09:00 | Hello, World! (ReadmeExample.js:26) 2022-03-13 09:29:51.305+09:00 | Enter func2 (ReadmeExample.js:15) 2022-03-13 09:29:51.307+09:00 | | contacts = [ 2022-03-13 09:29:51.307+09:00 | | (Contact){ 2022-03-13 09:29:51.307+09:00 | | id: 1, firstName: (length:5)'Akane', lastName: (length:5)'Apple', 2022-03-13 09:29:51.307+09:00 | | birthday: 1991-03-03 09:00:00.000+09:00 2022-03-13 09:29:51.307+09:00 | | }, 2022-03-13 09:29:51.308+09:00 | | (Contact){ 2022-03-13 09:29:51.308+09:00 | | id: 2, firstName: (length:6)'Yukari', lastName: (length:5)'Apple', 2022-03-13 09:29:51.308+09:00 | | birthday: 1992-04-04 09:00:00.000+09:00 2022-03-13 09:29:51.308+09:00 | | } 2022-03-13 09:29:51.308+09:00 | | ] (ReadmeExample.js:20) 2022-03-13 09:29:51.309+09:00 | Leave func2 (ReadmeExample.js:21) duration: 00:00:00.003 2022-03-13 09:29:51.309+09:00 Leave func1 (ReadmeExample.js:28) duration: 00:00:00.004

=== 3. Function List

This library has the following methods. These have no return value.

[options="header"] .Function List |=== |Function Name|Arguments|Return Value|Description |enter |None |None |Outputs function start to log.

|leave |None |None |Outputs method end to log.

|printMessage |message: the message |the message of an argument |Outputs the message to log.

|print |name: the value name + value: the value |the value of an argument |Outputs to the log in the form of + name = value

|===

=== 4. Properties of debugtrace

The following properties can be specified for on debugtrace.

[options="header", cols="2,8"] .debugtrace.properties |=== |Property Name|Description |formatEnter |The format function of the log output when entering functions + [.small]#Example:# +    debugtrace.formatEnter = (name, fileName, lineNumber) => +       `Enter ${name} (${fileName}:${lineNumber})` [.small]#[Initial setting]# + [.small]#Parameters:# +    name: The function name +    fileName: The file name +    lineNumber: The line number

|formatLeave |The format function of the log output when leaving functions + [.small]#Example:# +    debugtrace.formatLeave = (name, fileName, lineNumber, duration) => +       `Leave ${name} (${fileName}:${lineNumber}) duration: ${duration}` [.small]#[Initial setting]# + [.small]#Parameters:# +    name: the function name +    fileName: the file name +    lineNumber: the line number +    duration: the duration since invoking the corresponding enter function

|indentString |The indentation string for code + [.small]#Example:# +    debugtrace.indentString = '| ' [.small]#[Initial setting]#

|dataIndentString |The indentation string for data + [.small]#Example:# +    debugtrace.dataIndentString = ' ' [.small]#[Initial setting]#

|limitString |The string to represent that it has exceeded the limit + [.small]#Example:# +    debugtrace.limitString = '\...' [.small]#[Initial setting]#

|cyclicReferenceString |The string to represent that the cyclic reference occurs + [.small]#Example:# +    debugtrace.cyclicReferenceString = '*** cyclic reference ***' [.small]#[Initial setting]# +

|varNameValueSeparator |The separator string between the variable name and value + [.small]#Example:# +    debugtrace.varNameValueSeparator = ' = ' [.small]#[Initial setting]# +

|keyValueSeparator |The separator string between the key and value of Map object + [.small]#Example:# +    debugtrace.keyValueSeparator = ': ' [.small]#[Initial setting]# +

|formatPrintSuffix |The format function for string added by the print function [.small]#Example:# +    debugtrace.formatPrintSuffix = (name, fileName, lineNumber) => +      ` (${fileName}:${lineNumber})` [.small]#[Initial setting]# + [.small]#Parameters:# +    name: the function name [.small]#(Not used by default)# +    fileName: the file name +    lineNumber: the line number

|formatLength |The format function for array and string length + [.small]#Example:# +    debugtrace.formatLength = length => `length:${length}` [.small]#[Initial setting]# + [.small]#Parameters:# +    length: number of elements or string length

|formatSize |The format function for Map and Set + [.small]#Example:# +    debugtrace.formatSize = size => `size:${size}` [.small]#[Initial setting]# + [.small]#Parameters:# +    size: number of elements

|minimumOutputLengthAndSize |The minimum value to output the number of elements of array, Map and Set + [.small]#Example:# +    debugtrace.minimumOutputLengthAndSize = 5 [.small]#[Initial setting]#

|minimumOutputStringLength |The minimum value to output the length of string + [.small]#Example:# +    debugtrace.minimumOutputStringLength = 5 [.small]#[Initial setting]#

|formatDate |The format function for Date + [.small]#Example:# +    debugtrace.formatDate = date => { +      let timezoneOffset = date.getTimezoneOffset() +      const offsetSign = timezoneOffset < 0 ? &#x27;+&#x27; : &#x27;-&#x27; +      if (timezoneOffset < 0) +        timezoneOffset = -timezoneOffset +      const str = date.getFullYear() + '-' + +        ('0' + (date.getMonth () + 1 )).slice(-2) + '-' + +        ('0' + date.getDate  ()   ).slice(-2) + ' ' + +        ('0' + date.getHours ()   ).slice(-2) + ':' + +        ('0' + date.getMinutes()   ).slice(-2) + ':' + +        ('0' + date.getSeconds()   ).slice(-2) + '.' + +        ('00' + date.getMilliseconds() ).slice(-3) + offsetSign + +        ('0' + Math.floor(timezoneOffset / 60)).slice(-2) + ':' + +        ('0' + timezoneOffset % 60).slice(-2) +      return str +    } [.small]#[Initial setting]# + [.small]#Parameters:# +    date: a Date

|formatTime |The format function for duration of formatLeave + [.small]#Example:# +    debugtrace.formatTime = date => +      ('0' + date.getUTCHours () ).slice(-2) + ':' + +      ('0' + date.getUTCMinutes() ).slice(-2) + ':' + +      ('0' + date.getUTCSeconds() ).slice(-2) + '.' + +      ('00' + date.getUTCMilliseconds()).slice(-3) [.small]#[Initial setting]# + [.small]#Parameters:# +    date: a duration

|formatLogDate |The format function for the log date and time + [.small]#Example:# +    [.small]#See# formatDate + [.small]#Parameters:# +    date: a log Date

|maximumDataOutputWidth |The minimum value to output the length of string + [.small]#Example:# +    debugtrace.maximumDataOutputWidth = 70 [.small]#[Initial setting]#

|collectionLimit |The limit value of elements for array, Map and Set to output + [.small]#Example:# +    debugtrace.collectionLimit = 512 [.small]#[Initial setting]#

|stringLimit |The limit value of characters for string to output + [.small]#Example:# +    debugtrace.stringLimit = 8192 [.small]#[Initial setting]#

|reflectionNestLimit |The limit value for reflection nesting + [.small]#Example:# +    debugtrace.reflectionNestLimit = 4 [.small]#[Initial setting]#

|basicPrint + [.small]#(since 2.1.0)# |The basic print function + [.small]#Example:# +    debugtrace.basicPrint = console.log [.small]#[Initial setting]# +    debugtrace.basicPrint = console.eror [.small]#[Output to stderr]#

|===

=== 5. License

link:LICENSE.txt[The MIT License (MIT)]

(C) 2015 Masato Kokubo

=== 6. Release Notes

==== debugtrace-js 2.1.1 [.small .gray]#- March 13, 2022#

• The print and printMessage functions now return the argument value.

==== debugtrace-js 2.1.1 [.small .gray]#- October 9, 2021#

• Fixed a bug that an exception is thrown when outputting a type name.
• Changed to output Node.js version at startup.

==== debugtrace-js 2.1.0 [.small .gray]#- August 9, 2021#

• Improved function output (output only the first line of the function definition)
• Added the basicPrint function
• Improved the line break handling of data output

==== debugtrace-js 2.0.0 [.small .gray]#- August 2, 2020#

• Supported Node.js 10 or later
• Improved the line break handling of data output