convex-helpers 0.0.1

package/cjs/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/cjs/server/relationships.js

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var relationships_exports = {};
+__export(relationships_exports, {
+  asyncMap: () => asyncMap,
+  getAll: () => getAll,
+  getAllWithNulls: () => getAllWithNulls,
+  getManyFrom: () => getManyFrom,
+  getManyVia: () => getManyVia,
+  getOneFrom: () => getOneFrom,
+  getOneOrNullFrom: () => getOneOrNullFrom,
+  pruneNull: () => pruneNull
+});
+module.exports = __toCommonJS(relationships_exports);
+var import_values = require("convex/values");
+async function asyncMap(list, asyncTransform) {
+  const promises = [];
+  for (const item of list) {
+    promises.push(asyncTransform(item));
+  }
+  return Promise.all(promises);
+}
+async function getAll(db, ids) {
+  return pruneNull(await asyncMap(ids, db.get));
+}
+async function getAllWithNulls(db, ids) {
+  return asyncMap(ids, db.get);
+}
+async function getOneFrom(db, table, field, value) {
+  const ret = await db.query(table).withIndex("by_" + field, (q) => q.eq(field, value)).unique();
+  if (ret === null) {
+    throw new import_values.ConvexError(
+      `Can't find a document in ${table} with field ${field} equal to ${value}`
+    );
+  }
+  return ret;
+}
+async function getOneOrNullFrom(db, table, field, value) {
+  return db.query(table).withIndex("by_" + field, (q) => q.eq(field, value)).unique();
+}
+async function getManyFrom(db, table, field, value) {
+  return db.query(table).withIndex("by_" + field, (q) => q.eq(field, value)).collect();
+}
+async function getManyVia(db, table, toField, fromField, value) {
+  return pruneNull(
+    await asyncMap(
+      await getManyFrom(db, table, fromField, value),
+      (link) => db.get(link[toField])
+    )
+  );
+}
+function pruneNull(list) {
+  return list.filter((i) => i !== null);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  asyncMap,
+  getAll,
+  getAllWithNulls,
+  getManyFrom,
+  getManyVia,
+  getOneFrom,
+  getOneOrNullFrom,
+  pruneNull
+});

package/cjs/server/rowLevelSecurity.js

@@ -0,0 +1,273 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var rowLevelSecurity_exports = {};
+__export(rowLevelSecurity_exports, {
+  RowLevelSecurity: () => RowLevelSecurity
+});
+module.exports = __toCommonJS(rowLevelSecurity_exports);
+const RowLevelSecurity = (rules) => {
+  const withMutationRLS = (f) => {
+    return (ctx, ...args) => {
+      const wrappedDb = new WrapWriter(ctx, ctx.db, rules);
+      return f({ ...ctx, db: wrappedDb }, ...args);
+    };
+  };
+  const withQueryRLS = (f) => {
+    return (ctx, ...args) => {
+      const wrappedDb = new WrapReader(ctx, ctx.db, rules);
+      return f({ ...ctx, db: wrappedDb }, ...args);
+    };
+  };
+  return {
+    withMutationRLS,
+    withQueryRLS
+  };
+};
+async function asyncFilter(arr, predicate) {
+  const results = await Promise.all(arr.map(predicate));
+  return arr.filter((_v, index) => results[index]);
+}
+class WrapQuery {
+  q;
+  p;
+  iterator;
+  constructor(q, p) {
+    this.q = q;
+    this.p = p;
+  }
+  filter(predicate) {
+    return new WrapQuery(this.q.filter(predicate), this.p);
+  }
+  order(order) {
+    return new WrapQuery(this.q.order(order), this.p);
+  }
+  async paginate(paginationOpts) {
+    const result = await this.q.paginate(paginationOpts);
+    result.page = await asyncFilter(result.page, this.p);
+    return result;
+  }
+  async collect() {
+    const results = await this.q.collect();
+    return await asyncFilter(results, this.p);
+  }
+  async take(n) {
+    const results = [];
+    for await (const result of this) {
+      results.push(result);
+      if (results.length >= n) {
+        break;
+      }
+    }
+    return results;
+  }
+  async first() {
+    for await (const result of this) {
+      return result;
+    }
+    return null;
+  }
+  async unique() {
+    let uniqueResult = null;
+    for await (const result of this) {
+      if (uniqueResult === null) {
+        uniqueResult = result;
+      } else {
+        throw new Error("not unique");
+      }
+    }
+    return uniqueResult;
+  }
+  [Symbol.asyncIterator]() {
+    this.iterator = this.q[Symbol.asyncIterator]();
+    return this;
+  }
+  async next() {
+    for (; ; ) {
+      const { value, done } = await this.iterator.next();
+      if (value && await this.p(value)) {
+        return { value, done };
+      }
+      if (done) {
+        return { value: null, done: true };
+      }
+    }
+  }
+  return() {
+    return this.iterator.return();
+  }
+}
+class WrapQueryInitializer {
+  q;
+  p;
+  constructor(q, p) {
+    this.q = q;
+    this.p = p;
+  }
+  fullTableScan() {
+    return new WrapQuery(this.q.fullTableScan(), this.p);
+  }
+  withIndex(indexName, indexRange) {
+    return new WrapQuery(this.q.withIndex(indexName, indexRange), this.p);
+  }
+  withSearchIndex(indexName, searchFilter) {
+    return new WrapQuery(
+      this.q.withSearchIndex(indexName, searchFilter),
+      this.p
+    );
+  }
+  filter(predicate) {
+    return this.fullTableScan().filter(predicate);
+  }
+  order(order) {
+    return this.fullTableScan().order(order);
+  }
+  async paginate(paginationOpts) {
+    return this.fullTableScan().paginate(paginationOpts);
+  }
+  collect() {
+    return this.fullTableScan().collect();
+  }
+  take(n) {
+    return this.fullTableScan().take(n);
+  }
+  first() {
+    return this.fullTableScan().first();
+  }
+  unique() {
+    return this.fullTableScan().unique();
+  }
+  [Symbol.asyncIterator]() {
+    return this.fullTableScan()[Symbol.asyncIterator]();
+  }
+}
+class WrapReader {
+  ctx;
+  db;
+  rules;
+  constructor(ctx, db, rules) {
+    this.ctx = ctx;
+    this.db = db;
+    this.rules = rules;
+  }
+  normalizeId(tableName, id) {
+    return this.db.normalizeId(tableName, id);
+  }
+  tableName(id) {
+    for (const tableName of Object.keys(this.rules)) {
+      if (this.db.normalizeId(tableName, id)) {
+        return tableName;
+      }
+    }
+    return null;
+  }
+  async predicate(tableName, doc) {
+    if (!this.rules[tableName]?.read) {
+      return true;
+    }
+    return await this.rules[tableName].read(this.ctx, doc);
+  }
+  async get(id) {
+    const doc = await this.db.get(id);
+    if (doc) {
+      const tableName = this.tableName(id);
+      if (tableName && !await this.predicate(tableName, doc)) {
+        return null;
+      }
+      return doc;
+    }
+    return null;
+  }
+  query(tableName) {
+    return new WrapQueryInitializer(
+      this.db.query(tableName),
+      async (d) => await this.predicate(tableName, d)
+    );
+  }
+}
+class WrapWriter {
+  ctx;
+  db;
+  reader;
+  rules;
+  async modifyPredicate(tableName, doc) {
+    if (!this.rules[tableName]?.modify) {
+      return true;
+    }
+    return await this.rules[tableName].modify(this.ctx, doc);
+  }
+  constructor(ctx, db, rules) {
+    this.ctx = ctx;
+    this.db = db;
+    this.reader = new WrapReader(ctx, db, rules);
+    this.rules = rules;
+  }
+  normalizeId(tableName, id) {
+    return this.db.normalizeId(tableName, id);
+  }
+  async insert(table, value) {
+    const rules = this.rules[table];
+    if (rules?.insert && !await rules.insert(this.ctx, value)) {
+      throw new Error("insert access not allowed");
+    }
+    return await this.db.insert(table, value);
+  }
+  tableName(id) {
+    for (const tableName of Object.keys(this.rules)) {
+      if (this.db.normalizeId(tableName, id)) {
+        return tableName;
+      }
+    }
+    return null;
+  }
+  async checkAuth(id) {
+    const doc = await this.get(id);
+    if (doc === null) {
+      throw new Error("no read access or doc does not exist");
+    }
+    const tableName = this.tableName(id);
+    if (tableName === null) {
+      return;
+    }
+    if (!await this.modifyPredicate(tableName, doc)) {
+      throw new Error("write access not allowed");
+    }
+  }
+  async patch(id, value) {
+    await this.checkAuth(id);
+    return await this.db.patch(id, value);
+  }
+  async replace(id, value) {
+    await this.checkAuth(id);
+    return await this.db.replace(id, value);
+  }
+  async delete(id) {
+    await this.checkAuth(id);
+    return await this.db.delete(id);
+  }
+  get(id) {
+    return this.reader.get(id);
+  }
+  query(tableName) {
+    return this.reader.query(tableName);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RowLevelSecurity
+});

