Event types

The framework’s exported types for typed event handlers and accessor / error shapes. Type-only imports (no runtime cost) — use them when you want a named handler whose currentTarget narrows to the element it’s attached to, or when you’re typing a prop that receives a keyed-each() accessor.

import type {
  WhisqEvent,
  EventHandler,
  ItemAccessor,
  WhisqKeyByError,
  WhisqKeyByErrorFields,
  WhisqStructureError,
  WhisqStructureErrorFields,
} from "@whisq/core";

EventHandler<E, T>

The handler signature for a typed DOM event with a narrowed currentTarget.

type EventHandler<E extends Event = Event, T extends Element = Element> = (
  event: E & { currentTarget: T },
) => void;

Use when you want to extract a named handler from a component setup — types stay correct, currentTarget narrows to the right element type, and the return type stays void (handlers never need to return).

import type { EventHandler } from "@whisq/core";

const onSubmit: EventHandler<SubmitEvent, HTMLFormElement> = (e) => {
  e.preventDefault();
  e.currentTarget.reset();
};

form({ onsubmit: onSubmit }, /* ... */);

WhisqEvent<K, T>

Look up the event type from a DOM event name (as used in HTMLElementEventMap) and narrow the currentTarget to a target element.

type WhisqEvent<
  K extends keyof HTMLElementEventMap,
  T extends Element = Element,
> = HTMLElementEventMap[K] & { currentTarget: T };

Use when you want to name the exact event, instead of writing KeyboardEvent & { currentTarget: HTMLInputElement } by hand:

import type { WhisqEvent } from "@whisq/core";

function onSearchKey(e: WhisqEvent<"keydown", HTMLInputElement>) {
  if (e.key === "Enter") submit(e.currentTarget.value);
}

input({ onkeydown: onSearchKey });

When to use which

If you have…	Reach for…	Example
The event class (SubmitEvent, MouseEvent)	EventHandler<E, T>	EventHandler<SubmitEvent, HTMLFormElement>
The event name ("keydown", "input")	WhisqEvent<K, T>	WhisqEvent<"keydown", HTMLInputElement>

Both are interchangeable in practice; pick by which name you already have in your head.

ItemAccessor<T> (since alpha.8)

The hybrid accessor passed to a keyed each()’s render callback.

interface ItemAccessor<T> {
  (): T;                  // call form — pre-alpha.8 backwards-compat
  readonly value: T;      // .value form — canonical for new code
  peek(): T;              // peek form — read without subscribing
}

Use when typing a prop that receives a keyed-each() accessor — typically when extracting per-row markup into a child component:

import type { ItemAccessor } from "@whisq/core";

type TodoItemProps = { todo: ItemAccessor<Todo>; onRemove: (id: string) => void };

const TodoItem = component((props: TodoItemProps) =>
  li({ onclick: () => props.onRemove(props.todo.value.id) }, () => props.todo.value.text),
);

ItemAccessor<T> is structurally assignable to () => T, so it works unchanged with helpers typed as () => T (e.g. bindField). See /api/each/ and Nested Item Editing guide.

Dev-mode error classes

Both error classes are runtime exports (not pure types) — you can instanceof them, but production builds strip the throw sites in most cases.

WhisqKeyByError (since alpha.8)

Thrown by bindField() in dev mode (or with strict: true in any env) when a write can’t find an item in the source array whose keyBy(...) matches the accessor’s key. Carries sourceKeys, targetKey, and field for debugging.

interface WhisqKeyByErrorFields {
  sourceKeys: unknown[];   // keys present in the source at write time
  targetKey: unknown;      // the key the write was looking for
  field: string;           // the field bindField was writing
}

class WhisqKeyByError extends Error implements WhisqKeyByErrorFields { /* ... */ }

Full reference and the strict matrix: /api/bindfield/#dev-mode-behaviour-and-the-strict-option.

WhisqStructureError

Thrown by element / each() / match() / component() in dev mode when an API receives a value it can’t render. Carries expected, received, element, and an optional hint.

interface WhisqStructureErrorFields {
  expected: string;
  received: string;
  element: string;
  hint?: string;
  callsite?: string;
}

class WhisqStructureError extends Error implements WhisqStructureErrorFields { /* ... */ }

Full coverage of every dev-mode error message and its fix: /common-mistakes/#about-whisqstructureerror.

See also

• bindField() — uses WhisqKeyByError and EventHandler shapes.
• each() — origin of ItemAccessor<T>.
• Forms guide — typed handler patterns in action.
• LLM reference — Typed Event Handlers — canonical snippet.