Ctx<T>

EVT
Home GitHub
Search…
Why EVT ?
Operator<T, U> (type)
Ctx<T>
Ctx helps detach all Handlers that were attached in the goal of acompishing a certain task once the said task is done or aborted.
Get Ctx instance usingEvt.newCtx<T>() or Evt.getCtx(obj)​
The only difference between CtxVoid and Ctx<void> is that ctxVoid.done() can be called without argument when ctx<void>.done(result)must be called with an argument (null or undefined).
ctx.done(result?)
Detach, from the Evt instances they are attached to, all Handlers bound to the context.
Calling this method causes the Evt returned by ctx.getEvtDone() to be posted.
When an fλ operator return { "DETACH": ctx }, ctx.done() is invoked.
When it returns { "DETACH": ctx, "res": result }, ctx.done(result) is invoked.
To test if ctx.done() have been invoked already you can use:ctx.getEvtDone().postCount !== 0
Returns
ReturnType<ctx.getHandlers()> All the Handlers that were bound to the context. They are now detached, calling ctx.getHandler() just after ctx.done() returns an empty array.
Parameter
T for Ctx<T>
none for VoidCtx
ctx.abort(error)
Equivalent of ctx.done() to use when the task did not go through.
When a fλ operator returns { "DETACH": ctx, "err": error }, ctx.abort(error) is invoked.
Returns
ReturnType<ctx.done()> (cf ctx.done )
Parameter
Error an error that describes what went wrong.
ctx.evtDoneOrAborted
Tracks when ctx.done or ctx.abort are invoked.
For most use cases, it is more convenient to use ctx.waitFor([timeout])
Returns
For VoidCtx an Evt that posts:
{ handlers: Handler.WithEvt[] } when ctx.done() is called.
{ error: Error, handlers: Handler.WithEvt[] } when ctx.abort(error) is called.
For Ctx<T>, an Evt that post:
{ result: Result; handlers: Handler.WithEvt[]; } when ctx.done(result) is called.
{ error: Error, handlers: Handlers.WithEvt[]; } when ctx.abort(error) is called.
Handler.WithEvt<T> is just a type alias for an object that wraps a handler and the Evt it is attached to: { handler: Handler<T, any>, evt: Evt<T> }
Example
1
import { Evt } from "evt";
2
import { EventEmitter } from "events";
3
​
4
const ctx= Evt.newCtx();
5
​
6
const evtText = new Evt<string>();
7
const evtTime = new Evt<number>();
8
​
9
evtText.$attach(
10
    text=> [ text.length ],
11
    ctx, 
12
    count => console.log("1: " + count)
13
);
14
​
15
evtTime.waitFor(
16
    time => time < 0,
17
    ctx,
18
).then(time=> console.log("2: " +  time));
19
​
20
evtText
21
    .pipe(ctx)
22
    .pipe(text => [text.toUpperCase()])
23
    .attach(upperCaseText=> console.log("3: " + upperCaseText))
24
    ;
25
​
26
Evt.merge(ctx, [ evtText, evtTime ])
27
    .attach(textOrTime => console.log("4: " + textOrTime))
28
    ;
29
​
30
const ee= new EventEmitter();
31
​
32
Evt.from<string>(ctx, ee, "text")
33
    .attach(text=> console.log("5: " + text))
34
    ;
