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

package/src/QueryStreamPagination.ts

@@ -0,0 +1,357 @@
+import * as Chunk from "effect/Chunk";
+import * as Data from "effect/Data";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import type * as QueryStreamKey from "./QueryStreamKey.js";
+import * as QueryStreamKeyValues from "./QueryStreamKeyValues.js";
+
+const PageSize = Schema.Natural.pipe(
+  Schema.brand("~@confect/server/QueryStreamPagination/PageSize"),
+);
+type PageSize = typeof PageSize.Type;
+
+/**
+ * @experimental
+ */
+export class InvalidPageSizeError extends Data.TaggedError(
+  "InvalidPageSizeError",
+)<{
+  readonly numItems: number;
+}> {
+  override get message(): string {
+    return `QueryStream.paginate: numItems must be a nonnegative integer (received ${this.numItems})`;
+  }
+}
+
+/**
+ * @experimental
+ */
+export class EmptyInitialPageError extends Data.TaggedError(
+  "EmptyInitialPageError",
+) {
+  override get message(): string {
+    return "QueryStream.paginate: numItems of 0 with a null cursor is not supported";
+  }
+}
+
+/**
+ * @experimental
+ */
+export type Range = Data.TaggedEnum<{
+  Unpinned: {};
+  ThroughKey: { readonly key: QueryStreamKey.Complete };
+  ThroughEnd: {};
+}>;
+/**
+ * @experimental
+ */
+export const Range = Data.taggedEnum<Range>();
+
+/**
+ * @experimental
+ */
+export type Start = Data.TaggedEnum<{
+  Beginning: {};
+  After: {
+    readonly key: QueryStreamKey.Complete;
+    readonly cursor: string;
+  };
+}>;
+/**
+ * @experimental
+ */
+export const Start = Data.taggedEnum<Start>();
+
+/**
+ * @experimental
+ */
+export interface ScanRequest {
+  readonly numItems: PageSize;
+  readonly after: Option.Option<QueryStreamKey.Complete>;
+  readonly range: Range;
+}
+
+/**
+ * @experimental
+ */
+export type Request = Data.TaggedEnum<{
+  Unchanged: { readonly cursor: string };
+  Scan: ScanRequest;
+}>;
+const Request = Data.taggedEnum<Request>();
+
+/**
+ * @experimental
+ */
+export const parseRequest = (
+  numItems: number,
+  start: Start,
+  range: Range,
+): Result.Result<Request, InvalidPageSizeError | EmptyInitialPageError> =>
+  Result.flatMap(
+    Schema.decodeResult(PageSize)(numItems).pipe(
+      Result.mapError(() => new InvalidPageSizeError({ numItems })),
+    ),
+    (size): Result.Result<Request, EmptyInitialPageError> =>
+      size === 0
+        ? Start.$match(start, {
+            Beginning: () => Result.fail(new EmptyInitialPageError()),
+            After: ({ cursor }) =>
+              Result.succeed(Request.Unchanged({ cursor })),
+          })
+        : Result.succeed(
+            Request.Scan({
+              numItems: size,
+              after: Start.$match(start, {
+                Beginning: () => Option.none(),
+                After: ({ key }) => Option.some(key),
+              }),
+              range,
+            }),
+          ),
+  );
+
+/**
+ * A nonempty scan, including filtered markers.
+ */
+type Progress = Chunk.NonEmptyChunk<QueryStreamKey.Complete>;
+const append = (
+  progress: Option.Option<Progress>,
+  key: QueryStreamKey.Complete,
+): Progress =>
+  Option.match(progress, {
+    onNone: () => Chunk.of(key),
+    onSome: (keys) => Chunk.append(keys, key),
+  });
+const midpoint = (progress: Progress): QueryStreamKey.Complete =>
+  Option.getOrElse(
+    Chunk.get(progress, Math.floor((Chunk.size(progress) - 1) / 2)),
+    () => Chunk.headNonEmpty(progress),
+  );
+
+interface Stopped<Doc> {
+  readonly page: Chunk.Chunk<Doc>;
+  readonly progress: Progress;
+}
+
+/**
+ * @experimental
+ */
+export type QueryStreamPagination<Doc> = Data.TaggedEnum<{
+  Reading: {
+    readonly page: Chunk.Chunk<Doc>;
+    readonly progress: Option.Option<Progress>;
+  };
+  ItemLimit: Stopped<Doc>;
+  ReadLimit: Stopped<Doc>;
+}>;
+interface PaginationDefinition extends Data.TaggedEnum.WithGenerics<1> {
+  readonly taggedEnum: QueryStreamPagination<this["A"]>;
+}
+const QueryStreamPagination = Data.taggedEnum<PaginationDefinition>();
+
+/**
+ * @experimental
+ */
+export const initial = <Doc>(): QueryStreamPagination<Doc> =>
+  QueryStreamPagination.Reading({
+    page: Chunk.empty<Doc>(),
+    progress: Option.none(),
+  });
+
+/**
+ * @experimental
+ */
+export const record = <Doc>(
+  request: ScanRequest,
+  self: QueryStreamPagination<Doc>,
+  doc: Option.Option<Doc>,
+  key: QueryStreamKey.Complete,
+  readLimit: boolean,
+): QueryStreamPagination<Doc> =>
+  Match.value(self).pipe(
+    Match.tagsExhaustive({
+      Reading: (reading) => {
+        const progress = append(reading.progress, key);
+        const page = Option.match(doc, {
+          onNone: () => reading.page,
+          onSome: (value) => Chunk.append(reading.page, value),
+        });
+        const continueReading = () =>
+          QueryStreamPagination.Reading({
+            page,
+            progress: Option.some(progress),
+          });
+        return readLimit
+          ? QueryStreamPagination.ReadLimit({ page, progress })
+          : Range.$match(request.range, {
+              Unpinned: () =>
+                Chunk.size(page) >= request.numItems
+                  ? QueryStreamPagination.ItemLimit({ page, progress })
+                  : continueReading(),
+              ThroughKey: continueReading,
+              ThroughEnd: continueReading,
+            });
+      },
+      ItemLimit: () => self,
+      ReadLimit: () => self,
+    }),
+  );
+
+/**
+ * @experimental
+ */
+export type Continuation = Data.TaggedEnum<{
+  End: {};
+  Key: { readonly key: QueryStreamKey.Complete };
+}>;
+const Continuation = Data.taggedEnum<Continuation>();
+
+interface Split<Doc> {
+  readonly page: ReadonlyArray<Doc>;
+  readonly continuation: Continuation;
+  readonly splitKey: QueryStreamKey.Complete;
+}
+
+/**
+ * @experimental
+ */
+export type Outcome<Doc> = Data.TaggedEnum<{
+  Done: { readonly page: ReadonlyArray<Doc> };
+  Continue: {
+    readonly page: ReadonlyArray<Doc>;
+    readonly key: QueryStreamKey.Complete;
+  };
+  SplitRequired: Split<Doc>;
+  SplitRecommended: Split<Doc>;
+}>;
+
+/**
+ * @experimental
+ */
+export class UnsafePageBoundaryError extends Data.TaggedError(
+  "UnsafePageBoundaryError",
+)<{
+  readonly reason: "NoProgress" | "NoInteriorSplit";
+}> {
+  override get message(): string {
+    return Match.value(this.reason).pipe(
+      Match.when(
+        "NoProgress",
+        () => "The read budget stopped the page before any key was scanned",
+      ),
+      Match.when(
+        "NoInteriorSplit",
+        () => "The read budget stopped the page without an interior split key",
+      ),
+      Match.exhaustive,
+    );
+  }
+}
+
+const SOFT_MAX_SCAN_LENGTH = 16000;
+
+/**
+ * Decide the page result without reading a stream or serializing a cursor.
+ *
+ * @experimental
+ */
+export const finish = <Doc>(
+  request: ScanRequest,
+  self: QueryStreamPagination<Doc>,
+  upstreamStopped: boolean,
+): Result.Result<Outcome<Doc>, UnsafePageBoundaryError> => {
+  const page = Chunk.toArray(self.page);
+  const stopped = (
+    progress: Option.Option<Progress>,
+    readLimit: boolean,
+  ): Result.Result<Outcome<Doc>, UnsafePageBoundaryError> =>
+    Result.flatMap(
+      Result.fromOption(
+        progress,
+        () => new UnsafePageBoundaryError({ reason: "NoProgress" }),
+      ),
+      (scanned): Result.Result<Outcome<Doc>, UnsafePageBoundaryError> => {
+        const splitKey = midpoint(scanned);
+        const atEnd = Range.$match(request.range, {
+          Unpinned: () => false,
+          ThroughEnd: () => false,
+          ThroughKey: ({ key }) =>
+            QueryStreamKeyValues.Order("asc")(splitKey.values, key.values) ===
+            0,
+        });
+        if (readLimit && atEnd) {
+          return Result.fail(
+            new UnsafePageBoundaryError({ reason: "NoInteriorSplit" }),
+          );
+        }
+        const key = Chunk.lastNonEmpty(scanned);
+        if (readLimit)
+          return Result.succeed({
+            _tag: "SplitRequired",
+            page,
+            continuation: Continuation.Key({ key }),
+            splitKey,
+          });
+        return Result.succeed(
+          Chunk.size(scanned) >= SOFT_MAX_SCAN_LENGTH
+            ? {
+                _tag: "SplitRecommended",
+                page,
+                continuation: Continuation.Key({ key }),
+                splitKey,
+              }
+            : { _tag: "Continue", page, key },
+        );
+      },
+    );
+  const exhausted = (progress: Option.Option<Progress>): Outcome<Doc> => {
+    const finishRange = (
+      continuation: Continuation,
+      pinned: boolean,
+    ): Outcome<Doc> => {
+      const split = Option.filter(
+        progress,
+        (scanned) =>
+          pinned &&
+          (Chunk.size(scanned) >= SOFT_MAX_SCAN_LENGTH ||
+            page.length > request.numItems + 1),
+      );
+      return Option.match(split, {
+        onSome: (scanned): Outcome<Doc> => ({
+          _tag: "SplitRecommended",
+          page,
+          continuation,
+          splitKey: midpoint(scanned),
+        }),
+        onNone: () =>
+          Continuation.$match(continuation, {
+            End: (): Outcome<Doc> => ({ _tag: "Done", page }),
+            Key: ({ key }): Outcome<Doc> => ({
+              _tag: "Continue",
+              page,
+              key,
+            }),
+          }),
+      });
+    };
+    return Range.$match(request.range, {
+      Unpinned: () => finishRange(Continuation.End(), false),
+      ThroughEnd: () => finishRange(Continuation.End(), true),
+      ThroughKey: ({ key }) => finishRange(Continuation.Key({ key }), true),
+    });
+  };
+  return Match.value(self).pipe(
+    Match.tagsExhaustive({
+      Reading: ({ progress }) =>
+        upstreamStopped
+          ? stopped(progress, true)
+          : Result.succeed(exhausted(progress)),
+      ItemLimit: ({ progress }) =>
+        stopped(Option.some(progress), upstreamStopped),
+      ReadLimit: ({ progress }) => stopped(Option.some(progress), true),
+    }),
+  );
+};

