feat: add query builder package

.github/workflows/test.yml

@@ -0,0 +1,47 @@
+# Ensures packages test correctly
+name: Test Packages
+
+on:
+  push:
+
+jobs:
+  test:
+    name: Test Packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup NodeJS
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - uses: pnpm/action-setup@v2
+        name: Install pnpm
+        with:
+          version: 8
+          run_install: false
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - uses: actions/cache@v3
+        name: Setup pnpm cache
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build
+        run: pnpm build:packages
+
+      - name: Test
+        run: pnpm test

package.json

@@ -5,17 +5,17 @@
   "description": "monorepo for powersync javascript sdks",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "lint": "eslint .",
-    "clean": "pnpm run -r clean",
-    "ci:version": "changeset version && pnpm install --no-frozen-lockfile",
+    "build:packages": "pnpm run --filter './packages/**' -r build",
+    "build": "pnpm run -r build",
     "ci:publish": "changeset publish && git push --follow-tags",
-    "docs:start": "pnpm --filter docs start",
+    "ci:version": "changeset version && pnpm install --no-frozen-lockfile",
+    "clean": "pnpm run -r clean",
     "docs:build": "pnpm --filter docs build",
-    "build": "pnpm run -r build",
-    "build:packages": "pnpm run --filter './packages/**' -r build",
+    "docs:start": "pnpm --filter docs start",
     "format": "prettier --write .",
-    "release": "pnpm build:packages && pnpm changeset publish"
+    "lint": "eslint .",
+    "release": "pnpm build:packages && pnpm changeset publish",
+    "test": "pnpm run -r test"
   },
   "keywords": [],
   "type": "module",

packages/kysely-driver/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@powersync/kysely-driver",
+  "version": "0.0.1",
+  "description": "Kysely driver for PowerSync",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "author": "JOURNEYAPPS",
+  "license": "Apache-2.0",
+  "files": [
+    "lib"
+  ],
+  "repository": "https://github.com/powersync-ja/powersync-js",
+  "bugs": {
+    "url": "https://github.com/powersync-ja/powersync-js/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "homepage": "https://docs.powersync.com",
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "watch": "tsc --build -w",
+    "test": "pnpm build && vitest"
+  },
+  "dependencies": {
+    "@journeyapps/powersync-sdk-common": "workspace:*",
+    "kysely": "^0.27.2"
+  },
+  "devDependencies": {
+    "@journeyapps/powersync-sdk-web": "workspace:*",
+    "@journeyapps/wa-sqlite": "^0.1.1",
+    "@types/node": "^20.11.17",
+    "@vitest/browser": "^1.3.1",
+    "ts-loader": "^9.5.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "vite": "^5.1.1",
+    "vite-plugin-top-level-await": "^1.4.1",
+    "vite-plugin-wasm": "^3.3.0",
+    "vitest": "^1.3.0",
+    "webdriverio": "^8.32.3"
+  }
+}

packages/kysely-driver/src/index.ts

@@ -0,0 +1,3 @@
+import { createPowerSyncDb } from './sqlite/db';
+
+export { createPowerSyncDb };

packages/kysely-driver/src/sqlite/db.ts

@@ -0,0 +1,11 @@
+import { PowerSyncDialect } from './sqlite-dialect';
+import { Kysely } from 'kysely';
+import { type AbstractPowerSyncDatabase } from '@journeyapps/powersync-sdk-common';
+
+export const createPowerSyncDb = <T>(db: AbstractPowerSyncDatabase) => {
+  return new Kysely<T>({
+    dialect: new PowerSyncDialect({
+      db
+    })
+  });
+};

packages/kysely-driver/src/sqlite/sqlite-connection.ts

@@ -0,0 +1,111 @@
+import { type AbstractPowerSyncDatabase, type Transaction } from '@journeyapps/powersync-sdk-common';
+import { CompiledQuery, DatabaseConnection, QueryResult } from 'kysely';
+
+/**
+ * Represent a Kysely connection to the PowerSync database.
+ *
+ * The actual locks are acquired on-demand when a transaction is started.
+ *
+ * When not using transactions, we rely on the automatic locks.
+ *
+ * This allows us to bypass write locks when doing pure select queries outside a transaction.
+ */
+export class PowerSyncConnection implements DatabaseConnection {
+  readonly #db: AbstractPowerSyncDatabase;
+  #release?: () => void;
+  #tx?: Transaction;
+
+  constructor(db: AbstractPowerSyncDatabase) {
+    this.#db = db;
+  }
+
+  async executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>> {
+    const { sql, parameters, query } = compiledQuery;
+
+    const context = this.#tx ?? this.#db;
+
+    if (query.kind === 'SelectQueryNode') {
+      // Optimizaton: use getAll() instead of execute() if it's a select query
+      const rows = await context.getAll(sql, parameters as unknown[]);
+      return {
+        rows: rows as O[]
+      };
+    }
+
+    const result = await context.execute(sql, parameters as unknown[]);
+
+    return {
+      insertId: result.insertId ? BigInt(result.insertId!) : undefined,
+      numAffectedRows: BigInt(result.rowsAffected),
+      rows: result.rows?._array ?? []
+    };
+  }
+
+  async *streamQuery<R>(compiledQuery: CompiledQuery): AsyncIterableIterator<QueryResult<R>> {
+    // Not actually streamed
+    const results = await this.executeQuery<R>(compiledQuery);
+    yield {
+      rows: results.rows
+    };
+  }
+
+  async beginTransaction(): Promise<void> {
+    let doResolve: any;
+    let doReject: any;
+    let doRelease: any;
+
+    const lockPromise = new Promise<PowerSyncConnection>((resolve, reject) => {
+      doResolve = resolve;
+      doReject = reject;
+    });
+
+    this.#db
+      .writeTransaction(async (tx) => {
+        this.#tx = tx;
+        const releasePromise = new Promise<void>((reject) => {
+          doRelease = reject;
+        });
+        doResolve();
+        await releasePromise;
+      })
+      .catch(doReject);
+
+    await lockPromise;
+    this.#release = doRelease;
+  }
+
+  async commitTransaction(): Promise<void> {
+    if (!this.#tx) {
+      throw new Error('Transaction is not defined');
+    }
+
+    if (!this.#release) {
+      throw new Error('Release is not defined');
+    }
+
+    await this.#tx.commit();
+    this.#tx = undefined;
+    this.#release();
+    this.#release = undefined;
+  }
+
+  async rollbackTransaction(): Promise<void> {
+    if (!this.#tx) {
+      throw new Error('Transaction is not defined');
+    }
+
+    if (!this.#release) {
+      throw new Error('Release is not defined');
+    }
+
+    await this.#tx.rollback();
+    this.#tx = undefined;
+    this.#release();
+    this.#release = undefined;
+  }
+
+  async releaseConnection(): Promise<void> {
+    // is this write?
+    this.#db.disconnect();
+  }
+}

