Class: Tati

Tati(step_callback, stop_callback, error_callback, use_worker, default_root)

new Tati(step_callback, stop_callback, error_callback, use_worker, default_root)

Creates an instance of Tati. There can be multiple instances and each can be controlled separately.

Parameters:
Name Type Default Description
step_callback function null

The callback handler for stepping. It is called before the runner runs a breakpoint or steps to the next line. The row and column of the next step is given as the first and second arguments. If the watch flag is set, a third argument of watches values is also passed to the callback. The watched values is a dictionary, containing values of the local variables before running that step. If a variable is shadowed by another, the most recent value is shown.

If the step callback returns true, the execution will be paused until one of the functions step() or continue() is called. If it returns false the execution continues to the step or breakpoint.
stop_callback function null

Is called when the running of the code is finished.
error_callback function null

Is called when there is an error in parse or run time. The first and second arguments are the line and column, third argument would be the type of error (parse or runtime), and the forth would be the error description.

In case of parser errors, if error_callback argument is given to the constructor, Tati will call it.

In case of runtime errors, if error_callback argument is given to the constructor, Tati will call it. But it will not cancel the event or stop its propagation so it doesn't interfere with any other code handling mechanism.
use_worker boolean false

If set, the debugger will run in a web worker, much safer but communication with it will be limited so the context should be plain object and the script won't be able to interact with any other object (like DOM) directly.
default_root boolean

The this of the script being run. It is an empty object {} by default. It is important because it masks the Tati object or the worker that the script is being debugged in. If you want to set it to another object this is the way, but note that if use_worker is set to true, it will not work as expected because of the access limitations.
Source:

Methods

clearAllBreakpoints()

Clears all the breakpoints.

Source:

clearBreakpoint(line)

Clears the breakpoint on the given line.

Parameters:
Name Type Description
line integer

The breakpoint line.
Source:

configureUIRefreshRate(ui_refresh_steps, ui_refresh_time)

Configures the UI refresh checking. This is to make sure UI is responsive and specially the process is pausable, which cannot be ensured on every cycle because of performance considerations. As a result, UI refresh config is not for a precise flow control, for a precise control use the step_callback return value. For more info see Tati#constructor.

Parameters:
Name Type Description
ui_refresh_steps integer

How many steps to take before refreshing the UI.
ui_refresh_time integer

The time it will wait before continuing the process.
Source:

continue(get_worker_context_on_callback)

Runs to the next breakpoint or end. It will call the step_callback that was given to constructor on reaching a breakpoint.

Parameters:
Name Type Default Description
get_worker_context_on_callback boolean true

see Tati#step
Source:

debug(run_to_breakpoint)

Runs the prepared code with the debug codes. You can step line by line or run until reaching a breakpoint. It will call the step_callback that was given to constructor.

Parameters:
Name Type Default Description
run_to_breakpoint boolean false

If true it will continue running until reaching a breakpoint. If false, it will step line by line.
Source:

getContextList()

Returns the list of context variables.

Source:

getContextValue(varname)

Returns the value of a context variable. This can be used to access the results of the script being debugged. Of course, the only types that can be modified from inside the scripts are arrays and objects, i.e. the variables that are passed by reference and not by value. This will still be true when using workers, the only difference is that a cloning will be applied and the results will only contain plain objects. See also Tati#getWorkerContext

Parameters:
Name Type Description
varname string

The variable name.
Source:

(async) getWorkerContext()

This is used to update the context copy outside the worker. Note that this is not usually needed as Tati updates the context values before calling the step_callback, unless the get_worker_context_on_callback parameter is set to false. It may be needed when the context variables are big and transmitting them between the user instance and the worker are intensive. In such cases, if the user needs to check the new context values, they should call this before getting the context.

Note that this function is asynchronous, so you may need to use it with an await directive.

Source:

pause(get_worker_context_on_callback)

Pauses the script. When the script is running an intensive loop or process, checking for pause command will be done in intervals, which can be configured using Tati#configureUIRefreshRate.

When an script with a timeout or interval is being debugged but no breakpoint is set, pause will be applied on the next callback, Tati will prevent timer callback execution, but it doesn't stop the runtime event loop, so they will expire as defined.

Also note that Tati can only pause inside the given script and cannot enter the called functions that are defined elsewhere, i.e. native functions or external libraries.

Parameters:
Name Type Default Description
get_worker_context_on_callback boolean true

see Tati#step
Source:

prepare(code, watch_locals, step_loop_args, is_module)

Parses the given code, and prepares it for the flow with control, throws exception if there is a syntax problem in code.

Parameters:
Name Type Default Description
code string

The javascript code to compile/run.
watch_locals boolean true

If set, the callback will receive a snapshot of the local variables in an object too.
step_loop_args boolean true

If set, it will also step into loop test and update expressions, like i<n and i++ in the loop:

       for( let i=0; i<n; i++ ) {...}
is_module boolean false

If set, the code will be treated as module, i.e. import and export statements will work, otherwise they will raise an unexpected token error in parse time.
Source:

run()

Runs the prepared code as it is, without the debug codes. The only difference is that it is processed anyway, so the flow and the environment of the two debug/run procedures are the same.

Source:

setAllBreakpoints()

Sets all breakpoints. Breakpoints should be in the form of { 5: true, 10: true } where the keys are the line numbers and the breakpoint is only set if the value is exactly true.

Source:

setBreakpoint(line)

Sets a breakpoint on the given line.

Parameters:
Name Type Description
line integer

The breakpoint line.
Source:

(async) setContext(context, masked)

Sets context variables. The members of the context will be set as given in this object. The masked argument can be used to define the variables and objects to be masked. Note that the masked are given in a list of strings.

k.setContext({foo:123, bar:"hello"}, [document, window]);

The masked list is not necessary, and if not set, the masked list contains three predefined elements: globalThis, self and the class name of Tati, which is normally Tati itself.

This function should be called before calling prepare if the keys of the context or the members of the masked list are changed. But it won't be necessary if only the values of context variables are changed later.

Note that if use_worker is set to true in the constructor, the worker context objects are clones and are not directly accessible. So directly modifying the value of context variables won't work and you should use setContext or setContextVariable methods. Also note that the context object must be a plain object when using workers. Tati will automatically convert context variables to plain objects when using workers, which means the functions will be converted to undefined.

This function is asynchronous, so you may want to use await to make sure the context is set accordingly.

Parameters:
Name Type Description
context object

The new context object. If use_worker is set, it will be cloned to a plain object.
masked Array

The list of the objects and variables to be masked to undefined.
Source:

(async) setContextVariable(varname, value)

Sets or defines context variables. Like setContext, the prepare function should be called after adding new context properties. And if use_worker is set true, the clones of the set values will be used in the worker.

This function is asynchronous, so you may want to use await to make sure the context is set accordingly.

Parameters:
Name Type Description
varname string

The variable name.
value any

The new value. If use_worker is set, it will be cloned to a plain object.
Source:

step(get_worker_context_on_callback)

Steps to the next line/expression. It will call the step_callback that was given to constructor.

Parameters:
Name Type Default Description
get_worker_context_on_callback boolean true

When using workers, Tati updates the context values before calling the step_callback, unless the get_worker_context_on_callback parameter is set to false. It may be needed when the context variables are big and transmitting them between the user instance and the worker are intensive. In such cases, if the user needs to check the new context values, they should call Tati#getWorkerContext before getting the context.
Source: