Doser

Doser is an intermediary helper object designed for assembling series of incoming objects into arrays for following batch processing.

Those batches (portions, packs) can be limited:

• by size (with the maxSize option);
• by creation time (interval);

plus, explicit calls to .flush () let you implement any additional slicing modes. Normally, both options are set, so each batch published contains at least one but no more than maxSize data items, all of them not older than interval ms.

However, the number of items received during this interval may exceed maxSize, leading to multiple batches created, Doser doesn't limit this rate. To control the bandwidth, it is presumed to feed batches to a LinkedQueue instance: the .pipe () method is provided to facilitate this.

Though, in general, Doser is completely unaware of its output destination(s). Being an EventEmitter, it just publishes {data:[...]} objects as payload for 'data' events, so you can pass it for further processing with, say, IPC or whatever. In this case, it's up to API users to care about proper error routing and to avoid hanging event handlers.

Usage

// App Init:
const {Doser, LinkedQueue} = require ('doix')

app.myDoser = new Doser (app, {
    name: 'myDoser',
//  maxSize:  ... ,
//  interval: ... // ms
})

myDoser.pipe (new LinkedQueue (app, {
  name: 'q',
  request: {type: 'batch', action: 'process'},
}))

// Some Request Handler:

app.myDoser.push ({id: 1})
app.myDoser.push ({id: 2})

app.myDoser.flush () // not needed with `maxSize` and/or `interval` set

// {type: 'batch', action: 'process', data: [{id: 1}, {id: 2}]} will be processed

// App Stop:
app.myDoser.stop ()

Constructor

This class is considered abstract parent, so the constructor should be only called through super:

new Doser (app, options)

Parameters

Name	Description
app	an Application instance.
options	a bag of options (see below)

Options

Name	Type	Default	Description
name	String		The symbolic name of the instance, seen in logs
interval	Number		The interval, ms, for automatic flush ()
maxSize	Number	Infinity	The maximum batch size, before automatic flush ()

Properties

Name	Type	Description
app	Application	parent application
maxSize	Number	copy of the maxSize option
size	Number	number of items accumulated so far

Methods

flush ()

This synchronous method publishes the content accumulated so far.

If called when the buffer is empty, exits immediately without doing anything.

Otherwise,

• emits a 'data' event with {data:[...]}payload;
• recreates the internal buffer.

It's automatically called:

• by push (), when maxSize is reached;
• by the internal timer every interval ms, if configured.

pipe (linkedQueue)

This synchronous method subscribes linkedQueue to this instance's 'data' event the way that each batch published by the Doser is mapped into a corresponding LinkedQueue's {data: [...], ...} incoming request.

push (request)

This synchronous method push()es the request into the internal buffer.

And, if this makes it maxSize long, calls flush ().

stop ()

This synchronous method

• stops the internal timer (if any);
• makes the Doser instance unusable (next calls to push () throw errors);
• performs the ultimate flush () call;
• emits the 'finish' event.

Automatically called on app's 'finish'.