@dreamboard-games/sdk 0.2.0

package/src/reducer/inputs/many.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import type {
+  CollectorState,
+  InputCollector,
+  InputSelectionDescriptor,
+} from "../model/spec";
+import type { SchemaLike } from "../model/table";
+
+export type ManyOptions =
+  | {
+      count: number;
+      distinct?: boolean;
+    }
+  | {
+      min?: number;
+      max?: number;
+      distinct?: boolean;
+    };
+
+type NonRngCollector = InputCollector<SchemaLike<unknown>, CollectorState> & {
+  readonly kind: Exclude<InputCollector["kind"], "rng">;
+};
+
+type CollectorSchema<Collector extends NonRngCollector> = [Collector] extends [
+  InputCollector<infer Schema, CollectorState>,
+]
+  ? Schema
+  : never;
+
+type CollectorStateOf<Collector extends NonRngCollector> = [Collector] extends [
+  InputCollector<SchemaLike<unknown>, infer State>,
+]
+  ? State
+  : never;
+
+type CollectorKindOf<Collector extends NonRngCollector> = [Collector] extends [
+  {
+    readonly kind: infer Kind extends Exclude<InputCollector["kind"], "rng">;
+  },
+]
+  ? Kind
+  : never;
+
+export type ManyInputCollector<
+  Schema extends SchemaLike<unknown> = SchemaLike<unknown>,
+  State extends CollectorState = CollectorState,
+  Kind extends Exclude<InputCollector["kind"], "rng"> = Exclude<
+    InputCollector["kind"],
+    "rng"
+  >,
+> = InputCollector<z.ZodType<ReadonlyArray<z.infer<Schema>>>, State, Kind> & {
+  readonly selection: Extract<InputSelectionDescriptor, { mode: "many" }>;
+};
+
+function normalizeManyOptions(
+  options: ManyOptions,
+): Extract<InputSelectionDescriptor, { mode: "many" }> {
+  if ("count" in options) {
+    assertNonNegativeInteger(options.count, "many(...).count");
+    return {
+      mode: "many",
+      min: options.count,
+      max: options.count,
+      distinct: options.distinct,
+    };
+  }
+  const min = options.min ?? 0;
+  assertNonNegativeInteger(min, "many(...).min");
+  if (options.max !== undefined) {
+    assertNonNegativeInteger(options.max, "many(...).max");
+    if (options.max < min) {
+      throw new Error("many(...).max must be greater than or equal to min.");
+    }
+  }
+  return {
+    mode: "many",
+    min,
+    max: options.max,
+    distinct: options.distinct,
+  };
+}
+
+function assertNonNegativeInteger(value: number, label: string): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative integer.`);
+  }
+}
+
+export function many<Collector extends NonRngCollector>(
+  collector: Collector,
+  options: ManyOptions,
+): ManyInputCollector<
+  CollectorSchema<Collector>,
+  CollectorStateOf<Collector>,
+  CollectorKindOf<Collector>
+> &
+  Pick<Collector, "meta"> {
+  if ((collector as InputCollector).kind === "rng") {
+    throw new Error("many(...) cannot wrap rngInput collectors.");
+  }
+  const selection = normalizeManyOptions(options);
+  const {
+    schema: _schema,
+    selection: _selection,
+    defaultValue: _defaultValue,
+    ...rest
+  } = collector;
+  return {
+    ...rest,
+    schema: z.array(collector.schema as z.ZodTypeAny) as unknown as z.ZodType<
+      ReadonlyArray<z.infer<CollectorSchema<Collector>>>
+    >,
+    selection,
+  } as unknown as ManyInputCollector<
+    CollectorSchema<Collector>,
+    CollectorStateOf<Collector>,
+    CollectorKindOf<Collector>
+  > &
+    Pick<Collector, "meta">;
+}

package/src/reducer/inputs/promptInput.ts

@@ -0,0 +1,87 @@
+import type { SchemaLike } from "../model/table";
+import type { CollectorState, InputCollector } from "../model/spec";
+import type { ChoiceTargetRule } from "./choiceTarget";
+import type { z } from "zod";
+
+type SchemaStringValue<Schema extends SchemaLike<unknown>> = Extract<
+  Schema extends z.ZodType<infer V> ? V : never,
+  string
+>;
+
+/**
+ * `promptInput` marks an interaction as a prompt delivered to a player's
+ * inbox. The submitted value is validated by the supplied Zod schema.
+ *
+ * Static or free-form prompts need only `schema`. Finite dynamic choices use
+ * a built `choiceTarget.options(...).build()` rule so projected options and
+ * submit validation share one source of truth.
+ */
+export function promptInput<
+  Schema extends SchemaLike<unknown>,
+  State extends CollectorState = CollectorState,
+>(options: {
+  schema: Schema;
+  target?: ChoiceTargetRule<State, SchemaStringValue<Schema>>;
+}): InputCollector<Schema, State, "prompt"> {
+  const target = options.target;
+  return {
+    kind: "prompt",
+    schema: options.schema,
+    eligibleTargets: target
+      ? (((state, playerId, q) =>
+          target.eligible({
+            state: state as State,
+            playerId: playerId as never,
+            q: q as never,
+          })) as
+          | ((
+              state: CollectorState,
+              playerId: string,
+              q: unknown,
+            ) => ReadonlyArray<unknown>)
+          | undefined)
+      : undefined,
+    validateTarget: target
+      ? (((state, playerId, q, targetId) =>
+          target.validate(
+            {
+              state: state as State,
+              playerId: playerId as never,
+              q: q as never,
+            },
+            targetId as SchemaStringValue<Schema>,
+          )) as InputCollector<Schema, State, "prompt">["validateTarget"])
+      : undefined,
+    meta: target
+      ? {
+          options: (state: unknown, playerId: unknown, q: unknown) =>
+            target.options({
+              state: state as State,
+              playerId: playerId as never,
+              q: q as never,
+            }),
+          eligibleOptions: (state: unknown, playerId: unknown, q: unknown) =>
+            target.eligibleOptions({
+              state: state as State,
+              playerId: playerId as never,
+              q: q as never,
+            }),
+        }
+      : undefined,
+    domain: (state, playerId, q) => ({
+      type: "choice" as const,
+      choices: target
+        ? target
+            .options({
+              state: state as State,
+              playerId: playerId as never,
+              q: q as never,
+            })
+            .map((option) => ({
+              value: String(option.id),
+              label: option.label ?? String(option.id),
+            }))
+        : [],
+    }),
+  };
+}

package/src/reducer/inputs/rngInput.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import type { CollectorState, InputCollector } from "../model/spec";
+
+/**
+ * `rngInput.*` helpers produce collectors whose value is *sampled by the
+ * engine on submit* rather than supplied by the client. The schema pins
+ * the exact output shape so `ParamsOf<Collectors>` sees precisely typed
+ * results.
+ *
+ * Determinism:
+ *   Sampling happens inside `submitInteraction` only, never inside
+ *   `validateInteraction`. This lets clients dry-run a submission without
+ *   burning RNG state.
+ */
+
+type DieRoll = z.ZodObject<{ values: z.ZodArray<z.ZodNumber> }>;
+type CoinFlip = z.ZodObject<{
+  value: z.ZodEnum<{ heads: "heads"; tails: "tails" }>;
+}>;
+
+// The literal `kind: "rng"` is intentionally preserved in the return type
+// so `ClientParamsOf<Collectors>` can structurally detect engine-sampled
+// collectors and omit them from client-facing submit params.
+type RngCollector<
+  Schema extends DieRoll | CoinFlip,
+  State extends CollectorState,
+> = InputCollector<Schema, State, "rng">;
+
+/**
+ * Roll `count` d6s. The submitted value is `{ values: number[] }` with
+ * `values.length === count` and each face `1..6`.
+ */
+export function d6<State extends CollectorState = CollectorState>(
+  count: number = 1,
+): RngCollector<DieRoll, State> {
+  return {
+    kind: "rng",
+    schema: z.object({
+      values: z.array(z.number().int().min(1).max(6)).length(count),
+    }),
+    meta: { rng: "d6", count },
+  };
+}
+
+/** Flip a coin. The submitted value is `{ value: "heads" | "tails" }`. */
+export function coin<
+  State extends CollectorState = CollectorState,
+>(): RngCollector<CoinFlip, State> {
+  return {
+    kind: "rng",
+    schema: z.object({
+      value: z.enum(["heads", "tails"]),
+    }),
+    meta: { rng: "coin" },
+  };
+}
+
+export const rngInput = { d6, coin };

package/src/reducer/inputs/targetRule.ts

@@ -0,0 +1,123 @@
+import type { CollectorState, ValidationIssue } from "../model/spec";
+import type { PlayerIdOfState } from "../model/extract";
+import type { TableQueriesOfState } from "../model/queries";
+
+export type TargetContext<State extends CollectorState> = {
+  state: State;
+  playerId: PlayerIdOfState<State>;
+  q: TableQueriesOfState<State>;
+  values?: Readonly<Record<string, unknown>>;
+};
+
+export type TargetPredicateArgs<
+  State extends CollectorState,
+  Target,
+> = TargetContext<State> & {
+  targetId: Target;
+  target: Target;
+};
+
+export type TargetPredicate<State extends CollectorState, Target> = {
+  id: string;
+  errorCode: string;
+  message?: string;
+  test: (args: TargetPredicateArgs<State, Target>) => boolean;
+};
+
+export type BoundTargetRule<Target> = {
+  readonly eligible: () => readonly Target[];
+  readonly validate: (target: Target) => ValidationIssue | null;
+  readonly isEligible: (target: Target) => boolean;
+};
+
+export type TargetRule<State extends CollectorState, Target> = {
+  readonly eligible: (ctx: TargetContext<State>) => readonly Target[];
+  readonly validate: (
+    ctx: TargetContext<State>,
+    target: Target,
+  ) => ValidationIssue | null;
+  readonly isEligible: (ctx: TargetContext<State>, target: Target) => boolean;
+  readonly bind: (ctx: TargetContext<State>) => BoundTargetRule<Target>;
+};
+
+export type TargetRuleBuilder<
+  State extends CollectorState,
+  Target,
+  Rule extends TargetRule<State, Target>,
+> = {
+  readonly where: (
+    predicate: TargetPredicate<State, Target>,
+  ) => TargetRuleBuilder<State, Target, Rule>;
+  readonly build: () => Rule;
+};
+
+export type TargetCandidateResolver<State extends CollectorState, Target> = (
+  ctx: TargetContext<State>,
+) => readonly Target[];
+
+export type TargetRuleOptions = {
+  missingCandidateIssue?: ValidationIssue;
+  equals?: (left: unknown, right: unknown) => boolean;
+};
+
+const DEFAULT_MISSING_CANDIDATE_ISSUE: ValidationIssue = {
+  errorCode: "TARGET_NOT_ELIGIBLE",
+  message: "Target is not eligible.",
+};
+
+export function createTargetRule<State extends CollectorState, Target>(
+  candidates: TargetCandidateResolver<State, Target>,
+  predicates: readonly TargetPredicate<State, Target>[],
+  options: TargetRuleOptions = {},
+): TargetRule<State, Target> {
+  const missingCandidateIssue =
+    options.missingCandidateIssue ?? DEFAULT_MISSING_CANDIDATE_ISSUE;
+  const equals = options.equals ?? Object.is;
+
+  const validate = (
+    ctx: TargetContext<State>,
+    target: Target,
+  ): ValidationIssue | null => {
+    if (!candidates(ctx).some((candidate) => equals(candidate, target))) {
+      return missingCandidateIssue;
+    }
+    for (const predicate of predicates) {
+      if (!predicate.test({ ...ctx, targetId: target, target })) {
+        return {
+          errorCode: predicate.errorCode,
+          message: predicate.message,
+        };
+      }
+    }
+    return null;
+  };
+
+  const rule: TargetRule<State, Target> = {
+    eligible: (ctx) =>
+      candidates(ctx).filter((targetId) => validate(ctx, targetId) == null),
+    validate,
+    isEligible: (ctx, target) => validate(ctx, target) == null,
+    bind: (ctx) => ({
+      eligible: () => rule.eligible(ctx),
+      validate: (id) => rule.validate(ctx, id),
+      isEligible: (id) => rule.isEligible(ctx, id),
+    }),
+  };
+
+  return rule;
+}
+
+export function createTargetRuleBuilder<
+  State extends CollectorState,
+  Target,
+  Rule extends TargetRule<State, Target>,
+>(
+  buildRule: (predicates: readonly TargetPredicate<State, Target>[]) => Rule,
+  predicates: readonly TargetPredicate<State, Target>[] = [],
+): TargetRuleBuilder<State, Target, Rule> {
+  return {
+    where: (predicate) =>
+      createTargetRuleBuilder(buildRule, [...predicates, predicate]),
+    build: () => buildRule(predicates),
+  };
+}

package/src/reducer/inputs.ts

@@ -0,0 +1,41 @@
+export { formInput } from "./inputs/formInput";
+export {
+  defineInputs,
+  type DependencyValues,
+  type DefinedInputs,
+  type InputFieldRef,
+} from "./inputs/defineInputs";
+export { boardInput } from "./inputs/boardInput";
+export { boardTarget } from "./inputs/boardTarget";
+export type {
+  BoardTargetBuilder,
+  BoardTargetPredicate,
+  BoardTargetRule,
+  PlayerBoardSpaceTarget,
+} from "./inputs/boardTarget";
+export { cardTarget } from "./inputs/cardTarget";
+export type {
+  CardTargetBuilder,
+  CardTargetPredicate,
+  CardTargetRule,
+} from "./inputs/cardTarget";
+export { choiceTarget } from "./inputs/choiceTarget";
+export type {
+  ChoiceOptionsFactory,
+  ChoiceTargetOption,
+  ChoiceTargetBuilder,
+  ChoiceTargetPredicate,
+  ChoiceTargetRule,
+} from "./inputs/choiceTarget";
+export type {
+  BoundTargetRule,
+  TargetContext,
+  TargetPredicate,
+  TargetPredicateArgs,
+  TargetRule,
+  TargetRuleBuilder,
+} from "./inputs/targetRule";
+export { cardInput } from "./inputs/cardInput";
+export { promptInput } from "./inputs/promptInput";
+export { rngInput } from "./inputs/rngInput";
+export { many, type ManyOptions } from "./inputs/many";