package/esm/server/relationships.js

@@ -0,0 +1,41 @@
+"use strict";
+import { ConvexError } from "convex/values";
+export async function asyncMap(list, asyncTransform) {
+  const promises = [];
+  for (const item of list) {
+    promises.push(asyncTransform(item));
+  }
+  return Promise.all(promises);
+}
+export async function getAll(db, ids) {
+  return pruneNull(await asyncMap(ids, db.get));
+}
+export async function getAllWithNulls(db, ids) {
+  return asyncMap(ids, db.get);
+}
+export async function getOneFrom(db, table, field, value) {
+  const ret = await db.query(table).withIndex("by_" + field, (q) => q.eq(field, value)).unique();
+  if (ret === null) {
+    throw new ConvexError(
+      `Can't find a document in ${table} with field ${field} equal to ${value}`
+    );
+  }
+  return ret;
+}
+export async function getOneOrNullFrom(db, table, field, value) {
+  return db.query(table).withIndex("by_" + field, (q) => q.eq(field, value)).unique();
+}
+export async function getManyFrom(db, table, field, value) {
+  return db.query(table).withIndex("by_" + field, (q) => q.eq(field, value)).collect();
+}
+export async function getManyVia(db, table, toField, fromField, value) {
+  return pruneNull(
+    await asyncMap(
+      await getManyFrom(db, table, fromField, value),
+      (link) => db.get(link[toField])
+    )
+  );
+}
+export function pruneNull(list) {
+  return list.filter((i) => i !== null);
+}

package/esm/server/rowLevelSecurity.js

