convex-ents 0.8.1 → 0.9.0

package/dist/{index-uXk5iZ86.d.ts → index-nOBiMg01.d.ts}

@@ -144,37 +144,167 @@ interface PromiseEnts<EntsDataModel extends GenericEntsDataModel, Table extends
 }
 interface PromiseEntsOrNulls<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<(Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel> | null)[]> {
 }
-interface PromiseEdgeEntsOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEntsOrNull<EntsDataModel, Table> {
+interface PromiseEdgeOrderedEntsOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEntsOrNull<EntsDataModel, Table> {
+    /**
+     * Paginate the ents on the other end of the edge.
+     * Results are ordered by edge's `_creationTime`.
+     */
+    paginate(paginationOpts: PaginationOptions): PromisePaginationResultOrNull<EntsDataModel, Table>;
+    /**
+     * Take the first `n` ents on the other end of the edge
+     * ordered by edge's `_creationTime`.
+     */
+    take(n: number): PromiseEntsOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the first ent on the other end of the edge
+     * ordered by edge's `_creationTime`, or `null`.
+     */
+    first(): PromiseEntOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the only ent on the other end of the edge,
+     * `null` if there are none, or throws if there are more than one.
+     */
+    unique(): PromiseEntOrNull<EntsDataModel, Table>;
+}
+interface PromiseEdgeEntsOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEdgeOrderedEntsOrNull<EntsDataModel, Table> {
     /**
      * Returns whether there is an ent with given ID on the other side
      * the edge. Returns null if chained to a null result.
      * @param id The ID of the ent on the other end of the edge
      */
     has(id: GenericId<Table>): Promise<boolean | null>;
+    /**
+     * Query the ents on the other end of the edge
+     * ordered by edge's `_creationTime`.
+     */
+    order(order: "asc" | "desc", indexName?: IndexNames<NamedTableInfo<EntsDataModel, Table>>): PromiseEdgeOrderedEntsOrNull<EntsDataModel, Table>;
 }
-interface PromiseEdgeEntsWriterOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEntsWriterOrNull<EntsDataModel, Table> {
+interface PromiseEdgeOrderedEntsWriterOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEntsWriterOrNull<EntsDataModel, Table> {
+    /**
+     * Paginate the ents on the other end of the edge.
+     * Results are ordered by edge's `_creationTime`.
+     */
+    paginate(paginationOpts: PaginationOptions): PromisePaginationResultWriterOrNull<EntsDataModel, Table>;
+    /**
+     * Take the first `n` ents on the other end of the edge
+     * ordered by edge's `_creationTime`.
+     */
+    take(n: number): PromiseEntsWriterOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the first ent on the other end of the edge
+     * ordered by edge's `_creationTime`, or `null`.
+     */
+    first(): PromiseEntWriterOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the only ent on the other end of the edge,
+     * `null` if there are none, or throws if there are more than one.
+     */
+    unique(): PromiseEntWriterOrNull<EntsDataModel, Table>;
+}
+interface PromiseEdgeEntsWriterOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEdgeOrderedEntsWriterOrNull<EntsDataModel, Table> {
     /**
      * Returns whether there is an ent with given ID on the other side
      * the edge. Returns null if chained to a null result.
      * @param id The ID of the ent on the other end of the edge
      */
     has(id: GenericId<Table>): Promise<boolean | null>;
+    /**
+     * Query the ents on the other end of the edge
+     * ordered by edge's `_creationTime`.
+     */
+    order(order: "asc" | "desc", indexName?: IndexNames<NamedTableInfo<EntsDataModel, Table>>): PromiseEdgeOrderedEntsWriterOrNull<EntsDataModel, Table>;
 }
-interface PromiseEdgeEnts<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEnts<EntsDataModel, Table> {
+interface PromiseEdgeOrderedEnts<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEnts<EntsDataModel, Table> {
+    /**
+     * Paginate the ents on the other end of the edge.
+     * Results are ordered by edge's `_creationTime`.
+     */
+    paginate(paginationOpts: PaginationOptions): PromisePaginationResult<EntsDataModel, Table>;
+    /**
+     * Take the first `n` ents on the other end of the edge
+     * ordered by edge's `_creationTime`.
+     */
+    take(n: number): PromiseEnts<EntsDataModel, Table>;
+    /**
+     * Returns the first ent on the other end of the edge
+     * ordered by edge's `_creationTime`, or `null`.
+     */
+    first(): PromiseEntOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the first ent on the other end of the edge
+     * ordered by edge's `_creationTime`, or throws if there
+     * are no ents on the other end of the edge.
+     */
+    firstX(): PromiseEnt<EntsDataModel, Table>;
+    /**
+     * Returns the only ent on the other end of the edge,
+     * `null` if there are none, or throws if there are more than one.
+     */
+    unique(): PromiseEntOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the only ent on the other end of the edge,
+     * or throws if there are none or more than one.
+     */
+    uniqueX(): PromiseEnt<EntsDataModel, Table>;
+}
+interface PromiseEdgeEnts<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEdgeOrderedEnts<EntsDataModel, Table> {
     /**
      * Returns whether there is an ent with given ID on the other side
      * the edge.
      * @param id The ID of the ent on the other end of the edge
      */
     has(id: GenericId<Table>): Promise<boolean>;
+    /**
+     * Query the ents on the other end of the edge
+     * ordered by edge's `_creationTime`.
+     */
+    order(order: "asc" | "desc", indexName?: IndexNames<NamedTableInfo<EntsDataModel, Table>>): PromiseEdgeOrderedEnts<EntsDataModel, Table>;
+}
+interface PromiseEdgeOrderedEntsWriter<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEntsWriter<EntsDataModel, Table> {
+    /**
+     * Paginate the ents on the other end of the edge.
+     * Results are ordered by edge's `_creationTime`.
+     */
+    paginate(paginationOpts: PaginationOptions): PromisePaginationResultWriter<EntsDataModel, Table>;
+    /**
+     * Take the first `n` ents on the other end of the edge
+     * ordered by edge's `_creationTime`.
+     */
+    take(n: number): PromiseEntsWriter<EntsDataModel, Table>;
+    /**
+     * Returns the first ent on the other end of the edge
+     * ordered by edge's `_creationTime`, or `null`.
+     */
+    first(): PromiseEntWriterOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the first ent on the other end of the edge
+     * ordered by edge's `_creationTime`, or throws if there
+     * are no ents on the other end of the edge.
+     */
+    firstX(): PromiseEntWriter<EntsDataModel, Table>;
+    /**
+     * Returns the only ent on the other end of the edge,
+     * `null` if there are none, or throws if there are more than one.
+     */
+    unique(): PromiseEntWriterOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the only ent on the other end of the edge,
+     * or throws if there are none or more than one.
+     */
+    uniqueX(): PromiseEntWriter<EntsDataModel, Table>;
 }
-interface PromiseEdgeEntsWriter<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEntsWriter<EntsDataModel, Table> {
+interface PromiseEdgeEntsWriter<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEdgeOrderedEntsWriter<EntsDataModel, Table> {
     /**
      * Returns whether there is an ent with given ID on the other side
      * the edge.
      * @param id The ID of the ent on the other end of the edge
      */
     has(id: GenericId<Table>): Promise<boolean>;
+    /**
+     * Query the ents on the other end of the edge
+     * ordered by edge's `_creationTime`.
+     */
+    order(order: "asc" | "desc", indexName?: IndexNames<NamedTableInfo<EntsDataModel, Table>>): PromiseEdgeOrderedEntsWriter<EntsDataModel, Table>;
 }
 interface PromiseEntOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel> | null> {
     edge<Edge extends keyof EntsDataModel[Table]["edges"]>(edge: Edge): PromiseEdgeOrNull<EntsDataModel, Table, Edge>;
@@ -244,6 +374,10 @@ interface PromiseEntsWriter<EntsDataModel extends GenericEntsDataModel, Table ex
     firstX(): PromiseEntWriter<EntsDataModel, Table>;
     uniqueX(): PromiseEntWriter<EntsDataModel, Table>;
 }
+interface PromisePaginationResultWriterOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<PaginationResult<EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>> | null> {
+    docs(): Promise<PaginationResult<DocumentByName<EntsDataModel, Table>> | null>;
+    map<TOutput>(callbackFn: (value: EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>, index: number, array: EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[]) => Promise<TOutput> | TOutput): Promise<PaginationResult<TOutput> | null>;
+}
 interface PromisePaginationResultWriter<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<PaginationResult<EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>>> {
     docs(): Promise<PaginationResult<DocumentByName<EntsDataModel, Table>>>;
     map<TOutput>(callbackFn: (value: EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>, index: number, array: EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[]) => Promise<TOutput> | TOutput): Promise<PaginationResult<TOutput>>;
@@ -414,4 +548,4 @@ declare function getWriteRule(entDefinitions: GenericEntsDataModel, table: strin
 declare function getEdgeDefinitions<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>>(entDefinitions: EntsDataModel, table: Table): Record<keyof EntsDataModel[Table]["edges"], EdgeConfig>;
 declare function getDeletionConfig<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>>(entDefinitions: EntsDataModel, table: Table): DeletionConfig | undefined;
 
-export { getWriteRule as $, entsTableFactory as A, type EntsTable as B, type EntsTableWriter as C, type Ent as D, type EdgeChanges as E, type PromiseEdge as F, type GenericEnt as G, type PromiseEdgeOrThrow as H, type PromiseEdgeWriter as I, type PromiseEdgeWriterOrThrow as J, type PromiseEdgeWriterOrNull as K, type PromiseOrderedQueryWriter as L, type PromiseQueryWriter as M, type PromiseEntsWriter as N, type PromisePaginationResultWriter as O, type PromiseOrderedQueryOrNull as P, type PromiseTableWriter as Q, type PromiseEntWriterOrNull as R, type PromiseEntWriter as S, type GenericEntWriter as T, type PromiseEntId as U, type EntQueryCtx as V, WriterImplBase as W, type EntMutationCtx as X, type DocRetriever as Y, addEntRules as Z, getReadRule as _, type WithEdgeInserts as a, getEdgeDefinitions as a0, getDeletionConfig as a1, type WithEdges as b, type WithEdgePatches as c, type PromiseOrderedQueryWriterOrNull as d, type PromiseQueryOrNull as e, type PromiseQueryWriterOrNull as f, type PromiseTableBase as g, type PromiseTable as h, type PromiseOrderedQueryBase as i, type PromiseOrderedQuery as j, type PromiseQuery as k, type PromisePaginationResultOrNull as l, type PromisePaginationResult as m, type PromiseEntsOrNull as n, type PromiseEntsWriterOrNull as o, type PromiseEnts as p, type PromiseEntsOrNulls as q, type PromiseEdgeEntsOrNull as r, type PromiseEdgeEntsWriterOrNull as s, type PromiseEdgeEnts as t, type PromiseEdgeEntsWriter as u, type PromiseEntOrNull as v, type PromiseEnt as w, type PromiseArrayOrNull as x, type PromiseArray as y, entWrapper as z };
+export { type EntQueryCtx as $, type PromiseEnt as A, type PromiseArrayOrNull as B, type PromiseArray as C, entWrapper as D, type EdgeChanges as E, entsTableFactory as F, type EntsTable as G, type EntsTableWriter as H, type Ent as I, type GenericEnt as J, type PromiseEdge as K, type PromiseEdgeOrThrow as L, type PromiseEdgeWriter as M, type PromiseEdgeWriterOrThrow as N, type PromiseEdgeWriterOrNull as O, type PromiseOrderedQueryOrNull as P, type PromiseOrderedQueryWriter as Q, type PromiseQueryWriter as R, type PromiseEntsWriter as S, type PromisePaginationResultWriterOrNull as T, type PromisePaginationResultWriter as U, type PromiseTableWriter as V, WriterImplBase as W, type PromiseEntWriterOrNull as X, type PromiseEntWriter as Y, type GenericEntWriter as Z, type PromiseEntId as _, type WithEdgeInserts as a, type EntMutationCtx as a0, type DocRetriever as a1, addEntRules as a2, getReadRule as a3, getWriteRule as a4, getEdgeDefinitions as a5, getDeletionConfig as a6, type WithEdges as b, type WithEdgePatches as c, type PromiseOrderedQueryWriterOrNull as d, type PromiseQueryOrNull as e, type PromiseQueryWriterOrNull as f, type PromiseTableBase as g, type PromiseTable as h, type PromiseOrderedQueryBase as i, type PromiseOrderedQuery as j, type PromiseQuery as k, type PromisePaginationResultOrNull as l, type PromisePaginationResult as m, type PromiseEntsOrNull as n, type PromiseEntsWriterOrNull as o, type PromiseEnts as p, type PromiseEntsOrNulls as q, type PromiseEdgeOrderedEntsOrNull as r, type PromiseEdgeEntsOrNull as s, type PromiseEdgeOrderedEntsWriterOrNull as t, type PromiseEdgeEntsWriterOrNull as u, type PromiseEdgeOrderedEnts as v, type PromiseEdgeEnts as w, type PromiseEdgeOrderedEntsWriter as x, type PromiseEdgeEntsWriter as y, type PromiseEntOrNull as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { EntDefinition, defineEnt, defineEntFromTable, defineEntSchema, defineEntsFromTables, getEntDefinitions } from './schema.js';
-export { G as GenericEnt, T as GenericEntWriter, t as PromiseEdgeEnts, r as PromiseEdgeEntsOrNull, u as PromiseEdgeEntsWriter, I as PromiseEdgeWriter, K as PromiseEdgeWriterOrNull, J as PromiseEdgeWriterOrThrow, w as PromiseEnt, U as PromiseEntId, v as PromiseEntOrNull, S as PromiseEntWriter, R as PromiseEntWriterOrNull, p as PromiseEnts, n as PromiseEntsOrNull, q as PromiseEntsOrNulls, N as PromiseEntsWriter, o as PromiseEntsWriterOrNull, j as PromiseOrderedQuery, i as PromiseOrderedQueryBase, P as PromiseOrderedQueryOrNull, L as PromiseOrderedQueryWriter, d as PromiseOrderedQueryWriterOrNull, k as PromiseQuery, e as PromiseQueryOrNull, M as PromiseQueryWriter, f as PromiseQueryWriterOrNull, h as PromiseTable, g as PromiseTableBase, Q as PromiseTableWriter, Z as addEntRules, A as entsTableFactory } from './index-uXk5iZ86.js';
+export { J as GenericEnt, Z as GenericEntWriter, w as PromiseEdgeEnts, s as PromiseEdgeEntsOrNull, y as PromiseEdgeEntsWriter, M as PromiseEdgeWriter, O as PromiseEdgeWriterOrNull, N as PromiseEdgeWriterOrThrow, A as PromiseEnt, _ as PromiseEntId, z as PromiseEntOrNull, Y as PromiseEntWriter, X as PromiseEntWriterOrNull, p as PromiseEnts, n as PromiseEntsOrNull, q as PromiseEntsOrNulls, S as PromiseEntsWriter, o as PromiseEntsWriterOrNull, j as PromiseOrderedQuery, i as PromiseOrderedQueryBase, P as PromiseOrderedQueryOrNull, Q as PromiseOrderedQueryWriter, d as PromiseOrderedQueryWriterOrNull, k as PromiseQuery, e as PromiseQueryOrNull, R as PromiseQueryWriter, f as PromiseQueryWriterOrNull, h as PromiseTable, g as PromiseTableBase, V as PromiseTableWriter, a2 as addEntRules, F as entsTableFactory } from './index-nOBiMg01.js';
 export { scheduledDeleteFactory } from './deletion.js';
 import 'convex/server';
 import 'convex/values';

package/dist/index.js

@@ -131,10 +131,18 @@ function defineEntSchema(schema, options) {
           const edgeTableName = edge.type === "ref" && edge.table !== void 0 ? edge.table : inverseEdge === void 0 ? `${tableName}_${edge.name}` : inverseEdge.name !== tableName ? `${tableName}_${inverseEdge.name}_to_${edge.name}` : `${inverseEdge.name}_to_${edge.name}`;
           const forwardId = edge.type === "ref" && edge.field !== void 0 ? edge.field : inverseEdge === void 0 ? "aId" : tableName === otherTableName ? inverseEdge.name + "Id" : tableName + "Id";
           const inverseId = isSelfDirected && edge.type === "ref" && edge.inverseField !== void 0 ? edge.inverseField : inverseEdge === void 0 ? "bId" : inverseEdge.type === "ref" && inverseEdge.field !== void 0 ? inverseEdge.field : tableName === otherTableName ? edge.name + "Id" : otherTableName + "Id";
-          schema[edgeTableName] = defineEnt({
+          const edgeTable = defineEnt({
             [forwardId]: import_values.v.id(tableName),
             [inverseId]: import_values.v.id(otherTableName)
-          }).index(forwardId, [forwardId, inverseId]).index(inverseId, [inverseId, forwardId]);
+          }).index(forwardId, [forwardId]).index(inverseId, [inverseId]).index(`${forwardId}-${inverseId}`, [forwardId, inverseId]);
+          const isSymmetric = inverseEdge === void 0;
+          if (!isSymmetric) {
+            edgeTable.index(`${inverseId}-${forwardId}`, [
+              forwardId,
+              inverseId
+            ]);
+          }
+          schema[edgeTableName] = edgeTable;
           edge.type = "ref";
           edge.table = edgeTableName;
           edge.field = forwardId;
@@ -694,8 +702,13 @@ var PromiseQueryOrNullImpl = class _PromiseQueryOrNullImpl extends Promise {
       this.ctx,
       this.entDefinitions,
       this.table,
-      this.retrieve,
-      paginationOpts
+      async () => {
+        const query = await this.retrieve();
+        if (query === null) {
+          return null;
+        }
+        return await query.paginate(paginationOpts);
+      }
     );
   }
   take(n) {
@@ -811,50 +824,23 @@ var PromiseQueryOrNullImpl = class _PromiseQueryOrNullImpl extends Promise {
   }
   async _take(n) {
     const query = await this.retrieve();
-    if (query === null) {
-      return null;
-    }
-    const readPolicy = getReadRule(this.entDefinitions, this.table);
-    if (readPolicy === void 0) {
-      return await query.take(n);
-    }
-    let numItems = n;
-    const docs = [];
-    let hasMore = true;
-    const iterator = query[Symbol.asyncIterator]();
-    while (hasMore && docs.length < n) {
-      const page = [];
-      for (let i = 0; i < numItems; i++) {
-        const { done, value } = await iterator.next();
-        if (done) {
-          hasMore = false;
-          break;
-        }
-        page.push(value);
-      }
-      docs.push(
-        ...(await filterByReadRule(
-          this.ctx,
-          this.entDefinitions,
-          this.table,
-          page,
-          false
-        )).slice(0, n - docs.length)
-      );
-      numItems = Math.min(64, numItems * 2);
-    }
-    return docs;
+    return await takeFromQuery(
+      query,
+      n,
+      this.ctx,
+      this.entDefinitions,
+      this.table
+    );
   }
 };
 var PromisePaginationResultOrNullImpl = class extends Promise {
-  constructor(ctx, entDefinitions, table, retrieve, paginationOpts) {
+  constructor(ctx, entDefinitions, table, retrieve) {
     super(() => {
     });
     this.ctx = ctx;
     this.entDefinitions = entDefinitions;
     this.table = table;
     this.retrieve = retrieve;
-    this.paginationOpts = paginationOpts;
   }
   async map(callbackFn) {
     const result = await this;
@@ -867,11 +853,10 @@ var PromisePaginationResultOrNullImpl = class extends Promise {
     };
   }
   async docs() {
-    const query = await this.retrieve();
-    if (query === null) {
+    const result = await this.retrieve();
+    if (result === null) {
       return null;
     }
-    const result = await query.paginate(this.paginationOpts);
     return {
       ...result,
       page: await filterByReadRule(
@@ -1147,15 +1132,185 @@ var PromiseEntsOrNullImpl = class extends Promise {
     ).then(onfulfilled, onrejected);
   }
 };
-var PromiseEdgeOrNullImpl = class extends PromiseEntsOrNullImpl {
-  constructor(ctx, entDefinitions, table, field, retrieveRange) {
-    super(ctx, entDefinitions, table, () => retrieveRange((q) => q), false);
-    this.field = field;
-    this.retrieveRange = retrieveRange;
+var PromiseEdgeOrNullImpl = class _PromiseEdgeOrNullImpl extends PromiseEntsOrNullImpl {
+  constructor(ctx, entDefinitions, table, edgeDefinition, retrieveSourceId, retrieveQuery, retrieveDoc = async (edgeDoc) => {
+    const sourceId = edgeDoc[edgeDefinition.field];
+    const targetId = edgeDoc[edgeDefinition.ref];
+    const doc = await this.ctx.db.get(targetId);
+    if (doc === null) {
+      throw new Error(
+        `Dangling reference for edge "${edgeDefinition.name}" in table "${this.table}" for document with ID "${sourceId}": Could not find a document with ID "${targetId}" in table "${edgeDefinition.to}" (edge document ID is "${edgeDoc._id}").`
+      );
+    }
+    return doc;
+  }) {
+    super(
+      ctx,
+      entDefinitions,
+      table,
+      async () => {
+        const query = await retrieveQuery();
+        if (query === null) {
+          return null;
+        }
+        const edgeDocs = await query.collect();
+        return await Promise.all(edgeDocs.map(retrieveDoc));
+      },
+      false
+    );
+    this.edgeDefinition = edgeDefinition;
+    this.retrieveSourceId = retrieveSourceId;
+    this.retrieveQuery = retrieveQuery;
+    this.retrieveDoc = retrieveDoc;
+  }
+  async has(targetId) {
+    const sourceId = await this.retrieveSourceId();
+    if (sourceId === null) {
+      return null;
+    }
+    const edgeDoc = this.ctx.db.query(this.edgeDefinition.table).withIndex(
+      `${this.edgeDefinition.field}-${this.edgeDefinition.ref}`,
+      (q) => q.eq(this.edgeDefinition.field, sourceId).eq(
+        this.edgeDefinition.ref,
+        targetId
+      )
+    ).first();
+    return edgeDoc !== null;
   }
-  async has(id) {
-    const docs = await this.retrieveRange((q) => q.eq(this.field, id));
-    return (docs?.length ?? 0) > 0;
+  order(order) {
+    return new _PromiseEdgeOrNullImpl(
+      this.ctx,
+      this.entDefinitions,
+      this.table,
+      this.edgeDefinition,
+      this.retrieveSourceId,
+      async () => {
+        const query = await this.retrieveQuery();
+        if (query === null) {
+          return null;
+        }
+        return query.order(order);
+      }
+    );
+  }
+  paginate(paginationOpts) {
+    return new PromisePaginationResultOrNullImpl(
+      this.ctx,
+      this.entDefinitions,
+      this.table,
+      async () => {
+        const query = await this.retrieveQuery();
+        if (query === null) {
+          return null;
+        }
+        const result = await query.paginate(paginationOpts);
+        return {
+          ...result,
+          page: await Promise.all(result.page.map(this.retrieveDoc))
+        };
+      }
+    );
+  }
+  take(n) {
+    return new PromiseEntsOrNullImpl(
+      this.ctx,
+      this.entDefinitions,
+      this.table,
+      async () => {
+        return await this._take(n);
+      },
+      false
+    );
+  }
+  first() {
+    return new PromiseEntOrNullImpl(
+      this.ctx,
+      this.entDefinitions,
+      this.table,
+      async () => {
+        const docs = await this._take(1);
+        if (docs === null) {
+          return nullRetriever;
+        }
+        const [doc] = docs;
+        return loadedRetriever(doc);
+      },
+      false
+    );
+  }
+  firstX() {
+    return new PromiseEntWriterImpl(
+      this.ctx,
+      this.entDefinitions,
+      this.table,
+      async () => {
+        const docs = await this._take(1);
+        if (docs === null) {
+          return nullRetriever;
+        }
+        const [doc] = docs;
+        if (doc === void 0) {
+          throw new Error("Query returned no documents");
+        }
+        return loadedRetriever(doc);
+      },
+      false
+    );
+  }
+  unique() {
+    return new PromiseEntOrNullImpl(
+      this.ctx,
+      this.entDefinitions,
+      this.table,
+      async () => {
+        const docs = await this._take(2);
+        if (docs === null) {
+          return nullRetriever;
+        }
+        if (docs.length === 0) {
+          return nullRetriever;
+        }
+        if (docs.length === 2) {
+          throw new Error("unique() query returned more than one result");
+        }
+        const [doc] = docs;
+        return loadedRetriever(doc);
+      },
+      false
+    );
+  }
+  uniqueX() {
+    return new PromiseEntWriterImpl(
+      this.ctx,
+      this.entDefinitions,
+      this.table,
+      async () => {
+        const docs = await this._take(2);
+        if (docs === null) {
+          return nullRetriever;
+        }
+        if (docs.length === 0) {
+          throw new Error("Query returned no documents");
+        }
+        if (docs.length === 2) {
+          throw new Error("unique() query returned more than one result");
+        }
+        const [doc] = docs;
+        return loadedRetriever(doc);
+      },
+      true
+    );
+  }
+  async _take(n) {
+    const query = await this.retrieveQuery();
+    return await takeFromQuery(
+      query,
+      n,
+      this.ctx,
+      this.entDefinitions,
+      this.table,
+      this.retrieveDoc
+    );
   }
 };
 var PromiseEntOrNullImpl = class extends Promise {
@@ -1209,29 +1364,21 @@ var PromiseEntOrNullImpl = class extends Promise {
         return new PromiseEdgeOrNullImpl(
           this.ctx,
           this.entDefinitions,
-          edgeDefinition.to,
-          edgeDefinition.ref,
-          async (indexRange) => {
+          this.table,
+          edgeDefinition,
+          async () => {
+            const { id } = await this.retrieve();
+            return id;
+          },
+          async () => {
             const { id } = await this.retrieve();
             if (id === null) {
               return null;
             }
-            const edgeDocs = await this.ctx.db.query(edgeDefinition.table).withIndex(
+            return this.ctx.db.query(edgeDefinition.table).withIndex(
               edgeDefinition.field,
-              (q) => indexRange(q.eq(edgeDefinition.field, id))
-            ).collect();
-            return (await Promise.all(
-              edgeDocs.map(
-                (edgeDoc) => this.ctx.db.get(edgeDoc[edgeDefinition.ref])
-              )
-            )).filter((doc, i) => {
-              if (doc === null) {
-                throw new Error(
-                  `Dangling reference for edge "${edgeDefinition.name}" in table "${this.table}" for document with ID "${id}": Could not find a document with ID "${edgeDocs[i][edgeDefinition.field]}" in table "${edgeDefinition.to}" (edge document ID is "${edgeDocs[i]._id}").`
-                );
-              }
-              return true;
-            });
+              (q) => q.eq(edgeDefinition.field, id)
+            );
           }
         );
       }
@@ -1623,6 +1770,45 @@ function loadedRetriever(doc) {
 function addEntRules(entDefinitions, rules) {
   return { ...entDefinitions, rules };
 }
+async function takeFromQuery(query, n, ctx, entDefinitions, table, mapToResult) {
+  if (query === null) {
+    return null;
+  }
+  const readPolicy = getReadRule(entDefinitions, table);
+  if (readPolicy === void 0) {
+    const results = await query.take(n);
+    if (mapToResult === void 0) {
+      return results;
+    }
+    return Promise.all(results.map(mapToResult));
+  }
+  let numItems = n;
+  const docs = [];
+  let hasMore = true;
+  const iterator = query[Symbol.asyncIterator]();
+  while (hasMore && docs.length < n) {
+    const page = [];
+    for (let i = 0; i < numItems; i++) {
+      const { done, value } = await iterator.next();
+      if (done) {
+        hasMore = false;
+        break;
+      }
+      page.push(mapToResult === void 0 ? value : await mapToResult(value));
+    }
+    docs.push(
+      ...(await filterByReadRule(
+        ctx,
+        entDefinitions,
+        table,
+        page,
+        false
+      )).slice(0, n - docs.length)
+    );
+    numItems = Math.min(64, numItems * 2);
+  }
+  return docs;
+}
 async function filterByReadRule(ctx, entDefinitions, table, docs, throwIfNull) {
   if (docs === null) {
     return null;