@teamkeel/functions-runtime 0.0.1

package/src/QueryBuilder.js

@@ -0,0 +1,95 @@
+const { applyWhereConditions } = require("./applyWhereConditions");
+const {
+  applyLimit,
+  applyOffset,
+  applyOrderBy,
+} = require("./applyAdditionalQueryConstraints");
+const { applyJoins } = require("./applyJoins");
+const { camelCaseObject } = require("./casing");
+const { useDatabase } = require("./database");
+const { QueryContext } = require("./QueryContext");
+const tracing = require("./tracing");
+
+class QueryBuilder {
+  /**
+   * @param {string} tableName
+   * @param {import("./QueryContext").QueryContext} context
+   * @param {import("kysely").Kysely} db
+   */
+  constructor(tableName, context, db) {
+    this._tableName = tableName;
+    this._context = context;
+    this._db = db;
+  }
+
+  where(where) {
+    const context = this._context.clone();
+
+    let builder = applyJoins(context, this._db, where);
+    builder = applyWhereConditions(context, builder, where);
+
+    return new QueryBuilder(this._tableName, context, builder);
+  }
+
+  orWhere(where) {
+    const context = this._context.clone();
+
+    let builder = applyJoins(context, this._db, where);
+
+    builder = builder.orWhere((qb) => {
+      return applyWhereConditions(context, qb, where);
+    });
+
+    return new QueryBuilder(this._tableName, context, builder);
+  }
+
+  async findMany(params) {
+    const name = tracing.spanNameForModelAPI(this._modelName, "findMany");
+    const db = useDatabase();
+
+    return tracing.withSpan(name, async (span) => {
+      const context = new QueryContext([this._tableName], this._tableConfigMap);
+
+      let builder = db
+        .selectFrom((qb) => {
+          // this._db contains all of the where constraints and joins
+          // we want to include that in the sub query in the same way we
+          // add all of this information into the sub query in the ModelAPI's
+          // implementation of findMany
+          return this._db.as(this._tableName);
+        })
+        .selectAll();
+
+      // The only constraints added to the main query are the orderBy, limit and offset as they are performed on the "outer" set
+      if (params?.limit) {
+        builder = applyLimit(context, builder, params.limit);
+      }
+
+      if (params?.offset) {
+        builder = applyOffset(context, builder, params.offset);
+      }
+
+      if (
+        params?.orderBy !== undefined &&
+        Object.keys(params?.orderBy).length > 0
+      ) {
+        builder = applyOrderBy(
+          context,
+          builder,
+          this._tableName,
+          params.orderBy
+        );
+      } else {
+        builder = builder.orderBy(`${this._tableName}.id`);
+      }
+
+      const query = builder;
+
+      span.setAttribute("sql", query.compile().sql);
+      const rows = await builder.execute();
+      return rows.map((x) => camelCaseObject(x));
+    });
+  }
+}
+
+module.exports.QueryBuilder = QueryBuilder;

package/src/QueryContext.js

@@ -0,0 +1,90 @@
+/**
+ * QueryContext is used to store state about the current query, for example
+ * which joins have already been applied. It is used by applyJoins and
+ * applyWhereConditions to generate consistent table aliases for joins.
+ *
+ * This class has the concept of a "table path". This is just a list of tables, starting
+ * with some "root" table and ending with the table we're currently joining to. So
+ * for example if we started with a "product" table and joined from there to "order_item"
+ * and then to "order" and then to "customer" the table path would be:
+ *   ["product", "order_item", "order", "customer"]
+ * At this point the "current" table is "customer" and it's alias would be:
+ *   "product$order_item$order$customer"
+ */
+class QueryContext {
+  /**
+   * @param {string[]} tablePath This is the path from the "root" table to the "current table".
+   * @param {import("./ModelAPI").TableConfigMap} tableConfigMap
+   * @param {string[]} joins
+   */
+  constructor(tablePath, tableConfigMap, joins = []) {
+    this._tablePath = tablePath;
+    this._tableConfigMap = tableConfigMap;
+    this._joins = joins;
+  }
+
+  clone() {
+    return new QueryContext([...this._tablePath], this._tableConfigMap, [
+      ...this._joins,
+    ]);
+  }
+
+  /**
+   * Returns true if, given the current table path, a join to the given
+   * table has already been added.
+   * @param {string} table
+   * @returns {boolean}
+   */
+  hasJoin(table) {
+    const alias = joinAlias([...this._tablePath, table]);
+    return this._joins.includes(alias);
+  }
+
+  /**
+   * Adds table to the QueryContext's path and registers the join,
+   * calls fn, then pops the table off the path.
+   * @param {string} table
+   * @param {Function} fn
+   */
+  withJoin(table, fn) {
+    this._tablePath.push(table);
+    this._joins.push(this.tableAlias());
+
+    fn();
+
+    // Don't change the _joins list, we want to remember those
+    this._tablePath.pop();
+  }
+
+  /**
+   * Returns the alias that will be used for the current table
+   * @returns {string}
+   */
+  tableAlias() {
+    return joinAlias(this._tablePath);
+  }
+
+  /**
+   * Returns the current table name
+   * @returns {string}
+   */
+  tableName() {
+    return this._tablePath[this._tablePath.length - 1];
+  }
+
+  /**
+   * Return the TableConfig for the current table
+   * @returns {import("./ModelAPI").TableConfig | undefined}
+   */
+  tableConfig() {
+    return this._tableConfigMap[this.tableName()];
+  }
+}
+
+function joinAlias(tablePath) {
+  return tablePath.join("$");
+}
+
+module.exports = {
+  QueryContext,
+};

