Basic Formatting Utilities

Overview

This NPM module is a development/debugging tool designed to display the contents of one or more server-side objects as HTML tables.

This utility is designed to run inside a stateless container. Therefore, the generated HTML has been designed such that it will not make any further calls back to the app that generated it because that app probably no longer exists.

The screen shot below shows what the first few properties of the NodeJS process object might look like when displayed using the HTML generated by this utility.

Behaviour

• Object properties are listed in alphabetic order
• Only object properties of type Object, Array, Map or Set are considered expandable
• Click on the expand/collapse button in the Type column to hide or display this data
• By default:
  • Expandable object properties will be displayed in a collapsed state
  • Object properties of types Function and GeneratorFunction will be suppressed from the display
  • If you choose to display functions names (by calling show_fns()), their source code of will not be displayed

But Why?

When developing NodeJS apps, I frequently want to see inside the server-side objects with which I'm working. This is particulary true when I'm learning my way around a new framework.

To see inside objects, people typicially dump the object contents to the console using JSON.stringify; however, this approach has two problems:

1. The string representation created by JSON.stringify (even with the formatting options) can be difficult to read - especially if the object is large and deep
2. There is a more serious problem however: JSON.stringify() explodes when passed an object containing circular references

Therefore, rather than resorting to the tedious, trial-and-error approach of repeatedly calling JSON.stringify within a try/catch block, I decided to create a more user-friendly result by transforming the object into an HTML table whose rows could be expanded or collapsed as necessary.

Usage

The show_object function transforms a JavaScript object into an HTML table. If any property of this object is considered expandable (I.E. is of type Map, Object, Array or Set), then this property value will itself be transformed into a nested HTML table.

Transformation of expandable properties continues recursively until the pre-determined depth limit is reached. This is how I avoid circular references blowing up in my face...

By default, the depth limit is set to 3, but this can be adjusted by passing a positive integer to set_depth_limit()

By default, object properties of type Function or GeneratorFunction are suppressed altogether from the display. If however, you wish to display these properties, then call function show_fns().

IMPORTANT
Function source code will never be displayed.

Typically, the HTML generated by this utility will form just a fragment of some larger Web page.

Example 1: Display a Single Object as an HTML <DIV>

Call show_object to transform the contents a server-side object into an HTML <DIV> containing a <TABLE>:

var bfu     = require('basic-formatting-utils')
var request = ... /* Get an HTTP request object from somewhere */

var obj_as_html_div = bfu.show_object("HTTP Request", request)

Example 2: Display a Single Object as an Entire HTML Page

Enclose the call to show_object within calls to as_body and as_html in order to generate a complete HTML page that then wraps the <DIV> fragment.

We will also display the names of properties of type Function and GeneratorFunction:

var bfu     = require('basic-formatting-utils')
var request = ... /* Get an HTTP request object from somewhere */

bfu.show_fns()

var obj_as_html_page = 
  bfu.as_html([]
  , bfu.as_body([]
    , bfu.show_object("HTTP Request", request)
    )
  )

Example 3: Display Multiple Objects as an HTML <DIV>

Call show_objects (plural) to transform multiple objects into separate <DIV> elements that are then returned within a parent <DIV>:

var bfu     = require('basic-formatting-utils')
var request = ... /* Get an HTTP request object from somewhere */
var event   = ... /* The HTTP event that invoked this function */

bfu.show_objects([
  {title: "HTTP request", value: request}
, {title: "HTTP event",   value: event}
])

Example 4: Convenience Functions

There are two hard-coded functions that transform the NodeJS process and global objects respectively into HTML <DIV> fragments.

var bfu = require('basic-formatting-utils')
    
var process_as_html_div = bfu.show_nodejs_process()
var global_as_html_div  = bfu.show_nodejs_global()

API

Low-level Utilities

Name	Return Type	Description
package_version	String	Returns this utility's current package version
sizeOf	Number	For any object for which isExpandable returns true (see below), this function returns the number of enumerable elements/properties. Returns 0 for all other data types

Datatype Identifiers

