convex-ents 0.18.1 → 0.20.0

package/dist/shared.d.ts

@@ -1,6 +1,6 @@
-import { SystemDataModel, TableNamesInDataModel, FieldTypeFromFieldPath, DocumentByName } from 'convex/server';
+import { SystemDataModel, TableNamesInDataModel, FieldTypeFromFieldPath, DocumentByName, GenericDataModel, GenericDatabaseReader, QueryInitializer, NamedTableInfo, SystemTableNames } from 'convex/server';
 import { GenericEdgeConfig, GenericEntsDataModel, EdgeConfig } from './schema.js';
-import 'convex/values';
+import { GenericId } from 'convex/values';
 
 type EntsSystemDataModel = {
     [key in keyof SystemDataModel]: SystemDataModel[key] & {
@@ -8,10 +8,14 @@ type EntsSystemDataModel = {
     };
 };
 type PromiseEdgeResult<EdgeConfig extends GenericEdgeConfig, MultipleRef, MultipleField, SingleOptional, Single> = EdgeConfig["cardinality"] extends "multiple" ? EdgeConfig["type"] extends "ref" ? MultipleRef : MultipleField : EdgeConfig["type"] extends "ref" ? SingleOptional : EdgeConfig["optional"] extends true ? SingleOptional : Single;
-type IndexFieldTypesForEq<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>, T extends string[]> = Pop<{
+type IndexFieldTypesForEq<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>, T extends string[]> = PopIfSeveral<{
     [K in keyof T]: FieldTypeFromFieldPath<DocumentByName<EntsDataModel, Table>, T[K]>;
 }>;
-type Pop<T extends any[]> = T extends [...infer Rest, infer _Last] ? Rest : never;
+type PopIfSeveral<T extends any[]> = T extends [infer Only] ? [Only] : T extends [...infer Rest, infer _Last] ? Rest : never;
 declare function getEdgeDefinitions<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>>(entDefinitions: EntsDataModel, table: Table): Record<keyof EntsDataModel[Table]["edges"], EdgeConfig>;
+type UniqueIndexFieldName<T extends string[]> = T extends [infer Only] ? Only : T extends [infer Single, "_creationTime"] ? Single : never;
+declare function systemAwareGet<DataModel extends GenericDataModel, Table extends TableNamesInDataModel<DataModel>>(db: GenericDatabaseReader<DataModel>, table: Table, id: GenericId<Table>): Promise<DocumentByName<SystemDataModel, (Table & "_scheduled_functions") | (Table & "_storage")> | null> | Promise<DocumentByName<DataModel, Table> | null>;
+declare function systemAwareQuery<DataModel extends GenericDataModel, Table extends TableNamesInDataModel<DataModel>>(db: GenericDatabaseReader<DataModel>, table: Table): QueryInitializer<NamedTableInfo<DataModel, Table>>;
+declare function isSystemTable(table: string): table is SystemTableNames;
 
-export { type EntsSystemDataModel, type IndexFieldTypesForEq, type PromiseEdgeResult, getEdgeDefinitions };
+export { type EntsSystemDataModel, type IndexFieldTypesForEq, type PromiseEdgeResult, type UniqueIndexFieldName, getEdgeDefinitions, isSystemTable, systemAwareGet, systemAwareQuery };

package/dist/shared.js

@@ -20,14 +20,29 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/shared.ts
 var shared_exports = {};
 __export(shared_exports, {
-  getEdgeDefinitions: () => getEdgeDefinitions
+  getEdgeDefinitions: () => getEdgeDefinitions,
+  isSystemTable: () => isSystemTable,
+  systemAwareGet: () => systemAwareGet,
+  systemAwareQuery: () => systemAwareQuery
 });
 module.exports = __toCommonJS(shared_exports);
 function getEdgeDefinitions(entDefinitions, table) {
   return entDefinitions[table].edges;
 }
+function systemAwareGet(db, table, id) {
+  return isSystemTable(table) ? db.system.get(table, id) : db.get(table, id);
+}
+function systemAwareQuery(db, table) {
+  return isSystemTable(table) ? db.system.query(table) : db.query(table);
+}
+function isSystemTable(table) {
+  return table.startsWith("_");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  getEdgeDefinitions
+  getEdgeDefinitions,
+  isSystemTable,
+  systemAwareGet,
+  systemAwareQuery
 });
 //# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/shared.ts"],"sourcesContent":["import {\n  DocumentByName,\n  FieldTypeFromFieldPath,\n  SystemDataModel,\n  TableNamesInDataModel,\n} from \"convex/server\";\nimport { EdgeConfig, GenericEdgeConfig, GenericEntsDataModel } from \"./schema\";\n\nexport type EntsSystemDataModel = {\n  [key in keyof SystemDataModel]: SystemDataModel[key] & {\n    edges: Record<string, never>;\n  };\n};\n\nexport type PromiseEdgeResult<\n  EdgeConfig extends GenericEdgeConfig,\n  MultipleRef,\n  MultipleField,\n  SingleOptional,\n  Single,\n> = EdgeConfig[\"cardinality\"] extends \"multiple\"\n  ? EdgeConfig[\"type\"] extends \"ref\"\n    ? MultipleRef\n    : MultipleField\n  : EdgeConfig[\"type\"] extends \"ref\"\n    ? SingleOptional\n    : EdgeConfig[\"optional\"] extends true\n      ? SingleOptional\n      : Single;\n\nexport type IndexFieldTypesForEq<\n  EntsDataModel extends GenericEntsDataModel,\n  Table extends TableNamesInDataModel<EntsDataModel>,\n  T extends string[],\n> = Pop<{\n  [K in keyof T]: FieldTypeFromFieldPath<\n    DocumentByName<EntsDataModel, Table>,\n    T[K]\n  >;\n}>;\n\ntype Pop<T extends any[]> = T extends [...infer Rest, infer _Last]\n  ? Rest\n  : never;\n\nexport function getEdgeDefinitions<\n  EntsDataModel extends GenericEntsDataModel,\n  Table extends TableNamesInDataModel<EntsDataModel>,\n>(entDefinitions: EntsDataModel, table: Table) {\n  return entDefinitions[table].edges as Record<\n    keyof EntsDataModel[Table][\"edges\"],\n    EdgeConfig\n  >;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA6CO,SAAS,mBAGd,gBAA+B,OAAc;AAC7C,SAAO,eAAe,KAAK,EAAE;AAI/B;","names":[]}
+{"version":3,"sources":["../src/shared.ts"],"sourcesContent":["import {\n  DocumentByName,\n  FieldTypeFromFieldPath,\n  GenericDatabaseReader,\n  GenericDataModel,\n  NamedTableInfo,\n  QueryInitializer,\n  SystemDataModel,\n  SystemTableNames,\n  TableNamesInDataModel,\n} from \"convex/server\";\nimport { EdgeConfig, GenericEdgeConfig, GenericEntsDataModel } from \"./schema\";\nimport { GenericId } from \"convex/values\";\n\nexport type EntsSystemDataModel = {\n  [key in keyof SystemDataModel]: SystemDataModel[key] & {\n    edges: Record<string, never>;\n  };\n};\n\nexport type PromiseEdgeResult<\n  EdgeConfig extends GenericEdgeConfig,\n  MultipleRef,\n  MultipleField,\n  SingleOptional,\n  Single,\n> = EdgeConfig[\"cardinality\"] extends \"multiple\"\n  ? EdgeConfig[\"type\"] extends \"ref\"\n    ? MultipleRef\n    : MultipleField\n  : EdgeConfig[\"type\"] extends \"ref\"\n    ? SingleOptional\n    : EdgeConfig[\"optional\"] extends true\n      ? SingleOptional\n      : Single;\n\nexport type IndexFieldTypesForEq<\n  EntsDataModel extends GenericEntsDataModel,\n  Table extends TableNamesInDataModel<EntsDataModel>,\n  T extends string[],\n> = PopIfSeveral<{\n  [K in keyof T]: FieldTypeFromFieldPath<\n    DocumentByName<EntsDataModel, Table>,\n    T[K]\n  >;\n}>;\n\n// System indexes have only a single field, so we won't to perform\n// equality check on that field. Normal indexes always have _creationTime as the last field.\ntype PopIfSeveral<T extends any[]> = T extends [infer Only]\n  ? [Only]\n  : T extends [...infer Rest, infer _Last]\n    ? Rest\n    : never;\n\nexport function getEdgeDefinitions<\n  EntsDataModel extends GenericEntsDataModel,\n  Table extends TableNamesInDataModel<EntsDataModel>,\n>(entDefinitions: EntsDataModel, table: Table) {\n  return entDefinitions[table].edges as Record<\n    keyof EntsDataModel[Table][\"edges\"],\n    EdgeConfig\n  >;\n}\n\nexport type UniqueIndexFieldName<T extends string[]> = T extends [infer Only]\n  ? Only\n  : T extends [infer Single, \"_creationTime\"]\n    ? Single\n    : never;\n\nexport function systemAwareGet<\n  DataModel extends GenericDataModel,\n  Table extends TableNamesInDataModel<DataModel>,\n>(db: GenericDatabaseReader<DataModel>, table: Table, id: GenericId<Table>) {\n  return isSystemTable(table)\n    ? db.system.get(table, id as any)\n    : db.get(table, id);\n}\n\nexport function systemAwareQuery<\n  DataModel extends GenericDataModel,\n  Table extends TableNamesInDataModel<DataModel>,\n>(\n  db: GenericDatabaseReader<DataModel>,\n  table: Table,\n): QueryInitializer<NamedTableInfo<DataModel, Table>> {\n  return isSystemTable(table)\n    ? (db.system.query(table) as any)\n    : db.query(table);\n}\n\nexport function isSystemTable(table: string): table is SystemTableNames {\n  return table.startsWith(\"_\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuDO,SAAS,mBAGd,gBAA+B,OAAc;AAC7C,SAAO,eAAe,KAAK,EAAE;AAI/B;AAQO,SAAS,eAGd,IAAsC,OAAc,IAAsB;AAC1E,SAAO,cAAc,KAAK,IACtB,GAAG,OAAO,IAAI,OAAO,EAAS,IAC9B,GAAG,IAAI,OAAO,EAAE;AACtB;AAEO,SAAS,iBAId,IACA,OACoD;AACpD,SAAO,cAAc,KAAK,IACrB,GAAG,OAAO,MAAM,KAAK,IACtB,GAAG,MAAM,KAAK;AACpB;AAEO,SAAS,cAAc,OAA0C;AACtE,SAAO,MAAM,WAAW,GAAG;AAC7B;","names":[]}

package/dist/writer.d.ts

@@ -2,7 +2,7 @@ import { GenericEdgeConfig, GenericEntsDataModel, Expand, DeletionConfig } from
 import { GenericDocument, TableNamesInDataModel, DocumentByName, PaginationOptions, PaginationResult, IndexNames, NamedTableInfo, FilterBuilder, ExpressionOrValue, WithOptionalSystemFields, FieldTypeFromFieldPath, SearchIndexNames, SearchFilterBuilder, NamedSearchIndex, SearchFilter, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, StorageWriter, Scheduler, IndexRangeBuilder, NamedIndex, IndexRange, WithoutSystemFields } from 'convex/server';
 import { GenericId } from 'convex/values';
 import { ScheduledDeleteFuncRef } from './deletion.js';
-import { PromiseEdgeResult, EntsSystemDataModel, IndexFieldTypesForEq } from './shared.js';
+import { PromiseEdgeResult, EntsSystemDataModel, UniqueIndexFieldName, IndexFieldTypesForEq } from './shared.js';
 
 declare class WriterImplBase<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> {
     protected ctx: EntMutationCtx<EntsDataModel>;
@@ -34,7 +34,6 @@ type EdgeChanges = Record<string, {
     remove?: GenericId<any>[];
     removeEdges?: GenericId<any>[];
 }>;
-declare function isSystemTable(table: string): boolean;
 
 interface PromiseOrderedQueryOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[] | null> {
     filter(predicate: (q: FilterBuilder<NamedTableInfo<EntsDataModel, Table>>) => ExpressionOrValue<boolean>): this;
@@ -45,6 +44,28 @@ interface PromiseOrderedQueryOrNull<EntsDataModel extends GenericEntsDataModel,
     unique(): PromiseEntOrNull<EntsDataModel, Table>;
     docs(): Promise<DocumentByName<EntsDataModel, Table>[] | null>;
 }
+interface PromiseOrderedIdsQueryOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<GenericId<Table>[] | null> {
+    /**
+     * Map over the relevant IDs.
+     */
+    map<TOutput>(callbackFn: (value: GenericId<Table>, index: number, array: GenericId<Table>[]) => TOutput | Promise<TOutput>): PromiseArrayOrNull<TOutput>;
+    /**
+     * Paginate the relevant IDs.
+     */
+    paginate(paginationOpts: PaginationOptions): PromiseIdsPaginationResultOrNull<EntsDataModel, Table>;
+    /**
+     * Take the first `n` relevant IDs.
+     */
+    take(n: number): PromiseIdsOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the first relevant ID, or `null` if there are no relevant IDs.
+     */
+    first(): Promise<GenericId<Table> | null>;
+    /**
+     * Returns the only relevant ID, or `null` if there are none or throws if there is more than one.
+     */
+    unique(): Promise<GenericId<Table> | null>;
+}
 interface PromiseOrderedQueryWriterOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[] | null> {
     filter(predicate: (q: FilterBuilder<NamedTableInfo<EntsDataModel, Table>>) => ExpressionOrValue<boolean>): this;
     map<TOutput>(callbackFn: (value: Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>, index: number, array: Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[]) => Promise<TOutput> | TOutput): PromiseArrayOrNull<TOutput>;
@@ -61,9 +82,9 @@ interface PromiseQueryWriterOrNull<EntsDataModel extends GenericEntsDataModel, T
     order(order: "asc" | "desc", indexName?: IndexNames<NamedTableInfo<EntsDataModel, Table>>): PromiseOrderedQueryWriterOrNull<EntsDataModel, Table>;
 }
 interface PromiseTableBase<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> {
-    getMany<Indexes extends EntsDataModel[Table]["indexes"], Index extends keyof Indexes>(indexName: Index, values: FieldTypeFromFieldPath<DocumentByName<EntsDataModel, Table>, Indexes[Index][0]>[]): PromiseEntsOrNulls<EntsDataModel, Table>;
+    getMany<Indexes extends EntsDataModel[Table]["indexes"], Index extends keyof Indexes>(indexName: Index, values: FieldTypeFromFieldPath<DocumentByName<EntsDataModel, Table>, UniqueIndexFieldName<Indexes[Index]>>[]): PromiseEntsOrNulls<EntsDataModel, Table>;
     getMany(ids: GenericId<Table>[]): PromiseEntsOrNulls<EntsDataModel, Table>;
-    getManyX<Indexes extends EntsDataModel[Table]["indexes"], Index extends keyof Indexes>(indexName: Index, values: FieldTypeFromFieldPath<DocumentByName<EntsDataModel, Table>, Indexes[Index][0]>[]): PromiseEnts<EntsDataModel, Table>;
+    getManyX<Indexes extends EntsDataModel[Table]["indexes"], Index extends keyof Indexes>(indexName: Index, values: FieldTypeFromFieldPath<DocumentByName<EntsDataModel, Table>, UniqueIndexFieldName<Indexes[Index]>>[]): PromiseEnts<EntsDataModel, Table>;
     getManyX(ids: GenericId<Table>[]): PromiseEnts<EntsDataModel, Table>;
     /**
      * If given a valid ID for the given table, returns it, or returns null if the ID
@@ -130,6 +151,15 @@ interface PromiseOrderedQuery<EntsDataModel extends GenericEntsDataModel, Table
     unique(): PromiseEntOrNull<EntsDataModel, Table>;
     uniqueX(): PromiseEnt<EntsDataModel, Table>;
 }
+interface PromiseOrderedIdsQuery<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<GenericId<Table>[]> {
+    map<TOutput>(callbackFn: (value: GenericId<Table>, index: number, array: GenericId<Table>[]) => Promise<TOutput> | TOutput): PromiseArray<TOutput>;
+    paginate(paginationOpts: PaginationOptions): PromiseIdsPaginationResult<EntsDataModel, Table>;
+    take(n: number): PromiseIds<EntsDataModel, Table>;
+    first(): Promise<GenericId<Table> | null>;
+    firstX(): Promise<GenericId<Table>>;
+    unique(): Promise<GenericId<Table> | null>;
+    uniqueX(): Promise<GenericId<Table>>;
+}
 interface PromiseQuery<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseOrderedQuery<EntsDataModel, Table> {
     order(order: "asc" | "desc"): PromiseOrderedQuery<EntsDataModel, Table>;
 }
@@ -141,6 +171,12 @@ interface PromisePaginationResult<EntsDataModel extends GenericEntsDataModel, Ta
     docs(): Promise<PaginationResult<DocumentByName<EntsDataModel, Table>>>;
     map<TOutput>(callbackFn: (value: Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>, index: number, array: Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[]) => Promise<TOutput> | TOutput): Promise<PaginationResult<TOutput>>;
 }
+interface PromiseIdsPaginationResultOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<PaginationResult<GenericId<Table>> | null> {
+    map<TOutput>(callbackFn: (value: GenericId<Table>, index: number, array: GenericId<Table>[]) => Promise<TOutput> | TOutput): Promise<PaginationResult<TOutput> | null>;
+}
+interface PromiseIdsPaginationResult<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<PaginationResult<GenericId<Table>>> {
+    map<TOutput>(callbackFn: (value: GenericId<Table>, index: number, array: GenericId<Table>[]) => Promise<TOutput> | TOutput): Promise<PaginationResult<TOutput>>;
+}
 interface PromiseEntsOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[] | null> {
     map<TOutput>(callbackFn: (value: Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>, index: number, array: Ent<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[]) => Promise<TOutput> | TOutput): PromiseArrayOrNull<TOutput>;
     docs(): Promise<DocumentByName<EntsDataModel, Table>[] | null>;
@@ -155,6 +191,12 @@ 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 PromiseIdsOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<GenericId<Table>[] | null> {
+    map<TOutput>(callbackFn: (value: GenericId<Table>, index: number, array: GenericId<Table>[]) => Promise<TOutput> | TOutput): PromiseArrayOrNull<TOutput>;
+}
+interface PromiseIds<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<GenericId<Table>[]> {
+    map<TOutput>(callbackFn: (value: GenericId<Table>, index: number, array: GenericId<Table>[]) => Promise<TOutput> | TOutput): PromiseArrayOrNull<TOutput>;
+}
 interface PromiseEdgeOrderedEntsOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEntsOrNull<EntsDataModel, Table> {
     /**
      * Paginate the ents on the other end of the edge.
@@ -191,6 +233,13 @@ interface PromiseEdgeEntsOrNull<EntsDataModel extends GenericEntsDataModel, Tabl
     order(order: "asc" | "desc", indexName?: IndexNames<NamedTableInfo<EntsDataModel, Table>>): PromiseEdgeOrderedEntsOrNull<EntsDataModel, Table>;
 }
 interface PromiseEdgeOrderedEntsWriterOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEntsWriterOrNull<EntsDataModel, Table> {
+    /**
+     * Returns the IDs of the ents on the other end of the edge.
+     * Returns null if chained to a null result.
+     *
+     * Note that read rules are not applied to filter the returned IDs.
+     */
+    ids(): PromiseOrderedIdsQueryOrNull<EntsDataModel, Table>;
     /**
      * Paginate the ents on the other end of the edge.
      * Results are ordered by edge's `_creationTime`.
@@ -226,6 +275,12 @@ interface PromiseEdgeEntsWriterOrNull<EntsDataModel extends GenericEntsDataModel
     order(order: "asc" | "desc", indexName?: IndexNames<NamedTableInfo<EntsDataModel, Table>>): PromiseEdgeOrderedEntsWriterOrNull<EntsDataModel, Table>;
 }
 interface PromiseEdgeOrderedEnts<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseEnts<EntsDataModel, Table> {
+    /**
+     * Returns the IDs of the ents on the other end of the edge.
+     *
+     * Note that read rules are not applied to filter the returned IDs.
+     */
+    ids(): PromiseOrderedIdsQuery<EntsDataModel, Table>;
     /**
      * Paginate the ents on the other end of the edge.
      * Results are ordered by edge's `_creationTime`.
@@ -265,6 +320,12 @@ interface PromiseEdgeEnts<EntsDataModel extends GenericEntsDataModel, Table exte
      * @param id The ID of the ent on the other end of the edge
      */
     has(id: GenericId<Table>): Promise<boolean>;
+    /**
+     * Returns the IDs of the ents on the other end of the edge.
+     *
+     * Note that read rules are not applied to filter the returned IDs.
+     */
+    ids(): PromiseOrderedIdsQuery<EntsDataModel, Table>;
     /**
      * Query the ents on the other end of the edge
      * ordered by edge's `_creationTime`.
@@ -272,6 +333,12 @@ interface PromiseEdgeEnts<EntsDataModel extends GenericEntsDataModel, Table exte
     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> {
+    /**
+     * Returns the IDs of the ents on the other end of the edge.
+     *
+     * Note that read rules are not applied to filter the returned IDs.
+     */
+    ids(): PromiseOrderedIdsQuery<EntsDataModel, Table>;
     /**
      * Paginate the ents on the other end of the edge.
      * Results are ordered by edge's `_creationTime`.
@@ -346,7 +413,14 @@ type EntsTable<EntsDataModel extends GenericEntsDataModel> = EntsTableReader<Ent
     system: EntsTableReader<EntsSystemDataModel>;
 };
 type EntsTableWriter<EntsDataModel extends GenericEntsDataModel> = {
+    /**
+     * Read from and write to the given `table` using the index with the given `indexName`.
+     * Without the `indexRange` argument, the use of the index only affects the order of the results.
+     */
     <Table extends TableNamesInDataModel<EntsDataModel>, IndexName extends IndexNames<NamedTableInfo<EntsDataModel, Table>>>(table: Table, indexName: IndexName, indexRange?: (q: IndexRangeBuilder<DocumentByName<EntsDataModel, Table>, NamedIndex<NamedTableInfo<EntsDataModel, Table>, IndexName>>) => IndexRange): PromiseQueryWriter<EntsDataModel, Table>;
+    /**
+     * Read from and write to the given `table`.
+     */
     <Table extends TableNamesInDataModel<EntsDataModel>>(table: Table): PromiseTableWriter<Table, EntsDataModel>;
     system: EntsTableReader<EntsSystemDataModel>;
 };
@@ -364,12 +438,34 @@ type PromiseEdgeWriter<EntsDataModel extends GenericEntsDataModel, Table extends
 type PromiseEdgeWriterOrThrow<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>, Edge extends keyof EntsDataModel[Table]["edges"], Config extends GenericEdgeConfig = EntsDataModel[Table]["edges"][Edge], ToTable extends TableNamesInDataModel<EntsDataModel> = EntsDataModel[Table]["edges"][Edge]["to"]> = PromiseEdgeResult<Config, PromiseEdgeEntsWriter<EntsDataModel, ToTable>, PromiseQueryWriter<EntsDataModel, ToTable>, PromiseEntWriter<EntsDataModel, ToTable>, PromiseEntWriter<EntsDataModel, ToTable>>;
 type PromiseEdgeWriterOrNull<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>, Edge extends keyof EntsDataModel[Table]["edges"], Config extends GenericEdgeConfig = EntsDataModel[Table]["edges"][Edge], ToTable extends TableNamesInDataModel<EntsDataModel> = EntsDataModel[Table]["edges"][Edge]["to"]> = PromiseEdgeResult<Config, PromiseEdgeEntsWriterOrNull<EntsDataModel, ToTable>, PromiseQueryWriterOrNull<EntsDataModel, ToTable>, PromiseEntWriterOrNull<EntsDataModel, ToTable>, PromiseEntWriterOrNull<EntsDataModel, ToTable>>;
 interface PromiseOrderedQueryWriter<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[]>, PromiseOrderedQueryBase<EntsDataModel, Table> {
+    /**
+     * Paginate the relevant ents.
+     */
     paginate(paginationOpts: PaginationOptions): PromisePaginationResultWriter<EntsDataModel, Table>;
+    /**
+     * Map over the relevant ents.
+     */
     map<TOutput>(callbackFn: (value: EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>, index: number, array: EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>[]) => Promise<TOutput> | TOutput): PromiseArray<TOutput>;
+    /**
+     * Take the first `n` relevant ents.
+     */
     take(n: number): PromiseEntsWriter<EntsDataModel, Table>;
+    /**
+     * Returns the first relevant ent, or `null` if there are no ents.
+     */
     first(): PromiseEntWriterOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the first relevant ent, or throws if there are no ents.
+     */
     firstX(): PromiseEntWriter<EntsDataModel, Table>;
+    /**
+     * Returns the only relevant ent, `null` if there are none,
+     * or throws if there are more than one.
+     */
     unique(): PromiseEntWriterOrNull<EntsDataModel, Table>;
+    /**
+     * Returns the only relevant ent, or throws if there are none or more than one.
+     */
     uniqueX(): PromiseEntWriter<EntsDataModel, Table>;
 }
 interface PromiseQueryWriter<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends PromiseOrderedQueryWriter<EntsDataModel, Table> {
@@ -445,6 +541,9 @@ interface PromiseEntWriterOrNull<EntsDataModel extends GenericEntsDataModel, Tab
     doc(): Promise<DocumentByName<EntsDataModel, Table> | null>;
 }
 interface PromiseEntWriter<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>> extends Promise<EntWriter<Table, DocumentByName<EntsDataModel, Table>, EntsDataModel>> {
+    /**
+     * Traverse the given `edge`.
+     */
     edge<Edge extends keyof EntsDataModel[Table]["edges"]>(edge: Edge): PromiseEdgeWriter<EntsDataModel, Table, Edge>;
     edgeX<Edge extends keyof EntsDataModel[Table]["edges"]>(edge: Edge): PromiseEdgeWriterOrThrow<EntsDataModel, Table, Edge>;
     doc(): Promise<DocumentByName<EntsDataModel, Table>>;
@@ -551,4 +650,4 @@ declare function getWriteRule(entDefinitions: GenericEntsDataModel, table: strin
 }) => Promise<boolean>) | undefined;
 declare function getDeletionConfig<EntsDataModel extends GenericEntsDataModel, Table extends TableNamesInDataModel<EntsDataModel>>(entDefinitions: EntsDataModel, table: Table): DeletionConfig | undefined;
 
-export { getWriteRule as $, entWrapper as A, entsTableFactory as B, type EntsTableWriter as C, type Ent as D, type EntsTable as E, type EdgeChanges, 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 PromisePaginationResultWriterOrNull as O, type PromiseOrderedQueryOrNull as P, type PromisePaginationResultWriter as Q, type PromiseTableWriter as R, type PromiseEntWriterOrNull as S, type PromiseEntWriter as T, type GenericEntWriter as U, type PromiseEntId as V, type EntQueryCtx as W, type WithEdgeInserts, type WithEdgePatches, type WithEdges, WriterImplBase, type EntMutationCtx as X, type DocRetriever as Y, addEntRules as Z, getReadRule as _, type PromiseOrderedQueryWriterOrNull as a, getDeletionConfig as a0, type PromiseQueryOrNull as b, type PromiseQueryWriterOrNull as c, type PromiseTableBase as d, type PromiseTable as e, type PromiseOrderedQueryBase as f, type PromiseOrderedQuery as g, type PromiseQuery as h, type PromisePaginationResultOrNull as i, isSystemTable, type PromisePaginationResult as j, type PromiseEntsOrNull as k, type PromiseEntsWriterOrNull as l, type PromiseEnts as m, type PromiseEntsOrNulls as n, type PromiseEdgeOrderedEntsOrNull as o, type PromiseEdgeEntsOrNull as p, type PromiseEdgeOrderedEntsWriterOrNull as q, type PromiseEdgeEntsWriterOrNull as r, type PromiseEdgeOrderedEnts as s, type PromiseEdgeEnts as t, type PromiseEdgeOrderedEntsWriter as u, type PromiseEdgeEntsWriter as v, type PromiseEntOrNull as w, type PromiseEnt as x, type PromiseArrayOrNull as y, type PromiseArray as z };
+export { type PromiseEntId as $, type PromiseEdgeOrderedEntsWriter as A, type PromiseEdgeEntsWriter as B, type PromiseEntOrNull as C, type PromiseEnt as D, type PromiseArrayOrNull as E, type EdgeChanges, type PromiseArray as F, entWrapper as G, entsTableFactory as H, type EntsTable as I, type EntsTableWriter as J, type Ent as K, type GenericEnt as L, type PromiseEdge as M, type PromiseEdgeOrThrow as N, type PromiseEdgeWriter as O, type PromiseOrderedQueryOrNull as P, type PromiseEdgeWriterOrThrow as Q, type PromiseEdgeWriterOrNull as R, type PromiseOrderedQueryWriter as S, type PromiseQueryWriter as T, type PromiseEntsWriter as U, type PromisePaginationResultWriterOrNull as V, type PromisePaginationResultWriter as W, type WithEdgeInserts, type WithEdgePatches, type WithEdges, WriterImplBase, type PromiseTableWriter as X, type PromiseEntWriterOrNull as Y, type PromiseEntWriter as Z, type GenericEntWriter as _, type PromiseOrderedIdsQueryOrNull as a, type EntQueryCtx as a0, type EntMutationCtx as a1, type DocRetriever as a2, addEntRules as a3, getReadRule as a4, getWriteRule as a5, getDeletionConfig as a6, type PromiseOrderedQueryWriterOrNull as b, type PromiseQueryOrNull as c, type PromiseQueryWriterOrNull as d, type PromiseTableBase as e, type PromiseTable as f, type PromiseOrderedQueryBase as g, type PromiseOrderedQuery as h, type PromiseOrderedIdsQuery as i, type PromiseQuery as j, type PromisePaginationResultOrNull as k, type PromisePaginationResult as l, type PromiseIdsPaginationResultOrNull as m, type PromiseIdsPaginationResult as n, type PromiseEntsOrNull as o, type PromiseEntsWriterOrNull as p, type PromiseEnts as q, type PromiseEntsOrNulls as r, type PromiseIdsOrNull as s, type PromiseIds as t, type PromiseEdgeOrderedEntsOrNull as u, type PromiseEdgeEntsOrNull as v, type PromiseEdgeOrderedEntsWriterOrNull as w, type PromiseEdgeEntsWriterOrNull as x, type PromiseEdgeOrderedEnts as y, type PromiseEdgeEnts as z };

package/dist/writer.js

@@ -20,8 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/writer.ts
 var writer_exports = {};
 __export(writer_exports, {
-  WriterImplBase: () => WriterImplBase,
-  isSystemTable: () => isSystemTable
+  WriterImplBase: () => WriterImplBase
 });
 module.exports = __toCommonJS(writer_exports);
 var import_server2 = require("convex/server");
@@ -40,6 +39,12 @@ function edgeCompoundIndexNameRaw(idA, idB) {
 function getEdgeDefinitions(entDefinitions, table) {
   return entDefinitions[table].edges;
 }
+function systemAwareGet(db, table, id) {
+  return isSystemTable(table) ? db.system.get(table, id) : db.get(table, id);
+}
+function isSystemTable(table) {
+  return table.startsWith("_");
+}
 
 // src/functions.ts
 var PromiseQueryOrNullImpl = class _PromiseQueryOrNullImpl extends Promise {
@@ -66,7 +71,7 @@ var PromiseQueryOrNullImpl = class _PromiseQueryOrNullImpl extends Promise {
     );
   }
   map(callbackFn) {
-    return new PromiseArrayImpl(async () => {
+    return new PromiseArrayOrNullImpl(async () => {
       const array = await this;
       if (array === null) {
         return null;
@@ -227,6 +232,90 @@ var PromiseQueryOrNullImpl = class _PromiseQueryOrNullImpl extends Promise {
     );
   }
 };
+var PromiseIdsQueryOrNullImpl = class extends Promise {
+  constructor(retrieve, field) {
+    super(() => {
+    });
+    this.retrieve = retrieve;
+    this.field = field;
+  }
+  map(callbackFn) {
+    return new PromiseArrayOrNullImpl(async () => {
+      const array = await this;
+      if (array === null) {
+        return null;
+      }
+      return await Promise.all(array.map(callbackFn));
+    });
+  }
+  paginate(paginationOpts) {
+    return new PromiseIdsPaginationResultOrNullImpl(async () => {
+      const query = await this.retrieve();
+      if (query === null) {
+        return null;
+      }
+      const result = await query.paginate(paginationOpts);
+      return {
+        ...result,
+        page: result.page.map((id) => this._getId(id))
+      };
+    });
+  }
+  take(n) {
+    return new PromiseIdsOrNullImpl(async () => {
+      const query = await this.retrieve();
+      if (query === null) {
+        return null;
+      }
+      const result = await query.take(n);
+      return result.map((id) => this._getId(id));
+    });
+  }
+  async first() {
+    const query = await this.retrieve();
+    if (query === null) {
+      return null;
+    }
+    const doc = await query.first();
+    if (doc === null) {
+      return null;
+    }
+    return this._getId(doc);
+  }
+  async firstX() {
+    const id = await this.first();
+    if (id === null) {
+      throw new Error("Expected at least one ID, but got none");
+    }
+    return id;
+  }
+  async unique() {
+    const query = await this.retrieve();
+    if (query === null) {
+      return null;
+    }
+    const result = await query.unique();
+    if (result === null) {
+      return null;
+    }
+    return this._getId(result);
+  }
+  async uniqueX() {
+    const id = await this.unique();
+    if (id === null) {
+      throw new Error("Expected one unique ID, but got none");
+    }
+    return id;
+  }
+  then(onfulfilled, onrejected) {
+    return this.retrieve().then((query) => query === null ? null : query.collect()).then(
+      (docs) => docs === null ? null : docs.map((doc) => this._getId(doc))
+    ).then(onfulfilled, onrejected);
+  }
+  _getId(doc) {
+    return doc[this.field];
+  }
+};
 var PromisePaginationResultOrNullImpl = class extends Promise {
   constructor(ctx, entDefinitions, table, retrieve) {
     super(() => {
@@ -273,6 +362,26 @@ var PromisePaginationResultOrNullImpl = class extends Promise {
     ).then(onfulfilled, onrejected);
   }
 };
+var PromiseIdsPaginationResultOrNullImpl = class extends Promise {
+  constructor(retrieve) {
+    super(() => {
+    });
+    this.retrieve = retrieve;
+  }
+  async map(callbackFn) {
+    const result = await this;
+    if (result === null) {
+      return null;
+    }
+    return {
+      ...result,
+      page: await Promise.all(result.page.map(callbackFn))
+    };
+  }
+  then(onfulfilled, onrejected) {
+    return this.retrieve().then(onfulfilled, onrejected);
+  }
+};
 var PromiseEntsOrNullImpl = class extends Promise {
   constructor(ctx, entDefinitions, table, retrieve, throwIfNull) {
     super(() => {
@@ -284,7 +393,7 @@ var PromiseEntsOrNullImpl = class extends Promise {
     this.throwIfNull = throwIfNull;
   }
   map(callbackFn) {
-    return new PromiseArrayImpl(async () => {
+    return new PromiseArrayOrNullImpl(async () => {
       const array = await this;
       if (array === null) {
         return null;
@@ -386,11 +495,34 @@ var PromiseEntsOrNullImpl = class extends Promise {
     ).then(onfulfilled, onrejected);
   }
 };
+var PromiseIdsOrNullImpl = class extends Promise {
+  constructor(retrieve) {
+    super(() => {
+    });
+    this.retrieve = retrieve;
+  }
+  map(callbackFn) {
+    return new PromiseArrayOrNullImpl(async () => {
+      const array = await this;
+      if (array === null) {
+        return null;
+      }
+      return await Promise.all(array.map(callbackFn));
+    });
+  }
+  then(onfulfilled, onrejected) {
+    return this.retrieve().then(onfulfilled, onrejected);
+  }
+};
 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);
+    const doc = await systemAwareGet(
+      this.ctx.db,
+      edgeDefinition.to,
+      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}").`
@@ -417,6 +549,12 @@ var PromiseEdgeOrNullImpl = class _PromiseEdgeOrNullImpl extends PromiseEntsOrNu
     this.retrieveQuery = retrieveQuery;
     this.retrieveDoc = retrieveDoc;
   }
+  ids() {
+    return new PromiseIdsQueryOrNullImpl(
+      () => this.retrieveQuery(),
+      this.edgeDefinition.ref
+    );
+  }
   async has(targetId) {
     const sourceId = await this.retrieveSourceId();
     if (sourceId === null) {
@@ -686,7 +824,11 @@ var PromiseEntOrNullImpl = class extends Promise {
                 `Unexpected null reference for edge "${edgeDefinition.name}" in table "${this.table}" on document with ID "${id}": Expected an ID for a document in table "${edgeDefinition.to}".`
               );
             }
-            const otherDoc = await this.ctx.db.get(otherId);
+            const otherDoc = await systemAwareGet(
+              this.ctx.db,
+              edgeDefinition.to,
+              otherId
+            );
             if (otherDoc === null && edgeDefinition.to !== "_scheduled_functions") {
               throw new Error(
                 `Dangling reference for edge "${edgeDefinition.name}" in table "${this.table}" on document with ID "${id}": Could not find a document with ID "${otherId}" in table "${edgeDefinition.to}".`
@@ -700,7 +842,7 @@ var PromiseEntOrNullImpl = class extends Promise {
     );
   }
 };
-var PromiseArrayImpl = class extends Promise {
+var PromiseArrayOrNullImpl = class extends Promise {
   constructor(retrieve) {
     super(() => {
     });
@@ -894,7 +1036,7 @@ var PromiseEntWriterImpl = class extends PromiseEntOrNullImpl {
             }
             if (edgeDefinition.cardinality === "single") {
               if (edgeDefinition.type === "ref") {
-                const oldDoc = await this.ctx.db.get(docId);
+                const oldDoc = await this.ctx.db.get(this.table, docId);
                 if (oldDoc[key] !== void 0 && oldDoc[key] !== idOrIds) {
                   throw new Error("Cannot set 1:1 edge from ref end.");
                 }
@@ -956,7 +1098,10 @@ var PromiseEntIdImpl = class extends Promise {
       this.table,
       async () => {
         const id = await this.retrieve();
-        return { id, doc: async () => this.ctx.db.get(id) };
+        return {
+          id,
+          doc: async () => systemAwareGet(this.ctx.db, this.table, id)
+        };
       },
       true
     );
@@ -1078,7 +1223,7 @@ var WriterImplBase = class _WriterImplBase {
             }
           } else if (edgeDefinition.cardinality === "single") {
             if (edgeDefinition.deletion !== void 0 && (!isDeletingSoftly || edgeDefinition.deletion === "soft")) {
-              const doc = await this.ctx.db.get(id);
+              const doc = await this.ctx.db.get(this.table, id);
               if (doc !== null) {
                 const otherId = doc[edgeDefinition.field];
                 edges[key] = {
@@ -1284,7 +1429,7 @@ var WriterImplBase = class _WriterImplBase {
     if (id !== void 0) {
       const readPolicy = getReadRule(this.entDefinitions, this.table);
       if (readPolicy !== void 0) {
-        const doc = await this.ctx.db.get(id);
+        const doc = await this.ctx.db.get(this.table, id);
         if (doc === null) {
           throw new Error(
             `Cannot update document with ID "${id}" in table "${this.table} because it does not exist"`
@@ -1303,7 +1448,7 @@ var WriterImplBase = class _WriterImplBase {
       return;
     }
     const ent = id === void 0 ? void 0 : entWrapper(
-      await this.ctx.db.get(id),
+      await this.ctx.db.get(this.table, id),
       this.ctx,
       this.entDefinitions,
       this.table
@@ -1333,12 +1478,8 @@ var WriterImplBase = class _WriterImplBase {
     }
   }
 };
-function isSystemTable(table) {
-  return table.startsWith("_");
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  WriterImplBase,
-  isSystemTable
+  WriterImplBase
 });
 //# sourceMappingURL=writer.js.map