package/src/RequestHeaders.js

@@ -0,0 +1,21 @@
+class RequestHeaders {
+  /**
+   * @param {{Object.<string, string>}} requestHeaders Map of request headers submitted from the client
+   */
+
+  constructor(requestHeaders) {
+    this._headers = new Headers(requestHeaders);
+  }
+
+  get(key) {
+    return this._headers.get(key);
+  }
+
+  has(key) {
+    return this._headers.has(key);
+  }
+}
+
+module.exports = {
+  RequestHeaders,
+};

package/src/applyAdditionalQueryConstraints.js

@@ -0,0 +1,22 @@
+const { snakeCase } = require("change-case");
+
+function applyLimit(context, qb, limit) {
+  return qb.limit(limit);
+}
+
+function applyOffset(context, qb, offset) {
+  return qb.offset(offset);
+}
+
+function applyOrderBy(context, qb, tableName, orderBy = {}) {
+  Object.entries(orderBy).forEach(([key, sortOrder]) => {
+    qb = qb.orderBy(`${tableName}.${snakeCase(key)}`, sortOrder);
+  });
+  return qb;
+}
+
+module.exports = {
+  applyLimit,
+  applyOffset,
+  applyOrderBy,
+};

package/src/applyJoins.js

@@ -0,0 +1,65 @@
+/**
+ * Adds the joins required by the where conditions to the given
+ * Kysely instance and returns the resulting new Kysely instance.
+ * @param {import("./QueryContext").QueryContext} context
+ * @param {import("kysely").Kysely} qb
+ * @param {Object} where
+ * @returns {import("kysely").Kysely}
+ */
+function applyJoins(context, qb, where) {
+  const conf = context.tableConfig();
+  if (!conf) {
+    return qb;
+  }
+
+  const srcTable = context.tableAlias();
+
+  for (const key of Object.keys(where)) {
+    const rel = conf[key];
+    if (!rel) {
+      continue;
+    }
+
+    const targetTable = rel.referencesTable;
+
+    if (context.hasJoin(targetTable)) {
+      continue;
+    }
+
+    context.withJoin(targetTable, () => {
+      switch (rel.relationshipType) {
+        case "hasMany":
+          // For hasMany the primary key is on the source table
+          // and the foreign key is on the target table
+          qb = qb.innerJoin(
+            `${targetTable} as ${context.tableAlias()}`,
+            `${srcTable}.id`,
+            `${context.tableAlias()}.${rel.foreignKey}`
+          );
+          break;
+
+        case "belongsTo":
+          // For belongsTo the primary key is on the target table
+          // and the foreign key is on the source table
+          qb = qb.innerJoin(
+            `${targetTable} as ${context.tableAlias()}`,
+            `${srcTable}.${rel.foreignKey}`,
+            `${context.tableAlias()}.id`
+          );
+          break;
+        default:
+          throw new Error(`unknown relationshipType: ${rel.relationshipType}`);
+      }
+
+      // Keep traversing through the where conditions to see if
+      // more joins need to be applied
+      qb = applyJoins(context, qb, where[key]);
+    });
+  }
+
+  return qb;
+}
+
+module.exports = {
+  applyJoins,
+};

package/src/applyWhereConditions.js