packages/kysely-driver/src/sqlite/sqlite-dialect.ts

@@ -0,0 +1,36 @@
+import {
+  DatabaseIntrospector,
+  Dialect,
+  DialectAdapter,
+  Driver,
+  Kysely,
+  QueryCompiler,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler
+} from 'kysely';
+import { PowerSyncDialectConfig, PowerSyncDriver } from './sqlite-driver';
+
+export class PowerSyncDialect implements Dialect {
+  readonly #config: PowerSyncDialectConfig;
+
+  constructor(config: PowerSyncDialectConfig) {
+    this.#config = Object.freeze({ ...config });
+  }
+
+  createDriver(): Driver {
+    return new PowerSyncDriver(this.#config);
+  }
+
+  createQueryCompiler(): QueryCompiler {
+    return new SqliteQueryCompiler();
+  }
+
+  createAdapter(): DialectAdapter {
+    return new SqliteAdapter();
+  }
+
+  createIntrospector(db: Kysely<unknown>): DatabaseIntrospector {
+    return new SqliteIntrospector(db);
+  }
+}

packages/kysely-driver/src/sqlite/sqlite-driver.ts

@@ -0,0 +1,42 @@
+import { type AbstractPowerSyncDatabase } from '@journeyapps/powersync-sdk-common';
+import { DatabaseConnection, Driver } from 'kysely';
+import { PowerSyncConnection } from './sqlite-connection';
+
+export interface PowerSyncDialectConfig {
+  db: AbstractPowerSyncDatabase;
+}
+
+export class PowerSyncDriver implements Driver {
+  readonly #db: AbstractPowerSyncDatabase;
+
+  constructor(config: PowerSyncDialectConfig) {
+    this.#db = config.db;
+  }
+
+  async init(): Promise<void> { }
+
+  async acquireConnection(): Promise<DatabaseConnection> {
+    // Always create a new connection instance
+    return new PowerSyncConnection(this.#db);
+  }
+
+  async beginTransaction(connection: DatabaseConnection): Promise<void> {
+    await (connection as PowerSyncConnection).beginTransaction();
+  }
+
+  async commitTransaction(connection: DatabaseConnection): Promise<void> {
+    await (connection as PowerSyncConnection).commitTransaction();
+  }
+
+  async rollbackTransaction(connection: DatabaseConnection): Promise<void> {
+    await (connection as PowerSyncConnection).rollbackTransaction();
+  }
+
+  async releaseConnection(connection: DatabaseConnection): Promise<void> {
+    await (connection as PowerSyncConnection).releaseConnection();
+  }
+
+  async destroy(): Promise<void> {
+    this.#db.disconnectAndClear();
+  }
+}

packages/kysely-driver/tests/setup/db.ts

@@ -0,0 +1,33 @@
+import { Kysely } from 'kysely';
+import { PowerSyncDialect } from '../../src/sqlite/sqlite-dialect';
+import { Database } from './types';
+import {
+  Column,
+  ColumnType,
+  Schema,
+  Table,
+  WASQLitePowerSyncDatabaseOpenFactory
+} from '@journeyapps/powersync-sdk-web';
+
+const TestSchema = new Schema([
+  new Table({
+    name: 'users',
+    columns: [new Column({ name: 'name', type: ColumnType.TEXT })]
+  })
+]);
+
+export const getPowerSyncDb = () => {
+  const factory = new WASQLitePowerSyncDatabaseOpenFactory({
+    dbFilename: 'test.db',
+    schema: TestSchema
+  });
+
+  return factory.getInstance();
+};
+
+export const getKyselyDb = () =>
+  new Kysely<Database>({
+    dialect: new PowerSyncDialect({
+      db: getPowerSyncDb()
+    })
+  });

packages/kysely-driver/tests/setup/types.ts

@@ -0,0 +1,14 @@
+import { ColumnType, Insertable, Selectable, Updateable } from 'kysely';
+
+export interface Database {
+  users: UsersTable;
+}
+
+export interface UsersTable {
+  id: ColumnType<string, string, never>;
+  name: string;
+}
+
+export type Users = Selectable<UsersTable>;
+export type NewUsers = Insertable<UsersTable>;
+export type UsersUpdate = Updateable<UsersTable>;