@auxilium/datalynk-client 0.4.5 → 0.4.7

package/README.md

@@ -4,13 +4,21 @@
 
 ---
 
-Datalynk client library to integrate JavaScript clients with the Datalynk API
+Datalynk client library to integrate JavaScript clients with the Datalynk API.
 
 ## Table of Contents
 - [Datalynk Client Library](#datalynk-client-library)
   - [Table of Contents](#Table-of-Contents)
   - [Quick Start](#quick-start)
-  - [Examples](#examples)
+  - [Documentation](#documentation)
+    - [Integration](#integration)
+      - [Angular](#integration)
+      - [Node / Vue](#integration)
+      - [Vanalia JS](#integration)
+    - [Build Models](#build-models)
+    - [Authentication](#authentication)
+    - [Slice Engine](#slice-engine)
+    - [Sockets](#sockets)
 
 ## Quick Start
 1. Install the client library
@@ -29,45 +37,280 @@ Password: ********
 
 3. Create an API object & start making requests
 ```js
-import {API} from '@auxilium/datalynk-client'
-import {User} from './models/User.model'; // Created automatically in Step 2
-import {Slices} from './models/slices'; // Created automatically in Step 2
+import {API} from '@auxilium/datalynk-client';
 
 const api = new API('https://spoke.auxiliumgroup.com');
-const resp = await api.slice<User>(Slices.User).select().exec();
+const resp = await api.request({'$/auth/current':{}});
 ```
 
-## Examples
-```typescript
-// Login
-const user = await api.auth.login('spoke', 'username', 'password');
+## Documentation
 
-// Send custom request
-const resp = await api.request({"!/slice/permissionsLite": {}});
+<details>
+  <summary>
+    <h3 id="integration" style="display: inline">Integration</h3>
+  </summary>
 
-// Query
-const rows = await api.slice<T>(12345).select().exec().rows();
-const row = await api.slice<T>(12345).select(12345).exec().row();
+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:
 
-// Insert
-const key = await api.slice<Contact>(12345).insert({first: 'Bilbo', last: 'Baggins'}).exec().key();
-const keys = await api.slice<Contacts>(12345).insert([
-    {first: 'Darth', last: 'Vader'},
-    {first: 'John', last: 'Snow'}
-]).exec().keys();
+#### Angular
 
-// Update
-const success = await api.slice(12345).update(
-    {id: 1, first: 'Adam', last: 'Baxter'}
-).exec().key();
+**File:** `/src/services/datalynk.service.ts`
 
-// Socket synced slices
-const store = api.slice<T>(12345).sync();
-store.subscribe((rows: T[]) => console.log(rows));
-store.sync(false) // Unsubscribe from server events
+```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() {
+    super(environment.api, {/* options */});
+    window.api = this;
+
+    this.handleLogin('spoke', {/* login UI options */});
+
+    // Create store to cache slice data
+    this.contacts = this.slice<Contact>(Slices.Contact);
+  }
+}
+```
+
+#### Node / Vue
+
+**File:** `/src/services/datalynk.service.ts`
+
+```ts
+import {Api} from '@auxilium/datalynk-client';
+import {environment} from '../environment/environment';
+import {Contact} from '../models/contact';
+import {Slices} from '../models/slices';
+
+export const api = new Api(environment.api, {/* options */});
+// Create store to cache slice data
+export const contacts = api.slice<Contact>(Slices.Contact);
+```
+
+#### Vanilia JS
+
+**File:** `/index.html`
+
+```html
+<script type="module">
+  import {Api} from '@auxilium/datlaynk-client/dist/index.mjs';
+
+  var api = new Api('https://spoke.auxiliumgroup.com', /* options */);
+  // Create store to cache slice data
+  var contacts = api.slice(12345);
+</script>
 
-// Advanced example - Add flag to underage users
-const users = await api.slice(12345).select().exec().rows();
-users = users.map(user => ({...user, underage: user.age < 18}));
-api.slice(1245).update(users).exec();
 ```
+
+</details>
+
+<details>
+  <summary>
+    <h3 id="build-models" style="display: inline">Build Models</h3>
+  </summary>
+
+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:
+```bash
+$ npx build-models
+Output (src/models):
+Spoke: spoke
+Login: username
+Password: ********
+```
+
+2. Import models:
+```ts
+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()
+                                     .exec().rows();
+```
+
+</details>
+
+<details>
+  <summary>
+    <h3 id="authentication" style="display: inline">Authentication</h3>
+  </summary>
+
+#### Login flow
+
+This library comes with some logic to automatically handle the login flow & should be called at the startup of your application:
+
+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. Reload page if token changed
+```js
+await api.auth.handleLogin('spoke', {
+  background: 'url("...")', // CSS URL or hex color
+  color: '#ff0000', // hex color
+  title: '<img alt="logo" src="..." />', // text or HTML
+  titleColor: '#ffffff' // Color of title text
+});
+```
+
+#### Login UI
+
+Alternatively you can manage the login prompt manually:
+
+```js
+const prompt = api.auth.loginPrompt('spoke', options);
+await prompt.wait; // Wait for the user to login/close the prompt
+prompt.close(); // Close prompt manually
+```
+
+#### Programatically
+
+Manually login programatically:
+
+```js
+const user = await api.auth.login('spoke', 'username', 'password', '2faCode');
+```
+
+</details>
+
+<details>
+  <summary>
+    <h3 id="" style="display: inline">Slice Engine</h3>
+  </summary>
+
+This library comes with LINQ style query language to help make interacting with Slices easier by providing types & intelisense.
+
+#### Select
+
+```ts
+// Get a single record
+const row = await api.slice<T>(12345)
+                     .select(12345)
+                     .exec().row();
+
+// Get all slice records
+const rows = await api.slice<T>(12345)
+                      .select()
+                      .exec().rows();
+
+// Advanced queries
+const rows = await api.slice<T>(12345)
+                      .select()
+                      .where('field1', '==', 'value')
+                      .fields({'field1': 'field2'})
+                      .order('field2', true /* ascending */)
+                      .limit(10)
+                      .exec().rows();                      
+```
+
+#### Insert
+
+```ts
+// Insert record
+const key = await api.slice<Contact>(12345)
+                     .insert({first: 'Bilbo', last: 'Baggins'})
+                     .exec().key();
+
+// Insert multiple rows
+const keys = await api.slice<Contacts>(12345)
+                      .insert([
+                        {first: 'Darth', last: 'Vader'},
+                        {first: 'John', last: 'Snow'}
+                      ])
+                      .exec().keys();
+```
+
+#### Update
+
+```ts
+// Update a record
+const success = await api.slice(12345)
+                         .update({id: 1, first: 'James', last: 'Kirk'})
+                         .exec().key();
+
+// Update multiple rows with where
+await api.slice(12345)
+         .update({evil: true})
+         .where({first: 'Darth'})
+         .exec().keys();
+```
+
+#### Delete
+
+```ts
+// Delete a record
+const success = await api.slice(12345)
+                         .delete(12345)
+                         .exec().key();
+
+// Dlete multiple rows with where
+await api.slice(12345)
+         .delete()
+         .where({first: 'Darth'})
+         .exec().keys();
+```
+
+</details>
+
+<details>
+  <summary>
+    <h3 id="" style="display: inline">Sockets</h3>
+  </summary>
+
+
+#### Options
+
+The socket can have it's endpoint overriden or be turned off by setting it to false:
+```ts
+const api = new Api('https://spoke.auxiliumgroup.com', {
+  socket: false, // Disable
+  // socket: 'http://localhost:3000', // Override
+});
+```
+
+#### Slice Engine
+
+The Slice Engine's cache can be sycned with the server & subscribed to using [RXJS](https://rxjs.dev):
+
+```ts
+// 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);
+```
+
+#### Socket Events
+
+Alternatively socket events can be listened to directly using callbacks:
+
+```ts
+api.socket.sliceEvents(123, callbackFn(event)); // Listen to a specific slice
+api.socket.addListener(callbackFn(event)); // listen to all socket events
+```
+
+</details>

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@auxilium/datalynk-client",
 	"description": "Datalynk client library",
 	"repository": "https://gitlab.auxiliumgroup.com/ztimson/datalynk-client",
-	"version": "0.4.5",
+	"version": "0.4.7",
 	"author": "Zak Timson",
 	"private": false,
 	"main": "./dist/index.cjs",