@@ -0,0 +1,70 @@
+const { sql } = require("kysely");
+const { snakeCase } = require("./casing");
+
+const opMapping = {
+  startsWith: { op: "like", value: (v) => `${v}%` },
+  endsWith: { op: "like", value: (v) => `%${v}` },
+  contains: { op: "like", value: (v) => `%${v}%` },
+  oneOf: { op: "in" },
+  greaterThan: { op: ">" },
+  greaterThanOrEquals: { op: ">=" },
+  lessThan: { op: "<" },
+  lessThanOrEquals: { op: "<=" },
+  before: { op: "<" },
+  onOrBefore: { op: "<=" },
+  after: { op: ">" },
+  onOrAfter: { op: ">=" },
+  equals: { op: sql`is not distinct from` },
+  notEquals: { op: sql`is distinct from` },
+};
+
+/**
+ * Applies the given where conditions to the provided Kysely
+ * instance and returns the resulting new Kysely instance.
+ * @param {import("./QueryContext").QueryContext} context
+ * @param {import("kysely").Kysely} qb
+ * @param {Object} where
+ * @returns {import("kysely").Kysely}
+ */
+function applyWhereConditions(context, qb, where = {}) {
+  const conf = context.tableConfig();
+
+  for (const key of Object.keys(where)) {
+    const v = where[key];
+
+    // Handle nested where conditions e.g. using a join table
+    if (conf && conf[key]) {
+      const rel = conf[key];
+      context.withJoin(rel.referencesTable, () => {
+        qb = applyWhereConditions(context, qb, v);
+      });
+      continue;
+    }
+
+    const fieldName = `${context.tableAlias()}.${snakeCase(key)}`;
+
+    if (Object.prototype.toString.call(v) !== "[object Object]") {
+      qb = qb.where(fieldName, "=", v);
+      continue;
+    }
+
+    for (const op of Object.keys(v)) {
+      const mapping = opMapping[op];
+      if (!mapping) {
+        throw new Error(`invalid where condition: ${op}`);
+      }
+
+      qb = qb.where(
+        fieldName,
+        mapping.op,
+        mapping.value ? mapping.value(v[op]) : v[op]
+      );
+    }
+  }
+
+  return qb;
+}
+
+module.exports = {
+  applyWhereConditions,
+};

package/src/casing.js

@@ -0,0 +1,30 @@
+const { snakeCase, camelCase } = require("change-case");
+
+function camelCaseObject(obj = {}) {
+  const r = {};
+  for (const key of Object.keys(obj)) {
+    r[camelCase(key)] = obj[key];
+  }
+  return r;
+}
+
+function snakeCaseObject(obj) {
+  const r = {};
+  for (const key of Object.keys(obj)) {
+    r[snakeCase(key)] = obj[key];
+  }
+  return r;
+}
+
+function upperCamelCase(s) {
+  s = camelCase(s);
+  return s[0].toUpperCase() + s.substring(1);
+}
+
+module.exports = {
+  camelCaseObject,
+  snakeCaseObject,
+  snakeCase,
+  camelCase,
+  upperCamelCase,
+};

package/src/casing.test.js

@@ -0,0 +1,25 @@
+import { test, expect } from "vitest";
+import { camelCaseObject } from "./casing";
+
+const cases = {
+  FROM_SNAKE: {
+    input: {
+      id: "123",
+      slack_id: "xxx_2929",
+      api_key: "1234",
+    },
+    expected: {
+      id: "123",
+      slackId: "xxx_2929",
+      apiKey: "1234",
+    },
+  },
+};
+
+Object.entries(cases).map(([key, { input, expected }]) => {
+  test(key, () => {
+    const result = camelCaseObject(input);
+
+    expect(result).toEqual(expected);
+  });
+});

package/src/consts.js

@@ -0,0 +1,13 @@
+const PROTO_ACTION_TYPES = {
+  UNKNOWN: "OPERATION_TYPE_UNKNOWN",
+  CREATE: "OPERATION_TYPE_CREATE",
+  GET: "OPERATION_TYPE_GET",
+  LIST: "OPERATION_TYPE_LIST",
+  UPDATE: "OPERATION_TYPE_UPDATE",
+  DELETE: "OPERATION_TYPE_DELETE",
+  READ: "OPERATION_TYPE_READ",
+  WRITE: "OPERATION_TYPE_WRITE",
+  JOB: "JOB_TYPE",
+};
+
+module.exports.PROTO_ACTION_TYPES = PROTO_ACTION_TYPES;

package/src/database.js

