@dreamboard-games/sdk 0.2.0

package/dist/testing.d.ts

@@ -0,0 +1,149 @@
+import { a as ReducerSessionState, R as ReducerBundleContract } from './bundle-TIZcw8LB.js';
+import { P as PluginStateSnapshot$1, G as GameplaySnapshot$1 } from './runtime-api-DWxvTr-O.js';
+import { R as RuntimeAPI, a as PluginSessionState, V as ValidationResult } from './runtime-api-3dshj6kK.js';
+import './hex-color-MhOyuY-o.js';
+
+type TestRunner = "reducer" | "embedded" | "browser";
+type InteractionDescriptorLike = {
+    interactionId?: string;
+    surface?: string;
+    kind?: string;
+    availability?: InteractionAvailabilityLike;
+    context?: {
+        to?: string;
+    };
+} & Record<string, unknown>;
+type InteractionAvailabilityLike = {
+    status: "available";
+} | {
+    status: "notYourTurn";
+    reason: string;
+} | {
+    status: "insufficientResources";
+    reason: string;
+    missingResources?: Record<string, unknown>;
+} | {
+    status: "blocked";
+    reason: string;
+};
+type SnapshotMatcherHandler = (name: string | undefined, actual: unknown) => void;
+type RejectionExpectation = {
+    errorCode?: string;
+    message?: string | RegExp;
+};
+type ExpectMatchers = {
+    toBe: (expected: unknown) => void;
+    toEqual: (expected: unknown) => void;
+    toMatchObject: (expected: Record<string, unknown>) => void;
+    toBeDefined: () => void;
+    toBeUndefined: () => void;
+    toBeNull: () => void;
+    toContain: (expected: unknown) => void;
+    toContainEqual: (expected: unknown) => void;
+    toHaveLength: (expected: number) => void;
+    toBeGreaterThan: (expected: number) => void;
+    toBeGreaterThanOrEqual: (expected: number) => void;
+    toThrow: (predicate?: string | RegExp | ((error: Error) => boolean)) => void;
+    toMatchSnapshot: (filename?: string) => void;
+    toRejectWith: (expected: RejectionExpectation) => Promise<void>;
+    toHaveInteraction: (interactionId: string, opts?: Partial<InteractionDescriptorLike>) => void;
+    toBeGatedBy: (reason: string, opts?: {
+        interactionId?: string;
+    }) => void;
+    toBeActiveFor: (playerId: string, opts?: {
+        interactionId?: string;
+    }) => void;
+    not: {
+        toHaveInteraction: (interactionId: string) => void;
+    };
+};
+type ExpectFn = (actual: unknown) => ExpectMatchers;
+interface BaseContext<PlayerId extends string = string> {
+    game: {
+        start(): Promise<void>;
+        patchState?(mutator: (state: Record<string, unknown>) => void): Promise<void>;
+        submit(playerId: PlayerId, interactionId: string, params?: unknown): Promise<void>;
+    };
+    players(): readonly PlayerId[];
+    seat(index: number): PlayerId;
+}
+interface SharedScenarioContext<PlayerId extends string = string, StateName extends string = string, View = unknown, Descriptor extends InteractionDescriptorLike = InteractionDescriptorLike> extends BaseContext<PlayerId> {
+    state(): StateName;
+    view(playerId: PlayerId): View;
+    interactions(playerId: PlayerId): readonly Descriptor[];
+    expect: ExpectFn;
+}
+interface BaseDefinition {
+    id: string;
+    seed?: number;
+    players?: number;
+    setupProfileId?: string | null;
+    extends?: string;
+    setup: (ctx: BaseContext) => void | Promise<void>;
+}
+interface ScenarioDefinition<Runners extends readonly TestRunner[] = readonly ["reducer"], PhaseName extends string = string, StageName extends string = string> {
+    id: string;
+    description?: string;
+    from: string;
+    runners?: Runners;
+    phase?: PhaseName;
+    stage?: StageName;
+    when: (ctx: SharedScenarioContext) => void | Promise<void>;
+    then: (ctx: SharedScenarioContext) => void | Promise<void>;
+}
+declare function defineBase<const Definition extends BaseDefinition>(definition: Definition): Definition;
+declare function defineScenario<const Runners extends readonly TestRunner[] = readonly ["reducer"], const PhaseName extends string = string, const StageName extends string = string>(definition: ScenarioDefinition<Runners, PhaseName, StageName>): ScenarioDefinition<Runners, PhaseName, StageName>;
+
+type CreateExpectApiOptions = {
+    matchSnapshot?: SnapshotMatcherHandler;
+};
+declare function createExpectApi(options?: CreateExpectApiOptions): ExpectFn;
+
+type GameView = Record<string, unknown>;
+
+type PhaseName = string;
+
+type StageName = string;
+type InteractionId = string;
+type GameplaySnapshot = GameplaySnapshot$1<PhaseName, StageName, InteractionId>;
+type PluginStateSnapshot = Omit<PluginStateSnapshot$1<GameView, PhaseName, StageName, InteractionId>, "gameplay"> & {
+    gameplay: GameplaySnapshot;
+};
+
+type ReducerBundleLike = Pick<ReducerBundleContract, "projectSeatsDynamic" | "validateInput" | "dispatch">;
+type DeepReadonly<T> = T extends (...args: readonly unknown[]) => unknown ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: DeepReadonly<T[Key]>;
+} : T;
+type BaseStateArtifact = {
+    snapshot: DeepReadonly<ReducerSessionState>;
+    fingerprint: {
+        players: number;
+    };
+};
+type CreateTestRuntimeOptions = {
+    baseId: string;
+    baseStates: Record<string, BaseStateArtifact>;
+    bundle: ReducerBundleLike;
+    phase?: string;
+    playerIds?: readonly string[];
+    sessionId?: string;
+    userId?: string | null;
+    gameId?: string;
+    displayNameByPlayerId?: Record<string, string>;
+};
+type CreatedTestRuntime = {
+    runtime: RuntimeAPI & {
+        getSnapshot(): PluginStateSnapshot;
+        subscribeToState(listener: (state: PluginStateSnapshot) => void): () => void;
+        _subscribeToSessionState(listener: (state: PluginSessionState) => void): () => void;
+    };
+    getSnapshot(): PluginStateSnapshot;
+    players(): readonly string[];
+    seat(index: number): string;
+    submit(playerId: string, interactionId: string, params?: unknown): Promise<void>;
+    validate(playerId: string, interactionId: string, params?: unknown): Promise<ValidationResult>;
+    setControllingPlayer(playerId: string): void;
+};
+declare function createTestRuntime(options: CreateTestRuntimeOptions): CreatedTestRuntime;
+
+export { type BaseContext, type BaseDefinition, type CreateTestRuntimeOptions, type CreatedTestRuntime, type ExpectFn, type ExpectMatchers, type InteractionAvailabilityLike, type InteractionDescriptorLike, type RejectionExpectation, type ScenarioDefinition, type SharedScenarioContext, type SnapshotMatcherHandler, type TestRunner, createExpectApi, createTestRuntime, defineBase, defineScenario };