35
​
36
​
37
evtText.post("foo"); //Prints "1: 3" "3: FOO" "4: foo"
38
ee.emit("text", "bar"); //Prints "5: bar"
39
​
40
console.log(evtText.getHandlers().length); //Prints "3"
41
console.log(evtTime.getHandlers().length); //Prints "2"
42
​
43
console.log(ee.listenerCount("text")); //Print "1"
44
​
45
ctx.evtDoneOrAborted.attachOnce(
46
    ({handlers})=> {
47
​
48
        console.log(
49
            handlers.filter(({ evt })=> evt === evtText).length +
50
            " handlers detached from evtText"
51
        );
52
​
53
        console.log(
54
            handlers.filter(({ evt })=> evt === evtTime).length +
55
            " handlers detached from evtTime"
56
        );
57
​
58
        console.log(
59
            handlers.length + " handlers detached total"
60
        );
61
​
62
    }
63
);
64
​
65
//Prints:
66
//"3 handlers detached from evtText"
67
//"2 handlers detached from evtTime"
68
//"5 handlers detached total"
69
ctx.done();
70
​
71
console.log(evtText.getHandlers().length); //Prints "0"
72
console.log(evtTime.getHandlers().length); //Prints "0"
73
console.log(ee.listenerCount("text")); //Print "0"
74
​
75
evtText.post("foo"); //Prints nothing
76
ee.emit("text", "bar"); //Prints nothing
Copied!
​Run the example​
ctx.waitFor([timeout])
Tracks via a Promise that resolves when ctx.done() or ctx.abort() is invoked.
Returns
Promise<T> (T is the type argument of Ctx<T> ) A promise that resolve when ctx.done([result]) is invoked.
If ctx.abort(error) is invoked before ctx.done() the promise rejects with error.
If timeout was specified the promise rejects if ctx.done() was not invoked within timeout milliseconds. If it happens ctx.abort(timeoutError) is internally invoked timeoutError being an instance of EvtError.Timeout.
Parameter
number Optional, number of milliseconds before the promise reject if it hasn't fulfilled within this delay.
ctx.getHandlers()
Returns
Handler.WithEvt[] The Handlers that are bound to the context alongside with the Evt instance each one is attached to. The Handlers that are bound to the context but no longer attached to an Evt are not listed ( they are usually freed from memory anyway as there should be nor reference left of them as soon as they are detached ).
Example
1
//NOTE: Equivalent to evt.detach(ctx);
2
ctx
3
    .getHandlers()
4
    .filter(({ evt }))=> evt === evtString)
5
    .forEach(({ handler })=> handler.detach())
6
    ;
Copied!
ctx.evtAttach
Returns
Evt<Handler.WithEvt<any>> An Evt that posts every time a new handler bound to the context is attached.
1
import { Evt } from "evt";
2
​
3
const evtText = new Evt<string>();
4
​
5
const ctx= Evt.newCtx();
6
​
7
ctx.evtAttach.attach(handler => console.log(handler.timeout));
8
​
9
const timeout = 43;
10
​
11
evtText.attach(timeout, ()=>{}); //Prints "43"
Copied!
​Run the example​
ctx.evtDetach
Same as ctx.getEvtAttach() but post when handlers are detached. Note that a handler being detached does not mean that it has been explicitly detached. One-time handlers and handlers that have timed out are automatically detached.
Comprehensive example
Let us consider a practical use case of Ctx. The task is to download a file, we know the size of the file to download, we have an Evt<Uint8Array> that emits chunks of data, we want to accumulate them until we reach the expected file size. Multiple things can go wrong during the download:
The user can cancel the download.
The download can take too long.
Socket may disconnect .
The socket may send more data than expected.
Our expected output is a Promise<Uint8Array> that resolves with the downloaded file or reject if anything went wrong.
This is a possible implementation using Ctx<Uint8Array>:
1
import { Evt, VoidEvt } from "evt";
2
​
3
function downloadFile(
4
    { fileSize, evtChunk, evtBtnCancelClick, evtSocketError, timeout }: {
5
        fileSize: number;
6
        evtChunk: Evt<Uint8Array>;
7
        evtBtnCancelClick: VoidEvt;
8
        evtSocketError: Evt<Error>;
9
        timeout: number;
10
    }
11
): Promise<Uint8Array> {
12
​
13
    const ctxDl = Evt.newCtx<Uint8Array>();
14
​
15
    evtSocketError.attachOnce(
16
        ctxDl,
17
        error => ctxDl.abort(error)
18
    );
19
​
20
    evtBtnCancelClick.attachOnce(
21
        ctxDl,
22
        () => ctxDl.abort(new Error("Download canceled"))
23
    );
24
​
25
    evtChunk
26
        .pipe(ctxDl)
27
        .pipe([
28
            (chunk, { byteLength, chunks }) => [{
29
                "byteLength": byteLength + chunk.length,
30
                "chunks": [...chunks, chunk]
31
            }],
32
            {
33
                "byteLength": 0,
34
                "chunks": id<Uint8Array[]>([])
35
            }
36
        ])
37
        .pipe(({ byteLength }) => byteLength >= fileSize)
38
        .pipe(({ byteLength, chunks }) => byteLength !== fileSize ?
39
            { "DETACH": ctxDl, "err": new Error("File is larger than expected") } :
40
            [chunks]
41
        )
42
        .pipe(chunks => [concatTypedArray(chunks, fileSize)])
43
        .attach(rawFile => ctxDl.done(rawFile))
44
        ;
45
​
46
    return ctxDl.waitFor(timeout);
47
​
48
}
Copied!
​Run the example​
Whether the download is successful or not this use of Ctx enforce that there is no left over handlers on the Evt passed as input once the download attempt has completed.