Constructor
new ve.Filibuster()
#
A scrupulous event logger that logs state at every function call, and shortlists potentially significant observations for strict scrutiny.
Functions are wrapped to log entry/exit. This creates a comprehensive log of every watched function call (typically thousands per keystroke), together with the corresponding call stack.
Observer callbacks can be registered to watch certain global values (e.g. the DOM/DM content and selection). These at every watched function entry/exit, and when there is a change (typically a few times per keystroke), an observation is logged. Each observation shows the state change and call stack, and has a log number that points into the full call log.
Function wrapping generally takes place after object initialization. That means property lookups that have already happened (e.g. through .bind or setTimeout in a constructor) will not pass through the wrapper.
This code is inspired by United States v. Carolene Products Company, 304 U.S. 144 (1938), Footnote Four.
- Source:
A scrupulous event logger that logs state at every function call, and shortlists potentially significant observations for strict scrutiny.
Methods
clearLogs()
#
Clears logs, without detaching observers
- Source:
getObservationsHtml([branchPath]) → {string}
#
Get an HTML representation of part of the call tree, opened at each observation
In general, building HTML fragments like this is ugly; but this turns out to give better performance if the HTML representation is really large.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
branchPath |
Array.<number> |
optional |
Path to the part of the tree to represent |
- Source:
Returns:
HTML representation
- Type
- string
Get an HTML representation of part of the call tree, opened at each observation
In general, building HTML fragments like this is ugly; but this turns out to give better performance if the HTML representation is really large.
log(funcName, action, [args], [returned])
#
Log a function call. Called at the start and end of every monitored function call.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
funcName |
string | The name of the function |
|
action |
string | The function call phase: call|return|throw |
|
args |
Array |
optional |
The call arguments (if action === 'call') |
returned |
any |
optional |
The return value (if action === 'return') |
- Source:
observe(action)
#
Calls each observer, logging an observation if a change is detected. Called at the start and end of every monitored function call.
Parameters:
| Name | Type | Description |
|---|---|---|
action |
string | The function call phase: call|return|throw |
- Source:
setObserver(name, callback) → {ve.Filibuster}chainable
#
Attaches an observer callback. The callback returns a value representing the current state, which must be a string (this ensures state values are immutable, comparable with strict equality and easily dumpable).
The observer will be called before and after every function call. An observation is logged every time there is a difference between the current return value and the previous one.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string | The name of the observer, for display in the logs. |
callback |
function | The callback; must return a string |
- Source:
Returns:
- Type
- ve.Filibuster
start()
#
Start logging
- Source:
stop()
#
Stop logging
- Source:
wrapClass(klass, [nowrapList]) → {ve.Filibuster}chainable
#
Wrap the functions in a class with wrappers that perform logging.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
klass |
Object | The class with the function as a property |
|
nowrapList |
Array.<function()> |
optional |
Functions that should not be wrapped |
- Source:
Returns:
- Type
- ve.Filibuster
wrapFunction(container, klassName, fnName) → {ve.Filibuster}chainable
#
Replace a reference to a function with a wrapper that performs logging.
Note that the same function can be referenced multiple times; each reference would need wrapping separately.
Parameters:
| Name | Type | Description |
|---|---|---|
container |
Object | The container with the function as a property |
klassName |
string | The name of the container, for display in the logs |
fnName |
string | The property name of the function in the container |
- Source:
Returns:
- Type
- ve.Filibuster
wrapNamespace(ns, nsName, [nowrapList]) → {ve.Filibuster}chainable
#
Recursively wrap the functions in a namespace with wrappers that perform logging.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
ns |
Object | The namespace whose functions should be wrapped |
|
nsName |
string | The name of the namespace, for display in logs |
|
nowrapList |
Array.<function()> |
optional |
Functions that should not be wrapped |
- Source:
Returns:
- Type
- ve.Filibuster
clonePlain(val, [seen]) → {Object|string|number|null}static
#
null}static
#
Get a plain-old-data deep clone of val.
The resulting value is easily dumpable, and will not change if val changes.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
val |
Object
|
string
|
number
|
undefined
|
null
|
Value to analyze |
|
seen |
Set |
optional |
Seen objects, for recursion detection |
- Source:
Returns:
Plain old data object
- Type
-
Object
|
string
|
number
|
null