Skip to content

Commit

Permalink
feat(core): improve typing and jsdoc comments
Browse files Browse the repository at this point in the history
  • Loading branch information
andrewcourtice committed Nov 18, 2022
1 parent 754717f commit fb45370
Showing 1 changed file with 68 additions and 6 deletions.
74 changes: 68 additions & 6 deletions core/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ export type Mutation<TPayload, TResult = void> = undefined extends TPayload ? (p
export type ActionBody<TState extends BaseState, TPayload = undefined, TResult = void> = (payload: TPayload, mutator: (mutate: Mutator<TState, undefined, void>) => void) => Promise<TResult>;
export type Action<TPayload, TResult = void> = undefined extends TPayload ? (payload?: TPayload) => Promise<TResult> : (payload: TPayload) => Promise<TResult>;
export type EventHandler<TData = any> = (payload?: EventPayload<TData>) => void;
export type Trigger = <TPayload, TResult>(matcher: Matcher | Matchable, handler: TriggerHandler<TPayload, TResult>) => EventListener;
export type Trigger = <TPayload = any, TResult = any>(matcher: Matcher | Matchable, handler: TriggerHandler<TPayload, TResult>) => EventListener;
export type TriggerHandler<TPayload = any, TResult = any> = (data: TriggerEventData<TPayload, TResult>) => void;
export type BranchAccessor<TState extends BaseState, TValue> = (state: ReadState<TState>) => TValue;
export type InternalStores = Map<string, InternalStore<BaseState>>;
Expand All @@ -42,25 +42,56 @@ export interface EventListener {
dispose(): void;
}

export interface StoreRegistration {
type: RegistrationType;
producer: RegistrationValueProducer;
}

export interface EventPayload<TData = any> {
/**
* 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<TPayload = any, TResult = any> {
/**
* 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<TState extends BaseState> {
/**
* 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<TValue>(branchAccessor?: BranchAccessor<TState, TValue>, mutationName?: string): void;
}

Expand Down Expand Up @@ -288,13 +319,44 @@ export interface Store<TState extends BaseState> extends StoreBase<TState> {
*/
state: ReadState<TState>;

/**
* 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;
}

Expand Down

0 comments on commit fb45370

Please sign in to comment.