diff --git a/core/src/types.ts b/core/src/types.ts index ef8e3131..8f198989 100644 --- a/core/src/types.ts +++ b/core/src/types.ts @@ -23,7 +23,7 @@ export type Mutation = undefined extends TPayload ? (p export type ActionBody = (payload: TPayload, mutator: (mutate: Mutator) => void) => Promise; export type Action = undefined extends TPayload ? (payload?: TPayload) => Promise : (payload: TPayload) => Promise; export type EventHandler = (payload?: EventPayload) => void; -export type Trigger = (matcher: Matcher | Matchable, handler: TriggerHandler) => EventListener; +export type Trigger = (matcher: Matcher | Matchable, handler: TriggerHandler) => EventListener; export type TriggerHandler = (data: TriggerEventData) => void; export type BranchAccessor = (state: ReadState) => TValue; export type InternalStores = Map>; @@ -42,25 +42,56 @@ export interface EventListener { dispose(): void; } +export interface StoreRegistration { + type: RegistrationType; + producer: RegistrationValueProducer; +} + export interface EventPayload { + /** + * The name of the event sender. This could be the core library, any registered extension/plugin, or user-emitted events. + */ sender: string; + + /** + * The store on which this event took place. + */ store: string; + + /** + * A payload sent along with the event. + */ data: TData; } export interface TriggerEventData { + /** + * The name of the mutation/action that fired this trigger. + */ name: string; + + /** + * The payload provided to the mutation/action that fired this trigger. + */ payload: TPayload; - result?: TResult; -} -export interface StoreRegistration { - type: RegistrationType; - producer: RegistrationValueProducer; + /** + * The result returned from the mutation/action that fired this trigger. This is only populated for after and success triggers. + */ + result?: TResult; } export interface StoreSnapshot { + /** + * A readonly copy of state in the snapshot + */ get state(): TState; + + /** + * Apply the current snapshot's state to the store. This will essentially overwrite any changes to state since this snapshot was taken. + * @param branchAccessor - An optional branch accessor to apply a partial part of this snapshot to the store. + * @param mutationName - An optional mutation name to use when applying the snapshot. This is useful for identifying snapshot applications in the Harlem devtools. + */ apply(branchAccessor?: BranchAccessor, mutationName?: string): void; } @@ -288,13 +319,44 @@ export interface Store extends StoreBase { */ state: ReadState; + /** + * The trigger called before a mutation runs + */ onBeforeMutation: Trigger; + + /** + * The trigger called after a mutation runs, regardless of it was successful or not + */ onAfterMutation: Trigger; + + /** + * The trigger called upon successful completion of a mutation + */ onMutationSuccess: Trigger; + + /** + * The trigger called when a mutation fails + */ onMutationError: Trigger; + + /** + * The trigger called before an action runs + */ onBeforeAction: Trigger; + + /** + * The trigger called after an action runs, regardless of it was successful or not + */ onAfterAction: Trigger; + + /** + * The trigger called upon successful completion of an action + */ onActionSuccess: Trigger; + + /** + * The trigger called when an action fails + */ onActionError: Trigger; }