@cequrebackends/plugin-surrealdb 0.14.0

package/README.md

@@ -0,0 +1,21 @@
+# @cequrebackends/plugin-surrealdb
+
+SurrealDB database driver plugin for Cequre backends.
+
+## Installation
+
+```bash
+bun add @cequrebackends/plugin-surrealdb surrealdb
+```
+
+## Usage
+
+```typescript
+import { CequreRuntime } from "@cequrebackends/cequre-ts";
+import { surrealdb } from "@cequrebackends/plugin-surrealdb";
+
+const runtime = new CequreRuntime(schema, {
+  adapter: surrealdb({ url: "http://127.0.0.1:8000" }),
+  plugins: []
+});
+```

package/dist/adapter.d.ts

@@ -0,0 +1,69 @@
+import type { CequreAdapter, QueryArgs, PaginatedResult, CollectionConfig } from "@cequrebackends/cequre-ts";
+export type SurrealDBOptions = {
+    url: string;
+    namespace?: string;
+    database?: string;
+    auth?: {
+        username: string;
+        password: string;
+    };
+};
+/**
+ * SurrealDB adapter using the official SurrealDB JavaScript SDK v3.
+ */
+export declare class SurrealDBAdapter implements CequreAdapter {
+    readonly adapterType = "surrealdb";
+    readonly supportsGeneratedConstraintSQL = false;
+    private _connection;
+    private _RecordId;
+    private get db();
+    private options;
+    /** slug → ordered list of field names known from the Cequre config */
+    private _collectionFields;
+    constructor(options: SurrealDBOptions);
+    private _getRecordId;
+    /**
+     * Register collection field names so that `normalizeRecord` can hydrate
+     * fields that SurrealDB omits when their value is NONE.
+     */
+    configureCollections(collections: CollectionConfig[]): void;
+    connect(): Promise<void>;
+    private _connectInner;
+    disconnect(): Promise<void>;
+    ping(): Promise<void>;
+    getSystemTableStatements(): string[];
+    getCurrentSchema(): Promise<{
+        tables: string[];
+        columns: Record<string, string[]>;
+    }>;
+    recordMigration(version: string, description: string): Promise<void>;
+    getCurrentMigrationVersion(): Promise<string | null>;
+    createTableDDL(table: unknown, tableName?: string): string;
+    renameColumnDDL(table: string, oldName: string, _newName: string, column: unknown): string;
+    addColumnDDL(table: string, column: unknown): string | null;
+    dropColumnDDL(table: string, column: string): string;
+    dropTableDDL(table: string): string;
+    parseConstraintError(error: unknown): any;
+    find(collection: string, query: QueryArgs): Promise<PaginatedResult>;
+    count(collection: string, query?: Pick<QueryArgs, "where">): Promise<number>;
+    findById(collection: string, id: string): Promise<Record<string, unknown> | null>;
+    findByIds(collection: string, ids: string[]): Promise<Record<string, unknown>[]>;
+    create(collection: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    createMany(collection: string, docs: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;
+    update(collection: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    delete(collection: string, id: string): Promise<void>;
+    deleteMany(collection: string, ids: string[]): Promise<void>;
+    raw(query: string, params?: unknown[]): Promise<unknown>;
+    /**
+     * Normalizes a SurrealDB record to a plain object with a string `id` field.
+     * SurrealDB returns `id` as a RecordId object (table:uuid) — we extract just the ID part.
+     */
+    private normalizeRecord;
+    /**
+     * Recursively builds a SurrealQL WHERE expression supporting flat field
+     * conditions plus compound `or` / `and` arrays.
+     */
+    private buildSurrealWhere;
+    private buildSurrealOp;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { SurrealDBAdapter, type SurrealDBOptions } from "./adapter";
+export declare function surrealdb(options: SurrealDBOptions): SurrealDBAdapter;
+export * from "./adapter";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEpE,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAErE;AAED,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,533 @@
+// @bun
+var __require = import.meta.require;
+
+// src/adapter.ts
+import { ulid } from "@cequrebackends/cequre-ts";
+import { createLogger } from "@cequrebackends/cequre-ts";
+var logger = createLogger("SurrealDBAdapter");
+function generateSystemTablesSurreal() {
+  return ["DEFINE TABLE _cequre_migrations SCHEMALESS;", "DEFINE TABLE cequre_refresh_tokens SCHEMALESS;"];
+}
+function generateAddColumnSurreal(table, column) {
+  let ddl = `DEFINE FIELD ${surrealIdentifier(column.name)} ON ${surrealIdentifier(table)} TYPE any;`;
+  if (column.unique) {
+    ddl += `
+DEFINE INDEX unique_${column.name} ON TABLE ${surrealIdentifier(table)} COLUMNS ${surrealIdentifier(column.name)} UNIQUE;`;
+  }
+  return ddl;
+}
+function generateRenameColumnSurreal(table, oldName, newName) {
+  return `UPDATE ${table} SET ${newName} = ${oldName}; REMOVE FIELD ${oldName} ON TABLE ${table};`;
+}
+var _surrealModule = null;
+async function loadSurrealDB() {
+  if (_surrealModule)
+    return _surrealModule;
+  try {
+    _surrealModule = await import("surrealdb");
+    return _surrealModule;
+  } catch {
+    throw new Error("surrealdb is not installed. Run: bun add surrealdb");
+  }
+}
+var SURREAL_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function surrealIdentifier(identifier) {
+  if (!SURREAL_IDENTIFIER_RE.test(identifier)) {
+    throw new Error(`Invalid SurrealDB identifier '${identifier}'`);
+  }
+  return identifier;
+}
+function surrealPath(path) {
+  return path.split(".").map(surrealIdentifier).join(".");
+}
+
+class SurrealDBAdapter {
+  adapterType = "surrealdb";
+  supportsGeneratedConstraintSQL = false;
+  _connection = null;
+  _RecordId = null;
+  get db() {
+    if (!this._connection)
+      throw new Error("SurrealDB not connected. Call connect() first.");
+    return this._connection;
+  }
+  options;
+  _collectionFields = new Map;
+  constructor(options) {
+    this.options = options;
+  }
+  async _getRecordId() {
+    if (this._RecordId)
+      return this._RecordId;
+    const sdk = await loadSurrealDB();
+    this._RecordId = sdk.RecordId;
+    return this._RecordId;
+  }
+  configureCollections(collections) {
+    for (const colDef of collections) {
+      const col = colDef;
+      const names = col.fields.map((f) => f.name);
+      if (col.timestamps)
+        names.push("createdAt", "updatedAt");
+      if (col.softDelete)
+        names.push("deletedAt");
+      if (col.auth && col.requireEmailVerification)
+        names.push("emailVerified", "verifyToken");
+      if (col.auth && col.lockout)
+        names.push("loginAttempts", "lockedUntil");
+      this._collectionFields.set(col.slug, names);
+    }
+  }
+  async connect() {
+    const sdk = await loadSurrealDB();
+    if (!this._connection) {
+      this._connection = new sdk.Surreal;
+    }
+    this._RecordId = sdk.RecordId;
+    const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error(`SurrealDB connection timed out after 5s \u2014 is the server running at ${this.options.url}?`)), 5000));
+    await Promise.race([this._connectInner(), timeout]);
+  }
+  async _connectInner() {
+    await this.db.connect(this.options.url);
+    if (this.options.auth) {
+      await this.db.signin({
+        username: this.options.auth.username,
+        password: this.options.auth.password
+      });
+    }
+    const ns = this.options.namespace ?? "cequre-bun";
+    const db = this.options.database ?? "cequre-bun";
+    try {
+      await this.db.query(`DEFINE NAMESPACE IF NOT EXISTS ${ns};`);
+      await this.db.query(`USE NAMESPACE ${ns}; DEFINE DATABASE IF NOT EXISTS ${db};`);
+    } catch (e) {
+      logger.warn({ err: e }, "Failed to auto-create namespace/database. It might already exist or permissions are lacking.");
+    }
+    await this.db.use({
+      namespace: ns,
+      database: db
+    });
+    await this.db.query("RETURN true");
+    logger.info("Connected to SurrealDB");
+  }
+  async disconnect() {
+    if (this._connection)
+      await this._connection.close();
+    this._connection = null;
+  }
+  async ping() {
+    await this.db.query("RETURN true");
+  }
+  getSystemTableStatements() {
+    return generateSystemTablesSurreal();
+  }
+  async getCurrentSchema() {
+    const schema = {
+      tables: [],
+      columns: {}
+    };
+    const dbInfo = await this.raw("INFO FOR DB");
+    const tablesMap = dbInfo.tables ?? {};
+    schema.tables = Object.keys(tablesMap).filter((name) => !name.startsWith("cequre-bun_") && name !== "undefined" && name !== "null");
+    for (const tableName of schema.tables) {
+      const tableInfo = await this.raw(`INFO FOR TABLE ${tableName}`);
+      const fieldsMap = tableInfo.fields ?? {};
+      schema.columns[tableName] = Object.keys(fieldsMap).map((field) => `${field} string`);
+    }
+    return schema;
+  }
+  async recordMigration(version, description) {
+    const existing = await this.find("_cequre_migrations", {
+      where: { version: { eq: version } },
+      limit: 1,
+      page: 1
+    });
+    if (existing.docs.length > 0)
+      return;
+    await this.create("_cequre_migrations", {
+      version,
+      description,
+      applied_at: new Date().toISOString()
+    });
+  }
+  async getCurrentMigrationVersion() {
+    const result = await this.find("_cequre_migrations", {
+      sort: "-applied_at",
+      limit: 1,
+      page: 1
+    });
+    return result.docs[0]?.version ?? null;
+  }
+  createTableDDL(table, tableName) {
+    const name = tableName || table.name || table.slug;
+    let ddl = `DEFINE TABLE IF NOT EXISTS ${surrealIdentifier(name)} SCHEMALESS;`;
+    const fields = table.fields || [];
+    for (const field of fields) {
+      if (field.unique) {
+        ddl += `
+DEFINE INDEX IF NOT EXISTS unique_${field.name} ON TABLE ${surrealIdentifier(name)} COLUMNS ${surrealIdentifier(field.name)} UNIQUE;`;
+      }
+    }
+    return ddl;
+  }
+  renameColumnDDL(table, oldName, _newName, column) {
+    return generateRenameColumnSurreal(table, oldName, _newName);
+  }
+  addColumnDDL(table, column) {
+    return generateAddColumnSurreal(table, column);
+  }
+  dropColumnDDL(table, column) {
+    return `REMOVE FIELD ${surrealPath(column)} ON TABLE ${surrealIdentifier(table)};`;
+  }
+  dropTableDDL(table) {
+    return `REMOVE TABLE ${surrealIdentifier(table)};`;
+  }
+  parseConstraintError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const rawMessage = message;
+    const existsMatch = message.match(/Database record `([^`]+)` already exists/i) || message.match(/already exists/i) || message.match(/already contains/i);
+    if (existsMatch) {
+      return {
+        type: "unique",
+        rawMessage
+      };
+    }
+    return null;
+  }
+  async find(collection, query) {
+    const { where, sort, limit = 10, page = 1, cursor } = query;
+    let whereSql = "";
+    const params = {};
+    if (where) {
+      const ctx = { params, pIdx: 0 };
+      const sql = this.buildSurrealWhere(where, ctx);
+      if (sql)
+        whereSql = " WHERE " + sql;
+    }
+    let orderSql = "";
+    if (sort) {
+      const parts = sort.split(",").map((s) => s.trim()).filter(Boolean);
+      const orderParts = parts.map((part) => {
+        const desc = part.startsWith("-");
+        const field = desc ? part.slice(1) : part;
+        return `${surrealPath(field)} ${desc ? "DESC" : "ASC"}`;
+      });
+      if (orderParts.length > 0)
+        orderSql = ` ORDER BY ${orderParts.join(", ")}`;
+    }
+    if (cursor) {
+      let decoded;
+      try {
+        decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf-8"));
+      } catch {
+        throw new Error("Invalid cursor");
+      }
+      const primarySort = sort ? sort.split(",")[0].trim() : "id";
+      const desc = primarySort.startsWith("-");
+      const sortField = desc ? primarySort.slice(1) : primarySort;
+      const op = desc ? "<" : ">";
+      const cursorCondition = sortField === "id" ? `meta::id(id) ${op} $__cursorId` : `(${surrealPath(sortField)} ${op} $__cursorSortValue OR (${surrealPath(sortField)} = $__cursorSortValue AND meta::id(id) ${op} $__cursorId))`;
+      params.__cursorId = decoded.id;
+      if (sortField !== "id")
+        params.__cursorSortValue = decoded.sortValue;
+      whereSql = whereSql ? `${whereSql} AND ${cursorCondition}` : ` WHERE ${cursorCondition}`;
+      params.__limit = limit + 1;
+      const dataSql2 = `SELECT * FROM ${surrealIdentifier(collection)}${whereSql}${orderSql} LIMIT $__limit`;
+      logger.debug({ dataSql: dataSql2, params }, "Executing SurrealDB cursor find query");
+      const [docs2] = await this.db.query(dataSql2, params);
+      const normalizedDocs2 = (docs2 ?? []).map((doc) => this.normalizeRecord(collection, doc));
+      const hasNextPage = normalizedDocs2.length > limit;
+      const resultDocs = hasNextPage ? normalizedDocs2.slice(0, limit) : normalizedDocs2;
+      let nextCursor = null;
+      if (hasNextPage && resultDocs.length > 0) {
+        const lastDoc = resultDocs[resultDocs.length - 1];
+        nextCursor = Buffer.from(JSON.stringify({ id: lastDoc?.id, sortValue: sortField !== "id" ? lastDoc[sortField] : undefined })).toString("base64url");
+      }
+      return {
+        docs: resultDocs,
+        totalDocs: 0,
+        limit,
+        page: 0,
+        totalPages: 0,
+        hasNextPage,
+        hasPrevPage: true,
+        nextCursor,
+        prevCursor: null
+      };
+    }
+    const offset = (page - 1) * limit;
+    const dataSql = `SELECT * FROM ${surrealIdentifier(collection)}${whereSql}${orderSql} LIMIT $__limit START $__offset`;
+    const countSql = `SELECT count() AS total FROM ${surrealIdentifier(collection)}${whereSql} GROUP ALL`;
+    params.__limit = limit;
+    params.__offset = offset;
+    logger.debug({ dataSql, countSql, params }, "Executing SurrealDB find query");
+    const [countResult] = await this.db.query(countSql, params);
+    const totalDocs = countResult?.[0]?.total ?? 0;
+    const [docs] = await this.db.query(dataSql, params);
+    const normalizedDocs = (docs ?? []).map((doc) => this.normalizeRecord(collection, doc));
+    const totalPages = Math.ceil(totalDocs / limit);
+    return {
+      docs: normalizedDocs,
+      totalDocs,
+      limit,
+      page,
+      totalPages,
+      hasNextPage: page < totalPages,
+      hasPrevPage: page > 1
+    };
+  }
+  async count(collection, query) {
+    let whereSql = "";
+    const params = {};
+    if (query?.where) {
+      const ctx = { params, pIdx: 0 };
+      const sql = this.buildSurrealWhere(query.where, ctx);
+      if (sql)
+        whereSql = " WHERE " + sql;
+    }
+    const countSql = `SELECT count() AS total FROM ${surrealIdentifier(collection)}${whereSql} GROUP ALL`;
+    logger.debug({ countSql, params }, "Executing SurrealDB count query");
+    const [result] = await this.db.query(countSql, params);
+    return result?.[0]?.total ?? 0;
+  }
+  async findById(collection, id) {
+    logger.debug({ collection, id }, "Executing SurrealDB findById query");
+    const recordId = new (await this._getRecordId())(collection, id);
+    const result = await this.db.select(recordId);
+    if (!result)
+      return null;
+    return this.normalizeRecord(collection, result);
+  }
+  async findByIds(collection, ids) {
+    if (ids.length === 0)
+      return [];
+    logger.debug({ collection, count: ids.length }, "Executing SurrealDB findByIds query");
+    const RecordId = await this._getRecordId();
+    const recordIds = ids.map((id) => new RecordId(collection, id));
+    const [results] = await this.db.query(`SELECT * FROM $ids`, { ids: recordIds });
+    return (results ?? []).map((doc) => this.normalizeRecord(collection, doc));
+  }
+  async create(collection, data) {
+    const now = new Date;
+    const knownFields = new Set(this._collectionFields.get(collection) ?? []);
+    const { id: providedId, ...rest } = data;
+    const id = providedId ?? ulid();
+    const doc = { ...rest };
+    if (knownFields.size === 0 || knownFields.has("createdAt"))
+      doc.createdAt = doc.createdAt ?? now;
+    if (knownFields.size === 0 || knownFields.has("updatedAt"))
+      doc.updatedAt = now;
+    logger.debug({ collection, id, fields: Object.keys(doc) }, "Executing SurrealDB create");
+    const recordId = new (await this._getRecordId())(collection, id);
+    const result = await this.db.create(recordId).content(doc);
+    return this.normalizeRecord(collection, result);
+  }
+  async createMany(collection, docs) {
+    if (docs.length === 0)
+      return [];
+    const now = new Date;
+    const results = [];
+    const knownFields = new Set(this._collectionFields.get(collection) ?? []);
+    for (const data of docs) {
+      const { id: providedId, ...rest } = data;
+      const id = providedId ?? ulid();
+      const doc = { ...rest };
+      if (knownFields.size === 0 || knownFields.has("createdAt"))
+        doc.createdAt = doc.createdAt ?? now;
+      if (knownFields.size === 0 || knownFields.has("updatedAt"))
+        doc.updatedAt = now;
+      const recordId = new (await this._getRecordId())(collection, id);
+      const result = await this.db.create(recordId).content(doc);
+      results.push(this.normalizeRecord(collection, result));
+    }
+    return results;
+  }
+  async update(collection, id, data) {
+    const now = new Date;
+    const knownFields = new Set(this._collectionFields.get(collection) ?? []);
+    const updateData = { ...data };
+    if (knownFields.size === 0 || knownFields.has("updatedAt"))
+      updateData.updatedAt = now;
+    logger.debug({ collection, id, fields: Object.keys(updateData) }, "Executing SurrealDB update");
+    const recordId = new (await this._getRecordId())(collection, id);
+    const result = await this.db.update(recordId).merge(updateData);
+    if (!result) {
+      throw new Error(`Document with id '${id}' not found in collection '${collection}'`);
+    }
+    return this.normalizeRecord(collection, result);
+  }
+  async delete(collection, id) {
+    logger.debug({ collection, id }, "Executing SurrealDB delete");
+    const recordId = new (await this._getRecordId())(collection, id);
+    const result = await this.db.delete(recordId);
+    if (!result) {
+      throw new Error(`Document with id '${id}' not found in collection '${collection}'`);
+    }
+  }
+  async deleteMany(collection, ids) {
+    if (ids.length === 0)
+      return;
+    logger.debug({ collection, count: ids.length }, "Executing SurrealDB bulk delete");
+    const RecordId = await this._getRecordId();
+    const recordIds = ids.map((id) => new RecordId(collection, id));
+    await this.db.query(`DELETE $ids`, { ids: recordIds });
+  }
+  async raw(query, params) {
+    let surrealQuery = query;
+    const namedParams = {};
+    if (params && params.length > 0) {
+      for (let i = 0;i < params.length; i++) {
+        const positional = `$${i + 1}`;
+        const named = `__raw_${i}`;
+        surrealQuery = surrealQuery.replaceAll(positional, `$${named}`);
+        namedParams[named] = params[i];
+      }
+    }
+    try {
+      const results = await this.db.query(surrealQuery, namedParams);
+      return results[results.length - 1];
+    } catch (e) {
+      if (e.message && (e.message.includes("already exists") || e.message.includes("AlreadyExists"))) {
+        return null;
+      }
+      throw e;
+    }
+  }
+  normalizeRecord(collection, record) {
+    const normalized = {};
+    const knownFields = this._collectionFields.get(collection);
+    if (knownFields) {
+      for (const field of knownFields) {
+        normalized[field] = null;
+      }
+    }
+    for (const [key, value] of Object.entries(record)) {
+      if (key === "id") {
+        if (this._RecordId && value instanceof this._RecordId) {
+          normalized.id = String(value.id);
+        } else if (value !== null && typeof value === "object" && "id" in value && value.id !== undefined) {
+          normalized.id = String(value.id);
+        } else if (typeof value === "string" && value.includes(":")) {
+          normalized.id = value.split(":").slice(1).join(":");
+        } else {
+          normalized[key] = value;
+        }
+      } else {
+        normalized[key] = value;
+      }
+    }
+    return normalized;
+  }
+  buildSurrealWhere(where, ctx) {
+    const conditions = [];
+    for (const [key, value] of Object.entries(where)) {
+      if (key === "or" || key === "and" || key === "OR" || key === "AND") {
+        const sub = value;
+        if (!Array.isArray(sub) || sub.length === 0)
+          continue;
+        const parts = sub.map((clause) => this.buildSurrealWhere(clause, ctx)).filter(Boolean);
+        if (parts.length > 0) {
+          const joiner = key.toLowerCase() === "or" ? " OR " : " AND ";
+          conditions.push(`(${parts.join(joiner)})`);
+        }
+        continue;
+      }
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const ops = value;
+        const mode = ops.mode === "sensitive" ? "sensitive" : "insensitive";
+        for (const [op, opValue] of Object.entries(ops)) {
+          if (op === "mode")
+            continue;
+          const cond = this.buildSurrealOp(key, op, opValue, ctx, mode);
+          if (cond)
+            conditions.push(cond);
+        }
+      } else {
+        const p = `p${ctx.pIdx++}`;
+        const fieldExpr = key === "id" ? "meta::id(id)" : surrealPath(key);
+        conditions.push(`${fieldExpr} = $${p}`);
+        ctx.params[p] = value;
+      }
+    }
+    return conditions.length > 0 ? conditions.join(" AND ") : "";
+  }
+  buildSurrealOp(field, op, value, ctx, mode = "insensitive") {
+    const p = `p${ctx.pIdx++}`;
+    const fieldExpr = field === "id" ? "meta::id(id)" : surrealPath(field);
+    switch (op) {
+      case "eq":
+      case "neq":
+      case "gt":
+      case "gte":
+      case "lt":
+      case "lte": {
+        const sym = { eq: "=", neq: "!=", gt: ">", gte: ">=", lt: "<", lte: "<=" }[op];
+        ctx.params[p] = value;
+        return `${fieldExpr} ${sym} $${p}`;
+      }
+      case "in":
+        if (Array.isArray(value) && value.length > 0) {
+          ctx.params[p] = value;
+          return `${fieldExpr} IN $${p}`;
+        }
+        return null;
+      case "nin":
+        if (Array.isArray(value) && value.length > 0) {
+          ctx.params[p] = value;
+          return `${fieldExpr} NOT IN $${p}`;
+        }
+        return null;
+      case "exists":
+        ctx.pIdx--;
+        return value === true || value === "true" ? `${fieldExpr} != NONE` : `(${fieldExpr} = NONE OR ${fieldExpr} IS NULL)`;
+      case "like":
+      case "contains":
+        ctx.params[p] = value;
+        return `${fieldExpr} CONTAINS $${p}`;
+      case "startsWith":
+        ctx.params[p] = value;
+        return `${fieldExpr} CONTAINS $${p}`;
+      case "endsWith":
+        ctx.params[p] = value;
+        return `${fieldExpr} CONTAINS $${p}`;
+      case "notContains":
+        ctx.params[p] = value;
+        return `${fieldExpr} CONTAINSNOT $${p}`;
+      case "any":
+        if (Array.isArray(value) && value.length > 0) {
+          ctx.params[p] = value;
+          return `${fieldExpr} CONTAINSANY $${p}`;
+        }
+        ctx.pIdx--;
+        return null;
+      case "all":
+        if (Array.isArray(value) && value.length > 0) {
+          ctx.params[p] = value;
+          return `${fieldExpr} CONTAINSALL $${p}`;
+        }
+        ctx.pIdx--;
+        return null;
+      case "between": {
+        if (Array.isArray(value) && value.length === 2) {
+          const p2 = `p${ctx.pIdx++}`;
+          ctx.params[p] = value[0];
+          ctx.params[p2] = value[1];
+          return `${fieldExpr} >= $${p} AND ${fieldExpr} <= $${p2}`;
+        }
+        ctx.pIdx--;
+        return null;
+      }
+      default:
+        return null;
+    }
+  }
+}
+
+// src/index.ts
+function surrealdb(options) {
+  return new SurrealDBAdapter(options);
+}
+export {
+  surrealdb,
+  SurrealDBAdapter
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cequrebackends/plugin-surrealdb",
+  "version": "0.14.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target bun --packages external && tsc --emitDeclarationOnly"
+  },
+  "dependencies": {
+    "surrealdb": "^2.0.4"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.1-rc",
+    "@cequrebackends/cequre-ts": "0.13.0"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cequrebackends/cequre.git"
+  },
+  "peerDependencies": {
+    "@cequrebackends/cequre-ts": "0.13.0"
+  }
+}