@gaganref/confect-test 10.3.1-fork.9 → 10.3.1-fork.90

package/src/internal/Attempt.ts

@@ -0,0 +1,185 @@
+// oxlint-disable-next-line effecttsgo/node-builtin-import, no-restricted-imports -- An attempt's drain waits one real turn of the event loop, which is no deadline. 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/Clock.ts

@@ -0,0 +1,95 @@
+/**
+ * Convex pins `Date` inside a query or mutation to the time it started, and its
+ * scheduler reads `Date.now()` for `runAfter`. The kernel wraps the realm's
+ * `Date` so it answers a kernel invocation's time inside one and the host's
+ * everywhere else. It sets no host timer.
+ */
+
+import * as Globals from "./Globals.js";
+
+type DateConstructor = typeof globalThis.Date;
+
+interface State {
+  /**
+   * Each wrapper the kernel installed, and the `Date` it wraps.
+   */
+  readonly bases: WeakMap<DateConstructor, DateConstructor>;
+  readonly pinned: () => number | undefined;
+  /**
+   * Whether a kernel invocation is running, without reading its time.
+   */
+  readonly inside: () => boolean;
+}
+
+const key = Symbol.for("@confect/test/Clock");
+
+type Global = { [key]?: State; Date: DateConstructor };
+
+const wrap = (
+  base: DateConstructor,
+  pinned: () => number | undefined,
+): DateConstructor => {
+  const proxy: DateConstructor = new Proxy(base, {
+    get: (target, property) =>
+      property === "now"
+        ? () => pinned() ?? target.now()
+        : Reflect.get(target, property, target),
+    construct: (target, args, newTarget) => {
+      const at = args.length === 0 ? pinned() : undefined;
+      return Reflect.construct(
+        target,
+        at === undefined ? args : [at],
+        newTarget === proxy ? target : newTarget,
+      );
+    },
+    apply: (target, self, args) => {
+      const at = pinned();
+      return at === undefined
+        ? Reflect.apply(target, self, args)
+        : new target(at).toString();
+    },
+  });
+  return proxy;
+};
+
+/**
+ * Wrap the realm's current `Date`, unless the kernel already did. `pinned`
+ * answers the running invocation's time, or `undefined` outside one, and
+ * `inside` says whether one is running. The first install's callbacks answer
+ * for every later one, as with `globalThis.Convex`. A test that fakes `Date`
+ * replaces the wrapper while the fake is installed, and the next install wraps
+ * the `Date` the test restores.
+ */
+export const install = (
+  pinned: () => number | undefined,
+  inside: () => boolean,
+) => {
+  const global = globalThis as Global;
+  const state = (global[key] ??= { bases: new WeakMap(), pinned, inside });
+  const current = global.Date;
+  if (state.bases.has(current)) return;
+  const wrapper = wrap(current, () => state.pinned());
+  state.bases.set(wrapper, current);
+  global.Date = wrapper;
+};
+
+/**
+ * Whether `date` is the kernel's wrapper inside a running kernel invocation, so
+ * it already answers that invocation's time on the kernel's clock.
+ */
+export const answersInvocation = (date: DateConstructor): boolean => {
+  const state = (globalThis as Global)[key];
+  return state !== undefined && state.bases.has(date) && state.inside();
+};
+
+/**
+ * The host's time in milliseconds, never a kernel invocation's: the real clock,
+ * or a test's fake one while it is installed. It reads the test environment's
+ * `Date`, never the copy a bound handler pinned.
+ */
+export const hostNow = (): number =>
+  Globals.host(() => {
+    const global = globalThis as Global;
+    const current = global.Date;
+    return (global[key]?.bases.get(current) ?? current).now();
+  });

package/src/internal/ConvexTest.ts

@@ -0,0 +1,163 @@
+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";
+import type * as Scheduling from "./Scheduling.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>;
+  /**
+   * Move the kernel's clock forward, running each job due on the way at its
+   * deadline.
+   */
+  readonly advance: (ms: number) => Promise<void>;
+  /**
+   * The pending jobs, earliest deadline first.
+   */
+  readonly jobs: () => ReadonlyArray<Scheduling.Job>;
+  /**
+   * Run the jobs due now. No future deadline is crossed.
+   */
+  readonly finishInProgressScheduledFunctions: () => Promise<void>;
+  /**
+   * Run jobs at their deadlines until only standing jobs remain, or fail with
+   * `DrainBudgetExceeded` after `maxIterations` jobs. The kernel keeps its own
+   * clock, so it never calls `advanceTimers`.
+   */
+  readonly finishAllScheduledFunctions: (
+    advanceTimers?: () => void,
+    maxIterations?: number,
+  ) => Promise<void>;
+}
+
+/**
+ * How a kit registers a component beyond its schema and modules.
+ */
+export interface RegisterOptions {
+  /**
+   * The component's functions, as `module:export`, that schedule their own next
+   * run, such as the crons component's `public:rescheduler`. A job that runs
+   * one, or that one schedules, is never drain work.
+   */
+  readonly standing?: ReadonlyArray<string>;
+}
+
+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)),
+  advance: (ms: number) => world.advance(ms),
+  jobs: () => world.jobs(),
+  finishInProgressScheduledFunctions: () => world.advance(0),
+  finishAllScheduledFunctions: (
+    _advanceTimers?: () => void,
+    maxIterations?: number,
+  ) => world.drain(maxIterations),
+});
+
+/**
+ * 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. Scheduled
+ * functions run on the kernel's clock, never on a host timer.
+ */
+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,
+      options?: RegisterOptions,
+    ) => {
+      world.register(
+        componentPath,
+        componentSchema,
+        componentModules,
+        options?.standing,
+      );
+      return (componentsGeneric() as any)[componentPath];
+    },
+  };
+}