@slashdb/js-slashdb

js-slashdb

This repository contains JavaScript ES6 modules with classes and functions to create applications for SlashDB. Use this SDK directly if you're building a JavaScript application that needs to interact with SlashDB. If you're building a React application, you can use the SlashDB React SDK, which contains out-of-the-box hooks to build React-based applications with SlashDB. For other frameworks or pure JavaScript solutions, this SDK provides the developer with tools to use the following SlashDB features:

• SlashDB application configuration (partial; currently limited to R/O operations)
• Data Discovery
  • GET/POST/PUT/DELETE calls
  • all Data Discovery options, e.g. filtering, relations, sorting, stream, accept types, etc
• SQL Pass-Thru
  • GET/POST/PUT/DELETE calls
  • all SQL Pass-Thru options, e.g. query parameters, sorting, stream, accept types, etc
• Functions for creating SlashDB-compatible filters

Installation

To install the SDK in your application's folder using Node:

• Run npm install @slashdb/js-slashdb

When using npm to start your application, you can import all the classes/functions from the repository package:

import { 
  SlashDBClient, 
  DataDiscoveryDatabase, DataDiscoveryResource, DataDiscoveryFilter, 
  SQLPassThruQuery, SQLPassThruFilter, 
  eq, any, between, gte, lte, not, and, asc, desc, chgPlaceHolder
} from '@slashdb/js-slashdb';

Or import them separately:

import { SlashDBClient } from '@slashdb/js-slashdb/src/slashdbclient.js';
import { DataDiscoveryResource, DataDiscoveryDatabase } from '@slashdb/js-slashdb/src/datadiscovery.js';
import { DataDiscoveryFilter } from '@slashdb/js-slashdb/src/datadiscoveryfilter.js';
import { SQLPassThruQuery } from '@slashdb/js-slashdb/src/sqlpassthru.js';
import { SQLPassThruFilter } from '@slashdb/js-slashdb/src/sqlpassthrufilter.js';
import { eq, any, between, gte, lte, not, and, chgPlaceHolder, asc, desc } from '@slashdb/js-slashdb/src/filterfunctions.js';

If you aren't using npm, just reference the files in the src folder, e.g.:

import { 
  SlashDBClient, 
  DataDiscoveryDatabase, DataDiscoveryResource, DataDiscoveryFilter, 
  SQLPassThruQuery, SQLPassThruFilter, 
  eq, any, between, gte, lte, not, and, asc, desc, chgPlaceHolder 
} from './src/index.js';

A brief explanation of each module:

• src/slashdbclient.js : contains a class for connecting to SlashDB and retrieving configuration information
• src/datadiscovery.js : contains classes for making Data Discovery REST calls
• src/datadiscoveryfilter.js : contains a class for creating Data Discovery URL endpoints, including all the Data Discovery options
• src/sqlpassthru.js : contains a class for executing SQL Pass-Thru queries
• src/sqlpassthrufilter.js : contains a class for creating SQL Pass-Thru URL endpoints, including all the SQL Pass-Thru options
• src/filterfunctions.js : a set of functions to create SlashDB-compatible filters
• src/basefilter.js : an underlying class used by other classes (not necessary to import directly into your code)
• src/baserequesthandler.js : an underlying class used by other classes (not necessary to import directly into your code)
• src/fetchwrapper.js : underlying functions for fetching data used by other modules (not necessary to import directly into your code)

Full documentation of the modules can be found here.

SDK Quick Start

To get up and running with the SDK, here's a quick example:

const sdbConfig = {
  host: 'https://demo.slashdb.com',
  apiKey: '********'
}                                                                     // configuration object to initialize the SlashDB client
const sdbClient = new SlashDBClient();                                // create a SlashDB client to connect to a SlashDB instance
sdbClient.login();                                                    // login to host SlashDB server
const db = new DataDiscoveryDatabase(sdb1, 'Chinook');                 // access the Chinook Database that is on the SlashDB instance
const customerTable = new DataDiscoveryResource(db, 'Customer');       // access the Customer table in the Chinook database
const query = new SQLPassThruQuery('invoices-total-range', sdbClient); // access the invoices-total-range query that is on the SlashDB instance