@@ -0,0 +1,247 @@
+"use strict";
+export const RowLevelSecurity = (rules) => {
+  const withMutationRLS = (f) => {
+    return (ctx, ...args) => {
+      const wrappedDb = new WrapWriter(ctx, ctx.db, rules);
+      return f({ ...ctx, db: wrappedDb }, ...args);
+    };
+  };
+  const withQueryRLS = (f) => {
+    return (ctx, ...args) => {
+      const wrappedDb = new WrapReader(ctx, ctx.db, rules);
+      return f({ ...ctx, db: wrappedDb }, ...args);
+    };
+  };
+  return {
+    withMutationRLS,
+    withQueryRLS
+  };
+};
+async function asyncFilter(arr, predicate) {
+  const results = await Promise.all(arr.map(predicate));
+  return arr.filter((_v, index) => results[index]);
+}
+class WrapQuery {
+  q;
+  p;
+  iterator;
+  constructor(q, p) {
+    this.q = q;
+    this.p = p;
+  }
+  filter(predicate) {
+    return new WrapQuery(this.q.filter(predicate), this.p);
+  }
+  order(order) {
+    return new WrapQuery(this.q.order(order), this.p);
+  }
+  async paginate(paginationOpts) {
+    const result = await this.q.paginate(paginationOpts);
+    result.page = await asyncFilter(result.page, this.p);
+    return result;
+  }
+  async collect() {
+    const results = await this.q.collect();
+    return await asyncFilter(results, this.p);
+  }
+  async take(n) {
+    const results = [];
+    for await (const result of this) {
+      results.push(result);
+      if (results.length >= n) {
+        break;
+      }
+    }
+    return results;
+  }
+  async first() {
+    for await (const result of this) {
+      return result;
+    }
+    return null;
+  }
+  async unique() {
+    let uniqueResult = null;
+    for await (const result of this) {
+      if (uniqueResult === null) {
+        uniqueResult = result;
+      } else {
+        throw new Error("not unique");
+      }
+    }
+    return uniqueResult;
+  }
+  [Symbol.asyncIterator]() {
+    this.iterator = this.q[Symbol.asyncIterator]();
+    return this;
+  }
+  async next() {
+    for (; ; ) {
+      const { value, done } = await this.iterator.next();
+      if (value && await this.p(value)) {
+        return { value, done };
+      }
+      if (done) {
+        return { value: null, done: true };
+      }
+    }
+  }
+  return() {
+    return this.iterator.return();
+  }
+}
+class WrapQueryInitializer {
+  q;
+  p;
+  constructor(q, p) {
+    this.q = q;
+    this.p = p;
+  }
+  fullTableScan() {
+    return new WrapQuery(this.q.fullTableScan(), this.p);
+  }
+  withIndex(indexName, indexRange) {
+    return new WrapQuery(this.q.withIndex(indexName, indexRange), this.p);
+  }
+  withSearchIndex(indexName, searchFilter) {
+    return new WrapQuery(
+      this.q.withSearchIndex(indexName, searchFilter),
+      this.p
+    );
+  }
+  filter(predicate) {
+    return this.fullTableScan().filter(predicate);
+  }
+  order(order) {
+    return this.fullTableScan().order(order);
+  }
+  async paginate(paginationOpts) {
+    return this.fullTableScan().paginate(paginationOpts);
+  }
+  collect() {
+    return this.fullTableScan().collect();
+  }
+  take(n) {
+    return this.fullTableScan().take(n);
+  }
+  first() {
+    return this.fullTableScan().first();
+  }
+  unique() {
+    return this.fullTableScan().unique();
+  }
+  [Symbol.asyncIterator]() {
+    return this.fullTableScan()[Symbol.asyncIterator]();
+  }
+}
+class WrapReader {
+  ctx;
+  db;
+  rules;
+  constructor(ctx, db, rules) {
+    this.ctx = ctx;
+    this.db = db;
+    this.rules = rules;
+  }
+  normalizeId(tableName, id) {
+    return this.db.normalizeId(tableName, id);
+  }
+  tableName(id) {
+    for (const tableName of Object.keys(this.rules)) {
+      if (this.db.normalizeId(tableName, id)) {
+        return tableName;
+      }
+    }
+    return null;
+  }
+  async predicate(tableName, doc) {
+    if (!this.rules[tableName]?.read) {
+      return true;
+    }
+    return await this.rules[tableName].read(this.ctx, doc);
+  }
+  async get(id) {
+    const doc = await this.db.get(id);
+    if (doc) {
+      const tableName = this.tableName(id);
+      if (tableName && !await this.predicate(tableName, doc)) {
+        return null;
+      }
+      return doc;
+    }
+    return null;
+  }
+  query(tableName) {
+    return new WrapQueryInitializer(
+      this.db.query(tableName),
+      async (d) => await this.predicate(tableName, d)
+    );
+  }
+}
+class WrapWriter {
+  ctx;
+  db;
+  reader;
+  rules;
+  async modifyPredicate(tableName, doc) {
+    if (!this.rules[tableName]?.modify) {
+      return true;
+    }
+    return await this.rules[tableName].modify(this.ctx, doc);
+  }
+  constructor(ctx, db, rules) {
+    this.ctx = ctx;
+    this.db = db;
+    this.reader = new WrapReader(ctx, db, rules);
+    this.rules = rules;
+  }
+  normalizeId(tableName, id) {
+    return this.db.normalizeId(tableName, id);
+  }
+  async insert(table, value) {
+    const rules = this.rules[table];
+    if (rules?.insert && !await rules.insert(this.ctx, value)) {
+      throw new Error("insert access not allowed");
+    }
+    return await this.db.insert(table, value);
+  }
+  tableName(id) {
+    for (const tableName of Object.keys(this.rules)) {
+      if (this.db.normalizeId(tableName, id)) {
+        return tableName;
+      }
+    }
+    return null;
+  }
+  async checkAuth(id) {
+    const doc = await this.get(id);
+    if (doc === null) {
+      throw new Error("no read access or doc does not exist");
+    }
+    const tableName = this.tableName(id);
+    if (tableName === null) {
+      return;
+    }
+    if (!await this.modifyPredicate(tableName, doc)) {
+      throw new Error("write access not allowed");
+    }
+  }
+  async patch(id, value) {
+    await this.checkAuth(id);
+    return await this.db.patch(id, value);
+  }
+  async replace(id, value) {
+    await this.checkAuth(id);
+    return await this.db.replace(id, value);
+  }
+  async delete(id) {
+    await this.checkAuth(id);
+    return await this.db.delete(id);
+  }
+  get(id) {
+    return this.reader.get(id);
+  }
+  query(tableName) {
+    return this.reader.query(tableName);
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "convex-helpers",
+  "version": "0.0.1",
+  "description": "A collection of useful code to complement the official convex package.",
+  "exports": {
+    "./server": {
+      "types": "./server/",
+      "import": "./esm/server/",
+      "require": "./cjs/server/"
+    }
+  },
+  "files": [
+    "esm",
+    "cjs",
+    "server"
+  ],
+  "scripts": {
+    "build": "npm run clean && npm run build:esm 2>/dev/null && npm run build:cjs 2>/dev/null",
+    "clean": "rm -rf cjs esm",
+    "build:esm": "esbuild $(find server -iname \"*.ts\") --outdir=esm --outbase=. --loader:.ts=ts --platform=node --bundle=false",
+    "build:cjs": "esbuild $(find server -iname \"*.ts\") --outdir=cjs --outbase=. --loader:.ts=ts --platform=node --bundle=false --format=cjs && echo '{\"type\": \"commonjs\"}' > cjs/package.json",
+    "watch": "chokidar 'server/**/*.tsx' 'server/**/*.ts' 'package.json' -c 'npm run build:esm' --initial",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/get-convex/convex-helpers.git"
+  },
+  "keywords": [
+    "convex",
+    "database",
+    "react"
+  ],
+  "author": "Ian Macartney <ian@convex.dev>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/get-convex/convex-helpers/issues"
+  },
+  "homepage": "https://github.com/get-convex/convex-helpers#readme",
+  "peerDependencies": {
+    "convex": "1.0 - 1.5"
+  },
+  "devDependencies": {
+    "chokidar-cli": "^3.0.0",
+    "typescript": "^5.2.2"
+  }
+}

