📚 Satori Node.js SDK

Welcome to the official documentation for Satori Node.js SDK! 🚀
This library allows you to interact easily and efficiently with the Satori database via WebSockets, supporting CRUD operations, real-time notifications, and advanced queries.

✨ Main Features

• Ultra-fast CRUD operations ⚡
• Advanced queries using field_array 🔍
• Real-time notifications 📢
• Graph-like relations (vertices and references) 🕸️
• Data encryption and decryption 🔐

🚀 Installation

npm install satori-node

🏁 Basic Usage

import { Satori } from 'satori-node';

const client = new Satori({
  username: 'user',
  password: 'password',
  host: 'ws://localhost:2310'
});

await client.connect();

If you are inserting a vector you must specify data to a [f32] and type to vector

🗃️ CRUD Operations

Create Data

await client.set({
  key: 'user:123',
  data: { name: 'John', email: '[email protected]' },
  type: 'user' 
});

If you are inserting a vector you must specify data to a [f32] and type to vector

Read Data

const user = await client.get({ key: 'user:123' });

Modify a Field

await client.put({
  key: 'user:123',
  replace_field: 'name',
  replace_value: 'Peter'
});

Delete Data

await client.delete({ key: 'user:123' });

🧩 Advanced Queries with field_array 🔍

You can perform operations on multiple objects that meet certain conditions using the field_array field:

await client.get({
  field_array: [
    { field: 'email', value: '[email protected]' }
  ],
});

• field_array is an array of conditions { field, value }.
• You can combine it with one: true to get only the first matching result.

🔔 Real-time Notifications

Receive automatic updates when an object changes!

client.notify('user:123', data => {
  console.log('User updated!', data);
});

🕸️ Relations and Graphs

You can create relationships between objects (vertices):

await client.setVertex({
  key: 'user:123',
  vertex: 'friend:456',
  relation: 'friend',
  encryption_key: 'secret'
});

Retrieve vertices:

await client.getVertex({ key: 'user:123', encryption_key: 'secret' });

Delete a vertex:

await client.deleteVertex({ key: 'user:123', vertex: 'friend:456', encryption_key: 'secret' });

And traverse the graph with DFS:

await client.dfs({ node: 'user:123', relation: 'friend', encryption_key: 'secret' });

Additional graph algorithms:

• BFS Traversal:

  await client.graphBfs({ node: 'user:123' });

• DFS Traversal:

  await client.graphDfs({ node: 'user:123' });

• Shortest Path:

  await client.graphShortestPath({ node: 'user:123', target: 'user:456' });

• Connected Components:

  await client.graphConnectedComponents();

• Strongly Connected Components (SCC):

  await client.graphScc();

• Degree Centrality:

  await client.graphDegreeCentrality();

• Closeness Centrality:

  await client.graphClosenessCentrality();

• Graph Centroid:

  await client.graphCentroid();

🔐 Encryption and Security

Easily encrypt and decrypt data:

await client.encrypt({ key: 'user:123', encryption_key: 'secret' });
await client.decrypt({ key: 'user:123', encryption_key: 'secret' });

🧰 Schema Class (Data Model)

You can use the Schema class to model your data in an object-oriented way:

import Schema from 'satori-node/schema';

class User extends Schema {
  // Define your fields here
}

const user = new User({ name: 'Anna' }, client, 'user');
await user.set();

It includes useful methods such as:

• set, delete, encrypt, setVertex, getVertex, deleteVertex, dfs
• Graph methods: graphBfs, graphDfs, graphShortestPath, graphConnectedComponents, graphScc, graphDegreeCentrality, graphClosenessCentrality, graphCentroid
• Array methods: push, pop, splice, remove

📦 Array Manipulation Methods

Below are the available methods to manipulate arrays in the Satori database using the Node.js client:

🔹 push

Adds a value to an existing array in an object.

await client.push({ key: 'user:123', array: 'friends', value: 'user:456' });

• key: Object key.
• array: Name of the array.
• value: Value to add.

🔹 pop

Removes the last element from an array in an object.

await client.pop({ key: 'user:123', array: 'friends' });

• key: Object key.
• array: Name of the array.

🔹 splice

Modifies an array in an object (for example, to cut or replace elements).

await client.splice({ key: 'user:123', array: 'friends' });

• key: Object key.
• array: Name of the array.

🔹 remove

Removes a specific value from an array in an object.

await client.remove({ key: 'user:123', array: 'friends', value: 'user:456' });

• key: Object key.
• array: Name of the array.
• value: Value to remove.

🤖 AI Methods

Satori has AI features integrated that boost developers productivity.