const ddFilter = new DataDiscoveryFilter()                            // create a filter for Data Discovery operations
               .addFilter(any('FirstName','J*,H*'))                   // filter by column FirstName, starting with 'J' or 'H'
               .addFilter(eq('Country','USA'))                        // filter by column Country, matches 'USA'
               .sort('LastName',desc('FirstName'))                    // sort results by columns LastName, descending FirstName
               .cols('FirstName','LastName','Company');               // only return columns FirstName, LastName, Company

const sptFilter = new SQLPassThruFilter( { 'mintotal': 10, 'maxtotal': 20 } )   // create a filter for SQL Pass-Thru with these query parameters set
                .limit(3)                                                       // return only the first 3 results
                .sort('CustomerId');                                            // sort results by column CustomerId

let dd_results = await customerTable.get(ddFilter);                   // get the data from Customer table with the Data Discovery filter options applied (returns JSON)
let spt_results = await query.accept('csv').get(sptFilter);           // execute the invoices-total-range query with the SQL Pass-Thru filter options applied (returns CSV)

There's more examples in the demo application.

All the DataDiscovery/SQL Pass-Thru options in the documentation are supported. The SDK module documentation lists all the methods available.

Username/password login

If apiKey parameter is not provided on sdbClient instantiation, username and password can be provided on login.

const sdbConfig = {
  host: 'https://demo.slashdb.com',
  apiKey: '********'
}                                                                     // configuration object to initialize the SlashDB client
const sdbClient = new SlashDBClient();                                // create a SlashDB client to connect to a SlashDB instance
const username = "<username>";
const password = "<password>";
sdbClient.login(username, password);                                  // login to host SlashDB server

SSO Login

In order to login with SSO, additional parameters are required in sdbClient instantiation.

const sdbConfig = {
  host: 'https://demo.slashdb.com',
  sso: {
    idpId: "okta",
    redirectUri: "http://localhost:8081/redirect_url",
    popUp: true
  }
}                                                                     // configuration object to initialize the SlashDB client
const sdbClient = new SlashDBClient(sdbConfig);                                // create a SlashDB client to connect to a SlashDB instance
sdbClient.login();                                                    // login to host SlashDB server

SSO parameters can added or updated after sdbClient instantiation, this can be useful if several SSO methods are avalaible.

const sdbConfig = {
  host: 'https://demo.slashdb.com',
}                                                                     // configuration object to initialize the SlashDB client
const sdbClient = new SlashDBClient(sdbConfig);                                // create a SlashDB client to connect to a SlashDB instance
const sso = {
  idpId: "okta",
  redirectUri: "http://localhost:8081/redirect_url",
  popUp: true
}
sdbClient.updateSSO(sso);                                             // Updates SSO settings.
sdbClient.login();                                                    // login to host SlashDB server

Demo Application

There is a small demo application in this repository. To use it (assumes using Node, v18+ recommended) :

• Clone this repository to your system and open a shell in the repo folder
• Run npm install
• Run npm run localserver (starts an HTTP server on port 8081)
• Navigate in a browser to http://localhost:8081/examples/demo.html
• Open the developer console to see a few more operations in the demo. You can also use any of the classes/functions in the developer console.

Note that administrative features of the demo will be limited if you're using https://demo.slashdb.com as the host. You can set up your own SlashDB instance using Docker, or there's a number of other platforms that are also supported if you want to try all the features.

SlashDB - REST API to Databases for Reading & Writing

For more info about SlashDB, visit https://www.slashdb.com.

The complete SlashDB documentation is available at https://docs.slashdb.com.