feat: dataSource.execute(cmd, args, opts)

[bajtos]

Implement a new helper API for calling connector's "execute" method
in a promise-friendly way.

Example usage:

await MyModel.dataSource.execute(
  'SELECT * FROM Users WHERE email = ?',
  ['[email protected]'],
  {/* options */});

While it's possible to call MyModel.dataSource.execute directly, this new API adds promise support to existing callback-based connectors. When we upgrade connector API to use promises under the hood, consumers of this new API won't be affected by that change, as opposed to consumers of connector.execute that will have to upgrade their code.

/cc @koalabi

Related issues

• connect to Connecting to graph databases loopback-next#2053
• StackOverflow: How to execute arbitrary SQL query

Checklist

• New tests added or existing tests modified to cover all changes
• Code conforms with the style
  guide

[bajtos]

A related question on StackOverflow: How to execute arbitrary SQL query

[bajtos]

Added a new commit to remove callback style and keep Promise style only.

[jannyHou]

@bajtos Mostly LGTM 👏 , I left a concern about the command's type.

For the types in the callback flavour, I am ok to remove them.

[jannyHou]

@bajtos I found the command type here a bit confusing: the function types defined at the bottom of this PR only takes string type as command. Any particular reason to allow an object?

[bajtos]

the function types defined at the bottom of this PR only takes string type as command.

I forgot to update typedefs, they were describing a callback variant too. I'll fix that.

[bajtos]

Any particular reason to allow an object?

Some community connectors are using object value for the comman and I want to preserve support for those connectors.

See e.g. https://www.npmjs.com/package/loopback-connector-neo4j-graph

var cypher = {
    query: "MATCH (u:User {email: {email}}) RETURN u",
    params: {
        email: '[email protected]',
    }
};
// ...
ModelClass.dataSource.connector.execute(
    cypher,
    [],
    options,
    callback
);

I think the connector authors misunderstood how command & args are meant to be used together. I think the following would be a better usage:

ModelClass.dataSource.connector.execute(
  `MATCH (u:User {email: {email}}) RETURN u`,
   {email: '[email protected]'},
   options,
   callback);

Based on this analysis, I am going to change the type of args from array to object. (Note that arrays are objects too.)

[bajtos]

I have addressed the review comments and made the following extra changes:

• Enabled ES2017 (async functions) in eslint config
• Rewrote new tests using async/await. This is ok because juggler v4 requires Node.js 8+

@jannyHou LGTY now?

[jannyHou]

LGTM

[dougal83]

Is this supported for mongodb connector?

[jannyHou]

@dougal83 I believe so, mongodb has its execute implementation.

[dougal83]

@jannyHou Do you know if there are any usage examples?