@gaganref/confect-test 10.3.1-fork.87 → 10.3.1-fork.89

package/src/internal/Attempt.ts

@@ -0,0 +1,185 @@
+// oxlint-disable-next-line effecttsgo/node-builtin-import -- The drain waits a real turn of the event loop. Fake timers in a test replace the global `setImmediate`, not this one.
+import { setImmediate } from "node:timers/promises";
+import type { Attempt as AttemptNumber } from "./Invocation.js";
+import * as Kernel from "./Kernel.js";
+import type { DocumentId, StoredDocument } from "./KernelValues.js";
+import { tableNameFromId } from "./KernelValues.js";
+import type * as ReadSet from "./ReadSet.js";
+
+/**
+ * Pending writes, keyed by component path, then document ID. `null` deletes.
+ */
+type Overlay = Map<string, Map<DocumentId, StoredDocument | null>>;
+
+/**
+ * How long one frame takes syscalls: those it has running, those it has
+ * started, and whether it still takes them.
+ */
+interface Life {
+  running: number;
+  started: number;
+  open: boolean;
+}
+
+/**
+ * One frame of an attempt at a query or mutation: the committed state the
+ * attempt started from, its caller's frame and its own pending writes. The
+ * outermost frame belongs to the top-level function. Each nested mutation opens
+ * a child frame, which merges into its caller's frame when it returns and is
+ * dropped when it fails. Reads belong to the whole attempt and are never
+ * dropped: a failed nested mutation's reads stay in the attempt.
+ *
+ * Each frame has its own lifetime. A frame takes reads and writes until it is
+ * closed. A mutation's frame closes once its function has returned and no
+ * syscall it started is still running, so a write a detached fiber makes after
+ * the handler settled still lands in it, as on the binary. A nested mutation's
+ * frame closes before it merges into its caller's, so no write reaches it after
+ * its writes became its caller's.
+ *
+ * A frame belongs to one invocation, which alone writes to it, so a caller's
+ * write made while its nested mutation is in flight stays the caller's.
+ * `Kernel.apply` publishes the outermost frame's writes.
+ */
+export class KernelAttempt {
+  private readonly overlay: Overlay = new Map();
+  private readonly life: Life = { running: 0, started: 0, open: true };
+  private readonly allReads: Array<ReadSet.Read>;
+
+  constructor(
+    readonly snapshot: Kernel.State,
+    readonly number: AttemptNumber = 1,
+    private readonly parent?: KernelAttempt,
+  ) {
+    this.allReads = parent?.allReads ?? [];
+  }
+
+  get reads(): ReadonlyArray<ReadSet.Read> {
+    return this.allReads;
+  }
+
+  get closed(): boolean {
+    return !this.life.open;
+  }
+
+  readDocument(componentPath: string, id: DocumentId) {
+    this.allReads.push({ kind: "document", componentPath, id });
+  }
+
+  /**
+   * Record a read of an interval. The returned function advances how far the
+   * query examined it.
+   */
+  readInterval(
+    read: Omit<ReadSet.IntervalRead, "through">,
+  ): (through: ReadSet.Key | "end") => void {
+    const interval: ReadSet.IntervalRead = { ...read, through: null };
+    this.allReads.push(interval);
+    return (through) => {
+      interval.through = through;
+    };
+  }
+
+  /**
+   * A syscall began. `end` runs when it settles.
+   */
+  begin(): () => void {
+    const life = this.life;
+    life.running++;
+    life.started++;
+    return () => {
+      life.running--;
+    };
+  }
+
+  /**
+   * Resolves once a whole turn of the event loop passes with no syscall of this
+   * frame running or started. A nested call is a syscall of its caller's frame
+   * until it has drained.
+   */
+  drained(): Promise<void> {
+    const before = this.life.started;
+    return setImmediate().then(() =>
+      this.life.running === 0 && this.life.started === before
+        ? undefined
+        : this.drained(),
+    );
+  }
+
+  close() {
+    this.life.open = false;
+  }
+
+  /**
+   * The pending writes this frame sees, from the outermost frame to this one.
+   */
+  private overlays(): Array<Overlay> {
+    return this.parent === undefined
+      ? [this.overlay]
+      : [...this.parent.overlays(), this.overlay];
+  }
+
+  get(componentPath: string, id: DocumentId): StoredDocument | null {
+    for (const overlay of this.overlays().toReversed()) {
+      const write = overlay.get(componentPath)?.get(id);
+      if (write !== undefined) return write;
+    }
+    return Kernel.get(this.snapshot, componentPath, id)?.doc ?? null;
+  }
+
+  /**
+   * The table as this frame sees it, committed rows under every pending write
+   * from the outermost frame to this one.
+   */
+  scan(componentPath: string, tableName: string): Array<StoredDocument> {
+    const ids = new Set<DocumentId>();
+    for (const row of Kernel.rows(this.snapshot, componentPath, tableName))
+      ids.add(row.doc._id);
+    for (const overlay of this.overlays())
+      for (const id of overlay.get(componentPath)?.keys() ?? [])
+        if (tableNameFromId(id) === tableName) ids.add(id);
+    const docs: Array<StoredDocument> = [];
+    for (const id of ids) {
+      const doc = this.get(componentPath, id);
+      if (doc !== null) docs.push(doc);
+    }
+    return docs;
+  }
+
+  write(componentPath: string, id: DocumentId, doc: StoredDocument | null) {
+    const writes = this.overlay.get(componentPath) ?? new Map();
+    this.overlay.set(componentPath, writes);
+    writes.set(id, doc);
+  }
+
+  /**
+   * A nested mutation begins, in a frame of its own. Dropping a failed one is
+   * forgetting it.
+   */
+  child(): KernelAttempt {
+    return new KernelAttempt(this.snapshot, this.number, this);
+  }
+
+  /**
+   * A nested mutation returned and its frame closed. Its writes become its
+   * caller's.
+   */
+  merge() {
+    if (this.parent === undefined) {
+      throw new Error("The outermost frame of an attempt has no caller.");
+    }
+    if (this.life.open) {
+      throw new Error("A nested mutation's frame merges only once closed.");
+    }
+    for (const [componentPath, writes] of this.overlay)
+      for (const [id, doc] of writes) this.parent.write(componentPath, id, doc);
+  }
+
+  /**
+   * The outermost frame's writes, for `Kernel.apply`.
+   */
+  writes(): Array<Kernel.Write> {
+    return Array.from(this.overlay, ([componentPath, writes]) =>
+      Array.from(writes, ([id, doc]) => ({ componentPath, id, doc })),
+    ).flat();
+  }
+}