package/dist/testing.js

@@ -0,0 +1,513 @@
+import "./chunk-PZ5AY32C.js";
+
+// src/testing/definitions.ts
+function defineBase(definition) {
+  return definition;
+}
+function defineScenario(definition) {
+  return definition;
+}
+
+// src/testing/create-expect-api.ts
+import { isDeepStrictEqual } from "util";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function matchPartial(actual, expected, path = "value") {
+  if (!isRecord(expected)) {
+    return isDeepStrictEqual(actual, expected) ? null : `${path} does not match`;
+  }
+  if (!isRecord(actual)) {
+    return `${path} is not an object`;
+  }
+  for (const [key, expectedValue] of Object.entries(expected)) {
+    const actualValue = actual[key];
+    if (!(key in actual)) {
+      return `${path}.${key} is missing`;
+    }
+    const mismatch = matchPartial(actualValue, expectedValue, `${path}.${key}`);
+    if (mismatch) {
+      return mismatch;
+    }
+  }
+  return null;
+}
+function asDescriptorList(actual) {
+  if (!Array.isArray(actual)) {
+    throw new Error("Expected interaction descriptor array.");
+  }
+  return actual;
+}
+function findInteraction(descriptors, interactionId) {
+  return descriptors.find(
+    (descriptor) => descriptor.interactionId === interactionId
+  ) ?? null;
+}
+function assertDescriptorMatches(descriptor, opts) {
+  if (!opts) {
+    return;
+  }
+  const mismatch = matchPartial(descriptor, opts, "interaction");
+  if (mismatch) {
+    throw new Error(mismatch);
+  }
+}
+function createSubmissionErrorMatcher(actual, expected) {
+  const resolvePromise = () => {
+    if (typeof actual === "function") {
+      return Promise.resolve().then(() => actual());
+    }
+    return Promise.resolve(actual);
+  };
+  return resolvePromise().then(() => {
+    throw new Error("Expected promise to reject.");
+  }).catch((error) => {
+    if (!(error instanceof Error)) {
+      throw new Error("Expected rejection to be an Error.");
+    }
+    if (expected.errorCode !== void 0 && error.errorCode !== expected.errorCode) {
+      throw new Error(
+        `Expected rejection errorCode '${expected.errorCode}', received '${error.errorCode ?? "undefined"}'.`
+      );
+    }
+    if (typeof expected.message === "string" && error.message !== expected.message) {
+      throw new Error(
+        `Expected rejection message '${expected.message}', received '${error.message}'.`
+      );
+    }
+    if (expected.message instanceof RegExp && !expected.message.test(error.message)) {
+      throw new Error(
+        `Expected rejection message '${error.message}' to match ${String(expected.message)}.`
+      );
+    }
+  });
+}
+function assertLength(actual, expected) {
+  if (actual === null || actual === void 0 || typeof actual.length !== "number") {
+    throw new Error("toHaveLength expects a value with a numeric length.");
+  }
+  const length = actual.length;
+  if (length !== expected) {
+    throw new Error(`Expected length ${expected}, received ${length}.`);
+  }
+}
+function assertThrown(actual, predicate) {
+  if (typeof actual !== "function") {
+    throw new Error("toThrow expects a function.");
+  }
+  try {
+    actual();
+  } catch (error) {
+    if (!(error instanceof Error)) {
+      throw new Error("Thrown value is not an Error.");
+    }
+    if (predicate === void 0) {
+      return;
+    }
+    if (typeof predicate === "string" && error.message !== predicate) {
+      throw new Error(
+        `Expected thrown message '${predicate}', received '${error.message}'.`
+      );
+    }
+    if (predicate instanceof RegExp && !predicate.test(error.message)) {
+      throw new Error(
+        `Expected thrown message '${error.message}' to match ${String(predicate)}.`
+      );
+    }
+    if (typeof predicate === "function" && !predicate(error)) {
+      throw new Error("Thrown error did not satisfy predicate.");
+    }
+    return;
+  }
+  throw new Error("Expected function to throw.");
+}
+function createExpectApi(options = {}) {
+  const buildMatchers = (actual) => ({
+    toBe: (expected) => {
+      if (actual !== expected) {
+        throw new Error(
+          `Expected '${String(actual)}' to be '${String(expected)}'.`
+        );
+      }
+    },
+    toEqual: (expected) => {
+      if (!isDeepStrictEqual(actual, expected)) {
+        throw new Error("Expected values to be deeply equal.");
+      }
+    },
+    toMatchObject: (expected) => {
+      const mismatch = matchPartial(actual, expected);
+      if (mismatch) {
+        throw new Error(mismatch);
+      }
+    },
+    toBeDefined: () => {
+      if (actual === void 0) {
+        throw new Error("Expected value to be defined.");
+      }
+    },
+    toBeUndefined: () => {
+      if (actual !== void 0) {
+        throw new Error(
+          `Expected value to be undefined, but received '${String(actual)}'.`
+        );
+      }
+    },
+    toBeNull: () => {
+      if (actual !== null) {
+        throw new Error(
+          `Expected value to be null, but received '${String(actual)}'.`
+        );
+      }
+    },
+    toContain: (expected) => {
+      if (Array.isArray(actual)) {
+        if (!actual.includes(expected)) {
+          throw new Error("Expected array to contain value.");
+        }
+        return;
+      }
+      if (typeof actual === "string") {
+        if (!actual.includes(String(expected))) {
+          throw new Error("Expected string to contain value.");
+        }
+        return;
+      }
+      throw new Error("toContain expects an array or string actual value.");
+    },
+    toContainEqual: (expected) => {
+      if (!Array.isArray(actual)) {
+        throw new Error("toContainEqual expects an array actual value.");
+      }
+      if (!actual.some((value) => isDeepStrictEqual(value, expected))) {
+        throw new Error("Expected array to contain an equal value.");
+      }
+    },
+    toHaveLength: (expected) => {
+      assertLength(actual, expected);
+    },
+    toBeGreaterThan: (expected) => {
+      if (typeof actual !== "number") {
+        throw new Error("toBeGreaterThan expects a number actual value.");
+      }
+      if (actual <= expected) {
+        throw new Error(`Expected ${actual} to be > ${expected}.`);
+      }
+    },
+    toBeGreaterThanOrEqual: (expected) => {
+      if (typeof actual !== "number") {
+        throw new Error(
+          "toBeGreaterThanOrEqual expects a number actual value."
+        );
+      }
+      if (actual < expected) {
+        throw new Error(`Expected ${actual} to be >= ${expected}.`);
+      }
+    },
+    toThrow: (predicate) => {
+      assertThrown(actual, predicate);
+    },
+    toMatchSnapshot: (filename) => {
+      if (!options.matchSnapshot) {
+        throw new Error(
+          "Snapshot matching is not configured for this expect API."
+        );
+      }
+      options.matchSnapshot(filename, actual);
+    },
+    toRejectWith: (expected) => createSubmissionErrorMatcher(actual, expected),
+    toHaveInteraction: (interactionId, opts) => {
+      const descriptors = asDescriptorList(actual);
+      const descriptor = findInteraction(descriptors, interactionId);
+      if (!descriptor) {
+        throw new Error(`Expected interaction '${interactionId}' to exist.`);
+      }
+      assertDescriptorMatches(descriptor, opts);
+    },
+    toBeGatedBy: (reason, opts) => {
+      const descriptor = Array.isArray(actual) ? (() => {
+        if (!opts?.interactionId) {
+          throw new Error(
+            "toBeGatedBy on a descriptor array requires opts.interactionId."
+          );
+        }
+        return findInteraction(
+          asDescriptorList(actual),
+          opts.interactionId
+        );
+      })() : actual;
+      if (!descriptor) {
+        throw new Error("Expected interaction descriptor to exist.");
+      }
+      if (descriptor.availability?.status === "available") {
+        throw new Error("Expected interaction to be unavailable.");
+      }
+      const actualReason = descriptor.availability?.status === "notYourTurn" || descriptor.availability?.status === "insufficientResources" || descriptor.availability?.status === "blocked" ? descriptor.availability.reason : void 0;
+      if (actualReason !== reason) {
+        throw new Error(
+          `Expected unavailable reason '${reason}', received '${actualReason ?? "undefined"}'.`
+        );
+      }
+    },
+    toBeActiveFor: (playerId, opts) => {
+      const descriptor = Array.isArray(actual) ? (() => {
+        if (!opts?.interactionId) {
+          throw new Error(
+            "toBeActiveFor on a descriptor array requires opts.interactionId."
+          );
+        }
+        return findInteraction(
+          asDescriptorList(actual),
+          opts.interactionId
+        );
+      })() : actual;
+      if (!descriptor) {
+        throw new Error("Expected interaction descriptor to exist.");
+      }
+      if (descriptor.context?.to !== playerId) {
+        throw new Error(
+          `Expected interaction to target '${playerId}', received '${descriptor.context?.to ?? "undefined"}'.`
+        );
+      }
+      if (descriptor.availability?.status !== "available") {
+        throw new Error("Expected interaction to be available.");
+      }
+    },
+    not: {
+      toHaveInteraction: (interactionId) => {
+        const descriptors = asDescriptorList(actual);
+        if (findInteraction(descriptors, interactionId)) {
+          throw new Error(
+            `Expected interaction '${interactionId}' to be absent.`
+          );
+        }
+      }
+    }
+  });
+  return (actual) => buildMatchers(actual);
+}
+
+// src/testing/create-test-runtime.ts
+function cloneState(value) {
+  return structuredClone(value);
+}
+function createSubmissionError(errorCode, message) {
+  const error = new Error(message ?? "Interaction rejected");
+  error.name = "SubmissionError";
+  error.errorCode = errorCode;
+  return error;
+}
+function readFlowState(state) {
+  const flow = state.domain?.flow ?? {};
+  return {
+    currentPhase: flow.currentPhase ?? null,
+    activePlayers: Array.isArray(flow.activePlayers) ? flow.activePlayers : []
+  };
+}
+function resolvePlayerIds(options) {
+  if (options.explicitPlayerIds && options.explicitPlayerIds.length > 0) {
+    return [...options.explicitPlayerIds];
+  }
+  return Array.from(
+    { length: options.baseState.fingerprint.players },
+    (_, index) => `player-${index + 1}`
+  );
+}
+function isWireZoneHandles(value) {
+  return typeof value === "object" && value !== null;
+}
+function buildPluginSnapshot(options) {
+  const projection = options.bundle.projectSeatsDynamic({
+    state: options.state,
+    playerIds: [options.playerId]
+  });
+  const flow = readFlowState(options.state);
+  if (options.expectedPhase && flow.currentPhase !== options.expectedPhase) {
+    throw new Error(
+      `Expected base '${options.baseId}' to be in phase '${options.expectedPhase}', received '${flow.currentPhase ?? "null"}'.`
+    );
+  }
+  const interactionsByRef = projection.interactionsByRef ?? {};
+  const hydrateRefs = (refs) => (refs ?? []).map((ref) => interactionsByRef[ref]).filter(
+    (descriptor) => Boolean(descriptor)
+  );
+  const seat = projection.seats?.[options.playerId];
+  const zones = Object.fromEntries(
+    Object.entries(
+      seat?.zones ?? {}
+    ).map(([zoneId, zoneValue]) => {
+      const zone = isWireZoneHandles(zoneValue) ? zoneValue : {};
+      return [
+        zoneId,
+        {
+          cardIds: [...zone.cardIds ?? []],
+          cardViewsById: { ...zone.cardViewsById ?? {} },
+          playableByCardId: Object.fromEntries(
+            Object.entries(zone.playableByCardId ?? {}).map(
+              ([cardId, refs]) => [cardId, hydrateRefs(refs)]
+            )
+          )
+        }
+      ];
+    })
+  );
+  return {
+    view: seat?.view ?? null,
+    gameplay: {
+      currentPhase: flow.currentPhase,
+      currentStage: projection.currentStage ?? null,
+      activePlayers: flow.activePlayers,
+      simultaneousPhase: projection.simultaneousPhase ?? null,
+      availableInteractions: hydrateRefs(
+        seat?.availableInteractionRefs
+      ),
+      zones
+    },
+    lobby: null,
+    notifications: [],
+    session: {
+      sessionId: options.sessionId,
+      controllablePlayerIds: [...options.playerIds],
+      controllingPlayerId: options.playerId || null,
+      userId: options.userId
+    },
+    history: null,
+    syncId: options.version
+  };
+}
+function createTestRuntime(options) {
+  const baseState = options.baseStates[options.baseId];
+  if (!baseState) {
+    throw new Error(`Unknown test base '${options.baseId}'.`);
+  }
+  let currentState = cloneState(baseState.snapshot);
+  const playerIds = resolvePlayerIds({
+    baseState,
+    explicitPlayerIds: options.playerIds
+  });
+  const userId = options.userId ?? "test-user";
+  const sessionId = options.sessionId ?? "test-session";
+  let version = 0;
+  let currentPlayerId = playerIds[0] ?? "";
+  const stateListeners = /* @__PURE__ */ new Set();
+  const sessionListeners = /* @__PURE__ */ new Set();
+  const toReadySessionState = (snapshot) => ({
+    ...snapshot.session,
+    status: "ready"
+  });
+  let lastPluginSnapshot;
+  let lastSessionState;
+  const applyCurrentState = () => {
+    const previousSession = lastSessionState;
+    version += 1;
+    lastPluginSnapshot = buildPluginSnapshot({
+      state: currentState,
+      bundle: options.bundle,
+      playerId: currentPlayerId,
+      playerIds,
+      userId,
+      sessionId,
+      version,
+      expectedPhase: version === 1 ? options.phase : void 0,
+      baseId: options.baseId
+    });
+    lastSessionState = toReadySessionState(lastPluginSnapshot);
+    for (const listener of stateListeners) {
+      listener(lastPluginSnapshot);
+    }
+    if (!previousSession || previousSession.controllingPlayerId !== lastSessionState.controllingPlayerId || previousSession.controllablePlayerIds.join("\0") !== lastSessionState.controllablePlayerIds.join("\0")) {
+      for (const listener of sessionListeners) {
+        listener(lastSessionState);
+      }
+    }
+  };
+  applyCurrentState();
+  const validate = async (playerId, interactionId, params = {}) => {
+    const result = await options.bundle.validateInput({
+      state: currentState,
+      input: {
+        kind: "interaction",
+        playerId,
+        interactionId,
+        params
+      }
+    });
+    return {
+      valid: result.valid,
+      errorCode: result.errorCode,
+      message: result.message
+    };
+  };
+  const submit = async (playerId, interactionId, params = {}) => {
+    const validation = await validate(playerId, interactionId, params);
+    if (!validation.valid) {
+      throw createSubmissionError(validation.errorCode, validation.message);
+    }
+    const result = await options.bundle.dispatch({
+      state: currentState,
+      input: {
+        kind: "interaction",
+        playerId,
+        interactionId,
+        params
+      }
+    });
+    if (result.kind === "reject") {
+      throw createSubmissionError(result.errorCode, result.message);
+    }
+    currentState = cloneState(result.state);
+    applyCurrentState();
+  };
+  const setControllingPlayer = (playerId) => {
+    if (!playerIds.includes(playerId)) {
+      throw new Error(`Unknown controlling player '${playerId}'.`);
+    }
+    currentPlayerId = playerId;
+    applyCurrentState();
+  };
+  const runtime = {
+    validateInteraction: validate,
+    submitInteraction: submit,
+    getSessionState: () => lastSessionState,
+    disconnect: () => void 0,
+    switchPlayer: (playerId) => {
+      setControllingPlayer(playerId);
+    },
+    getSnapshot: () => lastPluginSnapshot,
+    subscribeToState: (listener) => {
+      stateListeners.add(listener);
+      return () => {
+        stateListeners.delete(listener);
+      };
+    },
+    _subscribeToSessionState: (listener) => {
+      sessionListeners.add(listener);
+      return () => {
+        sessionListeners.delete(listener);
+      };
+    }
+  };
+  return {
+    runtime,
+    getSnapshot: () => lastPluginSnapshot,
+    players: () => [...playerIds],
+    seat: (index) => {
+      if (!Number.isInteger(index) || index < 0 || index >= playerIds.length) {
+        throw new Error(
+          `seat(${index}) is out of range; base '${options.baseId}' has ${playerIds.length} player(s).`
+        );
+      }
+      return playerIds[index];
+    },
+    submit,
+    validate,
+    setControllingPlayer
+  };
+}
+export {
+  createExpectApi,
+  createTestRuntime,
+  defineBase,
+  defineScenario
+};
+//# sourceMappingURL=testing.js.map