feat: add @objectstack/driver-turso extending SqlDriver with Turso/libSQL support

- Refactor SqlDriver: private → protected for extensibility
- Fix count() bug: use ?? instead of || for zero-count handling
- Implement TursoDriver extending SqlDriver (zero CRUD duplication)
- Add multi-tenant router with TTL cache
- 53 tests passing (39 driver + 14 multi-tenant)
- 78 driver-sql regression tests passing

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/f3d58acb-4d15-42db-a9ef-f318b266842f

Author: Copilot

packages/plugins/driver-sql/src/sql-driver.ts

@@ -113,26 +113,26 @@ export class SqlDriver implements IDataDriver {
     queryCache: false,
   };
 
-  private knex: Knex;
-  private config: Knex.Config;
-  private jsonFields: Record<string, string[]> = {};
-  private booleanFields: Record<string, string[]> = {};
-  private tablesWithTimestamps: Set<string> = new Set();
+  protected knex: Knex;
+  protected config: Knex.Config;
+  protected jsonFields: Record<string, string[]> = {};
+  protected booleanFields: Record<string, string[]> = {};
+  protected tablesWithTimestamps: Set<string> = new Set();
 
   /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
-  private get isSqlite(): boolean {
+  protected get isSqlite(): boolean {
     const c = (this.config as any).client;
     return c === 'sqlite3' || c === 'better-sqlite3';
   }
 
   /** Whether the underlying database is PostgreSQL. */
-  private get isPostgres(): boolean {
+  protected get isPostgres(): boolean {
     const c = (this.config as any).client;
     return c === 'pg' || c === 'postgresql';
   }
 
   /** Whether the underlying database is MySQL. */
-  private get isMysql(): boolean {
+  protected get isMysql(): boolean {
     const c = (this.config as any).client;
     return c === 'mysql' || c === 'mysql2';
   }
@@ -364,7 +364,7 @@ export class SqlDriver implements IDataDriver {
     const result = await builder.count<{ count: number }[]>('* as count');
     if (result && result.length > 0) {
       const row: any = result[0];
-      return Number(row.count || row['count(*)']);
+      return Number(row.count ?? row['count(*)'] ?? 0);
     }
     return 0;
   }
@@ -702,7 +702,7 @@ export class SqlDriver implements IDataDriver {
     return this.knex;
   }
 
-  private getBuilder(object: string, options?: DriverOptions) {
+  protected getBuilder(object: string, options?: DriverOptions) {
     let builder = this.knex(object);
     if (options?.transaction) {
       builder = builder.transacting(options.transaction as Knex.Transaction);
@@ -712,7 +712,7 @@ export class SqlDriver implements IDataDriver {
 
   // ── Filter helpers ──────────────────────────────────────────────────────────
 
-  private applyFilters(builder: Knex.QueryBuilder, filters: any) {
+  protected applyFilters(builder: Knex.QueryBuilder, filters: any) {
     if (!filters) return;
 
     if (!Array.isArray(filters) && typeof filters === 'object') {
@@ -793,7 +793,7 @@ export class SqlDriver implements IDataDriver {
     }
   }
 
-  private applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp: 'and' | 'or' = 'and') {
+  protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp: 'and' | 'or' = 'and') {
     if (!condition || typeof condition !== 'object') return;
 
     for (const [key, value] of Object.entries(condition)) {
@@ -864,13 +864,13 @@ export class SqlDriver implements IDataDriver {
 
   // ── Field mapping ───────────────────────────────────────────────────────────
 
-  private mapSortField(field: string): string {
+  protected mapSortField(field: string): string {
     if (field === 'createdAt') return 'created_at';
     if (field === 'updatedAt') return 'updated_at';
     return field;
   }
 
-  private mapAggregateFunc(func: string): string {
+  protected mapAggregateFunc(func: string): string {
     switch (func) {
       case 'count':
         return 'count';
@@ -889,7 +889,7 @@ export class SqlDriver implements IDataDriver {
 
   // ── Window function builder ─────────────────────────────────────────────────
 
-  private buildWindowFunction(spec: any): string {
+  protected buildWindowFunction(spec: any): string {
     const func = spec.function.toUpperCase();
     let sql = `${func}()`;
 
@@ -917,7 +917,7 @@ export class SqlDriver implements IDataDriver {
 
   // ── Column creation helper ──────────────────────────────────────────────────
 
-  private createColumn(table: Knex.CreateTableBuilder, name: string, field: any) {
+  protected createColumn(table: Knex.CreateTableBuilder, name: string, field: any) {
     if (field.multiple) {
       table.json(name);
       return;
@@ -996,7 +996,7 @@ export class SqlDriver implements IDataDriver {
 
   // ── Database helpers ────────────────────────────────────────────────────────
 
-  private async ensureDatabaseExists() {
+  protected async ensureDatabaseExists() {
     if (!this.isPostgres) return;
 
     try {
@@ -1010,7 +1010,7 @@ export class SqlDriver implements IDataDriver {
     }
   }
 
-  private async createDatabase() {
+  protected async createDatabase() {
     const config = this.config as any;
     const connection = config.connection;
     let dbName = '';
@@ -1034,13 +1034,13 @@ export class SqlDriver implements IDataDriver {
     }
   }
 
-  private isJsonField(type: string, field: any): boolean {
+  protected isJsonField(type: string, field: any): boolean {
     return ['json', 'object', 'array', 'image', 'file', 'avatar', 'location'].includes(type) || field.multiple;
   }
 
   // ── SQLite serialisation ────────────────────────────────────────────────────
 
-  private formatInput(object: string, data: any): any {
+  protected formatInput(object: string, data: any): any {
     if (!this.isSqlite) return data;
 
     const fields = this.jsonFields[object];
@@ -1055,7 +1055,7 @@ export class SqlDriver implements IDataDriver {
     return copy;
   }
 
-  private formatOutput(object: string, data: any): any {
+  protected formatOutput(object: string, data: any): any {
     if (!data) return data;
 
     if (this.isSqlite) {
@@ -1087,7 +1087,7 @@ export class SqlDriver implements IDataDriver {
 
   // ── Introspection internals ─────────────────────────────────────────────────
 
-  private async introspectColumns(tableName: string): Promise<IntrospectedColumn[]> {
+  protected async introspectColumns(tableName: string): Promise<IntrospectedColumn[]> {
     const columnInfo = await this.knex(tableName).columnInfo();
     const columns: IntrospectedColumn[] = [];
 
@@ -1119,7 +1119,7 @@ export class SqlDriver implements IDataDriver {
     return columns;
   }
 
-  private async introspectForeignKeys(tableName: string): Promise<IntrospectedForeignKey[]> {
+  protected async introspectForeignKeys(tableName: string): Promise<IntrospectedForeignKey[]> {
     const foreignKeys: IntrospectedForeignKey[] = [];
 
     try {
@@ -1205,7 +1205,7 @@ export class SqlDriver implements IDataDriver {
     return foreignKeys;
   }
 
-  private async introspectPrimaryKeys(tableName: string): Promise<string[]> {
+  protected async introspectPrimaryKeys(tableName: string): Promise<string[]> {
     const primaryKeys: string[] = [];
 
     try {
@@ -1265,7 +1265,7 @@ export class SqlDriver implements IDataDriver {
     return primaryKeys;
   }
 
-  private async introspectUniqueConstraints(tableName: string): Promise<string[]> {
+  protected async introspectUniqueConstraints(tableName: string): Promise<string[]> {
     const uniqueColumns: string[] = [];
 
     try {

packages/plugins/driver-turso/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@objectstack/driver-turso",
+  "version": "3.2.9",
+  "license": "Apache-2.0",
+  "description": "Turso/libSQL Driver for ObjectStack — Edge-first SQLite with embedded replicas and multi-tenancy",
+  "keywords": [
+    "objectstack",
+    "driver",
+    "turso",
+    "libsql",
+    "sqlite",
+    "edge",
+    "serverless",
+    "embedded-replica",
+    "multi-tenant"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "dev": "tsc -w",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@objectstack/core": "workspace:*",
+    "@objectstack/driver-sql": "workspace:*",
+    "@objectstack/spec": "workspace:*",
+    "@libsql/client": "^0.17.2",
+    "nanoid": "^3.3.11"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "better-sqlite3": "^11.9.1",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.0"
+  }
+}

packages/plugins/driver-turso/src/index.ts

@@ -0,0 +1,87 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/driver-turso
+ *
+ * Turso/libSQL driver for ObjectStack — edge-first, globally distributed
+ * SQLite with embedded replicas and database-per-tenant multi-tenancy.
+ *
+ * Extends `@objectstack/driver-sql` (SqlDriver) and inherits all CRUD,
+ * schema management, filtering, aggregation, and introspection logic.
+ * Only Turso-specific features (connection modes, sync, multi-tenant)
+ * are implemented here — zero duplicated query/schema code.
+ *
+ * Supports three connection modes:
+ * 1. Local (Embedded): `url: 'file:./data/local.db'`
+ * 2. In-Memory (Testing): `url: ':memory:'`
+ * 3. Embedded Replica (Hybrid): `url` + `syncUrl`
+ *
+ * @example
+ * ```typescript
+ * import { TursoDriver } from '@objectstack/driver-turso';
+ *
+ * const driver = new TursoDriver({
+ *   url: 'file:./data/app.db',
+ * });
+ * await driver.connect();
+ * ```
+ */
+
+import { TursoDriver } from './turso-driver.js';
+
+export { TursoDriver, type TursoDriverConfig } from './turso-driver.js';
+
+export {
+  createMultiTenantRouter,
+  type MultiTenantConfig,
+  type MultiTenantRouter,
+} from './multi-tenant.js';
+
+/**
+ * Factory function to create a TursoDriver instance.
+ *
+ * @param config - Turso driver configuration
+ * @returns A new TursoDriver instance (not yet connected)
+ *
+ * @example
+ * ```typescript
+ * import { createTursoDriver } from '@objectstack/driver-turso';
+ *
+ * // Local file
+ * const driver = createTursoDriver({ url: 'file:./data/app.db' });
+ *
+ * // In-memory (testing)
+ * const driver = createTursoDriver({ url: ':memory:' });
+ *
+ * // Embedded replica
+ * const driver = createTursoDriver({
+ *   url: 'file:./data/replica.db',
+ *   syncUrl: 'libsql://my-db-orgname.turso.io',
+ *   authToken: process.env.TURSO_AUTH_TOKEN,
+ *   sync: { intervalSeconds: 60, onConnect: true },
+ * });
+ *
+ * await driver.connect();
+ * ```
+ */
+export function createTursoDriver(config: import('./turso-driver.js').TursoDriverConfig): TursoDriver {
+  return new TursoDriver(config);
+}
+
+export default {
+  id: 'com.objectstack.driver.turso',
+  version: '1.0.0',
+
+  onEnable: async (context: any) => {
+    const { logger, config, drivers } = context;
+    logger.info('[Turso Driver] Initializing...');
+
+    if (drivers) {
+      const driver = new TursoDriver(config);
+      drivers.register(driver);
+      logger.info(`[Turso Driver] Registered driver: ${driver.name}`);
+    } else {
+      logger.warn('[Turso Driver] No driver registry found in context.');
+    }
+  },
+};