@debros/orama 0.122.4-nightly

package/src/db/client.ts

@@ -0,0 +1,126 @@
+import { HttpClient } from "../core/http";
+import { QueryBuilder } from "./qb";
+import { Repository } from "./repository";
+import {
+  QueryResponse,
+  TransactionOp,
+  TransactionRequest,
+  Entity,
+  FindOptions,
+} from "./types";
+
+export class DBClient {
+  private httpClient: HttpClient;
+
+  constructor(httpClient: HttpClient) {
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Execute a write/DDL SQL statement.
+   */
+  async exec(
+    sql: string,
+    args: any[] = []
+  ): Promise<{ rows_affected: number; last_insert_id?: number }> {
+    return this.httpClient.post("/v1/rqlite/exec", { sql, args });
+  }
+
+  /**
+   * Execute a SELECT query.
+   */
+  async query<T = any>(sql: string, args: any[] = []): Promise<T[]> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/query",
+      { sql, args }
+    );
+    return response.items || [];
+  }
+
+  /**
+   * Find rows with map-based criteria.
+   */
+  async find<T = any>(
+    table: string,
+    criteria: Record<string, any> = {},
+    options: FindOptions = {}
+  ): Promise<T[]> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/find",
+      {
+        table,
+        criteria,
+        options,
+      }
+    );
+    return response.items || [];
+  }
+
+  /**
+   * Find a single row with map-based criteria.
+   */
+  async findOne<T = any>(
+    table: string,
+    criteria: Record<string, any>
+  ): Promise<T | null> {
+    return this.httpClient.post<T | null>("/v1/rqlite/find-one", {
+      table,
+      criteria,
+    });
+  }
+
+  /**
+   * Create a fluent QueryBuilder for complex SELECT queries.
+   */
+  createQueryBuilder(table: string): QueryBuilder {
+    return new QueryBuilder(this.httpClient, table);
+  }
+
+  /**
+   * Create a Repository for entity-based operations.
+   */
+  repository<T extends Record<string, any>>(
+    tableName: string,
+    primaryKey = "id"
+  ): Repository<T> {
+    return new Repository(this.httpClient, tableName, primaryKey);
+  }
+
+  /**
+   * Execute multiple operations atomically.
+   */
+  async transaction(
+    ops: TransactionOp[],
+    returnResults = true
+  ): Promise<any[]> {
+    const response = await this.httpClient.post<{ results?: any[] }>(
+      "/v1/rqlite/transaction",
+      {
+        ops,
+        return_results: returnResults,
+      }
+    );
+    return response.results || [];
+  }
+
+  /**
+   * Create a table from DDL SQL.
+   */
+  async createTable(schema: string): Promise<void> {
+    await this.httpClient.post("/v1/rqlite/create-table", { schema });
+  }
+
+  /**
+   * Drop a table.
+   */
+  async dropTable(table: string): Promise<void> {
+    await this.httpClient.post("/v1/rqlite/drop-table", { table });
+  }
+
+  /**
+   * Get current database schema.
+   */
+  async getSchema(): Promise<any> {
+    return this.httpClient.get("/v1/rqlite/schema");
+  }
+}

package/src/db/index.ts

@@ -0,0 +1,13 @@
+export { DBClient } from "./client";
+export { QueryBuilder } from "./qb";
+export { Repository } from "./repository";
+export type {
+  Entity,
+  QueryResponse,
+  TransactionOp,
+  TransactionRequest,
+  SelectOptions,
+  FindOptions,
+  ColumnDefinition,
+} from "./types";
+export { extractTableName, extractPrimaryKey } from "./types";

package/src/db/qb.ts

