Class Travels<S, F, A, P>

constructor

• new Travels<
      S,
      F extends boolean = false,
      A extends boolean = true,
      P extends { arrayLengthAssignment?: boolean; pathAsArray?: boolean } = {},
  >(
      initialState: S,
      options?: TravelsOptions<F, A, P>,
  ): Travels<S, F, A, P>

  Type Parameters

  • S
  • F extends boolean = false
  • A extends boolean = true
  • P extends { arrayLengthAssignment?: boolean; pathAsArray?: boolean } = {}

  Parameters

  • initialState: S
  • options: TravelsOptions<F, A, P> = {}

  Returns Travels<S, F, A, P>

mutable

archive

• archive(metadata?: TravelMetadata): void

  Parameters

  • Optionalmetadata: TravelMetadata

  Returns void

assertPersistenceCompatible

• assertPersistenceCompatible(): void

  Assert that state, retained patches, and metadata can round-trip through Travels' JSON persistence contract without normalization or data loss.

  Returns void

back

• back(amount?: number): void

  Go back in the history

  Parameters

  • amount: number = 1

  Returns void

batch

• batch<FN extends () => unknown>(
      metadata: TravelMetadata,
      fn: FN & SynchronousFunction<FN>,
  ): void

  Type Parameters

  • FN extends () => unknown

  Parameters

  • metadata: TravelMetadata
  • fn: FN & SynchronousFunction<FN>

  Returns void

• batch<FN extends () => unknown>(fn: FN & SynchronousFunction<FN>): void

  Type Parameters

  • FN extends () => unknown

  Parameters

  • fn: FN & SynchronousFunction<FN>

  Returns void

canArchive

• canArchive(): boolean

  Check if it's possible to archive the current state

  Returns boolean

canBack

• canBack(): boolean

  Check if it's possible to go back

  Returns boolean

canForward

• canForward(): boolean

  Check if it's possible to go forward

  Returns boolean

forward

• forward(amount?: number): void

  Go forward in the history

  Parameters

  • amount: number = 1

  Returns void

getControls

• getControls(): A extends true
      ? RebasableTravelsControls<S, F, P>
      : RebasableManualTravelsControls<S, F, P>

  Get the controls object

  Returns A extends true
      ? RebasableTravelsControls<S, F, P>
      : RebasableManualTravelsControls<S, F, P>

getHistory

• getHistory(): readonly S[]

  Get the complete history of states

  Returns readonly S[]

  The history array. Reference equality indicates cache hit.

  Remarks

  IMPORTANT: Treat the returned array and every state entry as read-only. They are cached internally.

  • In development mode, only the array container is frozen.
  • State entries are shared cached snapshots and are not deep-frozen.
  • In production mode, modifying the array or its entries will corrupt the cache.

getHistoryEntries

• getHistoryEntries(): TravelHistoryEntry<P>[]

  Returns TravelHistoryEntry<P>[]

getHistorySnapshot

• getHistorySnapshot(): S[]

  Return fully detached durable snapshots for every visible history state.

  Unlike getHistory(), this method never exposes the internal cache. It rejects runtime-only values rather than returning a partially shared clone.

  Returns S[]

getMetadata

• getMetadata(): (undefined | TravelMetadata)[]

  Returns (undefined | TravelMetadata)[]

getPatches

• getPatches(): TravelPatches<P>

  Get the patches history

  Returns TravelPatches<P>

getPosition

• getPosition(): number

  Get the current position in the history

  Returns number

getState

• getState(): S

  Get the current state

  Returns S

go

• go(nextPosition: number): void

  Go to a specific position in the history

  Parameters

  • nextPosition: number

  Returns void

pauseTracking

• pauseTracking(): void

  Returns void

rebase

• rebase(): void

  Remove all history and make the current state (including any unarchived temp patches) as the new initial state.

  This is a destructive operation that discards all history and overwrites the internal baseline. Future reset() calls will return to this snapshot.

  Returns void

recordPatches

• recordPatches(state: S, entry: TravelHistoryEntry<P>): void

  Record a patch pair that an external authoritative state owner has already committed.

  Parameters

  • state: S
  • entry: TravelHistoryEntry<P>

  Returns void

  Remarks

  This avoids running the update recipe through Mutative a second time. The supplied state must be the state after entry.patches were applied. Patch inputs are detached before they are retained, so later caller mutation cannot rewrite history.

replaceStateWithoutHistory

• replaceStateWithoutHistory(updater: Updater<S>): void

  Parameters

  • updater: Updater<S>

  Returns void

reset

• reset(): void

  Reset to the initial state

  Returns void

resumeTracking

• resumeTracking(): void

  Returns void

serialize

• serialize(options?: TravelsSerializeOptions): TravelsSerializedHistory<S, P>

  Serialize the current state, patch history, and position for persistence.

  Parameters

  • options: TravelsSerializeOptions = {}

  Returns TravelsSerializedHistory<S, P>

setState

• setState<U>(updater: SynchronousUpdater<S, U>, metadata?: TravelMetadata): void

  Update the state

  Type Parameters

  • U

  Parameters

  • updater: SynchronousUpdater<S, U>
  • Optionalmetadata: TravelMetadata

  Returns void

subscribe

• subscribe(listener: ObserverListener<S, P>): () => void

  Subscribe to state changes

  Parameters

  • listener: ObserverListener<S, P>

  Returns () => void

  Unsubscribe function

transaction

• transaction<FN extends () => unknown>(
      metadata: TravelMetadata,
      fn: FN & SynchronousFunction<FN>,
  ): void

  Type Parameters

  • FN extends () => unknown

  Parameters

  • metadata: TravelMetadata
  • fn: FN & SynchronousFunction<FN>

  Returns void

• transaction<FN extends () => unknown>(fn: FN & SynchronousFunction<FN>): void

  Type Parameters

  • FN extends () => unknown

  Parameters

  • fn: FN & SynchronousFunction<FN>

  Returns void

Staticdeserialize

• deserialize<
      S,
      P extends { arrayLengthAssignment?: boolean; pathAsArray?: boolean } = {},
  >(
      snapshot: unknown,
      options?: TravelsDeserializeOptions<S, P>,
  ): TravelsSerializedHistory<S, P>

  Validate and normalize a persisted Travels history snapshot.

  Type Parameters

  • S
  • P extends { arrayLengthAssignment?: boolean; pathAsArray?: boolean } = {}

  Parameters

  • snapshot: unknown
  • Optionaloptions: TravelsDeserializeOptions<S, P>

  Returns TravelsSerializedHistory<S, P>