Skip to content

Make settings flat, check every value, and add Pace.configure() - #578

Merged
CodeByZach merged 1 commit into
candidate-2.0from
settings
Nov 16, 2026
Merged

CodeByZach merged 1 commit into
candidate-2.0from
settings

Conversation

@CodeByZach

Copy link
Copy Markdown
Owner

Settings become one flat object, every value is checked, and Pace.configure() / Pace.getOptions() replace Pace.options.

Names (old names are removed, not aliased; each one gets a console warning that names its replacement):

Before Now
restartOnPushState restartOnNavigation
document trackDocument
eventLag trackEventLag (its tuning is now internal)
elements: { selectors } waitFor (checked every 100 ms; elements.checkInterval is removed)
ajax: false trackXHR, trackFetch, trackWebSockets: false
ajax.trackMethods requestMethods
ajax.ignoreURLs ignoreRequests
ajax.trackFetch, ajax.trackWebSockets, ajax.maxWait the same names, top level
minTime minVisible
ghostTime hideDelay

Checks. A wrong value or an unknown name is ignored with one console.warn that says what was expected, and the setting keeps its value. Pace no longer throws for a wrong value, and no longer breaks the page's own requests (ajax: { trackMethods: null } made xhr.open() throw).

Changing and reading settings. Pace.configure() changes settings without starting the bar; Pace.start(options) does the same, then starts. Request and navigation settings apply from the next request or navigation, the others from the next run. Pace.getOptions() returns a copy.

Where settings come from. data-pace-options is read only from pace's own <script>, even when markup like <img name="currentScript"> replaces document.currentScript. A window.paceOptions that isn't a plain object (such as <form id="paceOptions">) is ignored with a warning.

Request hooks. Pace hooks into XMLHttpRequest, fetch and WebSocket once it has started with that kind's setting on, so turning one on later works, and one that stays off is left alone.

Tests: every renamed setting has a test that fails on the previous code; each check, configure(), getOptions() and minVisible have new tests. The README lists every setting with its default.

- Settings are one flat object, and each setting given replaces that
  setting: no deep merge, and no question of whether a list is merged or
  replaced. The old names are removed, not kept as aliases:
    restartOnPushState      -> restartOnNavigation
    document                -> trackDocument
    eventLag                -> trackEventLag (its tuning is now internal)
    elements                -> waitFor (a list of selectors; checked every
                               100 ms, which elements.checkInterval set)
    ajax: false             -> trackXHR, trackFetch, trackWebSockets: false
    ajax.trackMethods       -> requestMethods
    ajax.ignoreURLs         -> ignoreRequests
    ajax.trackFetch, ajax.trackWebSockets, ajax.maxWait -> top level
    minTime                 -> minVisible
    ghostTime               -> hideDelay
- Every value is checked when it's given. A wrong value or an unknown name
  is ignored and logged once with console.warn, saying what was expected;
  an old name says what replaced it. Before, a wrong value was used as it
  was: ajax: { trackMethods: null } made the page's own xhr.open() throw,
  and an invalid selector stopped pace. A selector is checked with
  querySelector on an empty DocumentFragment, which throws for an invalid
  one, and an extra source with Reflect.construct, which throws before
  using its arguments when its target can't be used with new; neither
  runs or reads anything of the page's.
- Pace.configure() changes settings without starting the bar, and
  Pace.getOptions() returns a copy of them; Pace.options is removed.
  Settings about requests and navigation apply from the next request or
  navigation; the others from the next run, which keeps a copy of the
  settings it started with, so a bar that is showing doesn't change
  halfway.
- Values are copied when given, and the copy is what's checked and
  kept, so a page changing its own list later changes nothing. RegExps in
  ignoreRequests are copied too: one with the g flag that the page had
  frozen made the page's own send() throw when pace reset its lastIndex.
  A RegExp is recognized with RegExp.prototype's source getter, which
  throws for anything else, so one from another frame (which failed
  instanceof) works. An empty string in ignoreRequests, which matched
  every URL, is rejected. requestMethods match in any case.
- data-pace-options is read only from pace's own <script>, through
  Document.prototype's currentScript getter, since markup such as
  <img name="currentScript"> replaces document.currentScript. Before, the
  first <script data-pace-options> on the page was used. A
  window.paceOptions that isn't a plain object, such as a
  <form id="paceOptions"> the browser exposes under that name, is ignored
  with a warning; before, it stopped the bar.
- Pace hooks into XMLHttpRequest, fetch and WebSocket once it has started
  with that kind's setting on, so turning one on later works, and one that
  stays off is left alone. With its setting off, a kind isn't tracked even
  inside Pace.track.
- waitFor keeps checking every 100 ms: no event says when a selector
  starts to match, and a MutationObserver misses matches that come from
  state, such as :defined or :checked.

Tests cover each new name, every check, configure(), getOptions() and
minVisible, which no test covered before. The existing tests use the new
names; tests of values that are now rejected (maxWait: Infinity,
trackMethods that isn't an array) give way to tests of the warnings, and
the invalid-selector lifecycle test now uses an extra source that throws.
The README lists every setting with its default.
@CodeByZach
CodeByZach merged commit 2401dd7 into candidate-2.0 Nov 16, 2026
6 checks passed
@CodeByZach
CodeByZach deleted the settings branch November 16, 2026 14:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant