This library is written with vanilia JS & has no framework dependencies allowing easy integration with any front-end website. Here is some boilerplate to get you going:

Angular

File: /src/services/datalynk.service.ts

import {Injectable} from '@angular/core';
import {Api, Slice} from '@auxilium/datalynk-client';
import {environment} from '../environment/environment';
import {Contact} from '../models/contact';
import {Slices} from '../models/slices';

declare global {
  interface Window {
    api: Api;
  }
}

@Injectable({providedIn: 'root'})
export class DatalynkApi extends Api {
  contacts!: Slice<Contact>;

  constructor() {
    // Create API object & expose to window
    super(environment.api, {/* options */});
    window.api = this;

    // Handle logging in
    this.auth.handleLogin('spoke', {/* login UI options */});

    // Create store to cache slice data
    this.contacts = this.slice<Contact>(Slices.Contact);
  }
}
Copy

Node / Vue

File: /src/services/datalynk.service.ts

import {Api} from '@auxilium/datalynk-client';
import {environment} from '../environment/environment';
import {Contact} from '../models/contact';
import {Slices} from '../models/slices';

// Create API object & expose to window
export const api = window.api = new Api(environment.api, {/* options */});

// Handle logging in
api.auth.handleLogin('spoke', {/* login UI options */});

// Create store to cache slice data
export const contacts = api.slice<Contact>(Slices.Contact);
Copy

Vanilla JS

File: /index.html

<script type="module">
  import {Api} from '@auxilium/datlaynk-client/dist/index.mjs';

  // Create API object & expose to window
  var api = new Api('https://spoke.auxiliumgroup.com', /* options */);

  // Handle logging in
  api.auth.handleLogin('spoke', {/* login UI options */});

  // Create store to cache slice data
  var contacts = api.slice(12345);
</script>
Copy

This library comes with a command line tool for developers to automatically create Typescript models from the Datalynk metadata.

This takes most of the manual labour out of manually mapping the data & provides type safety.

1. Simply run the tool:

$ npx datalynk-models
Output (src/models):
Spoke: spoke
Login: username
Password: ********
Copy

2. Import models:

import {Slices} from 'models/slices'; // Import slices map
import {Contact} from 'models/contact'; // Import model for slice we will be using

const contacts: Contact[] = await api.slice<Contact>(Slices.Contact)
                                     .select()
                                     .rows().exec();
Copy

Api Request

Raw requests can be made using request

const response = await api.request({...});
Copy

Chain Map

Multiple results can be returned together as dictionary

const {user, report} = await api.chainMap({
    user: {'$/auth/current': {}},
    report: api.slice(52131).select().rows()
});
Copy

Chain Requests

Multiple requests can be chained together to run them in order. The last request's response will be returned

const report = await api.chain({'$/auth/current': {}}, api.slice(12345).select().rows());
Copy

Default Flow

99% of the time you will want to let the library handle the login flow:

1. It will check the URL for a token param: ?datalynkToken=...
2. It will check the localStorage for a saved token
3. It will prompt the user to login via UI
4. Lastly it will, reload page if the token changed

await api.auth.handleLogin('spoke', {/* Login UI Options */});
Copy

Fetch User

api.auth.user
Copy

Guest Login

Login as the guest account:

const guest = await api.auth.loginGuest();
console.log(api.auth.isGuest()) // True
Copy

Login UI

Prompt the user to login with the login page, defaults come from the clients theme.json file:

const prompt = api.auth.loginPrompt('spoke', {
  // Overrides theme.json
  title: "Title of App",
  logoPosition: "aboveTitle",
  subtitle: "Subtitle of App",
});
await prompt.wait; // Wait for the user to login/close the prompt
prompt.close(); // Close prompt manually
Copy

Full list of options

Manual Login

Login programmatically:

const user = await api.auth.login('spoke', 'username', 'password', '2faCode');
Copy

Support

PWA

Turns the website into an installable native app

• The PWA manifest can be configured with: manifest
• The install prompt can be configured with: pwaSettings

const api = new Api(`https://${spoke}.auxiliumgroup.com`, {
    name: "Workplace Occupational Health & Safety Inspection", // REQUIRED: App name
    manifest: { // Set/Override any manifest values
        scope: 'https://lynk-forms.scarborough.auxilium.world/OshawaCL/ohsinspection.html' 
    },
    pwaSettings: { // PWA install prompt settings
        timeout: 45, // seconds before prompt shows (default: 30)
        dismissExpiry: 3, // days before prompt shows again (0 = every refresh, default: 7)
        loginLink: true // Show install link in login screen
    },
});

// Manually trigger
api.pwa.prompt();
Copy

Static assets

Upload the service worker dist/service.worker.mjs to the root directory of the server to cache all files for use offline

const api = new Api(`https://${spoke}.auxiliumgroup.com`, {
  serviceWorker: 'https://.../service.worker.mjs', // Shouldnt be needed but can be overriden
});
Copy

Slice Engine

Slices can be used as normal offline using the slice engine by marking the slice as offline with: offline

const api = new Api(`https://${spoke}.auxiliumgroup.com`, {
  offline: [51306, 51531, 51563], // REQUIRED: Specify slices that must be stored offline
  socket: true // Make sure sockets are enabled
});
await api.slice(51306).insert({...}).exec();
const resp = await api.slice(51306).select().where('id', '<=', 100).exec();
Copy

API Requests

Any API request can be deferred until online, however you dont get responses when offline

• Only useful for submitting data or when we dont care about the response

api.request(..., {offline: true}).then((resp: T | void) => {
    if(resp != null) {
        // Online logic (has response payload)
    } else {
        // Offline logic (no response payload)
    }
});
Copy

Connection status

online$ remains available for a simple boolean check. Use status$ when the application needs to react differently to connectivity, authentication, and API failures:

api.status$.subscribe(status => {
    switch(status) {
        case 'online':
            // The API is responding normally
            break;
        case 'offline':
            // The network request could not reach the API
            break;
        case 'unauthorized':
            // The token expired or the API rejected it; prompt for login
            break;
        case 'unavailable':
            // The server returned a failure or a non-JSON API response
            break;
    }
});
Copy

Expired and rejected tokens are cleared from token$. Malformed responses reject with UnexpectedApiResponseError. Requests only enter the offline queue when {offline: true} is supplied; other requests reject so callers can handle the relevant status. api.offline reflects Datalynk availability, not only browser connectivity, so it can be true while navigator.onLine is still true during API/MySQL recovery. Offline-enabled slices use their local IndexedDB cache in either case.

PDFs can be generated using the API. PDFs can be optionally related to a record by passing an association

const resp = await api.pdf.fromUrl('https://google.com', {slice: 12345, row: 1, field: 'resume'});
Copy

This library comes with LINQ style query language to help make interacting with slices easier by providing types & intellisense.

Select

// Get a single record
const row = await api.slice<T>(12345)
                     .select(12345)
                     .row().exec();

// Get all slice records
const rows = await api.slice<T>(12345)
                      .select()
                      .rows().exec();

// Advanced queries
const rows = await api.slice<T>(12345)
                      .select()
                      .fields({'field1': 'field2'})
                      .where('field1', '<', 0)
                      .or()
                      .where({field1: 0, field2: false})
                      .order('field2', true) // ascending
                      .limit(10)
                      .rows().exec();                      
Copy

Count

const count = await api.slice(12345)
                       .count()
                       .where({field1: 'value'})
                       .count().exec();
Copy

Insert

// Insert record
const key = await api.slice<Contact>(12345)
                     .insert({first: 'Bilbo', last: 'Baggins'})
                     .id().exec();

// Insert multiple rows
const keys = await api.slice<Contacts>(12345)
                      .insert([
                        {first: 'Darth', last: 'Vader'},
                        {first: 'John', last: 'Snow'}
                      ])
                      .ids().exec();
Copy

Update

// Update a record
const success = await api.slice(12345)
                         .update({id: 1, first: 'James', last: 'Kirk'})
                         .id().exec();

// Update multiple rows with where
await api.slice(12345)
         .update({evil: true})
         .where({first: 'Darth'})
         .ids().exec();
Copy

Delete

// Delete a record
const success = await api.slice(12345)
                         .delete(12345)
                         .id().exec();

// Dlete multiple rows with where
await api.slice(12345)
         .delete()
         .where({first: 'Darth'})
         .ids().exec();
Copy

Sockets (enabled by default) can be turned off or configured to point to a custom URL

const api = new Api('https://spoke.auxiliumgroup.com', {
  socket: true, // Enable - Use default URL
  // socket: false, // Disable
  // socket: 'http://localhost:3000', // Enable - Custom socket server URL
});
Copy

Slice Engine

The Slice Engine's cache can be synced with the server & subscribed to using RXJS:

// Create cache/store
const contacts = api.slice<Contact>(Slices.Contact);

// Enable syncing
contacts.sync();

// Use RXJS to listen for events
contacts.sync().pipe(...).subscribe((cache: Contact[]) => {...});
// Or using Angular templates
'{{ contacts.sync() | async }}'

// Disable syncing
contacts.sync(false);
Copy

Socket Events

Alternatively socket events can be listened to directly using callbacks:

api.socket.sliceEvents(123, callbackFn(event)); // Listen to a specific slice
api.socket.addListener(callbackFn(event)); // listen to all socket events
Copy

Fetch File

const url = api.files.get(12345);
Copy

Upload File

Uploading files to datalynk is done by first uploading the file as form-data & then creating a reference to the upload ID in a slice.

// Get files from file input
const files = document.querySelector('#upload').files;

// Upload a file & associate it with a record in one call
api.files.upload(files, {slice: 12345, row: 1234, field: 'abc'});
// OR upload a file on its own
api.files.upload(files).then(uploaded => {
  // Associate file with a record manually
  const slice = 12345, row: 123;
  api.files.associate(uploaded.map(r => r.id), slice, row, 'field');
});

Copy

Connect to a WebRTC chatroom to send audio/video to peers

// Video elements to display stream on
const local = document.querySelector('#video1'); // <video id="video1" autoplay muted playsinline></video>
const remote = document.querySelector('#video2'); // <video id="video2" autoplay playsinline></video>

// Connect to a WebRTC room
const roomID = 'TEST_ROOM';
const session = await api.webrtc.connect(roomID, true, true); // audio = true, video = true

// Set local audio/video stream
local.srcObject = session.stream;

// Track is null on the initial connection, will fire again when the stream is ready
session.onConnected = (peer, stream) => {
  // Set remote audio/video stream if ready
  if(stream) remote.srcObject = stream;
}

// Disconnect from WebRTC room
session.disconnect();
Copy