@gaganref/confect-server 0.0.0-stage → 10.3.1-fork.10

package/src/QueryInitializer.ts

@@ -0,0 +1,537 @@
+import type * as IdScope from "@confect/core/IdScope";
+import type {
+  OrderedQuery as ConvexOrderedQuery,
+  QueryInitializer as ConvexQueryInitializer,
+  DocumentByInfo,
+  GenericTableIndexes,
+  Indexes,
+  IndexRange,
+  IndexRangeBuilder,
+  NamedIndex,
+  NamedSearchIndex,
+  NamedTableInfo,
+  Query,
+  SearchFilter,
+  SearchFilterBuilder,
+  SearchIndexes,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import { pipe } from "effect/Function";
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import type { ReadonlyRecord } from "effect/Record";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import type {
+  BaseDatabaseReader,
+  IndexFieldTypesForEq,
+} from "@confect/core/Types";
+import type * as DataModel from "./DataModel.js";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import * as Document from "./Document.js";
+import * as OrderedQuery from "./OrderedQuery.js";
+import * as QueryStream from "./QueryStream.js";
+import type * as QueryStreamKeyLabels from "./QueryStreamKeyLabels.js";
+import * as QueryStreamIndexRange from "./QueryStreamIndexRange.js";
+import type { QueryStreamOrderDirection as OrderDirection } from "./QueryStreamOrderDirection.js";
+import type * as Table from "./Table.js";
+
+type ConvexTableInfoFor<
+  DataModel_ extends DataModel.AnyWithProps,
+  TableName extends DataModel.TableNames<DataModel_>,
+> = DataModel.TableInfoWithName<DataModel_, TableName>;
+
+type TableInfoFor<
+  DataModel_ extends DataModel.AnyWithProps,
+  TableName extends DataModel.TableNames<DataModel_>,
+> = DataModel.TableInfoWithName_<DataModel_, TableName>;
+
+export interface QueryInitializer<
+  DataModel_ extends DataModel.AnyWithProps,
+  TableName extends DataModel.TableNames<DataModel_>,
+  Doc = DataModel.DocumentWithName<DataModel_, TableName>,
+  TargetKind extends DatabaseSchema.Target["kind"] = "app",
+> {
+  readonly get: {
+    (
+      id: DataModel.Id<DataModel_, TableName>,
+    ): Effect.Effect<Doc, Document.DocumentDecodeError | GetByIdFailure>;
+    <
+      IndexName extends keyof Indexes<
+        ConvexTableInfoFor<DataModel_, TableName>
+      >,
+    >(
+      indexName: IndexName,
+      ...indexFieldValues: IndexFieldTypesForEq<
+        DataModel.ToConvex<DataModel_>,
+        TableName,
+        Indexes<ConvexTableInfoFor<DataModel_, TableName>>[IndexName]
+      >
+    ): Effect.Effect<Doc, Document.DocumentDecodeError | GetByIndexFailure>;
+  };
+  readonly index: {
+    <
+      IndexName extends keyof Indexes<
+        ConvexTableInfoFor<DataModel_, TableName>
+      >,
+    >(
+      indexName: IndexName,
+      indexRange?: (
+        q: IndexRangeBuilder<
+          TableInfoFor<DataModel_, TableName>["convexDocument"],
+          NamedIndex<ConvexTableInfoFor<DataModel_, TableName>, IndexName>
+        >,
+      ) => IndexRange,
+      order?: OrderDirection,
+    ): OrderedQuery.OrderedQuery<
+      TableInfoFor<DataModel_, TableName>,
+      Doc,
+      TargetKind
+    >;
+    <
+      IndexName extends keyof Indexes<
+        ConvexTableInfoFor<DataModel_, TableName>
+      >,
+    >(
+      indexName: IndexName,
+      order?: OrderDirection,
+    ): OrderedQuery.OrderedQuery<
+      TableInfoFor<DataModel_, TableName>,
+      Doc,
+      TargetKind
+    >;
+  };
+  readonly search: <
+    IndexName extends keyof SearchIndexes<
+      ConvexTableInfoFor<DataModel_, TableName>
+    >,
+  >(
+    indexName: IndexName,
+    searchFilter: (
+      q: SearchFilterBuilder<
+        DocumentByInfo<ConvexTableInfoFor<DataModel_, TableName>>,
+        NamedSearchIndex<ConvexTableInfoFor<DataModel_, TableName>, IndexName>
+      >,
+    ) => SearchFilter,
+  ) => OrderedQuery.OrderedQuery<
+    TableInfoFor<DataModel_, TableName>,
+    Doc,
+    TargetKind
+  >;
+  /**
+   * EXPERIMENTAL—stream-first querying (see `notes/stream-based-querying.md`).
+   *
+   * Like `index`, but returns a {@link QueryStream.QueryStream}: a genuine
+   * Effect `Stream` of documents in index order that stays mergeable and
+   * paginable.
+   *
+   * In SQL terms: an index range scan—`SELECT * FROM table WHERE <range> ORDER
+   * BY <index fields> [DESC]`; `eq` calls are the equality predicates, the
+   * bound calls are the range predicates. The value is a reusable description
+   * of a query: each run re-runs the index query. * The typed range builder
+   * consumes `eq`-pinned fields from the index's field tuple at the type level,
+   * so the stream's visible label type is exactly the fields that still vary
+   * (the `ORDER BY` columns left after the equality predicates). The order
+   * direction is part of the type too: omitted, it is `"asc"`; a literal is
+   * tracked as that literal, and a value known only at runtime as the union.
+   * The order parameter is either absent or a direction—never `undefined`—so
+   * the type can't claim a literal the runtime default would contradict.
+   */
+  readonly stream: {
+    <
+      IndexName extends keyof Indexes<
+        ConvexTableInfoFor<DataModel_, TableName>
+      > &
+        string,
+      Range extends QueryStreamIndexRange.QueryStreamIndexRange,
+    >(
+      indexName: IndexName,
+      indexRange: (
+        q: QueryStreamIndexRange.Builder<
+          TableInfoFor<DataModel_, TableName>["convexDocument"],
+          NamedIndex<ConvexTableInfoFor<DataModel_, TableName>, IndexName>
+        >,
+      ) => Range,
+    ): QueryStream.QueryStream<
+      Doc,
+      QueryStreamKeyLabels.QueryStreamKeyLabels<
+        QueryStreamIndexRange.Remaining<Range>
+      >,
+      "asc",
+      Document.DocumentDecodeError,
+      never
+    >;
+    <
+      IndexName extends keyof Indexes<
+        ConvexTableInfoFor<DataModel_, TableName>
+      > &
+        string,
+      Range extends QueryStreamIndexRange.QueryStreamIndexRange,
+      Direction extends OrderDirection,
+    >(
+      indexName: IndexName,
+      indexRange: (
+        q: QueryStreamIndexRange.Builder<
+          TableInfoFor<DataModel_, TableName>["convexDocument"],
+          NamedIndex<ConvexTableInfoFor<DataModel_, TableName>, IndexName>
+        >,
+      ) => Range,
+      order: Direction,
+    ): QueryStream.QueryStream<
+      Doc,
+      QueryStreamKeyLabels.QueryStreamKeyLabels<
+        QueryStreamIndexRange.Remaining<Range>
+      >,
+      Direction,
+      Document.DocumentDecodeError,
+      never
+    >;
+    <
+      IndexName extends keyof Indexes<
+        ConvexTableInfoFor<DataModel_, TableName>
+      > &
+        string,
+    >(
+      indexName: IndexName,
+    ): QueryStream.QueryStream<
+      Doc,
+      QueryStreamKeyLabels.QueryStreamKeyLabels<
+        NamedIndex<ConvexTableInfoFor<DataModel_, TableName>, IndexName>
+      >,
+      "asc",
+      Document.DocumentDecodeError,
+      never
+    >;
+    <
+      IndexName extends keyof Indexes<
+        ConvexTableInfoFor<DataModel_, TableName>
+      > &
+        string,
+      Direction extends OrderDirection,
+    >(
+      indexName: IndexName,
+      order: Direction,
+    ): QueryStream.QueryStream<
+      Doc,
+      QueryStreamKeyLabels.QueryStreamKeyLabels<
+        NamedIndex<ConvexTableInfoFor<DataModel_, TableName>, IndexName>
+      >,
+      Direction,
+      Document.DocumentDecodeError,
+      never
+    >;
+  };
+}
+
+export function make<
+  Tables extends Table.AnyWithProps,
+  TableName extends Table.Name<Tables>,
+>(
+  convexDatabaseReader: BaseDatabaseReader<
+    DataModel.ToConvex<DataModel.FromTables<Tables>>
+  >,
+  table: Table.WithName<Tables, TableName> & { readonly scope: IdScope.App },
+): QueryInitializer<DataModel.FromTables<Tables>, TableName>;
+export function make<
+  Tables extends Table.AnyWithProps,
+  TableName extends Table.Name<Tables>,
+>(
+  convexDatabaseReader: BaseDatabaseReader<
+    DataModel.ToConvex<DataModel.FromTables<Tables>>
+  >,
+  table: Table.WithName<Tables, TableName>,
+): QueryInitializer<
+  DataModel.FromTables<Tables>,
+  TableName,
+  DataModel.DocumentWithName<DataModel.FromTables<Tables>, TableName>,
+  Table.Scope<Table.WithName<Tables, TableName>> extends IdScope.App
+    ? "app"
+    : "component"
+>;
+export function make<
+  Tables extends Table.AnyWithProps,
+  TableName extends Table.Name<Tables>,
+>(
+  convexDatabaseReader: BaseDatabaseReader<
+    DataModel.ToConvex<DataModel.FromTables<Tables>>
+  >,
+  table: Table.WithName<Tables, TableName>,
+): QueryInitializer<
+  DataModel.FromTables<Tables>,
+  TableName,
+  DataModel.DocumentWithName<DataModel.FromTables<Tables>, TableName>,
+  DatabaseSchema.Target["kind"]
+> {
+  const tableName = table.tableName;
+  type DataModel_ = DataModel.FromTables<Tables>;
+  type ConvexDataModel_ = DataModel.ToConvex<DataModel_>;
+  type ThisQueryInitializer = QueryInitializer<
+    DataModel_,
+    TableName,
+    DataModel.DocumentWithName<DataModel_, TableName>,
+    DatabaseSchema.Target["kind"]
+  >;
+  type QueryInitializerFunction<
+    FunctionName extends keyof ThisQueryInitializer,
+  > = ThisQueryInitializer[FunctionName];
+
+  const getByIndex = <
+    IndexName extends keyof Indexes<
+      DataModel.TableInfoWithName<DataModel_, TableName>
+    >,
+  >(
+    indexName: IndexName,
+    indexFieldValues: IndexFieldTypesForEq<
+      DataModel.ToConvex<DataModel_>,
+      TableName,
+      Indexes<DataModel.TableInfoWithName<DataModel_, TableName>>[IndexName]
+    >,
+  ): Effect.Effect<
+    DataModel.DocumentWithName<DataModel_, TableName>,
+    Document.DocumentDecodeError | GetByIndexFailure
+  > => {
+    const indexFieldPaths: GenericTableIndexes[keyof GenericTableIndexes] = (
+      table.indexes as GenericTableIndexes
+    )[indexName as keyof GenericTableIndexes]!;
+
+    return pipe(
+      Effect.promise(() =>
+        convexDatabaseReader
+          .query(tableName)
+          .withIndex(indexName, (q) =>
+            Array.reduce(
+              indexFieldValues,
+              q,
+              (q_, v, i) => q_.eq(indexFieldPaths[i] as any, v as any) as any,
+            ),
+          )
+          .unique(),
+      ),
+      Effect.andThen((value) =>
+        Effect.fromResult(
+          Result.fromNullishOr(
+            value,
+            () =>
+              new GetByIndexFailure({
+                tableName,
+                indexName: indexName as string,
+                indexFieldValues,
+              }),
+          ),
+        ),
+      ),
+      Effect.andThen(Document.decode(table)),
+    );
+  };
+
+  const get: QueryInitializerFunction<"get"> = ((
+    ...args: Parameters<QueryInitializerFunction<"get">>
+  ) => {
+    if (args.length === 1) {
+      const id = args[0] as GenericId<TableName>;
+
+      return getById<Tables, TableName>(convexDatabaseReader, table)(id);
+    } else {
+      const [indexName, ...indexFieldValues] = args;
+
+      return getByIndex(
+        indexName as keyof Indexes<
+          DataModel.TableInfoWithName<DataModel_, TableName>
+        >,
+        indexFieldValues,
+      );
+    }
+  }) as QueryInitializerFunction<"get">;
+
+  const index: QueryInitializerFunction<"index"> = <
+    IndexName extends keyof Indexes<
+      DataModel.TableInfoWithName<DataModel_, TableName>
+    >,
+  >(
+    indexName: IndexName,
+    indexRangeOrOrder?:
+      | ((
+          q: IndexRangeBuilder<
+            DataModel.TableInfoWithName_<
+              DataModel_,
+              TableName
+            >["convexDocument"],
+            NamedIndex<
+              DataModel.TableInfoWithName<DataModel_, TableName>,
+              IndexName
+            >
+          >,
+        ) => IndexRange)
+      | OrderDirection,
+    order?: OrderDirection,
+  ) => {
+    const {
+      applyWithIndex,
+      applyOrder,
+    }: {
+      applyWithIndex: (
+        queryInitializer: ConvexQueryInitializer<
+          NamedTableInfo<ConvexDataModel_, TableName>
+        >,
+      ) => Query<NamedTableInfo<ConvexDataModel_, TableName>>;
+      applyOrder: (
+        query: Query<NamedTableInfo<ConvexDataModel_, TableName>>,
+      ) => ConvexOrderedQuery<NamedTableInfo<ConvexDataModel_, TableName>>;
+    } =
+      indexRangeOrOrder === undefined
+        ? {
+            applyWithIndex: (q) => q.withIndex(indexName),
+            applyOrder: (q) => q.order("asc"),
+          }
+        : typeof indexRangeOrOrder === "function"
+          ? order === undefined
+            ? {
+                applyWithIndex: (q) =>
+                  q.withIndex(indexName, indexRangeOrOrder),
+                applyOrder: (q) => q.order("asc"),
+              }
+            : {
+                applyWithIndex: (q) =>
+                  q.withIndex(indexName, indexRangeOrOrder),
+                applyOrder: (q) => q.order(order),
+              }
+          : {
+              applyWithIndex: (q) => q.withIndex(indexName),
+              applyOrder: (q) => q.order(indexRangeOrOrder),
+            };
+
+    const orderedQuery = pipe(
+      convexDatabaseReader.query(tableName),
+      applyWithIndex,
+      applyOrder,
+    );
+
+    return OrderedQuery.make(orderedQuery, table);
+  };
+
+  const stream: QueryInitializerFunction<"stream"> = ((
+    indexName: string,
+    indexRangeOrOrder?:
+      | ((
+          q: QueryStreamIndexRange.Builder<any, any>,
+        ) => QueryStreamIndexRange.QueryStreamIndexRange)
+      | OrderDirection,
+    maybeOrder?: OrderDirection,
+  ) => {
+    const orderDirection = Predicate.isString(indexRangeOrOrder)
+      ? indexRangeOrOrder
+      : (maybeOrder ?? "asc");
+
+    // Without a range callback, the leaf scans the entire index.
+    const indexRange = Predicate.isFunction(indexRangeOrOrder)
+      ? indexRangeOrOrder(QueryStreamIndexRange.builder())
+      : QueryStreamIndexRange.builder();
+
+    // The type-level field tuple appends the `_creationTime` tiebreaker, but
+    // the runtime `table.indexes` record stores only the declared fields—append it here.
+    const indexFieldPaths: ReadonlyArray<string> =
+      indexName === "by_id"
+        ? ["_id"]
+        : indexName === "by_creation_time"
+          ? ["_creationTime"]
+          : pipe(
+              Option.fromUndefinedOr(
+                (
+                  table.indexes as ReadonlyRecord<string, ReadonlyArray<string>>
+                )[indexName],
+              ),
+              // An unknown index name is a defect, not an empty field list:
+              // silently empty fields would make key extraction and range
+              // splitting target the wrong fields.
+              Option.getOrThrowWith(
+                () =>
+                  new Error(
+                    `QueryInitializer.stream: table "${tableName}" has no index named "${indexName}"`,
+                  ),
+              ),
+              Array.append("_creationTime"),
+            );
+
+    return QueryStream.fromReflection({
+      reader: convexDatabaseReader as QueryStream.ReflectionReader,
+      table,
+      indexName,
+      indexFieldPaths,
+      indexRange,
+      orderDirection,
+    });
+  }) as QueryInitializerFunction<"stream">;
+
+  const search: QueryInitializerFunction<"search"> = (
+    indexName,
+    searchFilter,
+  ) =>
+    OrderedQuery.make(
+      convexDatabaseReader
+        .query(tableName)
+        .withSearchIndex(indexName, searchFilter),
+      table,
+    );
+
+  return {
+    get,
+    index,
+    search,
+    stream,
+  };
+}
+
+export const getById =
+  <Tables extends Table.AnyWithProps, TableName extends Table.Name<Tables>>(
+    convexDatabaseReader: BaseDatabaseReader<
+      DataModel.ToConvex<DataModel.FromTables<Tables>>
+    >,
+    table: Table.WithName<Tables, TableName>,
+  ) =>
+  (id: GenericId<TableName>) =>
+    pipe(
+      Effect.promise(() => convexDatabaseReader.get(id)),
+      Effect.andThen((value) =>
+        Effect.fromResult(
+          Result.fromNullishOr(
+            value,
+            () => new GetByIdFailure({ tableName: table.tableName, id }),
+          ),
+        ),
+      ),
+      Effect.andThen(Document.decode(table)),
+    );
+
+export class GetByIdFailure extends Schema.TaggedError<GetByIdFailure>()(
+  "GetByIdFailure",
+  {
+    id: Schema.String,
+    tableName: Schema.String,
+  },
+) {
+  override get message(): string {
+    return Document.documentErrorMessage({
+      id: this.id,
+      tableName: this.tableName,
+      message: "not found",
+    });
+  }
+}
+
+export class GetByIndexFailure extends Schema.TaggedError<GetByIndexFailure>()(
+  "GetByIndexFailure",
+  {
+    tableName: Schema.String,
+    indexName: Schema.String,
+    indexFieldValues: Schema.Array(Schema.Unknown),
+  },
+) {
+  override get message(): string {
+    return `No documents found in table '${this.tableName}' with index '${this.indexName}' and field values '${JSON.stringify(
+      this.indexFieldValues,
+      (_key, value) => (typeof value === "bigint" ? value.toString() : value),
+    )}'`;
+  }
+}

package/src/QueryRunner.ts

@@ -0,0 +1,91 @@
+import * as Ref from "@confect/core/Ref";
+import type { GenericActionCtx } from "convex/server";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Schema from "effect/Schema";
+import * as MutationTransactionContext from "./MutationTransactionContext.js";
+import * as QueryTransactionContext from "./QueryTransactionContext.js";
+
+export type Options = MutationTransactionContext.QueryOptions;
+
+const run = Effect.fn("QueryRunner.runQuery")(
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> => effect,
+);
+
+const make = (nativeRunQuery: GenericActionCtx<any>["runQuery"]) => {
+  function runQuery<Query extends Ref.AnyQuery>(
+    query: Query,
+    ...args: [...Ref.OptionalArgs<Query>, options?: undefined]
+  ): Effect.Effect<Ref.Returns<Query>, Ref.Error<Query> | Schema.SchemaError>;
+  function runQuery<Query extends Ref.AnyQuery>(
+    query: Query,
+    args: Ref.Args<Query>,
+    options:
+      | (QueryTransactionContext.Options & {
+          readonly useStaleSnapshot?: never;
+        })
+      | undefined,
+  ): Effect.Effect<
+    Ref.Returns<Query>,
+    Ref.Error<Query> | Schema.SchemaError,
+    QueryTransactionContext.QueryTransactionContext
+  >;
+  function runQuery<Query extends Ref.AnyQuery>(
+    query: Query,
+    args: Ref.Args<Query>,
+    options: Options & { readonly useStaleSnapshot: boolean },
+  ): Effect.Effect<
+    Ref.Returns<Query>,
+    Ref.Error<Query> | Schema.SchemaError,
+    MutationTransactionContext.MutationTransactionContext
+  >;
+  function runQuery<Query extends Ref.AnyQuery>(
+    query: Query,
+    args: Ref.Args<Query>,
+    options: Options | undefined,
+  ): Effect.Effect<
+    Ref.Returns<Query>,
+    Ref.Error<Query> | Schema.SchemaError,
+    | QueryTransactionContext.QueryTransactionContext
+    | MutationTransactionContext.MutationTransactionContext
+  >;
+  function runQuery<Query extends Ref.AnyQuery>(
+    query: Query,
+    args?: Ref.Args<Query>,
+    options?: Options,
+  ): Effect.Effect<
+    Ref.Returns<Query>,
+    Ref.Error<Query> | Schema.SchemaError,
+    | QueryTransactionContext.QueryTransactionContext
+    | MutationTransactionContext.MutationTransactionContext
+  > {
+    return run(
+      Effect.gen(function* () {
+        const actualArgs = (args ?? {}) as Ref.Args<Query>;
+        if (options?.useStaleSnapshot !== undefined) {
+          const controls =
+            yield* MutationTransactionContext.MutationTransactionContext;
+          return yield* controls.runQuery(query, actualArgs, options);
+        }
+        if (options !== undefined) {
+          const controls =
+            yield* QueryTransactionContext.QueryTransactionContext;
+          return yield* controls.runQuery(query, actualArgs, options);
+        }
+        return yield* Ref.runWithCodec(query, actualArgs, (ref, encodedArgs) =>
+          nativeRunQuery(ref, encodedArgs),
+        );
+      }),
+    );
+  }
+  return { runQuery };
+};
+
+export const QueryRunner = Context.Service<ReturnType<typeof make>>(
+  "@confect/server/QueryRunner",
+);
+export type QueryRunner = typeof QueryRunner.Identifier;
+
+export const layer = (runQuery: GenericActionCtx<any>["runQuery"]) =>
+  Layer.succeed(QueryRunner, make(runQuery));