# @opdb/base

> OpDB Base Classes

Latest version **0.0.3** (published 2020-04-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @opdb/base
pnpm add @opdb/base
yarn add @opdb/base
bun add @opdb/base
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.3 |
| Published | 2020-04-05 |
| First published | 2020-02-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 34.6 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Author | OpDB / Marvin Scharle |
| Maintainers | marvinscharle |

## Links

- npm: https://www.npmjs.com/package/@opdb/base
- Repository: https://github.com/OpDatabase/base
- Homepage: https://github.com/OpDatabase/base#readme
- Issues: https://github.com/OpDatabase/base/issues
- npm.io page: https://npm.io/package/@opdb/base

## Dependencies (3)

- [uuid](https://npm.io/package/uuid.md) ^3.4.0
- [chalk](https://npm.io/package/chalk.md) ^3.0.0
- [zone.js](https://npm.io/package/zone.js.md) ^0.10.2

## Recent versions

- 0.0.3 (latest) — 2020-04-05
- 0.0.2 — 2020-03-21
- 0.0.1 — 2020-02-15

## README

# @opdb/base

This is an abstraction layer for database connections, connection and transaction handling.

The package contains two major things:

1. Base classes to coordinate database connections
2. Interfaces to implement database drivers

## Base Classes

### Base

Main class. Maintains a connection to a database connection pool. 

To execute an SQL query run this:

```typescript
import { Base } from '@opdb/base';

// Returns Promise<any[]>, representing any line that shall be returned.
Base.execute(`SELECT * FROM users`);

// You can supply an interface to have a type-safe response.
Base.execute<{id: string, username: string}>(`SELECT * FROM users`);

// You can use placeholders to escape your SQL query. The placeholders will be replaced correctly
// for each database adapter automatically.
// This will run the SQL query `SELECT * FROM users WHERE id = 1`
Base.execute<{id: string, username: string}>(`SELECT * FROM users WHERE id = $id`, {id: 1});
```

To start a new transaction run this:

```typescript
import { Base } from '@opdb/base';

// Method `transaction` accepts a block. Any statement within the block is run inside the transaction
// This example will run the following SQL statements:
// - BEGIN;
// - UPDATE users SET username = `marc` WHERE id = 1;
// - COMMIT;
Base.transaction(async () => {
  await Base.execute(`UPDATE users SET username = $username WHERE id = $id`, {
    id: 1,
    username: 'marc',
  });
});

// If any exception occurs during the transaction, the transaction will be rolled back.
// This example will run the following SQL statements:
// - BEGIN
// - UPDATE users SET username = `marc` WHERE id = 1;
// - ROLLBACK;
Base.transaction(async () => {
  await Base.execute(`UPDATE users SET username = $username WHERE id = $id`, {
    id: 1,
    username: 'marc',
  });
  throw new Error();
});
```

### ConnectionPool

This class manages a pool of database connections. The connections themselves are managed by the database adapters.

To register a new adapter run this:

```typescript
import { ConnectionPool, DatabaseAdapter } from '@opdb/base';

class FancyDatabaseAdapter implements DatabaseAdapter {
  // Custom Implementation here
}

ConnectionPool.registerAdapter(FancyDatabaseAdapter);
```

To connect a given database adapter run this:

```typescript
import { Base } from '@opdb/base';

Base.connectionPool.connect({
  adapter: 'fancy-adapter',
  // Adapter specific config
});
```

To get a database connection from the connection pool, use this method:

```typescript
import { Base } from '@opdb/base';

// This will return a Promise<DatabaseClient> which will handle the database connection.
Base.connectionPool.getConnection();
```

## Important Notes
@opdb/base uses [zone.js](https://github.com/angular/angular/tree/master/packages/zone.js) for handling transactions.

At the moment, zone.js is unable to use native node async/await.

Therefore, you should use TypeScript or Babel to compile your code in ES2015.

---
_Source: https://npm.io/package/@opdb/base · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._