feat: initial implementation

.github/workflows/ci.yml

@@ -22,25 +22,3 @@ jobs:
 
       - name: Check fmt
         run: deno task check
-
-  test:
-    name: Tests
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Clone repo
-        uses: actions/checkout@v3
-
-      - name: Install deno
-        uses: denoland/setup-deno@v1
-
-      - name: Run unit tests
-        run: deno task test
-
-      - name: Generate lcov
-        run: deno coverage --unstable --lcov ./coverage > coverage.lcov
-
-      - name: Upload coverage
-        uses: codecov/codecov-action@v1
-        with:
-          files: coverage.lcov

.gitignore

@@ -196,3 +196,4 @@ $RECYCLE.BIN/
 # End of https://www.toptal.com/developers/gitignore/api/deno,linux,macos,windows,intellij+all,visualstudiocode
 
 coverage
+coverage.lcov

README.md

@@ -13,3 +13,223 @@ A subgoal is for this repo to live in Deno Standard Library and available in
 be available under `@db/core`.
 
 This repo is WIP and can change at any time.
+
+## Usage
+
+Minimal usage example:
+
+```ts
+await using db = new Client(connectionUrl, connectionOptions);
+await db.connect();
+await db.execute("SOME INSERT QUERY");
+const res = await db.query("SELECT * FROM table");
+```
+
+SQLx provides a standard for interacting with a database.
+
+### Client
+
+Full compliance with SQLx provides a database client with the following methods
+(see [SqlxClient](./lib/client.ts)):
+
+- `connect` (See [SqlxConnection](./lib/connection.ts)): Creates a connection to
+  the database
+- `close` (See [SqlxConnection](./lib/connection.ts)): Closes the connection to
+  the database
+- `execute` (See [SqlxQueriable](./lib/core.ts)): Executes a SQL statement
+- `query` (See [SqlxQueriable](./lib/core.ts)): Queries the database and returns
+  an array of object
+- `queryOne` (See [SqlxQueriable](./lib/core.ts)): Queries the database and
+  returns at most one entry as an object
+- `queryMany` (See [SqlxQueriable](./lib/core.ts)): Queries the database with an
+  async generator and yields each entry as an object
+- `queryArray` (See [SqlxQueriable](./lib/core.ts)): Queries the database and
+  returns an array of arrays
+- `queryOneArray` (See [SqlxQueriable](./lib/core.ts)): Queries the database and
+  returns at most one entry as an array
+- `queryManyArray` (See [SqlxQueriable](./lib/core.ts)): Queries the database
+  with an async generator and yields each entry as an array
+- `sql` (See [SqlxQueriable](./lib/core.ts)): Allows you to create a query using
+  template literals, and returns the entries as an array of objects. This is a
+  wrapper around `query`
+- `sqlArray` (See [SqlxQueriable](./lib/core.ts)): Allows you to create a query
+  using template literals, and returns the entries as an array of arrays. This
+  is a wrapper around `queryArray`
+- `prepare` (See [SqlxPreparable](./lib/core.ts)): Returns a prepared statement
+  class that contains a subset of the Queriable functions (see
+  [SqlxPreparedQueriable](./lib/core.ts))
+- `beginTransaction` (See [SqlxTransactionable](./lib/core.ts)): Returns a
+  transaction class that contains implements the queriable functions, as well as
+  transaction related functions (see [SqlxTransactionQueriable](./lib/core.ts))
+- `transaction` (See [SqlxTransactionable](./lib/core.ts)): A wrapper function
+  for transactions, handles the logic of beginning, committing and rollback a
+  transaction.
+
+### ClientPool
+
+Full compliance with SQLx provides a database client pool (a pool of clients)
+with the following methods (see [SqlxClientPool](./lib/pool.ts)):
+
+- `connect` (See [SqlxConnection](./lib/core.ts)): Creates the connection
+  classes and adds them to a connection pool, and optionally connects them to
+  the database
+- `close` (See [SqlxConnection](./lib/core.ts)): Closes all connections in the
+  pool
+- `acquire` (See [SqlxPoolable](./lib/core.ts)): Retrieves a
+  [SqlxPoolClient](./lib/pool.ts) (a subset of [Client](#client)), and connects
+  it if not already connected
+- `release` (See [SqlxPoolable](./lib/core.ts)): Releases a connection back to
+  the pool
+
+### Examples
+
+Using const (requires manual close at the end)
+
+```ts
+const db = new Client(connectionUrl, connectionOptions);
+await db.connect();
+await db.execute("SOME INSERT QUERY");
+const res = await db.query("SELECT * FROM table");
+await db.close();
+```
+
+Query object
+
+```ts
+await using db = new Client(connectionUrl, connectionOptions);
+await db.connect();
+await db.execute("SOME INSERT QUERY");
+const res = await db.query("SELECT * FROM table");
+console.log(res);
+// [{ col1: "some value" }]
+```
+
+Query array
+
+```ts
+await using db = new Client(connectionUrl, connectionOptions);
+await db.connect();
+await db.execute("SOME INSERT QUERY");
+const res = await db.queryArray("SELECT * FROM table");
+console.log(res);
+// [[ "some value" ]]
+```
+
+Query with template literals
+
+```ts
+await using db = new Client(connectionUrl, connectionOptions);
+await db.connect();
+await db.execute("SOME INSERT QUERY");
+const res = await db.sqlArray`SELECT * FROM table where id = ${id}`;
+console.log(res);
+// [[ "some value" ]]
+```
+
+Transaction
+
+```ts
+await using db = new Client(connectionUrl, connectionOptions);
+await db.connect();
+await db.execute("SOME INSERT QUERY");
+const transaction = await db.beginTransaction();
+await transaction.execute("SOME INSERT QUERY");
+await transaction.commitTransaction();
+// transaction can no longer be used
+```
+
+Transaction wrapper
+
+```ts
+await using db = new Client(connectionUrl, connectionOptions);
+await db.connect();
+await db.execute("SOME INSERT QUERY");
+const res = await db.transaction(async (t) => {
+  await t.execute("SOME INSERT QUERY");
+  return t.query("SOME SELECT QUERY");
+});
+console.log(res);
+// [{ col1: "some value" }]
+```
+
+Prepared statement
+
+```ts
+await using db = new Client(connectionUrl, connectionOptions);
+await db.connect();
+await db.execute("SOME INSERT QUERY");
+const prepared = db.prepare("SOME PREPARED STATEMENT");
+await prepared.query([...params]);
+console.log(res);
+// [{ col1: "some value" }]
+```
+
+## Implementation
+
+To be fully compliant with SQLx, you will need to implement the following
+classes for your database driver:
+
+- `Connection` ([SqlxConnection](./lib/connection.ts)): This represents the
+  connection to the database. This should preferably only contain the
+  functionality of containing a connection, and provide a minimum query method
+  to be used to query the database. The query method does not need to follow any
+  specific spec, but must be consumable by all query functions as well as
+  execute functions (see `SqlxQueriable`)
+- `Prepared` ([SqlxPreparedQueriable](./lib/core.ts)): This represents a
+  prepared statement. All queriable methods must be implemented
+- `Transaction` ([SqlxTransactionQueriable](./lib/core.ts)): This represents a
+  transaction. All queriable methods must be implemented
+- `Client` ([SqlxClient](./lib/client.ts)): This represents a database client
+- `ClientPool` ([SqlxClientPool](./lib/pool.ts)): This represents a pool of
+  clients
+- `PoolClient` ([SqlxPoolClient](./lib/pool.ts)): This represents a client to be
+  provided by a pool
+
+It is also however advisable to create the following sub classes to use in other
+classes:
+
+- [SqlxQueriable](./lib/core.ts): This represents a queriable base class that
+  contains the standard SQLx query methods. In most cases, this serves as a base
+  class for all other queriable classes
+- [SqlxEventTarget](./lib/events.ts): A typed event target class
+- [SqlxError](./lib/errors.ts): A typed error class
+
+### Inheritance graph
+
+In most cases, these are the classes and the inheritance graph that should be
+implemented. Notice how almost everything extends `SqlxBase` at the base.
+
+- SqlxConnection
+  - SqlxBase
+- SqlxPreparedQueriable
+  - SqlxBase
+- SqlxTransactionQueriable
+  - SqlxPreparable
+    - SqlxQueriable
+      - SqlxBase
+- SqlxClient
+  - SqlxTransactionable
+    - SqlxPreparable
+      - SqlxQueriable
+        - SqlxBase
+- SqlxPoolClient
+  - SqlxTransactionable
+    - SqlxPreparable
+      - SqlxQueriable
+        - SqlxBase
+- SqlxClientPool
+  - SqlxBase
+
+### Other
+
+There is also a [SqlxDeferredStack](./lib//deferred.ts) that is used by the pool
+as a helper for queuing and stacking the pool clients.
+
+### Base class
+
+SQLx uses implementable interfaces as well as base classes that needs to be
+inherited for desired functionality.
+
+At the base layer, you will have to extend the `SqlxBase` class for all SQLx
+derived classes. Alternatively, if this is not possible, you can implement
+SqlxBase, and ensure that the dynamic and static properties are accessible.

deno.json

@@ -1,26 +1,37 @@
 {
-  "name": "@db/sqlx",
-  "version": "0.0.1",
+  "name": "@halvardm/sqlx",
+  "version": "0.0.0-13",
+  "lock": false,
   "exports": {
     ".": "./mod.ts",
-    "./core": "./lib/core/mod.ts",
-    "./mysql": "./lib/mysql/mod.ts",
-    "./postgres": "./lib/postgres/mod.ts",
-    "./sqlite": "./lib/sqlite/mod.ts"
+    "./testing": "./lib/testing.ts"
   },
   "tasks": {
     "check": "deno task format:check && deno task lint:check && deno task type:check",
     "lint:check": "deno lint",
     "format:check": "deno fmt --check",
-    "type:check": "deno check mod.ts",
-    "test": "deno task db:start && deno test -A --unstable-ffi --coverage; deno task db:stop",
+    "type:check": "deno check lib/*.ts",
+    "doc:check": "deno doc --lint lib",
+    "test": "deno task db:restart && deno test -A --unstable-ffi --coverage; deno task db:stop",
+    "test:ga": "deno task db:start && deno test -A --unstable-ffi --coverage && deno task db:stop",
+    "coverage:lcov": "deno coverage --exclude=vendor --lcov > coverage.lcov",
+    "db:restart": "deno task db:stop && deno task db:start",
     "db:start": "docker compose up -d --remove-orphans --wait && sleep 2",
     "db:stop": "docker compose down --remove-orphans --volumes"
   },
+  "fmt": {
+    "exclude": [
+      "coverage",
+      "vendor"
+    ]
+  },
+  "lint": {
+    "exclude": [
+      "coverage",
+      "vendor"
+    ]
+  },
   "imports": {
-    "@db/mysql": "https://deno.land/x/mysql@v2.12.1/mod.ts",
-    "@db/postgres": "https://deno.land/x/postgres@v0.19.3/mod.ts",
-    "@db/sqlite": "jsr:@db/sqlite@^0.11.0",
     "@std/assert": "jsr:@std/assert@^0.219.1",
     "@std/testing": "jsr:@std/testing@^0.219.1"
   }