# node-sonic-channel
[](https://github.com/valeriansaliou/node-sonic-channel/actions?query=workflow%3A%22Test+and+Build%22) [](https://github.com/valeriansaliou/node-sonic-channel/actions?query=workflow%3A%22Build+and+Release%22) [](https://www.npmjs.com/package/sonic-channel) [](https://www.npmjs.com/package/sonic-channel) [](https://www.buymeacoffee.com/valeriansaliou)
**Sonic Channel integration for Node. Used in pair with Sonic, the fast, lightweight and schema-less search backend.**
Sonic Channel lets you manage your Sonic search index, from your NodeJS code. Query your index and get search results, push entries to your index and pop them programmatically.
**🇫🇷 Crafted in Nantes, France.**
## Who uses it?
Crisp
_👋 You use sonic-channel and you want to be listed there? [Contact me](https://valeriansaliou.name/)._
## How to install?
Include `sonic-channel` in your `package.json` dependencies.
Alternatively, you can run `npm install sonic-channel --save`.
## How to use?
### 1️⃣ Search channel
#### 1. Create the connection
`node-sonic-channel` can be instanciated in search mode as such:
```javascript
var SonicChannelSearch = require("sonic-channel").Search;
var sonicChannelSearch = new SonicChannelSearch({
host : "::1", // Or '127.0.0.1' if you are still using IPv4
port : 1491, // Default port is '1491'
auth : "SecretPassword" // Authentication password (if any)
}).connect({
connected : function() {
// Connected handler
console.info("Sonic Channel succeeded to connect to host (search).");
},
disconnected : function() {
// Disconnected handler
console.error("Sonic Channel is now disconnected (search).");
},
timeout : function() {
// Timeout handler
console.error("Sonic Channel connection timed out (search).");
},
retrying : function() {
// Retry handler
console.error("Trying to reconnect to Sonic Channel (search)...");
},
error : function(error) {
// Failure handler
console.error("Sonic Channel failed to connect to host (search).", error);
}
});
```
#### 2. Query the search index
Use the same `sonicChannelSearch` instance to query the search index:
```javascript
sonicChannelSearch.query("messages", "default", "valerian saliou")
.then(function(results) {
// Query results come there
})
.catch(function(error) {
// Query errors come there
});
```
#### 3. Teardown connection
If you need to teardown an ongoing connection to Sonic, use:
```javascript
sonicChannelSearch.close()
.then(function() {
// Close success handler
})
.catch(function(error) {
// Close errors come there
});
```
---
### 2️⃣ Ingest channel
#### 1. Create the connection
`node-sonic-channel` can be instanciated in ingest mode as such:
```javascript
var SonicChannelIngest = require("sonic-channel").Ingest;
var sonicChannelIngest = new SonicChannelIngest({
host : "::1", // Or '127.0.0.1' if you are still using IPv4
port : 1491, // Default port is '1491'
auth : "SecretPassword" // Authentication password (if any)
}).connect({
connected : function() {
// Connected handler
console.info("Sonic Channel succeeded to connect to host (ingest).");
},
disconnected : function() {
// Disconnected handler
console.error("Sonic Channel is now disconnected (ingest).");
},
timeout : function() {
// Timeout handler
console.error("Sonic Channel connection timed out (ingest).");
},
retrying : function() {
// Retry handler
console.error("Trying to reconnect to Sonic Channel (ingest)...");
},
error : function(error) {
// Failure handler
console.error("Sonic Channel failed to connect to host (ingest).", error);
}
});
```
#### 2. Manage the search index
Use the same `sonicChannelIngest` instance to push text to the search index:
```javascript
sonicChannelIngest.push("messages", "default", "conversation:1", "I met Valerian Saliou yesterday. Great fun!")
.then(function() {
// Push success handler
})
.catch(function(error) {
// Push errors come there
});
```
#### 3. Teardown connection
If you need to teardown an ongoing connection to Sonic, use:
```javascript
sonicChannelIngest.close()
.then(function() {
// Close success handler
})
.catch(function(error) {
// Close errors come there
});
```
---
### 3️⃣ Control channel
#### 1. Create the connection
`node-sonic-channel` can be instanciated in control mode as such:
```javascript
var SonicChannelControl = require("sonic-channel").Control;
var sonicChannelControl = new SonicChannelControl({
host : "::1", // Or '127.0.0.1' if you are still using IPv4
port : 1491, // Default port is '1491'
auth : "SecretPassword" // Authentication password (if any)
}).connect({
connected : function() {
// Connected handler
console.info("Sonic Channel succeeded to connect to host (control).");
},
disconnected : function() {
// Disconnected handler
console.error("Sonic Channel is now disconnected (control).");
},
timeout : function() {
// Timeout handler
console.error("Sonic Channel connection timed out (control).");
},
retrying : function() {
// Retry handler
console.error("Trying to reconnect to Sonic Channel (control)...");
},
error : function(error) {
// Failure handler
console.error("Sonic Channel failed to connect to host (control).", error);
}
});
```
#### 2. Administrate your Sonic server
_You may use the same `sonicChannelControl` instance to administrate your Sonic server._
#### 3. Teardown connection
If you need to teardown an ongoing connection to Sonic, use:
```javascript
sonicChannelControl.close()
.then(function() {
// Close success handler
})
.catch(function(error) {
// Close errors come there
});
```
## List of channel methods
_For details on argument values, see the [Sonic Channel Protocol specification](https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md)._
### Search channel
* `sonicChannelSearch.query(collection_id, bucket_id, terms_text, [options{limit, offset, lang}
