Improve docs for Operation hooks

[bajtos]

Judging by the recent discussions in GitHub issues, the current minimal documentation does not make it clear how to correctly use the hooks and why they are designed in a seemingly unintuitive way.

The goal of this task is to write down all knowledge that's in Miroslav's head at the moment, add information from comments in the issues linked below, and beef up the doc page Operation hooks.

A list of pain-points can be found here:

• Pain-points of the new Operation hooks loopbackio/loopback-datasource-juggler#482

Related issues:

• updateAttributes operational hooks: use instance, not where loopbackio/loopback-datasource-juggler#481
• Operational hook 'after delete' should receive id(s) loopbackio/loopback-datasource-juggler#474
• Fix #481 and #474 loopbackio/loopback-datasource-juggler#483
• Shared state for hooks invoked for a single operation loopbackio/loopback-datasource-juggler#484
• https://github.com/strongloop/loopback-datasource-juggler/pull/488/files#r25886292

[chandadharap]

I'd rather that Rand sit with you and get the info to update and improve docs, rather than you write this.

[crandmck]

Miroslav, I will go through the above issues and try to extract the pertinent info. I will likely have questions as a result.... Then let's meet and you can give me a brain dump, as Chanda suggests. You could also jot down some notes if you have some specific things you know you'd like to add to or change in the docs.

[crandmck]

This may not be completed this sprint, since the feature is being significantly reworked.

Miroslav said:

there are still pull requests in progress that will improve certain areas, so this docs work may be a longer term affair.

[bajtos]

@crandmck first few things that are ready to be documented.

Document "hookState" - see loopbackio/loopback-datasource-juggler#485 and loopbackio/loopback-datasource-juggler#484

Capture the information from loopbackio/loopback-datasource-juggler#483 (comment). The first part explains why there is "instance" object instead of providing always a "data" object. The second part explains different use cases of hooks.

Explain why the "before delete" and "after delete" hooks don't receive a list of deleted ids, see the discussion in loopbackio/loopback-datasource-juggler#474. Explain that a naive implementation of hooks creates a race condition (loopbackio/loopback-datasource-juggler#474 (comment)) and describe how it can be avoided (loopbackio/loopback-datasource-juggler#474 (comment)).

NOTE: loopbackio/loopback-datasource-juggler#488 is adding ctx.instance to both "delete" hooks when they are deleting a single model, we will need to describe that once the PR is landed. Because batch delete is not exposed via REST API by default (IIRC), in most cases ctx.instance should be a good solution for getting data of the deleted model (including the id).

loopbackio/loopback-datasource-juggler#481 contains useful information too, e.g. the first part of loopbackio/loopback-datasource-juggler#481 (comment) explains why "updateAttributes" does not have ctx.instance.

NOTE: loopbackio/loopback-datasource-juggler#488 is adding ctx.currentInstance to "before save" hook triggered by "updateAttributes", this should somewhat alleviate the problem.

[bajtos]

Some material for starting a FAQ section: loopbackio/loopback-datasource-juggler#482 (comment)

[bajtos]

Re-estimating to 1 story point. I'll only gather more pointers to relevant comments and pull requests, so that @crandmck can write the content himself.