Name	Return Type	Description
typeOf	String	Returns the actual data type of the object
isOfType	Function	Partial function that returns a function to check for a specific data type. E.G. If you want your own type checking function to test for an ArrayBuffer, then you could write var isArrayBuffer = isOfType("ArrayBuffer")
isArray	Boolean	Does exactly what it says on the tin...
isBigInt	Boolean	Does exactly what it says on the tin...
isExpandable	Boolean	Returns true only for objects of type Object, Array, Map or Set.
isFunction	Boolean	Returns true for objects of type Function or GeneratorFunction
isMap	Boolean	Does exactly what it says on the tin...
isNull	Boolean	Does exactly what it says on the tin...
isNullOrUndef	Boolean	Does exactly what it says on the tin...
isNumber	Boolean	Does exactly what it says on the tin...
isNumeric	Boolean	Returns true if the argument is either of type Number or BigInt
isObject	Boolean	Returns true both for a standard JavaScript Object and the NodeJs objects process and global. The latter two objects are included in this test because they return their own names when passed to typeOf(). The NodeJS object WebAssembly also behaves this way, but is deliberately ignored here.
isSet	Boolean	Does exactly what it says on the tin...
isSymbol	Boolean	Does exactly what it says on the tin...
isUndefined	Boolean	Does exactly what it says on the tin...

HTML Utilities

Name	Return Type	Description
as_html_el	Function	A partial function that accepts an HTML tag name and returns a function requiring two arguments. See as_<tag_name> below.
as_<tag_name>	String	A set of functions generated by calling the partial function as_html_el. E.G. to create a function that generates an HTML paragraph element, you could write: var as_p = as_html_el("p") Function as_p then requires two parameters: An array of the element's property values. Pass an empty array if the element does not need any defined properties The element's content in a form that is either a string, or where calling that object's toString() function returns something useful Any content passed to an empty HTML element (such as img) will be ignored E.G. To generate an HTML <table> element having some id property and where all the table rows have been built up in some accumulator array called acc, the call would be something like: as_table( ["id='someTableId'"] , acc.join("") )
get_depth_limit	Number	Returns the current recursion depth limit for displaying nested objects
set_depth_limit	Number	Sets a new recursion depth limit for displaying nested objects. The default depth is 3.
show_fns	Boolean	Switches on the display of object properties of type Function
hide_fns	Boolean	Switches off the display of object properties of type Function

Main Entry Point

Name	Return Type	Description
show_objects	String	Takes an array as a single argument in which each element is an object containing the following two properties title - Object description Do not include any formatting or encoded characters in this description as it is used to generate the value of the collapsible DIV's id property. value - The object to be displayed E.G. To display some HTTP request object req, you would write: show_objects([ {title: "HTTP request", value: req} ]) Returns a DIV element containing the following children: A small style sheet One or more DIV elements for each received object, each of which contains: The object's title The object represented as an HTML table A small block of JavaScript that: Populates each arrow image's src property Defines the expand/collapse functions
show_object	String	Convenience function for calling show_objects when only a single object needs to be displayed. E.G. To display some existing HTTP request object req, you would write: show_object("HTTP request", req)

Convenience Functions for NodeJS Objects

Name	Return Type	Description
show_nodejs_global	String	Transforms the NodeJS global object into an HTML <DIV> fragment
show_nodejs_process	String	Transforms the NodeJS process object into an HTML <DIV> fragment

Date/Time Functions

Name	Return Type	Description
datetime_by_timezone	String	A partial function that receives the offset (in minutes) of a given timezone from UTC and returns a function, that when passed a new Date() object, returns the current time in that timezone as a human readable string. var datetime_jst = datetime_by_timezone(540) /* Japan Standard Time is UTC+9 */ var tokyo_time = datetime_jst(new Date()) var datetime_brt = datetime_by_timezone(-180) /* Brasilia Time is UTC-3 */ var brasilia_time = datetime_brt(new Date())
datetime_<timezone>	String	When passed a new Date(), returns the current time for the particular zone. The only pre-configured timezone functions are: UTC-8.0 US Pacific Standard Time (_pst) UTC-5.0 US Eastern Standard Time (_est) UTC+0.0 Greenwich Mean Time (_gmt) UTC+1.0 Central European Standard Time (_cet) UTC+5.5 India Standard Time (_ist)