package/src/QueryStreamReadBudget.ts

@@ -0,0 +1,167 @@
+import type { GenericDocument } from "convex/server";
+import { getDocumentSize } from "convex/values";
+import * as Array from "effect/Array";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type * as Pull from "effect/Pull";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+import * as Tuple from "effect/Tuple";
+
+/**
+ * @experimental
+ */
+export interface QueryStreamReadBudget {
+  readonly isUnlimited: Effect.Effect<boolean>;
+  readonly isStopped: Effect.Effect<boolean>;
+  readonly isExhausted: Effect.Effect<boolean>;
+  readonly getReadCounts: Effect.Effect<ReadCounts>;
+  /**
+   * Returns a stream that records reads against this budget and stops
+   * requesting further batches once exhausted. Apply directly to the document
+   * source before buffering, filtering, or combining its output.
+   */
+  readonly accountFor: (
+    encodedDocuments: Stream.Stream<unknown>,
+  ) => Stream.Stream<unknown>;
+}
+
+const ReadLimit = Schema.Natural.pipe(
+  Schema.brand("~@confect/server/QueryStreamReadBudget/ReadLimit"),
+);
+
+/**
+ * @experimental
+ */
+export const Limits = Schema.Struct({
+  maximumRowsRead: Schema.OptionFromOptionalKey(ReadLimit),
+  maximumBytesRead: Schema.OptionFromOptionalKey(ReadLimit),
+});
+/**
+ * @experimental
+ */
+export type Limits = typeof Limits.Type;
+
+/**
+ * @experimental
+ */
+export class InvalidReadLimitError extends Data.TaggedError(
+  "InvalidReadLimitError",
+)<{
+  readonly cause: Schema.SchemaError;
+}> {
+  override get message(): string {
+    return `Invalid read limits: ${this.cause.message}`;
+  }
+}
+
+/**
+ * @experimental
+ */
+export interface ReadCounts {
+  readonly rowsRead: number;
+  readonly bytesRead: number;
+}
+
+type State = Data.TaggedEnum<{
+  Active: ReadCounts;
+  Stopped: ReadCounts;
+}>;
+
+const State = Data.taggedEnum<State>();
+
+/**
+ * @experimental
+ */
+export const QueryStreamReadBudget = Context.Service<QueryStreamReadBudget>(
+  "@confect/server/QueryStreamReadBudget",
+);
+
+const isExhausted = (state: State, limits: Limits): boolean =>
+  State.$match(state, {
+    Stopped: () => true,
+    Active: ({ rowsRead, bytesRead }) =>
+      Option.exists(limits.maximumRowsRead, (limit) => rowsRead >= limit) ||
+      Option.exists(limits.maximumBytesRead, (limit) => bytesRead >= limit),
+  });
+
+const readCounts = ({ rowsRead, bytesRead }: ReadCounts): ReadCounts => ({
+  rowsRead,
+  bytesRead,
+});
+
+const record = (
+  counts: ReadCounts,
+  documents: Array.NonEmptyReadonlyArray<unknown>,
+): ReadCounts => ({
+  rowsRead: counts.rowsRead + documents.length,
+  bytesRead: Array.reduce(
+    documents,
+    counts.bytesRead,
+    (bytes, document) => bytes + getDocumentSize(document as GenericDocument),
+  ),
+});
+
+/**
+ * @experimental
+ */
+export const make = Effect.fnUntraced(function* (
+  limits: Limits,
+): Effect.fn.Return<QueryStreamReadBudget> {
+  const unlimited =
+    Option.isNone(limits.maximumRowsRead) &&
+    Option.isNone(limits.maximumBytesRead);
+  const stateRef = yield* SynchronizedRef.make<State>(
+    State.Active({ rowsRead: 0, bytesRead: 0 }),
+  );
+  const accountForPull: (
+    pull: Pull.Pull<Array.NonEmptyReadonlyArray<unknown>>,
+  ) => Pull.Pull<Array.NonEmptyReadonlyArray<unknown>> = unlimited
+    ? (pull) =>
+        Effect.uninterruptibleMask((restore) =>
+          Effect.tap(restore(pull), (documents) =>
+            SynchronizedRef.update(stateRef, (state) =>
+              State.Active(record(state, documents)),
+            ),
+          ),
+        )
+    : (pull) =>
+        SynchronizedRef.modifyEffect(stateRef, (state) =>
+          Effect.gen(function* () {
+            if (isExhausted(state, limits)) {
+              return Tuple.make(
+                Option.none(),
+                State.Stopped(readCounts(state)),
+              );
+            }
+            const documents = yield* pull;
+            return Tuple.make(
+              Option.some(documents),
+              State.Active(record(state, documents)),
+            );
+          }),
+        ).pipe(
+          Effect.flatMap(
+            Option.match({
+              onNone: () => Cause.done(),
+              onSome: Effect.succeed,
+            }),
+          ),
+        );
+  return QueryStreamReadBudget.of({
+    isUnlimited: Effect.succeed(unlimited),
+    isStopped: Effect.map(SynchronizedRef.get(stateRef), State.$is("Stopped")),
+    isExhausted: Effect.map(SynchronizedRef.get(stateRef), (state) =>
+      isExhausted(state, limits),
+    ),
+    getReadCounts: Effect.map(SynchronizedRef.get(stateRef), readCounts),
+    accountFor: (encodedDocuments) =>
+      Stream.transformPull(encodedDocuments, (pull) =>
+        Effect.succeed(accountForPull(pull)),
+      ).pipe(Stream.scoped),
+  });
+});

package/src/QueryTransactionContext.ts

@@ -0,0 +1,37 @@
+import * as Ref from "@confect/core/Ref";
+import type {
+  GenericDataModel,
+  GenericQueryCtx,
+  TransactionLimits,
+} from "convex/server";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+export type { TransactionLimits } from "convex/server";
+
+export interface Options {
+  readonly transactionLimits?: TransactionLimits;
+}
+
+const make = (ctx: Pick<GenericQueryCtx<GenericDataModel>, "runQuery">) => ({
+  runQuery: Effect.fn("QueryTransactionContext.runQuery")(
+    <Query extends Ref.AnyQuery>(
+      query: Query,
+      args: Ref.Args<Query>,
+      options: Options,
+    ) =>
+      Ref.runWithCodec(query, args, (ref, encodedArgs) =>
+        ctx.runQuery(ref, encodedArgs, options),
+      ),
+  ),
+});
+
+export class QueryTransactionContext extends Context.Service<
+  QueryTransactionContext,
+  ReturnType<typeof make>
+>()("@confect/server/QueryTransactionContext") {}
+
+export const layer = (
+  ctx: Pick<GenericQueryCtx<GenericDataModel>, "runQuery">,
+) => Layer.succeed(QueryTransactionContext, make(ctx));