feat: support string templates for query

Author: pi0

README.md

@@ -34,17 +34,19 @@ pnpm add db0
 import { createDB, sql } from "db0";
 import sqlite from "db0/connectors/better-sqlite3";
 
+// Initiate database with SQLite connector
 const db = createDB(sqlite({}));
 
-await db.exec(
-  "CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, firstName TEXT, lastName TEXT, email TEXT)"
-);
+// Create users table
+await db.sql`CREATE TABLE IF NOT EXISTS users ("id" TEXT PRIMARY KEY, "firstName" TEXT, "lastName" TEXT, "email" TEXT)`;
 
-await db.prepare("INSERT INTO users VALUES (?, 'John', 'Doe', '')").run(id);
+// Add a new user
+const userId = "1001";
+await db.sql`INSERT INTO users VALUES (${userId}, 'John', 'Doe', '')`;
 
-const row = await db.prepare("SELECT * FROM users WHERE id = ?").get(id);
-
-console.log(row);
+// Query for users
+const { rows } = await db.query`SELECT * FROM users WHERE id = ${userId}`;
+console.log(rows);
 ```
 
 <!-- 👉 Check out the [the documentation](https://db0.unjs.io) for usage information. -->

docs/content/2.usage.md

@@ -28,15 +28,17 @@ pnpm add db0
 import { createDB, sql } from "db0";
 import sqlite from "db0/connectors/better-sqlite3";
 
+// Initiate database with SQLite connector
 const db = createDB(sqlite({}));
 
-await db.exec(
-  "CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, firstName TEXT, lastName TEXT, email TEXT)"
-);
+// Create users table
+await db.sql`CREATE TABLE IF NOT EXISTS users ("id" TEXT PRIMARY KEY, "firstName" TEXT, "lastName" TEXT, "email" TEXT)`;
 
-await db.prepare("INSERT INTO users VALUES (?, 'John', 'Doe', '')").run(id);
+// Add a new user
+const userId = "1001";
+await db.sql`INSERT INTO users VALUES (${userId}, 'John', 'Doe', '')`;
 
-const row = await db.prepare("SELECT * FROM users WHERE id = ?").get(id);
-
-console.log(row);
+// Query for users
+const { rows } = await db.query`SELECT * FROM users WHERE id = ${userId}`;
+console.log(rows);
 ```

src/connectors/postgresql.ts

@@ -44,6 +44,7 @@ export default function sqliteConnector(opts: ConnectorOptions) {
         run(...params) {
           return query(this._sql, params || this._params).then((r) => ({
             result: r,
+            rows: r.rows,
           }));
         },
         get(...params) {

src/db.ts

@@ -1,12 +1,52 @@
-import type { Connector, Database } from "./types";
+import type { Connector, Database, Primitive } from "./types";
 
 export function createDatabase(connector: Connector): Database {
   return <Database>{
     exec: (sql: string) => {
       return Promise.resolve(connector.exec(sql));
     },
+
     prepare: (sql: string) => {
       return connector.prepare(sql);
     },
+
+    sql: async (strings, ...values) => {
+      const [sql, params] = sqlTemplate(strings, ...values);
+      const res = await connector.prepare(sql).run(...params);
+      return res;
+    },
+
+    query: async (strings, ...values) => {
+      const [sql, params] = sqlTemplate(strings, ...values);
+      const rows = await connector.prepare(sql).all(...params);
+      return {
+        rows,
+      };
+    },
   };
 }
+
+export function sqlTemplate(
+  strings: TemplateStringsArray,
+  ...values: Primitive[]
+): [string, Primitive[]] {
+  if (!isTemplateStringsArray(strings) || !Array.isArray(values)) {
+    throw new Error("[db0] invalid template invokation");
+  }
+
+  let result = strings[0] || "";
+
+  for (let i = 1; i < strings.length; i++) {
+    result += `?${strings[i] ?? ""}`;
+  }
+
+  return [result, values];
+}
+
+function isTemplateStringsArray(
+  strings: unknown
+): strings is TemplateStringsArray {
+  return (
+    Array.isArray(strings) && "raw" in strings && Array.isArray(strings.raw)
+  );
+}

src/types.ts

@@ -1,8 +1,10 @@
+export type Primitive = string | number | boolean | undefined | null;
+
 export type Statement = {
-  bind(...params: unknown[]): Statement;
-  all(...params: unknown[]): Promise<unknown[]>;
-  run(...params: unknown[]): Promise<{ success: boolean }>;
-  get(...params: unknown[]): Promise<unknown>;
+  bind(...params: Primitive[]): Statement;
+  all(...params: Primitive[]): Promise<unknown[]>;
+  run(...params: Primitive[]): Promise<{ success: boolean }>;
+  get(...params: Primitive[]): Promise<unknown>;
 };
 
 export type ExecResult = unknown;
@@ -13,7 +15,15 @@ export type Connector = {
   prepare: (sql: string) => Statement;
 };
 
+type SqlTemplate<T> = (
+  strings: TemplateStringsArray,
+  ...values: Primitive[]
+) => T;
+
 export type Database = {
   exec: (sql: string) => Promise<ExecResult>;
   prepare: (sql: string) => Statement;
+
+  sql: SqlTemplate<Promise<ExecResult>>;
+  query: SqlTemplate<Promise<{ rows: unknown[] }>>;
 };

test/connectors/_tests.ts

@@ -7,30 +7,28 @@ export function testConnector(opts: { connector: Connector }) {
     db = createDatabase(opts.connector);
   });
 
+  const userId = "1001";
+
   it("drop and create table", async () => {
-    await db.exec(`DROP TABLE IF EXISTS users`);
-    const res = await db.exec(
-      `CREATE TABLE users ("id" TEXT PRIMARY KEY, "firstName" TEXT, "lastName" TEXT, "email" TEXT)`
-    );
-    expect(res).toBeDefined();
+    await db.sql`DROP TABLE IF EXISTS users`;
+    await db.sql`CREATE TABLE users ("id" TEXT PRIMARY KEY, "firstName" TEXT, "lastName" TEXT, "email" TEXT)`;
   });
 
   it("insert", async () => {
-    const res = await db
-      .prepare("INSERT INTO users VALUES (?, 'John', 'Doe', '')")
-      .run("123");
-    expect(res).toBeDefined();
+    await db.sql`INSERT INTO users VALUES (${userId}, 'John', 'Doe', '')`;
   });
 
   it("select", async () => {
-    const row = await db.prepare("SELECT * FROM users WHERE id = ?").get("123");
-    expect(row).toMatchInlineSnapshot(`
-      {
-        "email": "",
-        "firstName": "John",
-        "id": "123",
-        "lastName": "Doe",
-      }
+    const { rows } = await db.query`SELECT * FROM users WHERE id = ${userId}`;
+    expect(rows).toMatchInlineSnapshot(`
+      [
+        {
+          "email": "",
+          "firstName": "John",
+          "id": "1001",
+          "lastName": "Doe",
+        },
+      ]
     `);
   });
 }