[Docs] Update WIP section in Sequence page

[dhmlau]

Description / Steps to reproduce / Feature proposal

Originated from the docs cleanup epic: #1908

Under Key Concepts > Sequence page, there are a few sections that are marked as "Work in Progress". We should have it updated.

Acceptance Criteria

From Sequence page, review and update accordingly for the following sections:

• Query string parameters
• Invoking controller methods
• Writing the response
• Keeping your Sequences

[bajtos]

Invoking controller methods

• How to use invoke() in simple and advanced use cases.
• Explain what happens when you call invoke()
• Mention caching use case
• Can I call invoke multiple times?

Personally, I am proposing to keep this simple for now and simply explain how to call invoke (show what we are doing in the default Sequence) and explain what happens under the hood.

We can always add more content or improve the first version later.

For controller methods

• A controller instance is instantiated from the context.
• As part of the instantiation, constructor and property dependencies are injected.
• The appropriate controller method is invoked via the chain of interceptors.
• Arguments decorated with @param are resolved using data parsed from the request.
• Arguments decorated with @inject are resolved from the context.
• Arguments with no decorators are set to undefined, which is replaced by the argument default value if it's provided.

For route handlers

• The handler function is invoked via the chain of interceptors.
• The array of method arguments is constructed using OpenAPI spec provided at handler registration time.
• Dependency injection is supported at the moment.

Writing the response

• Must call sendResponse() exactly once
• Streams?

The sequence action is called send now, not sendResponse.

I this place, I would explain that LB works differently from Express. In Express, the handler is responsible for setting response status code, headers and writing the response body. In LoopBack, controller methods and route handlers return data describing the response and it's the responsibility of the Sequence to send that data back to the client. This design makes it easier to transform the response before it's sent.

The sequence should call send with (transformed) data. Under the hood, send performs all steps required to send back the response, from content-negotiation to serialization of the response body.

LB4 does not yet provide first-class support for streaming responses, see #2230. As a short-term workaround, controller methods are allowed to send the response directly, effectively bypassing send action. The default implementation of send is prepared to handle this case, see here:

https://github.com/strongloop/loopback-next/blob/bf07ff959a1f90577849b61221b292d3127696d6/packages/rest/src/writer.ts#L22-L26

Keeping your Sequences

• Try and use existing actions
• Implement your own version of built in actions
• Publish reusable actions to npm

"Try and use existing actions" - I think this is already covered by the existing documentation, e.g. the example at the top of the page (https://loopback.io/doc/en/lb4/Sequence.html#what-is-a-sequence) shows how to use existing actions, https://loopback.io/doc/en/lb4/Sequence.html#custom-sequences shows how to extend the default sequence. As far as I am concerned, this is good enough for now. But maybe we to be more explicit about this aspect, write a short paragraph explaining that sequences can leverage default actions and point to the examples elsewhere?

"Implement your own version of built in actions" - I think this is already covered by https://loopback.io/doc/en/lb4/Sequence.html#custom-sequences.

"Publish reusable actions to npm" - I feel this is about extension authoring, IMO such content should live under Extending LoopBack. Here in key concepts, I would simply add a link pointing to a new page in Extending LoopBack. However, such page does not exist yet. I am not sure if writing it is in the scope of this user story, maybe we should create a new task to review current documentation for people that want to build and publish a custom implementation of a sequence action, and ensure all important aspects of this scenario (story) are correctly documented.

Thoughts?

As I see the placeholders, they were created in early LB4 days where our documentation was minimal. Their purpose was to serve as reminders of what content we may want to write. Since those days, a lot of new content was added, some of the new content is already covering topics listed in the reminders. IMO, we should not treat these reminders as a fixed plan to follow, a list of placeholders to fill with content. Instead, we should use them as discussion starters, as a list of topics and scenarios to cover in our docs.

[b-admike]

Thank you for the detailed background/clarification @bajtos. I agree with your points and will follow through with your proposal for the rest of the doc updates.

[b-admike]

@bajtos I agree to your proposal for Publish reusable actions to npm section and created #3021 for it.