@absurd-sqlite/sdk 0.2.0-alpha.0

package/src/absurd-types.ts

@@ -0,0 +1,149 @@
+import type {
+  ClaimedTask,
+  JsonValue,
+  SpawnOptions,
+  SpawnResult,
+  TaskHandler,
+  TaskRegistrationOptions,
+  WorkerOptions,
+} from "absurd-sdk";
+
+import type { SQLiteRestBindParams } from "./sqlite-types";
+
+/**
+ * Minimal query interface compatible with Absurd's database operations.
+ */
+export interface Queryable {
+  /**
+   * Execute a parameterized SQL query and return rows.
+   * @param sql SQL text with parameter placeholders.
+   * @param params Optional positional parameters.
+   */
+  query<R extends object = Record<string, any>>(
+    sql: string,
+    params?: SQLiteRestBindParams
+  ): Promise<{ rows: R[] }>;
+}
+
+/**
+ * Background worker handle returned by startWorker().
+ */
+export interface Worker {
+  /**
+   * Stop the worker loop and wait for in-flight tasks to settle.
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Absurd client interface.
+ */
+export interface AbsurdClient {
+  /**
+   * Create a new client bound to the provided connection.
+   * @param con Connection to use for queries.
+   * @param owned If true, close the connection when close() is called.
+   */
+  // bindToConnection(con: Queryable, owned?: boolean): this;
+
+  /**
+   * Register a task handler.
+   * @param options Task registration options.
+   * @param handler Async task handler.
+   */
+  registerTask<P = any, R = any>(
+    options: TaskRegistrationOptions,
+    handler: TaskHandler<P, R>
+  ): void;
+
+  /**
+   * Create a queue.
+   * @param queueName Optional queue name (defaults to client queue).
+   */
+  createQueue(queueName?: string): Promise<void>;
+  /**
+   * Drop a queue.
+   * @param queueName Optional queue name (defaults to client queue).
+   */
+  dropQueue(queueName?: string): Promise<void>;
+  /**
+   * List available queues.
+   */
+  listQueues(): Promise<Array<string>>;
+
+  /**
+   * Spawn a task execution.
+   * @param taskName Task name.
+   * @param params Task parameters.
+   * @param options Spawn options including queue and retry behavior.
+   */
+  spawn<P = any>(
+    taskName: string,
+    params: P,
+    options?: SpawnOptions
+  ): Promise<SpawnResult>;
+
+  /**
+   * Emit an event on a queue.
+   * @param eventName Non-empty event name.
+   * @param payload Optional JSON payload.
+   * @param queueName Optional queue name (defaults to client queue).
+   */
+  emitEvent(
+    eventName: string,
+    payload?: JsonValue,
+    queueName?: string
+  ): Promise<void>;
+
+  /**
+   * Cancel a task by ID.
+   * @param taskID Task identifier.
+   * @param queueName Optional queue name (defaults to client queue).
+   */
+  cancelTask(taskID: string, queueName?: string): Promise<void>;
+
+  /**
+   * Claim tasks for processing.
+   * @param options Claiming options.
+   */
+  claimTasks(options?: {
+    batchSize?: number;
+    claimTimeout?: number;
+    workerId?: string;
+  }): Promise<ClaimedTask[]>;
+
+  /**
+   * Claim and process a batch of tasks sequentially.
+   * @param workerId Worker identifier.
+   * @param claimTimeout Lease duration in seconds.
+   * @param batchSize Max tasks to process.
+   */
+  workBatch(
+    workerId?: string,
+    claimTimeout?: number,
+    batchSize?: number
+  ): Promise<void>;
+
+  /**
+   * Start a background worker that polls and executes tasks.
+   * @param options Worker behavior options.
+   */
+  startWorker(options?: WorkerOptions): Promise<Worker>;
+
+  /**
+   * Close the client and any owned resources.
+   */
+  close(): Promise<void>;
+
+  /**
+   * Execute a claimed task (used by workers).
+   * @param task Claimed task record.
+   * @param claimTimeout Lease duration in seconds.
+   * @param options Execution options.
+   */
+  executeTask(
+    task: ClaimedTask,
+    claimTimeout: number,
+    options?: { fatalOnLeaseTimeout?: boolean }
+  ): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+import { Absurd as AbsurdBase } from "absurd-sdk";
+
+import type { AbsurdClient } from "./absurd-types";
+import type { SQLiteDatabase } from "./sqlite-types";
+import { SqliteConnection } from "./sqlite";
+
+export type { AbsurdClient, Queryable, Worker } from "./absurd-types";
+export type {
+  AbsurdHooks,
+  AbsurdOptions,
+  CancellationPolicy,
+  ClaimedTask,
+  JsonObject,
+  JsonValue,
+  RetryStrategy,
+  SpawnOptions,
+  SpawnResult,
+  TaskContext,
+  TaskHandler,
+  TaskRegistrationOptions,
+  WorkerOptions,
+} from "absurd-sdk";
+export type {
+  SQLiteBindParams,
+  SQLiteBindValue,
+  SQLiteColumnDefinition,
+  SQLiteDatabase,
+  SQLiteRestBindParams,
+  SQLiteStatement,
+  SQLiteVerboseLog,
+} from "./sqlite-types";
+
+export class Absurd extends AbsurdBase implements AbsurdClient {
+  private db: SQLiteDatabase;
+
+  constructor(db: SQLiteDatabase, extensionPath: string) {
+    db.loadExtension(extensionPath);
+    const queryable = new SqliteConnection(db);
+    super(queryable);
+    this.db = db;
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}

package/src/sqlite-types.ts

@@ -0,0 +1,35 @@
+export type SQLiteBindValue = number | string | Buffer | bigint | Date | null;
+
+export type SQLiteBindParams =
+  | SQLiteBindValue[]
+  | Record<string, SQLiteBindValue>;
+
+export type SQLiteRestBindParams = SQLiteBindValue[] | [SQLiteBindParams];
+
+export interface SQLiteColumnDefinition {
+  name: string;
+  column: string | null;
+  table: string | null;
+  database: string | null;
+  type: string | null;
+}
+
+export interface SQLiteStatement<Result extends object = Record<string, any>> {
+  readonly: boolean;
+  columns(): SQLiteColumnDefinition[];
+  all(...args: SQLiteRestBindParams): Result[];
+  run(...args: SQLiteRestBindParams): number;
+}
+
+export interface SQLiteDatabase {
+  prepare<Result extends object = Record<string, any>>(
+    sql: string
+  ): SQLiteStatement<Result>;
+  close(): void;
+  loadExtension(path: string): void;
+}
+
+export type SQLiteVerboseLog = (
+  message?: any,
+  ...optionalParams: any[]
+) => void;

package/src/sqlite.ts

@@ -0,0 +1,162 @@
+import type { Queryable } from "./absurd-types";
+import type {
+  SQLiteRestBindParams,
+  SQLiteDatabase,
+  SQLiteStatement,
+  SQLiteVerboseLog,
+} from "./sqlite-types";
+
+export class SqliteConnection implements Queryable {
+  private readonly db: SQLiteDatabase;
+
+  constructor(db: SQLiteDatabase) {
+    this.db = db;
+    // TODO: verbose logging
+  }
+
+  async query<R extends object = Record<string, any>>(
+    sql: string,
+    params?: SQLiteRestBindParams
+  ): Promise<{ rows: R[] }> {
+    const sqliteQuery = rewritePostgresQuery(sql);
+    const sqliteParams = rewritePostgresParams(params);
+
+    const statement = this.db.prepare(sqliteQuery);
+    if (!statement.readonly) {
+      // this indicates `return_data` is false
+      // https://github.com/WiseLibs/better-sqlite3/blob/6209be238d6a1b181f516e4e636986604b0f62e1/src/objects/statement.cpp#L134C83-L134C95
+      throw new Error("The query() method is only statements that return data");
+    }
+
+    const rowsDecoded = statement
+      .all(sqliteParams)
+      .map((row) => decodeRowValues(statement, row));
+
+    return { rows: rowsDecoded };
+  }
+
+  async exec(sql: string, params?: SQLiteRestBindParams): Promise<void> {
+    const sqliteQuery = rewritePostgresQuery(sql);
+    const sqliteParams = rewritePostgresParams(params);
+
+    this.db.prepare(sqliteQuery).run(sqliteParams);
+  }
+}
+
+const namedParamPrefix = "p";
+
+function rewritePostgresQuery(text: string): string {
+  return text
+    .replace(/\$(\d+)/g, `:${namedParamPrefix}$1`)
+    .replace(/absurd\.(\w+)/g, "absurd_$1");
+}
+
+function rewritePostgresParams<I = any>(
+  params?: SQLiteRestBindParams
+): Record<string, I> {
+  if (!params) {
+    return {};
+  }
+
+  const rewrittenParams: Record<string, I> = {};
+  params.forEach((value, index) => {
+    const paramKey = `${namedParamPrefix}${index + 1}`;
+    const encodedParamValue = encodeColumnValue(value);
+
+    rewrittenParams[paramKey] = encodedParamValue;
+  });
+  return rewrittenParams;
+}
+
+function decodeRowValues<U extends object, R extends object = any>(
+  statement: SQLiteStatement,
+  row: U,
+  verbose?: SQLiteVerboseLog
+): R {
+  const columns = statement.columns();
+
+  const decodedRow: any = {};
+  for (const column of columns) {
+    const columnName = column.name;
+    const columnType = column.type;
+    const rawValue = (row as Record<string, unknown>)[columnName];
+    const decodedValue = decodeColumnValue(
+      rawValue,
+      columnName,
+      columnType,
+      verbose
+    );
+    decodedRow[columnName] = decodedValue;
+  }
+
+  return decodedRow as R;
+}
+
+function decodeColumnValue<V = any>(
+  value: unknown | V,
+  columnName: string,
+  columnType: string | null,
+  verbose?: SQLiteVerboseLog
+): V | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  if (columnType === null) {
+    if (typeof value === "string") {
+      // When column type is not known but the value is string
+      // try parse it as JSON -- for cases where the column is computed
+      // e.g. `SELECT json(x) as y from ....`
+      // FIXME: better type detection
+      let rv: V;
+      let isValidJSON = false;
+      try {
+        rv = JSON.parse(value) as V;
+        isValidJSON = true;
+      } catch (e) {
+        verbose?.(`Failed to decode string column ${columnName} as JSON`, e);
+        rv = value as V;
+      }
+      if (isValidJSON) {
+        verbose?.(`Decoded column ${columnName} with null as JSON`);
+      }
+      return rv;
+    }
+
+    verbose?.(`Column ${columnName} has null type, returning raw value`);
+    return value as V;
+  }
+
+  const columnTypeName = columnType.toLowerCase();
+  if (columnTypeName === "blob") {
+    // BLOB values are JSON string decoded from JSONB
+    try {
+      return JSON.parse(value.toString()) as V;
+    } catch (e) {
+      verbose?.(`Failed to decode BLOB column ${columnName} as JSON`, e);
+      throw e;
+    }
+  }
+
+  if (columnTypeName === "datetime") {
+    if (typeof value !== "number") {
+      throw new Error(
+        `Expected datetime column ${columnName} to be a number, got ${typeof value}`
+      );
+    }
+    return new Date(value) as V;
+  }
+
+  // For other types, return as is
+  return value as V;
+}
+
+function encodeColumnValue(value: any): any {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "number" && Number.isInteger(value)) {
+    return value.toString();
+  }
+  return value;
+}