js-indexus-sdk
v1.0.26
Published
A powerful toolkit for decentralized, peer-to-peer networks.
Downloads
844
Readme
Indexus SDK
Welcome to the Indexus SDK, a powerful toolkit designed to facilitate the addition and retrieval of items in decentralized, peer-to-peer collections. With Indexus, developers can effortlessly manage data within collections, enabling efficient searches and data retrieval without the need to understand the underlying complexities of the network.
🌐 Demo Websites
Upcoming applications to see Indexus in action:
Ephemeral Global Chat: Demo Link
- A global chat platform allowing users to post and view messages on a world map in real-time.
Multilevel Collaborative Drawing: Demo Link
- A web application where users collaboratively create layered artworks, building upon each other's contributions.
Multi-Collection Search: Demo Link
- A unified search interface querying multiple collections like accommodations, hotels, and landmarks simultaneously.
Multi-Dimensional Temporal Analysis: Demo Link
- An analytical tool for visualizing data trends over time across different geographic regions.
Geolocated News and Articles: Demo Link
- Access news and articles from various sources, filtered by publication date and location.
Semantic Search Engine: Demo Link
- An advanced search engine leveraging semantic understanding to deliver contextually relevant results.
About the SDK
The Indexus SDK allows developers to build decentralized applications by providing a structured approach to adding items to collections and performing efficient searches within those collections. By abstracting the complexities of the underlying peer-to-peer network, Indexus enables you to focus on creating innovative applications with seamless data management capabilities.
Table of Contents
- Features
- Installation
- Getting Started
- Main Components
- Example Usage
- Roadmap
- Advanced Concepts
- Troubleshooting
- Contributing
- License
Features
Granted
- Add Items to Collections: Easily add items (references) into decentralized collections with minimal code.
- Search Capabilities: Perform efficient searches within collections to retrieve items based on specific criteria.
- Incremental Search: Quickly retrieve subsequent items based on proximity to indexed items.
- Simplified API: Interact with the network using straightforward methods without worrying about the underlying peer-to-peer mechanisms.
- Modular Architecture: Organized components for collections, items, and networking, allowing for easy integration and extension.
Upcoming
- Aggregation Functions: Aggregate data using sum, average, min, max, and more.
- Sorting and Filtering: Sort and filter items within collections on chosen dimensions.
Installation
Prerequisites
- Node.js (v14 or newer)
- npm (v6 or newer)
Steps
Install the Indexus SDK
npm install js-indexus-sdk
Getting Started
Setting Up Your Environment
Ensure Node.js and npm are Installed
Verify the installation by checking the versions:
node -v # Should output Node.js version npm -v # Should output npm version
Initialize Your Project
Create a new project directory and initialize npm:
mkdir my-indexus-project cd my-indexus-project npm init -y
Install the Indexus SDK
npm install js-indexus-sdk
Running the Example
Copy the example code provided in the Example Usage section into a file named main.js
and run:
node main.js
Main Components
1. Entities
- Item: Represents individual data items within a collection.
- Collection: Manages a group of items with defined dimensions and configurations.
- Space: Defines the operational space based on collection dimensions.
- Locality: Handles adding items to collections and performing search operations.
2. Networking
- API: Facilitates communication within the network, handling requests like adding items and searching.
- Network: Manages interactions, including connecting to bootstrap peers.
3. Utilities
- Dimensions (Spherical & Linear): Define different dimensional models for data representation.
- Encoding Utilities: Provide functions like
charsToNumbers
for data encoding.
Example Usage
Below is an example of how to set up and use the Indexus SDK. This example demonstrates adding an item to a collection and performing a search operation.
// main.js
import {
Item,
Collection,
Space,
Locality,
Peer,
Network,
API,
Spherical,
Linear,
} from "js-indexus-sdk";
function timeout(ms) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
async function run() {
const protocol = "https"
const bootstraps = ["bootstrap.testnet.indexus.network|21000"];
// Instantiate collections
const helloworld = new Collection("R9zIWvyC3RcBy2AIH9jeZIqUywU", [
{
name: "gps",
type: "spherical",
args: [-90, -180, 90, 180],
},
{
name: "time",
type: "linear",
args: [-126230400 * 16 * 16 * 8, 126230400 * 16 * 16 * 8],
},
]);
// Initialize spaces
const space = new Space(
helloworld.dimensions(),
helloworld.mask(),
helloworld.offset()
);
const spaces = {};
spaces[helloworld.name()] = space;
// Initialize options object
const options = {};
// Create dimensions and options
const geospatiality = space.dimension(0);
options[geospatiality.name()] = {
origin: geospatiality.newPoint([0, 0]), // San Francisco coordinates
filters: geospatiality.newFilter([0, 0], [0, 360]), // Distance in km, direction in degrees
};
const temporality = space.dimension(1);
options[temporality.name()] = {
origin: temporality.newPoint([Date.now() / 1000]), // Current time in Unix timestamp
filters: temporality.newFilter([0, 0], [0]), // One year in seconds
};
// Define cap, limit, and step
const cap = 2; // Maximum number of sets to process per layer
const step = 10; // Number of items to return per output step
const output = {
send: (result) => console.log("Output:", result),
};
const monitoring = {
send: (message) => {}, //console.log("Monitoring:", message),
};
// Create a new Network instance
const api = new API();
const network = new Network(protocol, api, bootstraps);
// Create a new Locality instance
const indexus = new Locality(
spaces,
options,
cap,
step,
output,
monitoring,
network
);
const item = new Item(
helloworld.name(),
space.encode(
[
geospatiality.newPoint([0, 0]),
temporality.newPoint([Date.now() / 1000]),
],
27
),
[150],
"myFirstItemId"
);
await indexus.addItem(item);
await timeout(3000);
try {
await indexus.search();
} catch (error) {
console.error("An error occurred during the search process:", error);
}
}
// Run the async function
run();
Explanation
- Importing Modules: Import the necessary classes and utilities from the Indexus SDK.
- Configuration:
- Bootstraps: Defines the initial peer(s) to connect with.
- Collections: Defines a collection with spherical and linear dimensions.
- Spaces and Options:
- Space: Initializes the operational space based on the collection's dimensions.
- Options: Sets up options for geospatiality and temporality, including origin points and filters.
- Network Setup:
- API & Network: Initializes the API and network instances to manage interactions.
- Locality: Creates a locality instance to handle adding items and performing searches.
- Adding an Item:
- Item Creation: Creates a new item with encoded spatial and temporal data.
- Adding to Collection: Adds the item to the collection using the
indexus.addItem
method.
- Searching:
- Timeout: Waits for a few seconds to ensure the item is propagated.
- Search Operation: Performs a search operation to retrieve items from the collection.
Roadmap
We are continuously working to enhance the Indexus SDK and its capabilities. Here's a high-level roadmap of what's coming next:
SDK Enhancements
- Aggregation Functions: Implement sum, average, min, max operations on item properties.
- Advanced Filtering and Sorting: Introduce more robust filtering and sorting options within collections.
Documentation
- Comprehensive Guides: Expand our documentation with detailed guides and tutorials.
- API Reference: Provide an exhaustive API reference for all SDK functionalities.
Community and Collaboration
- Open Source Contributions: Encourage community contributions and provide support for developers.
- Community Events: Host webinars and workshops to engage with the developer community.
Upcoming Use Cases and Demos
Stay tuned for updates and new releases!
Advanced Concepts
While the Indexus SDK abstracts the complexities of the underlying peer-to-peer network, it's built upon a robust protocol that ensures data is efficiently stored, indexed, and retrieved across a decentralized network of nodes.
Overview of the Indexus Protocol
- Decentralized Data Management: Indexus uses a peer-to-peer protocol to distribute data across multiple nodes, ensuring high availability and resilience.
- Binary Space Partitioning (BSP): Data is organized using BSP, allowing for efficient multidimensional searches and proximity queries.
- Eventual Consistency: The system ensures that all nodes eventually reach a consistent state, even in the presence of network partitions or node failures.
- Conflict Resolution: Indexus integrates Conflict-free Replicated Data Types (CRDT) to handle data synchronization and conflict resolution seamlessly.
- Caching and Replication: Frequently accessed data is cached by neighboring nodes, improving access speed and reducing latency.
- Delegation Mechanism: Sub-parts of collections are delegated to different nodes when they reach a certain size, ensuring balanced data distribution.
Troubleshooting
Common Issues
Cannot Find Module 'js-indexus-sdk'
Cause: The Indexus SDK is not installed in your project.
Solution:
- Install the SDK:
npm install js-indexus-sdk
- Install the SDK:
Await is Only Valid in Async Functions
Cause: Using
await
at the top level outside of an async function.Solution:
- Wrap your code in an
async
function and call it.
- Wrap your code in an
Network Errors
Cause: Unable to connect to the bootstrap peer or network issues.
Solution:
- Ensure that the bootstrap peer (
bootstrap.testnet.indexus.network:21000
) is accessible. - Check your network connection and firewall settings.
- Ensure that the bootstrap peer (
Contributing
We welcome contributions from the community! If you'd like to contribute to the Indexus SDK, please follow these guidelines:
- Fork the Repository
- Create a Feature Branch
git checkout -b feature/YourFeature
- Commit Your Changes
- Push to Your Fork
- Create a Pull Request
Please ensure that your code adheres to the project's coding standards and includes appropriate tests and documentation.
License
This project is licensed under the MIT License.
Contact
For any inquiries or support, please contact [email protected].
Happy Coding with Indexus SDK! 🚀
Notes
The Indexus SDK simplifies the process of adding items to decentralized collections and performing efficient searches. By decoupling the data exploration protocol from its display, developers can focus on creating innovative user experiences while benefiting from the robust, decentralized infrastructure provided by Indexus.
This README was last updated on October 2, 2024.