debugtrace-js v2.1.2

= 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 | | 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.txtThe 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