sonic-channel

node-sonic-channel

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.

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:

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:

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:

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:

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:

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:

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:

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:

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.

Search channel

• sonicChannelSearch.query(collection_id<string>, bucket_id<string>, terms_text<string>, [options{limit<number>, offset<number>, lang<string>}<object>]?) ➡️ Promise(results<object>, error<object>)
• sonicChannelSearch.suggest(collection_id<string>, bucket_id<string>, word_text<string>, [options{limit<number>}<object>]?) ➡️ Promise(results<object>, error<object>)
• sonicChannelSearch.list(collection_id<string>, bucket_id<string>, [options{limit<number>, offset<number>}<object>]?) ➡️ Promise(results<object>, error<object>)

Ingest channel

• sonicChannelIngest.push(collection_id<string>, bucket_id<string>, object_id<string>, text<string>, [options{lang<string>}<object>]?) ➡️ Promise(_, error<object>)
• sonicChannelIngest.pop(collection_id<string>, bucket_id<string>, object_id<string>, text<string>) ➡️ Promise(count<number>, error<object>)
• sonicChannelIngest.count<number>(collection_id<string>, [bucket_id<string>]?, [object_id<string>]?) ➡️ Promise(count<number>, error<object>)
• sonicChannelIngest.flushc(collection_id<string>) ➡️ Promise(count<number>, error<object>)
• sonicChannelIngest.flushb(collection_id<string>, bucket_id<string>) ➡️ Promise(count<number>, error<object>)
• sonicChannelIngest.flusho(collection_id<string>, bucket_id<string>, object_id<string>) ➡️ Promise(count<number>, error<object>)

Control channel

• sonicChannelControl.trigger(action<string>, [data<string>]?) ➡️ Promise(_, error<object>)
• sonicChannelControl.info() ➡️ Promise(results<object>, error<object>)

What is Sonic?

ℹ️ Wondering what Sonic is? Check out valeriansaliou/sonic.

How is it linked to Sonic?

node-sonic-channel maintains persistent TCP connections to the Sonic network interfaces that are listening on your running Sonic instance. In case node-sonic-channel gets disconnected from Sonic, it will retry to connect once the connection is established again.

You can configure the connection details of your Sonic instance when initializing node-sonic-channel from your code; via the Sonic host and port.

Changelog

1.3.1 (2023-01-09)

New Features

• Automate the package release process via GitHub Actions (ie. npm publish) [@valeriansaliou].