@@ -0,0 +1,163 @@
+const { Kysely, PostgresDialect, CamelCasePlugin } = require("kysely");
+const { AsyncLocalStorage } = require("async_hooks");
+const pg = require("pg");
+const { PROTO_ACTION_TYPES } = require("./consts");
+const { withSpan } = require("./tracing");
+
+// withDatabase is responsible for setting the correct database client in our AsyncLocalStorage
+// so that the the code in a custom function uses the correct client.
+// For GET and LIST action types, no transaction is used, but for
+// actions that mutate data such as CREATE, DELETE & UPDATE, all of the code inside
+// the user's custom function is wrapped in a transaction so we can rollback
+// the transaction if something goes wrong.
+// withDatabase shouldn't be exposed in the public api of the sdk
+async function withDatabase(db, actionType, cb) {
+  let requiresTransaction = true;
+
+  switch (actionType) {
+    case PROTO_ACTION_TYPES.JOB:
+    case PROTO_ACTION_TYPES.GET:
+    case PROTO_ACTION_TYPES.LIST:
+      requiresTransaction = false;
+      break;
+  }
+
+  if (requiresTransaction) {
+    return db.transaction().execute(async (transaction) => {
+      return dbInstance.run(transaction, async () => {
+        return cb({ transaction });
+      });
+    });
+  }
+
+  return dbInstance.run(db, async () => {
+    return cb({ transaction: db });
+  });
+}
+
+let db = null;
+
+const dbInstance = new AsyncLocalStorage();
+
+// useDatabase will retrieve the database client set by withDatabase from the local storage
+function useDatabase() {
+  // retrieve the instance of the database client from the store which is aware of
+  // which context the current connection to the db is running in - e.g does the context
+  // require a transaction or not?
+  let fromStore = dbInstance.getStore();
+  if (fromStore) {
+    return fromStore;
+  }
+
+  // if the NODE_ENV is 'test' then we know we are inside of the vitest environment
+  // which covers any test files ending in *.test.ts. Custom function code runs in a different node process which will not have this environment variable. Tests written using our testing
+  // framework call actions (and in turn custom function code) over http using the ActionExecutor class
+  if ("NODE_ENV" in process.env && process.env.NODE_ENV == "test") {
+    return getDatabaseClient();
+  }
+
+  // If we've gotten to this point, then we know that we are in a custom function runtime server
+  // context and we haven't been able to retrieve the in-context instance of Kysely, which means we should throw an error.
+  throw new Error("useDatabase must be called within a function");
+}
+
+// getDatabaseClient will return a brand new instance of Kysely. Every instance of Kysely
+// represents an individual connection to the database.
+// not to be exported externally from our sdk - consumers should use useDatabase
+function getDatabaseClient() {
+  // 'db' represents the singleton connection to the database which is stored
+  // as a module scope variable.
+  if (db) {
+    return db;
+  }
+
+  db = new Kysely({
+    dialect: getDialect(),
+    plugins: [
+      // allows users to query using camelCased versions of the database column names, which
+      // should match the names we use in our schema.
+      // https://kysely-org.github.io/kysely/classes/CamelCasePlugin.html
+      // If they don't, then we can create a custom implementation of the plugin where we control
+      // the casing behaviour (see url above for example)
+      new CamelCasePlugin(),
+    ],
+    log(event) {
+      if ("DEBUG" in process.env) {
+        if (event.level === "query") {
+          console.log(event.query.sql);
+          console.log(event.query.parameters);
+        }
+      }
+    },
+  });
+
+  return db;
+}
+
+class InstrumentedPool extends pg.Pool {
+  async connect(...args) {
+    const _super = super.connect.bind(this);
+    return withSpan("Database Connect", function () {
+      return _super(...args);
+    });
+  }
+}
+
+const txStatements = {
+  begin: "Transaction Begin",
+  commit: "Transaction Commit",
+  rollback: "Transaction Rollback",
+};
+
+class InstrumentedClient extends pg.Client {
+  async query(...args) {
+    const _super = super.query.bind(this);
+    const sql = args[0];
+
+    let sqlAttribute = false;
+
+    let spanName = txStatements[sql.toLowerCase()];
+    if (!spanName) {
+      spanName = "Database Query";
+      sqlAttribute = true;
+    }
+
+    return withSpan(spanName, function (span) {
+      if (sqlAttribute) {
+        span.setAttribute("sql", args[0]);
+      }
+      return _super(...args);
+    });
+  }
+}
+
+function getDialect() {
+  const dbConnType = process.env["KEEL_DB_CONN_TYPE"];
+  switch (dbConnType) {
+    case "pg":
+      return new PostgresDialect({
+        pool: new InstrumentedPool({
+          Client: InstrumentedClient,
+          connectionString: mustEnv("KEEL_DB_CONN"),
+        }),
+      });
+
+    default:
+      throw Error("unexpected KEEL_DB_CONN_TYPE: " + dbConnType);
+  }
+}
+
+function mustEnv(key) {
+  const v = process.env[key];
+  if (!v) {
+    throw new Error(`expected environment variable ${key} to be set`);
+  }
+  return v;
+}
+
+// initialise the database client at module scope level so the db variable is set
+getDatabaseClient();
+
+module.exports.getDatabaseClient = getDatabaseClient;
+module.exports.useDatabase = useDatabase;
+module.exports.withDatabase = withDatabase;