# Official MonkDB TS/JS SDK

![Version](https://img.shields.io/badge/version-0.1.6-blue.svg)
![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)
![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)
![Last Updated](https://img.shields.io/badge/last%20updated-March%2026%2C%202025-success)

Welcome to the official TypeScript SDK for MonkDB, an AI-native database designed to handle diverse data workloads seamlessly. This SDK empowers developers to interact with MonkDB using TypeScript, leveraging its robust features for modern application development.​

**Note**:

The `@monkdb/monkdb` TS/JS SDK, which is authored using modern **ESM (ECMAScript Modules)**, fully supports both **JavaScript** and **TypeScript** environments, provided the runtime supports ESM. 

## ✅ `@monkdb/monkdb` SDK Compatibility and Usage Guide

### 🔧 Module System:

The SDK is authored and published as an ES Module (ESM).
- ✅ Works seamlessly in TypeScript projects.
- ✅ Fully usable in JavaScript (ESM) projects.
- ⚠️ Not directly compatible with legacy CommonJS (require()) environments unless transpiled or imported via dynamic import (await import()).

### 📦 Package Details:

- **Package**: @monkdb/monkdb
- **Version**: 0.1.6 (latest as of now)
- **Module Type**: ESM
- **Types**: Bundled TypeScript type declarations (.d.ts)

### 💻 Node.js Version Support

To use the SDK without any issues, make sure you're using a Node.js version that natively supports ESM and modern TypeScript features.

| Node.js Version  | ESM Support                                          | @monkdb/monkdb SDK Compatibility                     |
|------------------|-----------------------------------------------------|------------------------------------------------------|
| >=14.13.0       | ✅ Experimental ESM support with flags or .mjs      | ⚠️ Works with caveats (not recommended)              |
| >=16.0.0        | ✅ Stable ESM support                                | ✅ Fully compatible                                   |
| >=18.0.0        | ✅ Stable + LTS                                     | ✅ Recommended                                        |
| >=20.0.0        | ✅ LTS + Modern runtime features                     | ✅ Fully supported                                    |
| >=21.x.x        | ✅ Latest features, top-tier performance            | ✅ Fully supported                                    |
| <=14.x          | ⛔ ESM not fully supported                           | ❌ Not compatible                                     |


- ✅ **Recommended Node.js version**: 18.x or newer
- ⚠️ **Minimum working version**: 14.13.0 (with "type": "module" and/or .mjs extensions)
- ❌ **Not supported**: Node <=14.x, legacy CommonJS-only environments

---

## 🚀 Features

- **🕒 Time Series Data**: Efficiently store and analyze time-series data, enabling applications to process and query time-stamped information with ease.​

- **🧠 Vector Data Integration**: Manage and query vector data, facilitating operations like similarity searches and machine learning model integrations.​

- **🔍 Full-Text Search**: Perform comprehensive text searches across your datasets, enhancing the retrieval of relevant information through advanced indexing and querying capabilities.​

- **🌍 Geospatial Queries**: Execute complex geospatial queries to handle location-based data, supporting applications that require spatial analysis and mapping functionalities.​

- **📦 Blob Storage**: Store and retrieve binary large objects (BLOBs), allowing for the management of multimedia files, documents, and other large data types within the database.​

- **📄 Document Store with SQL Interface**: Combine the flexibility of a document store with the power of SQL, providing a PGWire-compatible SQL interface for structured querying of unstructured data.

- **🚀 Streaming SQL**- Run realtime/streaming data workloads to perform petabyte scale SQL analytics (realtime).

---

## 📦 Installation

To install the MonkDB's **TypeScript SDK**, use `npm` or `yarn`:

```bash
npm install @monkdb/monkdb
```

or 

```bash
yarn add @monkdb/monkdb
```

---

## 🧪 Usage

### Typescript Usage Example

Here's a basic example of how to establish a connection to MonkDB and execute queries using the SDK:

```ts
// index.ts
import { MonkConnection } from '@monkdb/monkdb';

const connection = new MonkConnection({
  servers: ['http://127.0.0.1:4200'],
  username: 'your_username',
  password: 'your_password',
});

const cursor = connection.cursor();

async function runQuery() {
  await cursor.execute('SELECT * FROM your_table');
  const results = cursor.fetchall();
  console.log(results);
}

runQuery().catch(console.error).finally(() => {
  cursor.close();
  connection.close();
});
```

No special setup is needed beyond `tsconfig.json` with `"module": "ES2020"` or higher.

### JavaScript Usage Example

Here's a basic example of how to establish a connection to MonkDB and execute queries using the SDK:

```js
// index.js
import { MonkConnection } from '@monkdb/monkdb';

const conn = new MonkConnection({
  servers: ['http://localhost:4200'],
  username: 'monk',
  password: 'monk',
  schema: 'doc',
});

const cursor = conn.cursor();

await cursor.execute('SELECT * FROM my_table');
const rows = cursor.fetchall();

console.log(rows);

cursor.close();
conn.close();
```

Ensure your `package.json` contains:

```json
"type": "module"
```
---


## 📚 Documentation
Visit our [tech documentation](https://bitbucket.org/atomstatedev/documentation/src/main/) on how to execute use cases on MonkDB.

---

## Examples

To get a feel of MonkDB using TS/JS, please follow the instructions available in this [README](https://bitbucket.org/atomstatedev/monkdb.ts/src/main/examples/README.md) file.

---

## 📜 License
This project is licensed under the **Apache-2.0** License.

---

## 🤝 Support

For enterprise support or any inquiries, please contact us at 📧 [support@monkdb.com](mailto:support@monkdb.com).

---