docs: elaborate Repository.execute method

[hacksparrow]

Addresses #5264. Adds more details to the Repository.execute API doc.

Checklist

• DCO (Developer Certificate of Origin) signed in all commits
• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

[bajtos]

Please note the support for non-SQL connectors has been already landed. #3342 is mostly done, the remaining work is to investigate one test failure for PostgreSQL and update connector docs.

A detailed documentation for different execute flavors was added in #6030. The api doc comments are in DefaultCrudRepository, because I feel the content is specific to the implementation provided by loopback-datasource-juggler and our connectors.

See also loopbackio/loopback-datasource-juggler#1855.

There is also "regular" documentation in Executing database commands, it was added by #6047.

In the light of the above, your proposal seems to me as out of touch with the current status. At the same time, I see how the current ExecutableRepository API and docs are not consistent with the rest of the framework, so let's discuss how to get it on par.

[bajtos]

FYI: I removed the task "Add a MongoDB example to the Repository.execute API docs like #6453" from #3342, because the MongoDB example is already in place as far as #3342 is concerned.

[hacksparrow]

In the light of the above, your proposal seems to me as out of touch with the current status.

The repo method is indeed ready for both SQL and no-SQL, that note is meant for the feature support in our official connectors.

I have tested with MySQL connector it works fine. Looked at the Postgres connector, it should work. Looked at the MongoDB connector, it doesn't look like it would work; and when tried didn't work as expected.

When we don't have the MongoDB connector working, how do "Add a MongoDB example as part of this story."?

Or did I misunderstand something about the MongoDB connector?

[hacksparrow]

Oh, I got the MongoDB connector working. It was a case of mismatched expectation.

We should document that the result object will be whatever the underlying connector returns, and that Repository will not perform any serialization or optimization.

[hacksparrow]

@bajtos I have updated the PR.

[bajtos]

I feel this pull request is making the situation a bit messy. It does add more information to ExecutableRepository.execute, but this information is partially duplicating documentation from DefaultCrudRepository.execute and does not cover everything documented in DefaultCrudRepository.

I'd like us to step back, ask ourselves what is the goal of #5264 and how to reach it, considering all the works that has been already done in #6034.

I opened #5264 because it was not clear to me how to use execute method and found it difficult to help our users asking questions on StackOverflow without that information. #6034 added the information needed, but it may be difficult to find when looking at ExecutableRepository.execute docs.

The first question we should ask: How much juggler/connector-specific information do we want to encode into ExecutableRepository.execute? I see two options:

1. Keep ExecutableRepository.execute generic, document connector-specific stuff in DefaultCrudRepository.
2. Push connector-specific things (method overloads, API doc comments) to ExecutableRepository.execute.

If we pick the first option, then I thin we should change the signature of ExecutableRepository.execute to (...args: PositionalParameters), to make sure it covers all different connector flavors. Documentation wise, we can add links (e.g. using @see keyword) to different DefaultCrudRepository.execute flavors (SQL, MongoDB, generic). No need to duplicate the content.

If we pick the second option, then I would move most (if not all) of API docs from DefaultCrudRepository to ExecutableRepository, together with the different method overloads (SQL, MongoDB, generic). I don't know our API docs tooling will provide a link from DefaultCrudRepository.execute api docs to the method we are inheriting from (ExecutableRepository.execute). If it does not, then we should add a link from DefaultCrudRepository.execute to ExecutableRepository.execute.

To re-iterate: we already have the content written, now we need a better way how to organize it and make it easier to find, while avoiding duplication. Feel free to choose a different approach as long as it provides a good DX and meets those high-level goals.

[bajtos]

Are you sure the string 'find' is assignable to NamedParameters | PositionalParameters?

ATM, ExecutableRepository.execute provides SQL-like flavor only:

interface ExecutableRepository { 
  execute(
    command: Command,
    parameters: NamedParameters | PositionalParameters,
    options?: Options,
  ): Promise<AnyObject>;
}

To support other connectors, I had to add few more overloads in #6030:

interface ExecutableRepository { 
  // MongoDB
  execute(
     collectionName: string,
     command: string,
     ...parameters: PositionalParameters
   ): Promise<AnyObject>;

  // Other connectors
  execute(...args: PositionalParameters): Promise<AnyObject>;
}

[agnes512]

we already have the content written, now we need a better way how to organize it and make it easier to find, while avoiding duplication.

+1. IMO it would be good if we can somehow navigate to DefaultCrudRepository.execute.

[hacksparrow]

Please note the support for non-SQL connectors has been already landed. #3342 is mostly done, the remaining work is to investigate one test failure for PostgreSQL and update connector docs.

A detailed documentation for different execute flavors was added in #6030. The api doc comments are in DefaultCrudRepository, because I feel the content is specific to the implementation provided by loopback-datasource-juggler and our connectors.

See also loopbackio/loopback-datasource-juggler#1855.

There is also "regular" documentation in Executing database commands, it was added by #6047.

In the light of the above, your proposal seems to me as out of touch with the current status. At the same time, I see how the current ExecutableRepository API and docs are not consistent with the rest of the framework, so let's discuss how to get it on par.

Most of the original goal of this PR is already in place now, better to open a new issue and PR as and when required. Closing this.