package/server/relationships.ts

@@ -0,0 +1,272 @@
+import {
+  FieldTypeFromFieldPath,
+  Indexes,
+  NamedTableInfo,
+  TableNamesInDataModel,
+  GenericDataModel,
+  GenericDatabaseReader,
+  DocumentByName,
+} from "convex/server";
+import { ConvexError, GenericId } from "convex/values";
+
+/**
+ * asyncMap returns the results of applying an async function over an list.
+ *
+ * @param list - Iterable object of items, e.g. an Array, Set, Object.keys
+ * @param asyncTransform
+ * @returns
+ */
+export async function asyncMap<FromType, ToType>(
+  list: Iterable<FromType>,
+  asyncTransform: (item: FromType) => Promise<ToType>
+): Promise<ToType[]> {
+  const promises: Promise<ToType>[] = [];
+  for (const item of list) {
+    promises.push(asyncTransform(item));
+  }
+  return Promise.all(promises);
+}
+
+/**
+ * getAll returns a list of Documents corresponding to the `Id`s passed in.
+ * @param db A database object, usually passed from a mutation or query ctx.
+ * @param ids An list (or other iterable) of Ids pointing to a table.
+ * @returns The Documents referenced by the Ids, in order.
+ */
+export async function getAll<
+  DataModel extends GenericDataModel,
+  TableName extends string = TableNamesInDataModel<DataModel>
+>(
+  db: GenericDatabaseReader<DataModel>,
+  ids: GenericId<TableName>[]
+): Promise<(DocumentByName<DataModel, TableName> | null)[]> {
+  return pruneNull(await asyncMap(ids, db.get));
+}
+
+/**
+ * getAllOrNone returns a list of Documents or null for the `Id`s passed in.
+ * @param db A database object, usually passed from a mutation or query ctx.
+ * @param ids An list (or other iterable) of Ids pointing to a table.
+ * @returns The Documents referenced by the Ids, in order. `null` if not found.
+ */
+export async function getAllWithNulls<
+  DataModel extends GenericDataModel,
+  TableName extends string = TableNamesInDataModel<DataModel>
+>(
+  db: GenericDatabaseReader<DataModel>,
+  ids: GenericId<TableName>[]
+): Promise<(DocumentByName<DataModel, TableName> | null)[]> {
+  return asyncMap(ids, db.get);
+}
+
+// `FieldPath`s that have a `"FieldPath"` index on [`FieldPath`, ...]
+// type LookupFieldPaths<TableName extends TableNames> =   {[FieldPath in DataModel[TableName]["fieldPaths"]]: FieldPath extends keyof DataModel[TableName]["indexes"]? Indexes<NamedTableInfo<DataModel, TableName>>[FieldPath][0] extends FieldPath ? FieldPath : never: never}[DataModel[TableName]["fieldPaths"]]
+
+// `FieldPath`s that have a `"by_${FieldPath}""` index on [`FieldPath`, ...]
+type LookupFieldPaths<
+  DataModel extends GenericDataModel,
+  TableName extends string = TableNamesInDataModel<DataModel>
+> = {
+  [FieldPath in DataModel[TableName]["fieldPaths"]]: `by_${FieldPath}` extends keyof DataModel[TableName]["indexes"]
+    ? Indexes<
+        NamedTableInfo<DataModel, TableName>
+      >[`by_${FieldPath}`][0] extends FieldPath
+      ? FieldPath
+      : never
+    : never;
+}[DataModel[TableName]["fieldPaths"]];
+
+type TablesWithLookups<
+  DataModel extends GenericDataModel,
+  TableNames extends string = TableNamesInDataModel<DataModel>
+> = {
+  [TableName in TableNames]: LookupFieldPaths<
+    DataModel,
+    TableName
+  > extends never
+    ? never
+    : TableName;
+}[TableNames];
+
+/**
+ * Get a document that references a value with a field indexed `by_${field}`
+ *
+ * Useful for fetching a document with a one-to-one relationship via backref.
+ * @param db DatabaseReader, passed in from the function ctx
+ * @param table The table to fetch the target document from.
+ * @param field The field on that table that should match the specified value.
+ * @param value The value to look up the document by, usually an ID.
+ * @returns The document matching the value. Throws if not found.
+ */
+export async function getOneFrom<
+  DataModel extends GenericDataModel,
+  TableName extends TablesWithLookups<DataModel>,
+  Field extends LookupFieldPaths<DataModel, TableName>
+>(
+  db: GenericDatabaseReader<DataModel>,
+  table: TableName,
+  field: Field,
+  value: FieldTypeFromFieldPath<DocumentByName<DataModel, TableName>, Field>
+): Promise<DocumentByName<DataModel, TableName>> {
+  const ret = await db
+    .query(table)
+    .withIndex("by_" + field, (q) => q.eq(field, value as any))
+    .unique();
+  if (ret === null) {
+    throw new ConvexError(
+      `Can't find a document in ${table} with field ${field} equal to ${value}`
+    );
+  }
+  return ret;
+}
+
+/**
+ * Get a document that references a value with a field indexed `by_${field}`
+ *
+ * Useful for fetching a document with a one-to-one relationship via backref.
+ * @param db DatabaseReader, passed in from the function ctx
+ * @param table The table to fetch the target document from.
+ * @param field The field on that table that should match the specified value.
+ * @param value The value to look up the document by, usually an ID.
+ * @returns The document matching the value, or null if none found.
+ */
+export async function getOneOrNullFrom<
+  DataModel extends GenericDataModel,
+  TableName extends TablesWithLookups<DataModel>,
+  Field extends LookupFieldPaths<DataModel, TableName>
+>(
+  db: GenericDatabaseReader<DataModel>,
+  table: TableName,
+  field: Field,
+  value: FieldTypeFromFieldPath<DocumentByName<DataModel, TableName>, Field>
+): Promise<DocumentByName<DataModel, TableName> | null> {
+  return db
+    .query(table)
+    .withIndex("by_" + field, (q) => q.eq(field, value as any))
+    .unique();
+}
+
+/**
+ * Get a list of documents matching a value with a field indexed `by_${field}`.
+ *
+ * Useful for fetching many documents related to a given value via backrefs.
+ * @param db DatabaseReader, passed in from the function ctx
+ * @param table The table to fetch the target document from.
+ * @param field The field on that table that should match the specified value.
+ * @param value The value to look up the document by, usually an ID.
+ * @returns The documents matching the value, if any.
+ */
+export async function getManyFrom<
+  DataModel extends GenericDataModel,
+  TableName extends TablesWithLookups<DataModel>,
+  Field extends LookupFieldPaths<DataModel, TableName>
+>(
+  db: GenericDatabaseReader<DataModel>,
+  table: TableName,
+  field: Field,
+  value: FieldTypeFromFieldPath<DocumentByName<DataModel, TableName>, Field>
+): Promise<DocumentByName<DataModel, TableName>[]> {
+  return db
+    .query(table)
+    .withIndex("by_" + field, (q) => q.eq(field, value as any))
+    .collect();
+}
+
+// File paths to fields that are IDs, excluding "_id".
+type IdFilePaths<
+  DataModel extends GenericDataModel,
+  InTableName extends TablesWithLookups<DataModel>,
+  TableName extends TableNamesInDataModel<DataModel>
+> = {
+  [FieldName in DataModel[InTableName]["fieldPaths"]]: FieldTypeFromFieldPath<
+    DocumentByName<DataModel, InTableName>,
+    FieldName
+  > extends GenericId<TableName>
+    ? FieldName extends "_id"
+      ? never
+      : FieldName
+    : never;
+}[DataModel[InTableName]["fieldPaths"]];
+
+// Whether a table has an ID field that isn't its sole lookup field.
+// These can operate as join tables, going from one table to another.
+// One field has an indexed field for lookup, and another has the ID to get.
+type LookupAndIdFilePaths<
+  DataModel extends GenericDataModel,
+  TableName extends TablesWithLookups<DataModel>
+> = {
+  [FieldPath in IdFilePaths<
+    DataModel,
+    TableName,
+    TableNamesInDataModel<DataModel>
+  >]: LookupFieldPaths<DataModel, TableName> extends FieldPath ? never : true;
+}[IdFilePaths<DataModel, TableName, TableNamesInDataModel<DataModel>>];
+
+// The table names that  match LookupAndIdFields.
+// These are the possible "join" or "edge" or "relationship" tables.
+type JoinTables<DataModel extends GenericDataModel> = {
+  [TableName in TablesWithLookups<DataModel>]: LookupAndIdFilePaths<
+    DataModel,
+    TableName
+  > extends never
+    ? never
+    : TableName;
+}[TablesWithLookups<DataModel>];
+
+// many-to-many via lookup table
+/**
+ * Get related documents by using a join table.
+ *
+ * It will find all join table entries matching a value, then look up all the
+ * documents pointed to by the join table entries. Useful for many-to-many
+ * relationships.
+ * @param db DatabaseReader, passed in from the function ctx
+ * @param table The table to fetch the target document from.
+ * @param toField The ID field on the table pointing at target documents.
+ * @param fromField The field on the table to compare to the value.
+ * @param value The value to match the fromField on the table, usually an ID.
+ * @returns The documents targeted by matching documents in the table, if any.
+ */
+export async function getManyVia<
+  DataModel extends GenericDataModel,
+  JoinTableName extends JoinTables<DataModel>,
+  ToField extends IdFilePaths<
+    DataModel,
+    JoinTableName,
+    TableNamesInDataModel<DataModel>
+  >,
+  FromField extends Exclude<
+    LookupFieldPaths<DataModel, JoinTableName>,
+    ToField
+  >,
+  TargetTableName extends FieldTypeFromFieldPath<
+    DocumentByName<DataModel, JoinTableName>,
+    ToField
+  > extends GenericId<infer TargetTableName>
+    ? TargetTableName
+    : never
+>(
+  db: GenericDatabaseReader<DataModel>,
+  table: JoinTableName,
+  toField: ToField,
+  fromField: FromField,
+  value: FieldTypeFromFieldPath<
+    DocumentByName<DataModel, JoinTableName>,
+    FromField
+  >
+): Promise<DocumentByName<DataModel, TargetTableName>[]> {
+  return pruneNull(
+    await asyncMap(await getManyFrom(db, table, fromField, value), (link) =>
+      db.get((link as any)[toField])
+    )
+  );
+}
+
+/**
+ * Filters out null elements from an array.
+ * @param list List of elements that might be null.
+ * @returns List of elements with nulls removed.
+ */
+export function pruneNull<T>(list: (T | null)[]): T[] {
+  return list.filter((i) => i !== null) as T[];
+}

