# Blockflow SDK

Blockflow SDK provides a unified interface for interacting with different types of databases, including MongoDB, PostgreSQL, and DuckDB. The SDK offers a range of database operations through a simple, intuitive API, enabling developers to work with their data efficiently.

## Table of Contents

- [Installation](#installation)
- [Getting Started](#getting-started)
- [Database Clients](#database-clients)
  - [MongoClient](#mongoclient)
  - [PostgresClient](#postgresclient)
  - [DuckDBClient](#duckdbclient)
- [Database Operations](#database-operations)
  - [NativeDBOperations](#nativedboperations)
  - [InstanceDBOperations](#instancedboperations)
  - [APIDBOperations](#apidboperations)
- [Usage Examples](#usage-examples)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)

## Installation

Install the package via npm:

```bash
npm install blockflow-sdk
```

Or via yarn:

yarn add blockflow-sdk

Getting Started

To use the SDK, import the desired client based on the database you want to interact with. Each client provides methods for performing database operations like querying, inserting, updating, and deleting records.

import { MongoClient, PostgresClient, DuckDBClient } from "blockflow-sdk";
import {
  Bind,
  BlockflowInternalDatabase,
  InstanceMetadata,
} from "blockflow-sdk/utils";

// Example of creating a MongoDB client instance
const bind: Bind = {
  sdk: new BlockflowInternalDatabase(),
  metadata: {
    type: "Instance",
    blocknumber: 123,
    blockhash: "0xabc",
    chainId: 1,
    computeId: "compute-123",
  },
};

const mongoClient = new MongoClient(bind);

Database Clients

MongoClient

MongoClient is used to interact with a MongoDB database. It extends the ClientBase class and provides access to MongoDB-specific operations through the .db() method.

const mongoDbOperations = mongoClient.db({ name: "users", reorg: false });
// Use mongoDbOperations to perform CRUD operations

PostgresClient

PostgresClient is used to interact with a PostgreSQL database. It also extends ClientBase and allows you to perform PostgreSQL-specific database operations.

const postgresClient = new PostgresClient(bind);
const postgresDbOperations = postgresClient.db({
  name: "orders",
  reorg: false,
});

DuckDBClient

DuckDBClient is used to interact with a DuckDB database. It provides a similar interface to other clients, allowing you to use DuckDB in a unified manner.

const duckDbClient = new DuckDBClient(bind);
const duckDbOperations = duckDbClient.db({ name: "analytics", reorg: false });

Database Operations

NativeDBOperations

Provides native database operations such as find, findOne, aggregate, create, update, and delete.

const operations = mongoClient.db({ name: "users", reorg: false });
const users = await operations.find({ age: { $gt: 18 } });

InstanceDBOperations

Specialized for database operations tied to a specific instance. It includes methods like save and load, injecting metadata into the records.

const instanceOperations = mongoClient.db({
  name: "transactions",
  reorg: true,
});
await instanceOperations.save({ userId: "123", amount: 500 });

APIDBOperations

Exposes API-level database operations like find, findOne, aggregate, and query.

const apiOperations = postgresClient.db({ name: "api_logs", reorg: false });
const logs = await apiOperations.query("SELECT * FROM logs WHERE status = ?", [
  "success",
]);

Usage Examples

Performing a Simple Query

const userOperations = mongoClient.db({ name: "users", reorg: false });
const allUsers = await userOperations.find({});

Inserting Data

await userOperations.create({ name: "John Doe", age: 30 });

Updating Data

await userOperations.update({ name: "John Doe" }, { age: 31 });

Aggregating Data

const aggregatedData = await userOperations.aggregate([
  { $match: { age: { $gt: 18 } } },
  { $group: { _id: null, averageAge: { $avg: "$age" } } },
]);

API Reference

ClientBase

Base class for all database clients. Use this class to create instances of MongoClient, PostgresClient, or DuckDBClient.

db(entity: BlockflowSchemas): NativeDBOperations | InstanceDBOperations | APIDBOperations

Returns an instance of the appropriate database operations class based on the provided schema.

• Parameters:

  • entity - An object defining the schema with properties name (string) and reorg (boolean).

• Returns: An instance of NativeDBOperations, InstanceDBOperations, or APIDBOperations based on the schema.

Additional Information

• The SDK dynamically determines the return type of the .db() method based on the entity schema provided.
• Use the reorg property in the schema to determine whether to use NativeDBOperations, InstanceDBOperations, or APIDBOperations.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.

License

This project is licensed under the MIT License.