ScheduleFlushToURL function in `nuqs` source code.

In this article, we review scheduleFlushToURL function in nuqs source code. We will look at:

1. scheduleFlushToURL function

2. Usage

scheduleFlushToURL function

scheduleFlushToURL is a function that you would find in update-queue.ts file in nuqs package. To understand what this function does, we can review the comment, defined just above this function starting from line number 73. 

Here’s the functon’s comment: 

/**
 * Eventually flush the update queue to the URL query string.
 *
 * This takes care of throttling to avoid hitting browsers limits
 * on calls to the history pushState/replaceState APIs, and defers
 * the call so that individual query state updates can be batched
 * when running in the same event loop tick.
 *
 * @returns a Promise to the URLSearchParams that have been applied.
 */
export function scheduleFlushToURL({
  getSearchParamsSnapshot = getSearchParamsSnapshotFromLocation,
  updateUrl,
  rateLimitFactor = 1
}: Pick<
  AdapterInterface,
  'updateUrl' | 'getSearchParamsSnapshot' | 'rateLimitFactor'
>) {

At line number 22, you will find a variable named flushPromiceCache and Its return type is Promise<URLSearchParams> and it is initialized to null.At line number 91, you will find this if Statement:

 if (flushPromiseCache === null) {

A new promise is assigned to the variable flushPromiseCache. It does some computation and there is also debug used. 

There are two functions that are defined inside this promise the first one is flushNow.

 function flushNow() {
        lastFlushTimestamp = performance.now()
        const [search, error] = flushUpdateQueue({
          updateUrl,
          getSearchParamsSnapshot
        })
        if (error === null) {
          resolve(search)
        } else {
          reject(search)
        }
        flushPromiseCache = null
      }

The second one is runOnNextTick:

function runOnNextTick() {
        const now = performance.now()
        const timeSinceLastFlush = now - lastFlushTimestamp
        const throttleMs = queueOptions.throttleMs
        const flushInMs =
          rateLimitFactor *
          Math.max(0, Math.min(throttleMs, throttleMs - timeSinceLastFlush))
        debug(
          '[nuqs queue] Scheduling flush in %f ms. Throttled at %f ms',
          flushInMs,
          throttleMs
        )
        if (flushInMs === 0) {
          // Since we're already in the "next tick" from queued updates,
          // no need to do setTimeout(0) here.
          flushNow()
        } else {
          setTimeout(flushNow, flushInMs)
        }
      }

Lets look at the comment defined just above the runOnNextTick function:

// We run the logic on the next event loop tick to allow
// multiple query updates to set their own throttleMs value.

And finally the promise is returned.

Usage

You will find that this schedulerFlushToURL is used overall in three places

schedulerFlushToURL function is returned at line number 295 in a function named useQueryState.ts 

sheduleFlushToURL is imported from update-queue 

import {
  FLUSH_RATE_LIMIT_MS,
  enqueueQueryStringUpdate,
  getQueuedValue,
  scheduleFlushToURL
} from './update-queue'

About me:

Hey, my name is Ramu Narasinga. I study large open-source projects and create content about their codebase architecture and best practices, sharing it through articles, videos.

Configure features such as Changesets, Supabase auth in your Next.js project using Think Throo CLI.

Email — ramu@thinkthroo.com

My Github — https://github.com/ramu-narasinga

My website — https://ramunarasinga.com

My YouTube channel — https://www.youtube.com/@ramu-narasinga

Learning platform — https://thinkthroo.com

Codebase Architecture — https://app.thinkthroo.com/architecture

Best practices — https://app.thinkthroo.com/best-practices

Production-grade projects — https://app.thinkthroo.com/production-grade-projects

References

1. https://github.com/47ng/nuqs/blob/next/packages/nuqs/src/useQueryState.ts#L295

2. https://github.com/47ng/nuqs/blob/next/packages/nuqs/src/update-queue.ts#L83

3. https://github.com/47ng/nuqs/blob/next/packages/nuqs/src/update-queue.ts#L22