@@ -0,0 +1,111 @@
+import { HttpClient } from "../core/http";
+import { SelectOptions, QueryResponse } from "./types";
+
+export class QueryBuilder {
+  private httpClient: HttpClient;
+  private table: string;
+  private options: SelectOptions = {};
+
+  constructor(httpClient: HttpClient, table: string) {
+    this.httpClient = httpClient;
+    this.table = table;
+  }
+
+  select(...columns: string[]): this {
+    this.options.select = columns;
+    return this;
+  }
+
+  innerJoin(table: string, on: string): this {
+    if (!this.options.joins) this.options.joins = [];
+    this.options.joins.push({ kind: "INNER", table, on });
+    return this;
+  }
+
+  leftJoin(table: string, on: string): this {
+    if (!this.options.joins) this.options.joins = [];
+    this.options.joins.push({ kind: "LEFT", table, on });
+    return this;
+  }
+
+  rightJoin(table: string, on: string): this {
+    if (!this.options.joins) this.options.joins = [];
+    this.options.joins.push({ kind: "RIGHT", table, on });
+    return this;
+  }
+
+  where(expr: string, args?: any[]): this {
+    if (!this.options.where) this.options.where = [];
+    this.options.where.push({ conj: "AND", expr, args });
+    return this;
+  }
+
+  andWhere(expr: string, args?: any[]): this {
+    return this.where(expr, args);
+  }
+
+  orWhere(expr: string, args?: any[]): this {
+    if (!this.options.where) this.options.where = [];
+    this.options.where.push({ conj: "OR", expr, args });
+    return this;
+  }
+
+  groupBy(...columns: string[]): this {
+    this.options.group_by = columns;
+    return this;
+  }
+
+  orderBy(...columns: string[]): this {
+    this.options.order_by = columns;
+    return this;
+  }
+
+  limit(n: number): this {
+    this.options.limit = n;
+    return this;
+  }
+
+  offset(n: number): this {
+    this.options.offset = n;
+    return this;
+  }
+
+  async getMany<T = any>(ctx?: any): Promise<T[]> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/select",
+      {
+        table: this.table,
+        ...this.options,
+      }
+    );
+    return response.items || [];
+  }
+
+  async getOne<T = any>(ctx?: any): Promise<T | null> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/select",
+      {
+        table: this.table,
+        ...this.options,
+        one: true,
+        limit: 1,
+      }
+    );
+    const items = response.items || [];
+    return items.length > 0 ? items[0] : null;
+  }
+
+  async count(): Promise<number> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/select",
+      {
+        table: this.table,
+        select: ["COUNT(*) AS count"],
+        where: this.options.where,
+        one: true,
+      }
+    );
+    const items = response.items || [];
+    return items.length > 0 ? items[0].count : 0;
+  }
+}

package/src/db/repository.ts