package/server/rowLevelSecurity.ts

@@ -0,0 +1,443 @@
+import {
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+  DocumentByInfo,
+  DocumentByName,
+  Expression,
+  FilterBuilder,
+  FunctionArgs,
+  GenericDataModel,
+  GenericTableInfo,
+  IndexRange,
+  IndexRangeBuilder,
+  Indexes,
+  GenericMutationCtx,
+  NamedIndex,
+  NamedSearchIndex,
+  NamedTableInfo,
+  OrderedQuery,
+  PaginationOptions,
+  PaginationResult,
+  Query,
+  GenericQueryCtx,
+  QueryInitializer,
+  SearchFilter,
+  SearchFilterBuilder,
+  SearchIndexes,
+  TableNamesInDataModel,
+  WithoutSystemFields,
+} from "convex/server";
+import { GenericId } from "convex/values";
+
+type Rule<Ctx, D> = (ctx: Ctx, doc: D) => Promise<boolean>;
+
+export type Rules<Ctx, DataModel extends GenericDataModel> = {
+  [T in TableNamesInDataModel<DataModel>]?: {
+    read?: Rule<Ctx, DocumentByName<DataModel, T>>;
+    modify?: Rule<Ctx, DocumentByName<DataModel, T>>;
+    insert?: Rule<Ctx, WithoutSystemFields<DocumentByName<DataModel, T>>>;
+  };
+};
+
+/**
+ * Apply row level security (RLS) to queries and mutations with the returned
+ * middleware functions.
+ *
+ * Example:
+ * ```
+ * // Defined in a common file so it can be used by all queries and mutations.
+ * import { Auth } from "convex/server";
+ * import { DataModel } from "./_generated/dataModel";
+ * import { DatabaseReader } from "./_generated/server";
+ * import { RowLevelSecurity } from "./rowLevelSecurity";
+ *
+ * export const {withMutationRLS} = RowLevelSecurity<{auth: Auth, db: DatabaseReader}, DataModel>(
+ *  {
+ *    cookies: {
+ *      read: async ({auth}, cookie) => !cookie.eaten,
+ *      modify: async ({auth, db}, cookie) => {
+ *        const user = await getUser(auth, db);
+ *        return user.isParent;  // only parents can reach the cookies.
+ *      },
+ *  }
+ * );
+ * // Mutation with row level security enabled.
+ * export const eatCookie = mutation(withMutationRLS(
+ *  async ({db}, {cookieId}) => {
+ *   // throws "does not exist" error if cookie is already eaten or doesn't exist.
+ *   // throws "write access" error if authorized user is not a parent.
+ *   await db.patch(cookieId, {eaten: true});
+ * }));
+ * ```
+ *
+ * Notes:
+ * * Rules may read any row in `db` -- rules do not apply recursively within the
+ *   rule functions themselves.
+ * * Tables with no rule default to full access.
+ * * Middleware functions like `withUser` can be composed with RowLevelSecurity
+ *   to cache fetches in `ctx`. e.g.
+ * ```
+ * const {withQueryRLS} = RowLevelSecurity<{user: Doc<"users">}, DataModel>(
+ *  {
+ *    cookies: async ({user}, cookie) => user.isParent,
+ *  }
+ * );
+ * export default query(withUser(withRLS(...)));
+ * ```
+ *
+ * @param rules - rule for each table, determining whether a row is accessible.
+ *  - "read" rule says whether a document should be visible.
+ *  - "modify" rule says whether to throw an error on `replace`, `patch`, and `delete`.
+ *  - "insert" rule says whether to throw an error on `insert`.
+ *
+ * @returns Functions `withQueryRLS` and `withMutationRLS` to be passed to
+ * `query` or `mutation` respectively.
+ *  For each row read, modified, or inserted, the security rules are applied.
+ */
+export const RowLevelSecurity = <RuleCtx, DataModel extends GenericDataModel>(
+  rules: Rules<RuleCtx, DataModel>
+) => {
+  const withMutationRLS = <
+    Ctx extends GenericMutationCtx<DataModel>,
+    Args extends ArgsArray,
+    Output
+  >(
+    f: Handler<Ctx, Args, Output>
+  ): Handler<Ctx, Args, Output> => {
+    return ((ctx: any, ...args: any[]) => {
+      const wrappedDb = new WrapWriter(ctx, ctx.db, rules);
+      return (f as any)({ ...ctx, db: wrappedDb }, ...args);
+    }) as Handler<Ctx, Args, Output>;
+  };
+  const withQueryRLS = <
+    Ctx extends GenericQueryCtx<DataModel>,
+    Args extends ArgsArray,
+    Output
+  >(
+    f: Handler<Ctx, Args, Output>
+  ): Handler<Ctx, Args, Output> => {
+    return ((ctx: any, ...args: any[]) => {
+      const wrappedDb = new WrapReader(ctx, ctx.db, rules);
+      return (f as any)({ ...ctx, db: wrappedDb }, ...args);
+    }) as Handler<Ctx, Args, Output>;
+  };
+  return {
+    withMutationRLS,
+    withQueryRLS,
+  };
+};
+
+type ArgsArray = [] | [FunctionArgs<any>];
+type Handler<Ctx, Args extends ArgsArray, Output> = (
+  ctx: Ctx,
+  ...args: Args
+) => Output;
+
+type AuthPredicate<T extends GenericTableInfo> = (
+  doc: DocumentByInfo<T>
+) => Promise<boolean>;
+
+async function asyncFilter<T>(
+  arr: T[],
+  predicate: (d: T) => Promise<boolean>
+): Promise<T[]> {
+  const results = await Promise.all(arr.map(predicate));
+  return arr.filter((_v, index) => results[index]);
+}
+
+class WrapQuery<T extends GenericTableInfo> implements Query<T> {
+  q: Query<T>;
+  p: AuthPredicate<T>;
+  iterator?: AsyncIterator<any>;
+  constructor(q: Query<T> | OrderedQuery<T>, p: AuthPredicate<T>) {
+    this.q = q as Query<T>;
+    this.p = p;
+  }
+  filter(predicate: (q: FilterBuilder<T>) => Expression<boolean>): this {
+    return new WrapQuery(this.q.filter(predicate), this.p) as this;
+  }
+  order(order: "asc" | "desc"): WrapQuery<T> {
+    return new WrapQuery(this.q.order(order), this.p);
+  }
+  async paginate(
+    paginationOpts: PaginationOptions
+  ): Promise<PaginationResult<DocumentByInfo<T>>> {
+    const result = await this.q.paginate(paginationOpts);
+    result.page = await asyncFilter(result.page, this.p);
+    return result;
+  }
+  async collect(): Promise<DocumentByInfo<T>[]> {
+    const results = await this.q.collect();
+    return await asyncFilter(results, this.p);
+  }
+  async take(n: number): Promise<DocumentByInfo<T>[]> {
+    const results = [];
+    for await (const result of this) {
+      results.push(result);
+      if (results.length >= n) {
+        break;
+      }
+    }
+    return results;
+  }
+  async first(): Promise<DocumentByInfo<T> | null> {
+    for await (const result of this) {
+      return result;
+    }
+    return null;
+  }
+  async unique(): Promise<DocumentByInfo<T> | null> {
+    let uniqueResult = null;
+    for await (const result of this) {
+      if (uniqueResult === null) {
+        uniqueResult = result;
+      } else {
+        throw new Error("not unique");
+      }
+    }
+    return uniqueResult;
+  }
+  [Symbol.asyncIterator](): AsyncIterator<DocumentByInfo<T>, any, undefined> {
+    this.iterator = this.q[Symbol.asyncIterator]();
+    return this;
+  }
+  async next(): Promise<IteratorResult<any>> {
+    for (;;) {
+      const { value, done } = await this.iterator!.next();
+      if (value && (await this.p(value))) {
+        return { value, done };
+      }
+      if (done) {
+        return { value: null, done: true };
+      }
+    }
+  }
+  return() {
+    return this.iterator!.return!();
+  }
+}
+
+class WrapQueryInitializer<T extends GenericTableInfo>
+  implements QueryInitializer<T>
+{
+  q: QueryInitializer<T>;
+  p: AuthPredicate<T>;
+  constructor(q: QueryInitializer<T>, p: AuthPredicate<T>) {
+    this.q = q;
+    this.p = p;
+  }
+  fullTableScan(): Query<T> {
+    return new WrapQuery(this.q.fullTableScan(), this.p);
+  }
+  withIndex<IndexName extends keyof Indexes<T>>(
+    indexName: IndexName,
+    indexRange?:
+      | ((
+          q: IndexRangeBuilder<DocumentByInfo<T>, NamedIndex<T, IndexName>, 0>
+        ) => IndexRange)
+      | undefined
+  ): Query<T> {
+    return new WrapQuery(this.q.withIndex(indexName, indexRange), this.p);
+  }
+  withSearchIndex<IndexName extends keyof SearchIndexes<T>>(
+    indexName: IndexName,
+    searchFilter: (
+      q: SearchFilterBuilder<DocumentByInfo<T>, NamedSearchIndex<T, IndexName>>
+    ) => SearchFilter
+  ): OrderedQuery<T> {
+    return new WrapQuery(
+      this.q.withSearchIndex(indexName, searchFilter),
+      this.p
+    );
+  }
+  filter(predicate: (q: FilterBuilder<T>) => Expression<boolean>): this {
+    return this.fullTableScan().filter(predicate) as this;
+  }
+  order(order: "asc" | "desc"): OrderedQuery<T> {
+    return this.fullTableScan().order(order);
+  }
+  async paginate(
+    paginationOpts: PaginationOptions
+  ): Promise<PaginationResult<DocumentByInfo<T>>> {
+    return this.fullTableScan().paginate(paginationOpts);
+  }
+  collect(): Promise<DocumentByInfo<T>[]> {
+    return this.fullTableScan().collect();
+  }
+  take(n: number): Promise<DocumentByInfo<T>[]> {
+    return this.fullTableScan().take(n);
+  }
+  first(): Promise<DocumentByInfo<T> | null> {
+    return this.fullTableScan().first();
+  }
+  unique(): Promise<DocumentByInfo<T> | null> {
+    return this.fullTableScan().unique();
+  }
+  [Symbol.asyncIterator](): AsyncIterator<DocumentByInfo<T>, any, undefined> {
+    return this.fullTableScan()[Symbol.asyncIterator]();
+  }
+}
+
+class WrapReader<Ctx, DataModel extends GenericDataModel>
+  implements GenericDatabaseReader<DataModel>
+{
+  ctx: Ctx;
+  db: GenericDatabaseReader<DataModel>;
+  rules: Rules<Ctx, DataModel>;
+
+  constructor(
+    ctx: Ctx,
+    db: GenericDatabaseReader<DataModel>,
+    rules: Rules<Ctx, DataModel>
+  ) {
+    this.ctx = ctx;
+    this.db = db;
+    this.rules = rules;
+  }
+
+  normalizeId<TableName extends TableNamesInDataModel<DataModel>>(
+    tableName: TableName,
+    id: string
+  ): GenericId<TableName> | null {
+    return this.db.normalizeId(tableName, id);
+  }
+
+  tableName<TableName extends string>(
+    id: GenericId<TableName>
+  ): TableName | null {
+    for (const tableName of Object.keys(this.rules)) {
+      if (this.db.normalizeId(tableName, id)) {
+        return tableName as TableName;
+      }
+    }
+    return null;
+  }
+
+  async predicate<T extends GenericTableInfo>(
+    tableName: string,
+    doc: DocumentByInfo<T>
+  ): Promise<boolean> {
+    if (!this.rules[tableName]?.read) {
+      return true;
+    }
+    return await this.rules[tableName]!.read!(this.ctx, doc);
+  }
+
+  async get<TableName extends string>(id: GenericId<TableName>): Promise<any> {
+    const doc = await this.db.get(id);
+    if (doc) {
+      const tableName = this.tableName(id);
+      if (tableName && !(await this.predicate(tableName, doc))) {
+        return null;
+      }
+      return doc;
+    }
+    return null;
+  }
+
+  query<TableName extends string>(
+    tableName: TableName
+  ): QueryInitializer<NamedTableInfo<DataModel, TableName>> {
+    return new WrapQueryInitializer(
+      this.db.query(tableName),
+      async (d) => await this.predicate(tableName, d)
+    );
+  }
+}
+
+class WrapWriter<Ctx, DataModel extends GenericDataModel>
+  implements GenericDatabaseWriter<DataModel>
+{
+  ctx: Ctx;
+  db: GenericDatabaseWriter<DataModel>;
+  reader: GenericDatabaseReader<DataModel>;
+  rules: Rules<Ctx, DataModel>;
+
+  async modifyPredicate<T extends GenericTableInfo>(
+    tableName: string,
+    doc: DocumentByInfo<T>
+  ): Promise<boolean> {
+    if (!this.rules[tableName]?.modify) {
+      return true;
+    }
+    return await this.rules[tableName]!.modify!(this.ctx, doc);
+  }
+
+  constructor(
+    ctx: Ctx,
+    db: GenericDatabaseWriter<DataModel>,
+    rules: Rules<Ctx, DataModel>
+  ) {
+    this.ctx = ctx;
+    this.db = db;
+    this.reader = new WrapReader(ctx, db, rules);
+    this.rules = rules;
+  }
+  normalizeId<TableName extends TableNamesInDataModel<DataModel>>(
+    tableName: TableName,
+    id: string
+  ): GenericId<TableName> | null {
+    return this.db.normalizeId(tableName, id);
+  }
+  async insert<TableName extends string>(
+    table: TableName,
+    value: any
+  ): Promise<any> {
+    const rules = this.rules[table];
+    if (rules?.insert && !(await rules.insert(this.ctx, value))) {
+      throw new Error("insert access not allowed");
+    }
+    return await this.db.insert(table, value);
+  }
+  tableName<TableName extends string>(
+    id: GenericId<TableName>
+  ): TableName | null {
+    for (const tableName of Object.keys(this.rules)) {
+      if (this.db.normalizeId(tableName, id)) {
+        return tableName as TableName;
+      }
+    }
+    return null;
+  }
+  async checkAuth<TableName extends string>(id: GenericId<TableName>) {
+    // Note all writes already do a `db.get` internally, so this isn't
+    // an extra read; it's just populating the cache earlier.
+    // Since we call `this.get`, read access controls apply and this may return
+    // null even if the document exists.
+    const doc = await this.get(id);
+    if (doc === null) {
+      throw new Error("no read access or doc does not exist");
+    }
+    const tableName = this.tableName(id);
+    if (tableName === null) {
+      return;
+    }
+    if (!(await this.modifyPredicate(tableName, doc))) {
+      throw new Error("write access not allowed");
+    }
+  }
+  async patch<TableName extends string>(
+    id: GenericId<TableName>,
+    value: Partial<any>
+  ): Promise<void> {
+    await this.checkAuth(id);
+    return await this.db.patch(id, value);
+  }
+  async replace<TableName extends string>(
+    id: GenericId<TableName>,
+    value: any
+  ): Promise<void> {
+    await this.checkAuth(id);
+    return await this.db.replace(id, value);
+  }
+  async delete(id: GenericId<string>): Promise<void> {
+    await this.checkAuth(id);
+    return await this.db.delete(id);
+  }
+  get<TableName extends string>(id: GenericId<TableName>): Promise<any> {
+    return this.reader.get(id);
+  }
+  query<TableName extends string>(tableName: TableName): QueryInitializer<any> {
+    return this.reader.query(tableName);
+  }
+}