Alfa-Data-Client

Client for Alfa-Data service REST API.

How to use

Install

    npm install @alfa-wells/alfa-data-client --save

Example

    const client = require("@alfa-wells/alfa-data-client")("http://localhost:3001/alfa-data")
    let credentials = {
        user: "frank", 
        password: "Frank1234"
    }
    let connection = client.connection("connection-configuration-id", credentials)

    let result = await connection.execute("select * from employee where id = {? id }", { id: 123 })

API

Client

Create

    const client = require("@alfa-wells/alfa-data-client")(<server_url>[, <timeout>])

The server url should contain the protocol and can declare a port and a base path. Default timeout is 120000ms (2 minutes).

Configurations

    client.configurations()

Returns a list of all available configurations. Each configuration has:

• name: Display name of the configuration.
• type : Database type. Current supported types are oracle and sql-server.
• id: The short id of the connection configuration.

async/await

    try {
        let list = await client.configurations()
        //list = [{name: "My local database", type: "oracle", id: "my-local-db"}]
    } catch (err) {
        //Ups! Error
    }

Promises

     client.configurations()
        .then(list => {
             //list = [{name: "My local database", type: "oracle", id: "my-local-db"}]
        })
        .catch(err => {
            //Ups! Error
        })

Connect

Creates a connection to a configured database. Returns a promise that resolves to a Connection object.

    client.connection(<configuration_id> [, <credentials>])

async/await

    let credentials = {
        user: "frank", 
        password: "Frank1234"
    }
    try {
        let connection = await client.connect("my-local-db", credentials)
        //Do something with it
    } catch (err) {
        //Ups! Error
    }

Promises

    let credentials = {
        user: "frank", 
        password: "Frank1234"
    }
    client.connect("my-local-db", credentials)
        .then(connection => {
             //Do something with it
        })
        .catch(err => {
            //Ups! Error
        })

Connection

Re-creates a connection from an id. Returns a Connection object.

    client.connection(<connection_id>)

Connection object

Info

Returns information about this connection.

    connection.info()

Return an object with the properties:

• valid: boolean. True if this connection is still valid for querying, false if not.
• configuration: String. The id of the connection configuration used to create this connection.
• message: String. Error message when valid is false. It will be absent or it'll have a non significant value when valid is true.

async/await

    try {
        let info = await connection.info()
        console.log(info.valid)
        //Prints true
    } catch (err) {
        //Ups! Error
    }

Promises

    connection.info()
        .then(info => {
             console.log(info.valid)
             //Prints true
        })
        .catch(err => {
            //Ups! Error
        })

Execute

Executes a query using this connection. Returns a promise that resolves to a result set.

    connection.execute(<sql_string>[, <arguments>])

The result of a query is an object with the properties:

• columns: Array of Column objects. A column has two properties:
  • name: String. The name of the column.
  • type: String. The Javascript class name of the values in the column (String, Number, Date, Boolean, etc.)
• rows: Array o rows (also arrays). Each position in the row is a value of the type described in the corresponding column description.
• count: Row count. It´s expected to be equal to rows.length

async/await

    let empolyee = {
        id: '12'
        name: 'Frank Robinson',
    }
    let sql = "select * from employees where id = {?id} or name = {?name}"
    try {
        let result = await connection.execute(sql, employee)
        //=> a result set
    } catch (err) {
        //Ups! Error
    }

Promises

    let empolyee = {
        id: '12'
        name: 'Frank Robinson',
    }
    let sql = "select * from employees where id = {?id} or name = {?name}"
    connection.execute(sql, employee)
        .then(result => {
             //=> a result set
        })
        .catch(err => {
            //Ups! Error
        })

Execute all

Executes a list of queries using this connection in a single request. Returns a promise that resolves to a list of objects containing a result set.

    connection.executeAll(<Array-of_queries>)

Each query can be:

• string: The plain sql to execute.
• object: An object with the properties:
  • sql: The plain sql to execute.
  • arguments: (Optional) An object containing the named arguments of the query.

The promise is resolved to a listof objects with the properties:

• ok: Boolean. True if the corresponding query could be executed successfully, false otherwise.
• error: String. Error message when ok is false. When ok is true, this property will be absent or it'll have a non significant value.
• columns: Array of Column objects. A column has two properties:
  • name: String. The name of the column.
  • type: String. The Javascript class name of the values in the column (String, Number, Date, Boolean, etc.)
• rows: Array o rows (also arrays). Each position in the row is a value of the type described in the corresponding column description.
• count: Row count. It´s expected to be equal to rows.length

async/await

    let query1 = {
        sql: "select * from employees where id = {?id} or name = {?name}",
        arguments: {
            id: '12'
            name: 'Frank Robinson',
        }
    let query2 = "select * from employees"
    try {
        let results = await connection.executeAll([query1, query2])
        //=> a list of two objects
    } catch (err) {
        //Ups! Error
    }

Promises

    let query1 = {
        sql: "select * from employees where id = {?id} or name = {?name}",
        arguments: {
            id: '12'
            name: 'Frank Robinson',
        }
    let query2 = "select * from employees"
    
    connection.executeAll([query1, query2])
        .then(results => {
             //=> a list of two objects
        })
        .catch(err => {
            //Ups! Error
        })

Id

Returns a string representing this connection. Used to recreate it with client.connection().

    connection.id