🔹 set_middleware

Make the LLM analyze incoming querys and decide if it must reject them, accept them or modify them.

await client.set_middleware({
    "operation": "SET",
    "middleware": "Only accept requests that have the amount field specified, and convert its value to dollars"
});

🔹 ann

Perform an Approximate Nearest Neighbors search

// By key
await client.ann({ key: 'user:123', k: 5 });

// By vector
await client.ann({ vector: [0.1, 0.2, 0.3, ...], k: 5, ef: 25 });

• key: Source object key (use embedding from this object)
• vector: Query vector as array of floats (alternative to key)
• k: Number of nearest neighbors to return (default: 5)
• ef: Search width parameter (default: 25)
• use: For key-based search, use "data" or "embedding" (default: "embedding")

🔹 getSimilar

Perform approximate nearest neighbor search (alias for ANN with full vector support)

// By key
await client.getSimilar({ key: 'user:123', k: 10 });

// By vector
await client.getSimilar({ vector: [0.1, 0.2, 0.3, ...], k: 10 });

• key: Source object key (use embedding from this object)
• vector: Query vector as array of floats (alternative to key)
• k: Number of nearest neighbors to return (default: 5)
• ef: Search width parameter (default: 25)
• use: For key-based search, use "data" or "embedding" (default: "embedding")

🔹 query

Make querys in natural language

await client.query({'query' : 'Insert the value 5 into the grades array of user:123', 'backend' : 'openai:gpt-4o-mini'|);

• query: Your query in natural language.
• ref: The LLM backend. Must be openai:model-name or ollama:model-name, if not specified openai:gpt-4o-mini will be used as default. If you're using OpenAI as your backend you must specify the OPENAI_API_KEY env variable.

🔹 ask

Ask question about your data in natural language

await client.ask({'question' : 'How many user over 25 years old do we have. Just return the number.', 'backend' : 'openai:gpt-4o-mini'});

• question: Your question in natural language.
• ref: The LLM backend. Must be openai:model-name or ollama:model-name, if not specified openai:gpt-4o-mini will be used as default. If you're using OpenAI as your backend you must specify the OPENAI_API_KEY env variable.

System Analytics

🔹 get_operations

Returns all operations executed on the database.

🔹 get_access_frequency

Returns the number of times an object has been queried or accessed.

await client.get_access_frequency({'key' : 'jhon'})

🔹 set_mindspace

Create or update a mindspace with a specific configuration.

await client.set_mindspace({
  mindspace_id: 'my_mindspace',
  config: 'Configuration string for the mindspace'
});

• mindspace_id (optional): Identifier for the mindspace. If not provided, a default will be used.
• config: Configuration string defining the mindspace behavior.

🔹 create_mindspace

Create a new mindspace (alias for SET_MINDSPACE).

await client.create_mindspace({
  mindspace_id: 'my_mindspace',
  config: 'Configuration string for the mindspace'
});

• mindspace_id (optional): Identifier for the mindspace. If not provided, a UUID will be generated.
• config: Configuration string defining the mindspace behavior.

🔹 delete_mindspace

Delete an existing mindspace.

await client.delete_mindspace({
  mindspace_id: 'my_mindspace'
});

• mindspace_id: Identifier of the mindspace to delete.

🔹 chat_mindspace

Interact with a mindspace by sending a message.

await client.chat_mindspace({
  mindspace_id: 'my_mindspace',
  message: 'Hello, how can you help me?'
});

• mindspace_id: Identifier of the mindspace to chat with.
• message: The message to send to the mindspace.

🔹 lecture_mindspace

Import text corpus into a mindspace for semantic search and context retrieval.

await client.lecture_mindspace({
  mindspace_id: 'my_mindspace',
  corpus: 'User John Doe is a software engineer who specializes in Rust and distributed systems...'
});

• mindspace_id: Mindspace ID to import into
• corpus: Text content to import

Responses

All responses obbey the following pattern:

{
  data: any //the requested data if any
  message: string //status message
  type: string //SUCCESS || ERROR
}

AI responses obbey a different patern:

ask

{
  response: string //response to the question
}

query

{
  result: string //response from the operation made in the db
  status: string //status
}

ann

{
  results: array //response from the operation made in the db
}

🧠 Key Concepts

• key: Unique identifier of the object.
• type: Object type (e.g., 'user').
• field_array: Advanced filters for bulk operations.
• notifications: Subscription to real-time changes.
• vertices: Graph-like relationships between objects.

💬 Questions or Suggestions?

Feel free to open an issue or contribute! With ❤️ from the Satori team.