## Foundation: Base Classes

These classes provide the foundation for database interactions in the package. While Models and Repositories offer convenient high-level APIs, the base classes give you direct access to queries, records, and table operations when you need more control.

### Query

The `Query` class allows you to build and execute database queries. It provides methods like `Run()` for non-SELECT queries, `All()` and `Get()` for fetching results, `Count()` for counting records, and `DoesTableExist()` for checking table existence.

## Example Usage:

```typescript
import { Query } from '@kirbkis/database-handler-core';

const query = new Query({
  tableName: 'users',
  query: 'SELECT * FROM users WHERE age > @age',
  parameters: { age: 18 },
  adapterName: 'myDatabase',
});

const results = await query.All();
console.log(results);
```

**Note:**

The query string should use `@paramName` placeholders for parameters. Other formats (`:param`, `?`, `$1`) are not supported at this level — parameter conversion is handled by the adapter.

**Parameters:**

| Parameter     | Type     | Description                                         | Optional? |
| ------------- | -------- | --------------------------------------------------- | --------- |
| `tableName`   | `string` | The name of the database table to query             | No        |
| `query`       | `string` | The SQL query string with `@paramName` placeholders | Yes       |
| `parameters`  | `object` | Key-value pairs for query parameters                | Yes       |
| `adapterName` | `string` | The name of the database adapter to use             | Yes       |

**Methods:**

| Method                              | Description                                                          |
| ----------------------------------- | -------------------------------------------------------------------- |
| `Run()`                             | Execute a non-SELECT query (INSERT, UPDATE, DELETE)                  |
| `All()`                             | Execute a SELECT query and return all matching rows as `Record[]`    |
| `Get()`                             | Execute a SELECT query and return the first matching row as `Record` |
| `Count()`                           | Execute a COUNT query and return the result as a number              |
| `DoesTableExist()`                  | Check if the table exists in the database                            |
| `TableColumnInformation(tableName)` | Get raw column metadata for a table                                  |

---

### Record

The `Record` class represents a single row in a database table. It provides methods to manipulate the record, such as `Insert()`, `Delete()`, and `Update()`.

While the actual data is stored in the `.values` property, the Record class implements custom inspection methods so that `console.log(record)` displays the data directly rather than the wrapper object. Records also support JSON serialization and can be converted to strings for logging.

## Example Usage:

```typescript
import { Record } from '@kirbkis/database-handler-core';

const record = new Record({
  table: 'users',
  values: { name: 'John Doe', age: 30 },
  adapter: 'myDatabase',
});

await record.Insert();
console.log('Record inserted with ID:', record.values.id);

res.json(record); // Returns the record data as JSON
```

**Parameters:**
| Parameter | Type | Description | Optional? |
|-----------|------|-------------|-----------|
| `table` | `string` | The name of the database table | No |
| `values` | `object` | Key-value pairs representing the record's data | No |
| `adapter` | `string` | The name of the database adapter to use | Yes |

**Methods:**

| Method                               | Description                                                                  |
| ------------------------------------ | ---------------------------------------------------------------------------- |
| `Insert()`                           | Insert this record into the database; updates `values` with the inserted row |
| `Update(newValues, whereParameters)` | Update this record in the database with new values                           |
| `Delete(primaryKey?)`                | Delete this record (performs a soft delete if `deleted_at` column exists)    |
| `toJSON()`                           | Returns the raw values object (used by `JSON.stringify`)                     |
| `toString()`                         | Returns a pretty-printed JSON string of the values                           |

---

### Table

The `Table` class provides a high-level interface for common database table operations. It abstracts away SQL syntax by offering methods like `FetchRecords()` for fetching multiple rows, `FetchSingleRecord()` for fetching a single row, `CreateRecord()` for adding data, and `FetchJoined()` for combining tables. You can also retrieve table metadata, count records, check table existence, inspect generated SQL, and drop tables.

## Example Usage:

```typescript
import { Table } from '@kirbkis/database-handler-core';

const usersTable = new Table({
  name: 'users',
  adapter: 'myDatabase',
});

const allUsers = await usersTable.FetchRecords({
  base: { from: 'users' },
});
console.log(allUsers);
```

**Note:**

For more information check the [Table class documentation](https://github.com/IamKirbki/npm-database-handler/wiki/Table).

**Parameters:**
| Parameter | Type | Description | Optional? |
|-----------|------|-------------|-----------|
| `name` | `string` | The name of the database table | No |
| `adapter` | `string` | The name of the database adapter to use | Yes |

**Methods:**

| Method                               | Description                                                  |
| ------------------------------------ | ------------------------------------------------------------ |
| `FetchRecords(queryLayers)`          | Fetch multiple records using structured `QueryLayers`        |
| `FetchSingleRecord(queryLayers)`     | Fetch a single record (wraps `FetchRecords` with `limit: 1`) |
| `RecordsCount()`                     | Get the total count of records in the table                  |
| `CreateRecord(values)`               | Insert a new record into the table                           |
| `FetchJoined(queryLayers)`           | Perform JOIN operations; nested results split by table       |
| `exists()`                           | Check if the table exists in the database                    |
| `toSql(queryLayers)`                 | Return the SQL string for a query without executing it       |
| `Drop()`                             | Drop the table from the database                             |
| `TableColumnInformation(tableName?)` | Get raw column metadata                                      |
| `ReadableTableColumnInformation()`   | Get human-readable column metadata                           |