Job

Job is a class of single-use objects created for each execution of a business method taken from Application's modules according to its namingConventions.

(The name means job as in Queueing theory, not Oracle Database's periodic tasks)

This class implements the basic workflow:

• take this.request (a plain object);
• determine this.method to call (if null, do nothing more);
• execute it, either obtaining this.result or catching this.error;
• finally, release all resources possibly used.

Every step is transparently tracked down. The execution time can be limited.

Job is presumed to never be inherited from. Its instances are configured by parent JobSources.

Properties

Private

Name	Description
[Symbol('todo')]	An Array of Promises to be awaited for during outcome ()
[Symbol('timestamps')]	An object of event-to-timestamp pairs plus the 'created' key with the constructor call timestamp
[Symbol('maxLatency')]	The maximum time between the constructor call and the end or error event, Infinity by default
[Symbol('minLatency')]	The minimum time between the constructor call and the next event, 0 by default

Public

Name	Description
app	the Application instance this job belongs to
src	the JobSource this job comes from (if any)
parent	absent by default, by convention this property should be set to this by a job creating another job.
id	the unique identifier of this job to use in logs etc. By default, is generated with crypto.randomUUID, but this can be overridden by setting id in generators object
request	request parameters, an an Object. Think PHP's $_REQUEST generalization.
user	By convention, this property must represent the system's actor performing the actual Job: for security checks, logging etc. Missing by default.
method	the business method to be executed, with [ModuleMap.MODULE] and [ModuleMap.METHOD_NAME] properties set
module	the module containing the business method to be executed: fetched from method [ModuleMap.MODULE]
result	the result returned by the business method and to be returned by outcome ()
error	the error thrown by the business method and to be thrown by outcome (), with [Job.INSTANCE] set to the originated job
logger	A winston Logger
tracker	the Tracker listening to the job's events and registering it with logger
[Tracker.LOGGING_DETAILS]	computed via src.getJobLoggingDetails
[Tracker.LOGGING_ID]	computed as id
[Tracker.LOGGING_PARENT]	computed as src
[Tracker.LOGGING_EVENTS]	set from app.globals entry, adjusted with src.globals. See also Application's default globals

Constructor

Never to be called directly. Job instances must be produced only by calling the factory method createJob ().

Methods

Application level

outcome ()

This asynchronous method implements the job's lifecycle:

• calling app.getMethod (request) to determine the method to execute;
• invoking callMethod with the business method and then:
  • if it throws an Error, set it to error and rethrow;
  • if it throws something other, set to error () and rethrow a NotAnError value;
  • otherwise, set the output value to result and return it.

At each step but the last one, outcome () calls broadcast () with the corresponding event name to process asynchronous event handlers before proceeding to the next stage. The next event is just emitted, so all its handlers must be synchronous and neither of them can throw an error.

Each event handler defined as a (not arrow) function sees the Job instance as this and can modify its content. The execution order is fixed, so for each event subsequent handlers see the job state modified by previous ones. In particular, if the business method throws something, the error property may be rewritten by error handlers and if finally it gets undefined, outcome () returns undefined instead of throwing anything.

raise (message, payload = {})

This method, designed to be called from business methods, throws a Job.CustomError instance with the given message and an extra [Job.PAYLOAD] property. Moreover, if the payload is a non null, object all of its properties are copied into the error instance.

resources (clazz)

This generator method iterates over all job's resources provided by pools of a given clazz.

waitFor (promise)

This synchronous method registers the given promise to be awaited for before outcome () to proceeding to the next stage. It is to be called from event handlers.

fail (error)

This is a wrapper around waitFor that postpones a Promise immediately rejecting with the given error.

Internal

callMethod (func)

This asynchronous method invokes func as a method of this job and, normally, returns its result or rethrows the error. If [Symbol('maxLatency')] is finite and the time is out, throws an expirationError () instead.

expirationError ()

This synchronous method returns (not throws) an Error with the message "Timeout expired".

getTimeLeft (period)

This synchronous method returns period minus the number of milliseconds elapsed from the job creation.

setMaxLatency (ms)

This synchronous method sets the Symbol('maxLatency') private property to the non-negative integer ms. If set to a finite number, the end event cannot occur later than ms milliseconds since the job creation. Incase of such a delay, the expirationError result is thrown.

setMinLatency (ms)

This synchronous method sets the Symbol('minLatency') private property to the non-negative integer ms. If set, the next event will be emitted not earlier than ms milliseconds since the job creation, even if the result is obtained and all resources are freed.

broadcast (event, payload)

This asynchronous method implements a single step of the job's lifecycle:

• writes the current timestamp into this [Symbol ('timestamps')] [event];
• initializes the TODO list;
• emits the event (which handlers should either be synchronous or call waitFor (promise));
• awaits for all promises from the TODO list.

Events

Name	When emitted	Purpose
init	Beginning of the lifecycle	Logging, adjusting the request content (e. g. fetching it from a stream)
start	Just before calling the method	Security checks, logging
end	The result is obtained and set as a property	Rewriting result, reporting it
error	The error is caught and set as a property	Rewriting error, reporting it
finish	Guaranteed to be emitted after all end / error handlers are done working	Cleaning up, logging
next	After asynchronous finish handlers, but not earlier than Symbol('minLatency') ms from job creation	Scheduling chained jobs. Only synchronous functions allowed