# DBJS – Quick Start Guide

This short guide walks you through the most common tasks when using **DBJS**, a lightweight in‑memory database library written in TypeScript.

---

## 1. Installation

```bash
npm i @dbjs/core   # or yarn add @dbjs/core
```

The package exports a single class `DBTable` that you can import directly:

```ts
import { DBTable } from "dbjs-core";
```

---

## 2. Creating a Table

You can create a table from an array of plain objects or from JSON.

### From an Array

```ts
const users = new DBTable([
    { id: 1, name: "Alice", age: 30 },
    { id: 2, name: "Bob", age: 25 },
]);
```

### From JSON

```ts
const json = `[
  {"id":3,"name":"Carol","age":27}
]`;
const table = DBTable.fromJson(json);
```

---

## 3. Basic Operations

| Operation             | Example                                  | Result                        |
| --------------------- | ---------------------------------------- | ----------------------------- |
| **count**             | `dbTable.count`                          | Number of rows                |
| **top / bottom**      | `dbTable.top(1)`                         | First/Last row(s)             |
| **whereColumnEquals** | `dbTable.whereColumnEquals("age", 25)`   | Rows where age is 25          |
| **incrementColumn**   | `dbTable.incrementColumn("age")`         | Increments every age by 1     |
| **setColumn**         | `dbTable.setColumn("status", "active")`  | Sets status for all rows      |
| **select**            | `dbTable.select(["id", "name"])`         | New table with only id & name |
| **union**             | `dbTable.union(otherTable)`              | Combines two tables           |
| **mergeTableBy**      | `dbTable.mergeTableBy(orders, "userId")` | Joins on userId               |

---

## 4. Advanced Features

### Distinct Rows

```ts
const unique = users.distinct();
```

### Shuffling

```ts
const shuffled = users.shuffle();
```

### Splitting for Training / Testing

```ts
const [train, test] = users.split(80); // 80% train, 20% test
```

---

## 5. Serialisation

| Method                 | Purpose                                                  |
| ---------------------- | -------------------------------------------------------- |
| `toJSON()`             | Convert table to JSON string (pretty‑printed by default) |
| `fromJson(json)`       | Recreate a table from JSON                               |
| `toSuperArrays()`      | Get each column as a `SuperArray` instance               |
| `fromSuperArrays(obj)` | Build a table from an object of `SuperArray`s            |

---

## 6. Extending DBTable

If you need custom behaviour, extend the class:

```ts
class MyTable extends DBTable {
    // add your own methods here
}
```

All existing methods will return instances of `MyTable` thanks to the internal `currentConstructor` logic.

---

## 7. Tips & Gotchas

-   **Immutability** – Most query methods (`where…`, `select`, etc.) return a _new_ table; they do not mutate the original.
-   **Chaining** – You can chain calls: `users.whereColumnGreaterThan("age", 20).orderBy("name").top(5)`.
-   **Type safety** – When using TypeScript, define an interface for your rows and pass it to `DBTable<YourInterface>`.

---

## 8. Example Project

```ts
import { DBTable } from "dbjs-core";

interface Person {
    id: number;
    name: string;
    age: number;
}

const data: Person[] = [
    { id: 1, name: "Alice", age: 30 },
    { id: 2, name: "Bob", age: 25 },
];

const table = new DBTable<Person>(data);

// Find all people older than 26 and sort by name
const result = table.whereColumnGreaterThan("age", 26).orderBy("name");
console.log(result.data);
```

---

## 9. Support & Contribution

Feel free to open issues or pull requests on the GitHub repository. Documentation improvements are always welcome!