@uirouter/core
Version:
UI-Router Core: Framework agnostic, State-based routing for JavaScript Single Page Apps
528 lines (527 loc) • 20.1 kB
TypeScript
import { StateDeclaration, StateOrName } from '../state/interface';
import { TransitionOptions, TreeChanges, IHookRegistry, RegisteredHooks, HookRegOptions, HookMatchCriteria, TransitionStateHookFn, TransitionHookFn } from './interface';
import { RegisteredHook } from './hookRegistry';
import { PathNode } from '../path/pathNode';
import { StateObject } from '../state/stateObject';
import { TargetState } from '../state/targetState';
import { Resolvable } from '../resolve/resolvable';
import { ViewConfig } from '../view/interface';
import { UIRouter } from '../router';
import { UIInjector } from '../interface';
import { ResolvableLiteral } from '../resolve/interface';
import { Rejection } from './rejectFactory';
/**
* Represents a transition between two states.
*
* When navigating to a state, we are transitioning **from** the current state **to** the new state.
*
* This object contains all contextual information about the to/from states, parameters, resolves.
* It has information about all states being entered and exited as a result of the transition.
*/
export declare class Transition implements IHookRegistry {
/** @internal */
static diToken: typeof Transition;
/**
* A unique identifier for the transition.
*
* This is an auto incrementing integer, starting from `0`.
*/
$id: number;
/**
* A reference to the [[UIRouter]] instance
*
* This reference can be used to access the router services, such as the [[StateService]]
*/
router: UIRouter;
/** @internal */
private _deferred;
/**
* This promise is resolved or rejected based on the outcome of the Transition.
*
* When the transition is successful, the promise is resolved
* When the transition is unsuccessful, the promise is rejected with the [[Rejection]] or javascript error
*/
promise: Promise<any>;
/**
* A boolean which indicates if the transition was successful
*
* After a successful transition, this value is set to true.
* After an unsuccessful transition, this value is set to false.
*
* The value will be undefined if the transition is not complete
*/
success: boolean;
/** @internal */
_aborted: boolean;
/** @internal */
private _error;
/** @internal Holds the hook registration functions such as those passed to Transition.onStart() */
_registeredHooks: RegisteredHooks;
/** @internal */
private _options;
/** @internal */
private _treeChanges;
/** @internal */
private _targetState;
/** @internal */
private _hookBuilder;
/** @internal */
onBefore(criteria: HookMatchCriteria, callback: TransitionHookFn, options?: HookRegOptions): Function;
/** @inheritdoc */
onStart(criteria: HookMatchCriteria, callback: TransitionHookFn, options?: HookRegOptions): Function;
/** @inheritdoc */
onExit(criteria: HookMatchCriteria, callback: TransitionStateHookFn, options?: HookRegOptions): Function;
/** @inheritdoc */
onRetain(criteria: HookMatchCriteria, callback: TransitionStateHookFn, options?: HookRegOptions): Function;
/** @inheritdoc */
onEnter(criteria: HookMatchCriteria, callback: TransitionStateHookFn, options?: HookRegOptions): Function;
/** @inheritdoc */
onFinish(criteria: HookMatchCriteria, callback: TransitionHookFn, options?: HookRegOptions): Function;
/** @inheritdoc */
onSuccess(criteria: HookMatchCriteria, callback: TransitionHookFn, options?: HookRegOptions): Function;
/** @inheritdoc */
onError(criteria: HookMatchCriteria, callback: TransitionHookFn, options?: HookRegOptions): Function;
/** @internal
* Creates the transition-level hook registration functions
* (which can then be used to register hooks)
*/
private createTransitionHookRegFns;
/** @internal */
getHooks(hookName: string): RegisteredHook[];
/**
* Creates a new Transition object.
*
* If the target state is not valid, an error is thrown.
*
* @internal
*
* @param fromPath The path of [[PathNode]]s from which the transition is leaving. The last node in the `fromPath`
* encapsulates the "from state".
* @param targetState The target state and parameters being transitioned to (also, the transition options)
* @param router The [[UIRouter]] instance
* @internal
*/
constructor(fromPath: PathNode[], targetState: TargetState, router: UIRouter);
private applyViewConfigs;
/**
* @internal
* @returns the internal from [State] object
*/
$from(): StateObject;
/**
* @internal
* @returns the internal to [State] object
*/
$to(): StateObject;
/**
* Returns the "from state"
*
* Returns the state that the transition is coming *from*.
*
* @returns The state declaration object for the Transition's ("from state").
*/
from(): StateDeclaration;
/**
* Returns the "to state"
*
* Returns the state that the transition is going *to*.
*
* @returns The state declaration object for the Transition's target state ("to state").
*/
to(): StateDeclaration;
/**
* Gets the Target State
*
* A transition's [[TargetState]] encapsulates the [[to]] state, the [[params]], and the [[options]] as a single object.
*
* @returns the [[TargetState]] of this Transition
*/
targetState(): TargetState;
/**
* Determines whether two transitions are equivalent.
* @deprecated
*/
is(compare: Transition | {
to?: any;
from?: any;
}): boolean;
/**
* Gets transition parameter values
*
* Returns the parameter values for a transition as key/value pairs.
* This object is immutable.
*
* By default, returns the new parameter values (for the "to state").
*
* #### Example:
* ```js
* var toParams = transition.params();
* ```
*
* To return the previous parameter values, supply `'from'` as the `pathname` argument.
*
* #### Example:
* ```js
* var fromParams = transition.params('from');
* ```
*
* @param pathname the name of the treeChanges path to get parameter values for:
* (`'to'`, `'from'`, `'entering'`, `'exiting'`, `'retained'`)
*
* @returns transition parameter values for the desired path.
*/
params(pathname?: string): {
[paramName: string]: any;
};
params<T>(pathname?: string): T;
/**
* Gets the new values of any parameters that changed during this transition.
*
* Returns any parameter values that have changed during a transition, as key/value pairs.
*
* - Any parameter values that have changed will be present on the returned object reflecting the new value.
* - Any parameters that *not* have changed will not be present on the returned object.
* - Any new parameters that weren't present in the "from" state, but are now present in the "to" state will be present on the returned object.
* - Any previous parameters that are no longer present (because the "to" state doesn't have them) will be included with a value of `undefined`.
*
* The returned object is immutable.
*
* #### Examples:
*
* Given:
* ```js
* var stateA = { name: 'stateA', url: '/stateA/:param1/param2' }
* var stateB = { name: 'stateB', url: '/stateB/:param3' }
* var stateC = { name: 'stateB.nest', url: '/nest/:param4' }
* ```
*
* #### Example 1
*
* From `/stateA/abc/def` to `/stateA/abc/xyz`
*
* ```js
* var changed = transition.paramsChanged()
* // changed is { param2: 'xyz' }
* ```
*
* The value of `param2` changed to `xyz`.
* The value of `param1` stayed the same so its value is not present.
*
* #### Example 2
*
* From `/stateA/abc/def` to `/stateB/123`
*
* ```js
* var changed = transition.paramsChanged()
* // changed is { param1: undefined, param2: undefined, param3: '123' }
* ```
*
* The value `param3` is present because it is a new param.
* Both `param1` and `param2` are no longer present so their value is undefined.
*
* #### Example 3
*
* From `/stateB/123` to `/stateB/123/nest/456`
*
* ```js
* var changed = transition.paramsChanged()
* // changed is { param4: '456' }
* ```
*
* The value `param4` is present because it is a new param.
* The value of `param3` did not change, so its value is not present.
*
* @returns an immutable object with changed parameter keys/values.
*/
paramsChanged(): {
[paramName: string]: any;
};
paramsChanged<T>(): T;
/**
* Creates a [[UIInjector]] Dependency Injector
*
* Returns a Dependency Injector for the Transition's target state (to state).
* The injector provides resolve values which the target state has access to.
*
* The `UIInjector` can also provide values from the native root/global injector (ng1/ng2).
*
* #### Example:
* ```js
* .onEnter({ entering: 'myState' }, trans => {
* var myResolveValue = trans.injector().get('myResolve');
* // Inject a global service from the global/native injector (if it exists)
* var MyService = trans.injector().get('MyService');
* })
* ```
*
* In some cases (such as `onBefore`), you may need access to some resolve data but it has not yet been fetched.
* You can use [[UIInjector.getAsync]] to get a promise for the data.
* #### Example:
* ```js
* .onBefore({}, trans => {
* return trans.injector().getAsync('myResolve').then(myResolveValue =>
* return myResolveValue !== 'ABORT';
* });
* });
* ```
*
* If a `state` is provided, the injector that is returned will be limited to resolve values that the provided state has access to.
* This can be useful if both a parent state `foo` and a child state `foo.bar` have both defined a resolve such as `data`.
* #### Example:
* ```js
* .onEnter({ to: 'foo.bar' }, trans => {
* // returns result of `foo` state's `myResolve` resolve
* // even though `foo.bar` also has a `myResolve` resolve
* var fooData = trans.injector('foo').get('myResolve');
* });
* ```
*
* If you need resolve data from the exiting states, pass `'from'` as `pathName`.
* The resolve data from the `from` path will be returned.
* #### Example:
* ```js
* .onExit({ exiting: 'foo.bar' }, trans => {
* // Gets the resolve value of `myResolve` from the state being exited
* var fooData = trans.injector(null, 'from').get('myResolve');
* });
* ```
*
*
* @param state Limits the resolves provided to only the resolves the provided state has access to.
* @param pathName Default: `'to'`: Chooses the path for which to create the injector. Use this to access resolves for `exiting` states.
*
* @returns a [[UIInjector]]
*/
injector(state?: StateOrName, pathName?: string): UIInjector;
/**
* Gets all available resolve tokens (keys)
*
* This method can be used in conjunction with [[injector]] to inspect the resolve values
* available to the Transition.
*
* This returns all the tokens defined on [[StateDeclaration.resolve]] blocks, for the states
* in the Transition's [[TreeChanges.to]] path.
*
* #### Example:
* This example logs all resolve values
* ```js
* let tokens = trans.getResolveTokens();
* tokens.forEach(token => console.log(token + " = " + trans.injector().get(token)));
* ```
*
* #### Example:
* This example creates promises for each resolve value.
* This triggers fetches of resolves (if any have not yet been fetched).
* When all promises have all settled, it logs the resolve values.
* ```js
* let tokens = trans.getResolveTokens();
* let promise = tokens.map(token => trans.injector().getAsync(token));
* Promise.all(promises).then(values => console.log("Resolved values: " + values));
* ```
*
* Note: Angular 1 users whould use `$q.all()`
*
* @param pathname resolve context's path name (e.g., `to` or `from`)
*
* @returns an array of resolve tokens (keys)
*/
getResolveTokens(pathname?: string): any[];
/**
* Dynamically adds a new [[Resolvable]] (i.e., [[StateDeclaration.resolve]]) to this transition.
*
* Allows a transition hook to dynamically add a Resolvable to this Transition.
*
* Use the [[Transition.injector]] to retrieve the resolved data in subsequent hooks ([[UIInjector.get]]).
*
* If a `state` argument is provided, the Resolvable is processed when that state is being entered.
* If no `state` is provided then the root state is used.
* If the given `state` has already been entered, the Resolvable is processed when any child state is entered.
* If no child states will be entered, the Resolvable is processed during the `onFinish` phase of the Transition.
*
* The `state` argument also scopes the resolved data.
* The resolved data is available from the injector for that `state` and any children states.
*
* #### Example:
* ```js
* transitionService.onBefore({}, transition => {
* transition.addResolvable({
* token: 'myResolve',
* deps: ['MyService'],
* resolveFn: myService => myService.getData()
* });
* });
* ```
*
* @param resolvable a [[ResolvableLiteral]] object (or a [[Resolvable]])
* @param state the state in the "to path" which should receive the new resolve (otherwise, the root state)
*/
addResolvable(resolvable: Resolvable | ResolvableLiteral, state?: StateOrName): void;
/**
* Gets the transition from which this transition was redirected.
*
* If the current transition is a redirect, this method returns the transition that was redirected.
*
* #### Example:
* ```js
* let transitionA = $state.go('A').transition
* transitionA.onStart({}, () => $state.target('B'));
* $transitions.onSuccess({ to: 'B' }, (trans) => {
* trans.to().name === 'B'; // true
* trans.redirectedFrom() === transitionA; // true
* });
* ```
*
* @returns The previous Transition, or null if this Transition is not the result of a redirection
*/
redirectedFrom(): Transition;
/**
* Gets the original transition in a redirect chain
*
* A transition might belong to a long chain of multiple redirects.
* This method walks the [[redirectedFrom]] chain back to the original (first) transition in the chain.
*
* #### Example:
* ```js
* // states
* registry.register({ name: 'A', redirectTo: 'B' });
* registry.register({ name: 'B', redirectTo: 'C' });
* registry.register({ name: 'C', redirectTo: 'D' });
* registry.register({ name: 'D' });
*
* let transitionA = $state.go('A').transition
*
* $transitions.onSuccess({ to: 'D' }, (trans) => {
* trans.to().name === 'D'; // true
* trans.redirectedFrom().to().name === 'C'; // true
* trans.originalTransition() === transitionA; // true
* trans.originalTransition().to().name === 'A'; // true
* });
* ```
*
* @returns The original Transition that started a redirect chain
*/
originalTransition(): Transition;
/**
* Get the transition options
*
* @returns the options for this Transition.
*/
options(): TransitionOptions;
/**
* Gets the states being entered.
*
* @returns an array of states that will be entered during this transition.
*/
entering(): StateDeclaration[];
/**
* Gets the states being exited.
*
* @returns an array of states that will be exited during this transition.
*/
exiting(): StateDeclaration[];
/**
* Gets the states being retained.
*
* @returns an array of states that are already entered from a previous Transition, that will not be
* exited during this Transition
*/
retained(): StateDeclaration[];
/**
* Get the [[ViewConfig]]s associated with this Transition
*
* Each state can define one or more views (template/controller), which are encapsulated as `ViewConfig` objects.
* This method fetches the `ViewConfigs` for a given path in the Transition (e.g., "to" or "entering").
*
* @param pathname the name of the path to fetch views for:
* (`'to'`, `'from'`, `'entering'`, `'exiting'`, `'retained'`)
* @param state If provided, only returns the `ViewConfig`s for a single state in the path
*
* @returns a list of ViewConfig objects for the given path.
*/
views(pathname?: string, state?: StateObject): ViewConfig[];
/**
* Return the transition's tree changes
*
* A transition goes from one state/parameters to another state/parameters.
* During a transition, states are entered and/or exited.
*
* This function returns various branches (paths) which represent the changes to the
* active state tree that are caused by the transition.
*
* @param pathname The name of the tree changes path to get:
* (`'to'`, `'from'`, `'entering'`, `'exiting'`, `'retained'`)
*/
treeChanges(pathname: string): PathNode[];
treeChanges(): TreeChanges;
/**
* Creates a new transition that is a redirection of the current one.
*
* This transition can be returned from a [[TransitionService]] hook to
* redirect a transition to a new state and/or set of parameters.
*
* @internal
*
* @returns Returns a new [[Transition]] instance.
*/
redirect(targetState: TargetState): Transition;
/** @internal If a transition doesn't exit/enter any states, returns any [[Param]] whose value changed */
private _changedParams;
/**
* Returns true if the transition is dynamic.
*
* A transition is dynamic if no states are entered nor exited, but at least one dynamic parameter has changed.
*
* @returns true if the Transition is dynamic
*/
dynamic(): boolean;
/**
* Returns true if the transition is ignored.
*
* A transition is ignored if no states are entered nor exited, and no parameter values have changed.
*
* @returns true if the Transition is ignored.
*/
ignored(): boolean;
/** @internal */
_ignoredReason(): 'SameAsCurrent' | 'SameAsPending' | undefined;
/**
* Runs the transition
*
* This method is generally called from the [[StateService.transitionTo]]
*
* @internal
*
* @returns a promise for a successful transition.
*/
run(): Promise<any>;
/** Checks if this transition is currently active/running. */
isActive: () => boolean;
/**
* Checks if the Transition is valid
*
* @returns true if the Transition is valid
*/
valid(): boolean;
/**
* Aborts this transition
*
* Imperative API to abort a Transition.
* This only applies to Transitions that are not yet complete.
*/
abort(): void;
/**
* The Transition error reason.
*
* If the transition is invalid (and could not be run), returns the reason the transition is invalid.
* If the transition was valid and ran, but was not successful, returns the reason the transition failed.
*
* @returns a transition rejection explaining why the transition is invalid, or the reason the transition failed.
*/
error(): Rejection;
/**
* A string representation of the Transition
*
* @returns A string representation of the Transition
*/
toString(): string;
}