@@ -0,0 +1,128 @@
+import { HttpClient } from "../core/http";
+import { QueryBuilder } from "./qb";
+import { QueryResponse, FindOptions } from "./types";
+import { SDKError } from "../errors";
+
+export class Repository<T extends Record<string, any>> {
+  private httpClient: HttpClient;
+  private tableName: string;
+  private primaryKey: string;
+
+  constructor(httpClient: HttpClient, tableName: string, primaryKey = "id") {
+    this.httpClient = httpClient;
+    this.tableName = tableName;
+    this.primaryKey = primaryKey;
+  }
+
+  createQueryBuilder(): QueryBuilder {
+    return new QueryBuilder(this.httpClient, this.tableName);
+  }
+
+  async find(
+    criteria: Record<string, any> = {},
+    options: FindOptions = {}
+  ): Promise<T[]> {
+    const response = await this.httpClient.post<QueryResponse>(
+      "/v1/rqlite/find",
+      {
+        table: this.tableName,
+        criteria,
+        options,
+      }
+    );
+    return response.items || [];
+  }
+
+  async findOne(criteria: Record<string, any>): Promise<T | null> {
+    try {
+      const response = await this.httpClient.post<T | null>(
+        "/v1/rqlite/find-one",
+        {
+          table: this.tableName,
+          criteria,
+        }
+      );
+      return response;
+    } catch (error) {
+      // Return null if not found instead of throwing
+      if (error instanceof SDKError && error.httpStatus === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async save(entity: T): Promise<T> {
+    const pkValue = entity[this.primaryKey];
+
+    if (!pkValue) {
+      // INSERT
+      const response = await this.httpClient.post<{
+        rows_affected: number;
+        last_insert_id: number;
+      }>("/v1/rqlite/exec", {
+        sql: this.buildInsertSql(entity),
+        args: this.buildInsertArgs(entity),
+      });
+
+      if (response.last_insert_id) {
+        (entity as any)[this.primaryKey] = response.last_insert_id;
+      }
+      return entity;
+    } else {
+      // UPDATE
+      await this.httpClient.post("/v1/rqlite/exec", {
+        sql: this.buildUpdateSql(entity),
+        args: this.buildUpdateArgs(entity),
+      });
+      return entity;
+    }
+  }
+
+  async remove(entity: T | Record<string, any>): Promise<void> {
+    const pkValue = entity[this.primaryKey];
+    if (!pkValue) {
+      throw new SDKError(
+        `Primary key "${this.primaryKey}" is required for remove`,
+        400,
+        "MISSING_PK"
+      );
+    }
+
+    await this.httpClient.post("/v1/rqlite/exec", {
+      sql: `DELETE FROM ${this.tableName} WHERE ${this.primaryKey} = ?`,
+      args: [pkValue],
+    });
+  }
+
+  private buildInsertSql(entity: T): string {
+    const columns = Object.keys(entity).filter((k) => entity[k] !== undefined);
+    const placeholders = columns.map(() => "?").join(", ");
+    return `INSERT INTO ${this.tableName} (${columns.join(
+      ", "
+    )}) VALUES (${placeholders})`;
+  }
+
+  private buildInsertArgs(entity: T): any[] {
+    return Object.entries(entity)
+      .filter(([, v]) => v !== undefined)
+      .map(([, v]) => v);
+  }
+
+  private buildUpdateSql(entity: T): string {
+    const columns = Object.keys(entity)
+      .filter((k) => entity[k] !== undefined && k !== this.primaryKey)
+      .map((k) => `${k} = ?`);
+    return `UPDATE ${this.tableName} SET ${columns.join(", ")} WHERE ${
+      this.primaryKey
+    } = ?`;
+  }
+
+  private buildUpdateArgs(entity: T): any[] {
+    const args = Object.entries(entity)
+      .filter(([k, v]) => v !== undefined && k !== this.primaryKey)
+      .map(([, v]) => v);
+    args.push(entity[this.primaryKey]);
+    return args;
+  }
+}

package/src/db/types.ts

@@ -0,0 +1,67 @@
+export interface Entity {
+  TableName(): string;
+}
+
+export interface QueryResponse {
+  columns?: string[];
+  rows?: any[][];
+  count?: number;
+  items?: any[];
+}
+
+export interface TransactionOp {
+  kind: "exec" | "query";
+  sql: string;
+  args?: any[];
+}
+
+export interface TransactionRequest {
+  statements?: string[];
+  ops?: TransactionOp[];
+  return_results?: boolean;
+}
+
+export interface SelectOptions {
+  select?: string[];
+  joins?: Array<{
+    kind: "INNER" | "LEFT" | "RIGHT" | "FULL";
+    table: string;
+    on: string;
+  }>;
+  where?: Array<{
+    conj?: "AND" | "OR";
+    expr: string;
+    args?: any[];
+  }>;
+  group_by?: string[];
+  order_by?: string[];
+  limit?: number;
+  offset?: number;
+  one?: boolean;
+}
+
+export type FindOptions = Omit<SelectOptions, "select" | "joins" | "one">;
+
+export interface ColumnDefinition {
+  name: string;
+  isPrimaryKey?: boolean;
+  isAutoIncrement?: boolean;
+}
+
+export function extractTableName(entity: Entity | string): string {
+  if (typeof entity === "string") return entity;
+  return entity.TableName();
+}
+
+export function extractPrimaryKey(entity: any): string | undefined {
+  if (typeof entity === "string") return undefined;
+
+  // Check for explicit pk tag
+  const metadata = (entity as any)._dbMetadata;
+  if (metadata?.primaryKey) return metadata.primaryKey;
+
+  // Check for ID field
+  if (entity.id !== undefined) return "id";
+
+  return undefined;
+}

package/src/errors.ts

@@ -0,0 +1,38 @@
+export class SDKError extends Error {
+  public readonly httpStatus: number;
+  public readonly code: string;
+  public readonly details: Record<string, any>;
+
+  constructor(
+    message: string,
+    httpStatus: number = 500,
+    code: string = "SDK_ERROR",
+    details: Record<string, any> = {}
+  ) {
+    super(message);
+    this.name = "SDKError";
+    this.httpStatus = httpStatus;
+    this.code = code;
+    this.details = details;
+  }
+
+  static fromResponse(
+    status: number,
+    body: any,
+    message?: string
+  ): SDKError {
+    const errorMsg = message || body?.error || `HTTP ${status}`;
+    const code = body?.code || `HTTP_${status}`;
+    return new SDKError(errorMsg, status, code, body);
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      httpStatus: this.httpStatus,
+      code: this.code,
+      details: this.details,
+    };
+  }
+}

package/src/functions/client.ts

@@ -0,0 +1,62 @@
+/**
+ * Functions Client
+ * Client for calling serverless functions on the Orama Network
+ */
+
+import { HttpClient } from "../core/http";
+import { SDKError } from "../errors";
+
+export interface FunctionsClientConfig {
+  /**
+   * Base URL for the functions gateway
+   * Defaults to using the same baseURL as the HTTP client
+   */
+  gatewayURL?: string;
+  
+  /**
+   * Namespace for the functions
+   */
+  namespace: string;
+}
+
+export class FunctionsClient {
+  private httpClient: HttpClient;
+  private gatewayURL?: string;
+  private namespace: string;
+
+  constructor(httpClient: HttpClient, config?: FunctionsClientConfig) {
+    this.httpClient = httpClient;
+    this.gatewayURL = config?.gatewayURL;
+    this.namespace = config?.namespace ?? "default";
+  }
+
+  /**
+   * Invoke a serverless function by name
+   * 
+   * @param functionName - Name of the function to invoke
+   * @param input - Input payload for the function
+   * @returns The function response
+   */
+  async invoke<TInput = any, TOutput = any>(
+    functionName: string,
+    input: TInput
+  ): Promise<TOutput> {
+    const url = this.gatewayURL
+      ? `${this.gatewayURL}/v1/invoke/${this.namespace}/${functionName}`
+      : `/v1/invoke/${this.namespace}/${functionName}`;
+
+    try {
+      const response = await this.httpClient.post<TOutput>(url, input);
+      return response;
+    } catch (error) {
+      if (error instanceof SDKError) {
+        throw error;
+      }
+      throw new SDKError(
+        `Function ${functionName} failed`,
+        500,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+}

package/src/functions/index.ts

@@ -0,0 +1,2 @@
+export { FunctionsClient, type FunctionsClientConfig } from "./client";
+export type { FunctionResponse, SuccessResponse } from "./types";

package/src/functions/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Serverless Functions Types
+ * Type definitions for calling serverless functions on the Orama Network
+ */
+
+/**
+ * Generic response from a serverless function
+ */
+export interface FunctionResponse<T = unknown> {
+  success: boolean;
+  error?: string;
+  data?: T;
+}
+
+/**
+ * Standard success/error response used by many functions
+ */
+export interface SuccessResponse {
+  success: boolean;
+  error?: string;
+}