README.md

ThingsDB.js

Description

This project provides a JavaScript connector library that enables seamless interaction with ThingsDB, from both backend and frontend environments. It simplifies data access, manipulation, and querying for developers using JavaScript.

✅ Requirements

• ThingsDB v1 with enabled websocket
• Javascript

💾 Instalation

This library is available for both frontend and backend. You should choose installation method by your need.

browser

Package is automatically available at unpkg. You can find latest version of package at https://unpkg.com/thingsdb.js@latest/dist/thingsdb.js

Add this into your html head:

<script src="https://unpkg.com/thingsdb.js@latest/dist/thingsdb.js"></script>

npm

Package is available at npm https://www.npmjs.com/package/thingsdb.js

Run this command to install package into your project:

npm i thingsdb.js

🖥️ Usage

Class ThingsDB provide all functionality related to websocket connection with ThingsDB. It contains set of method which are based on documentation. Every method has comment (annotation) with required information and link to documentation. //not yet

Available methods

Method	Arguments	Description	Returns
__construct	uri: string = 'ws://127.0.0.1:9270'	ThingsDB constructor	ThingsDB instance
connect		Initialize websocket connection	Promise<void>
disconnect		Close websocket connection	Promise<void>
ping		Ping, useful as keep-alive	Promise<void>
auth	username: string = 'admin', password: string = 'pass'	Authorization with username and password	Promise<void>
authToken	token: string	Authorization with token	Promise<void>
query	scope: string, code: string, vars?: {}	Query ThingsDB	Promise<any>
run	scope: string, procedure: string, args?: any[]	Run a procedure	Promise<any>
join	scope: string, ...ids: number[]	Join one or more room(s)	Promise<(number|null)[]> - Array as requested ids to connect. Successful join returns same id at the same index. Unsuccessful returns null at that index.
leave	scope: string, ...ids: number[]	Leave one or more room(s)	Promise<(number|null)[]> - Same as join.
emit	scope: string, roomId: number, event: string, args: any[] = []	Emit an event to a room	Promise<void>
addEventListener	callback: (type: EventType, message: any) => void	Add listener for events	void
removeEventListener	callback: (type: EventType, message: any) => void	Remove listener for events	void

Listening

Listening is specific state in which you listen for emitted packages from ThingsDB. You can read more about it in docs.

join, emit, leave also emit package towards the one who did it. Therefore, don't be surprised when first package received with your registered event listener will be ON_JOIN|ON_LEAVE|ON_EMIT event type.

Event types

• NODE_STATUS = 0,
• WARNING = 5,
• ON_JOIN = 6,
• ON_LEAVE = 7,
• ON_EMIT = 8,
• ON_DELETE = 9

Also available as enum EventType for typescript.

Example

const thingsdb = new ThingsDB();
thingsdb.connect().then(() => {
    thingsdb.auth().then(() => {
        thingsdb.query('@:stuff', '"Hello World!";').then(response => {
            console.log(response); // will be "Hello World!"
        });
    });
});