package/src/internal/ConvexTest.ts

@@ -0,0 +1,118 @@
+import type {
+  GenericSchema,
+  SchemaDefinition,
+  UserIdentity,
+} from "convex/server";
+import { componentsGeneric } from "convex/server";
+import * as Execution from "./Execution.js";
+import type * as Kernel from "./Kernel.js";
+import * as KernelRefusal from "./KernelRefusal.js";
+
+type Modules = Record<string, () => Promise<any>>;
+
+/**
+ * What the kernel adds to convex-test's surface, typed. The shim itself returns
+ * `any`, as convex-test's callers expect.
+ */
+export interface KernelControls {
+  readonly query: (reference: any, args?: any) => Promise<any>;
+  readonly mutation: (reference: any, args?: any) => Promise<any>;
+  readonly action: (reference: any, args?: any) => Promise<any>;
+  readonly prepare: (
+    reference: any,
+    args?: any,
+  ) => Promise<Execution.HeldAttempt>;
+  readonly apply: (id: string) => Promise<Execution.KernelApply>;
+  readonly held: () => ReadonlyArray<Execution.HeldAttempt>;
+}
+
+const isSchemaDefinition = (
+  value: unknown,
+): value is SchemaDefinition<GenericSchema, boolean> =>
+  value !== null &&
+  typeof value === "object" &&
+  "tables" in value &&
+  typeof (value as { tables: unknown }).tables === "object";
+
+const accessor = (world: Execution.World, caller: Execution.Caller): any => ({
+  query: (reference: any, args?: any) => world.query(caller, reference, args),
+  mutation: (reference: any, args?: any) =>
+    world.mutation(caller, reference, args),
+  action: (reference: any, args?: any) => world.action(caller, reference, args),
+  prepare: (reference: any, args?: any) =>
+    world.prepare(caller, reference, args),
+  apply: (id: string) => world.apply(id),
+  held: () => world.held(),
+  run: (handler: (ctx: any) => any) => world.run(caller, "", handler),
+  runInComponent: (componentPath: string, handler: (ctx: any) => any) =>
+    world.run(caller, componentPath, handler),
+  withIdentity: (identity: Partial<UserIdentity>) =>
+    accessor(world, Execution.withIdentity(caller, identity)),
+  withRequestMetadata: (metadata: {
+    readonly ip?: string | null;
+    readonly userAgent?: string | null;
+  }) =>
+    accessor(world, {
+      ...caller,
+      ip: metadata.ip ?? null,
+      userAgent: metadata.userAgent ?? null,
+    }),
+  fetch: () => Promise.reject(KernelRefusal.rowPending("HTTP routes", 6)),
+  jwks: () => Promise.reject(KernelRefusal.rowPending("JWT verification", 6)),
+  finishInProgressScheduledFunctions: () =>
+    Promise.reject(KernelRefusal.rowPending("the scheduler", 5)),
+  finishAllScheduledFunctions: () =>
+    Promise.reject(KernelRefusal.rowPending("the scheduler", 5)),
+});
+
+/**
+ * The test kernel under convex-test's `convexTest` signature. The fork's kernel
+ * lane aliases `convex-test` to this module, so every suite that calls
+ * `convexTest` directly, and `TestConfect` itself, runs on the kernel.
+ *
+ * Beyond convex-test, `prepare` runs a mutation to its commit point and holds
+ * it, and `apply` validates and publishes a held attempt. `mutation` applies
+ * each attempt it prepares at once and prepares the next on a conflict, up to
+ * attempt 5. `runtime` supplies the clock and commit timestamps.
+ */
+export function convexTest(
+  schemaOrOptions?:
+    | SchemaDefinition<GenericSchema, boolean>
+    | {
+        readonly schema?: SchemaDefinition<GenericSchema, boolean>;
+        readonly modules?: Modules;
+        readonly transactionLimits?: unknown;
+        readonly runtime?: Kernel.KernelRuntime;
+      },
+  modules?: Modules,
+): any {
+  let schema: SchemaDefinition<GenericSchema, boolean> | undefined;
+  let runtime: Kernel.KernelRuntime | undefined;
+  if (isSchemaDefinition(schemaOrOptions)) {
+    schema = schemaOrOptions;
+  } else if (schemaOrOptions !== undefined) {
+    if (schemaOrOptions.transactionLimits !== undefined) {
+      throw KernelRefusal.rowPending("transaction limits", 6);
+    }
+    schema = schemaOrOptions.schema;
+    modules = schemaOrOptions.modules;
+    runtime = schemaOrOptions.runtime;
+  }
+  if (modules === undefined) {
+    throw new Error(
+      "The test kernel needs the modules map: pass `import.meta.glob(...)` as the second argument.",
+    );
+  }
+  const world = new Execution.World(schema, modules, runtime);
+  return {
+    ...accessor(world, Execution.anonymous),
+    registerComponent: (
+      componentPath: string,
+      componentSchema: SchemaDefinition<GenericSchema, boolean>,
+      componentModules: Modules,
+    ) => {
+      world.register(componentPath, componentSchema, componentModules);
+      return (componentsGeneric() as any)[componentPath];
+    },
+  };
+}