DEV Community: apisurfer

JS Date constructor timezone oddity

apisurfer — Thu, 11 Jan 2024 10:23:39 +0000

new Date('YYYY-MM-DD') might not do what you think it does

For a long time, I only did Date manipulation in JS via some date library that wrapped over the native Date object. There were always a lot of missing features on the native Date. But for some time now I've been listening to how date libraries are rarely necessary these days.

After my short encounter with it, I wouldn't say so. I wasn't aware of how well-protected we all were by those battle-tested date libraries. It's such an easy way to shoot yourself in the foot using plain Date objects. This example alone is enough to make you rethink some things:

new Date('2024-01-01')

What do you think this does? The date format is OK. The date should be parsed and we should get a Date object with the specified date set internally, right? Well, correct to some extent, but it depends on the time zone...

What if I told you that you could end up with a 2023-12-31 when converting that object to a string? If you don't know about Date quirks it's almost a certainty you will end up with this bug eventually.

What if I told you that you could end up with two different dates for these 2 inputs to the Date constructor:

2024-01-01
2024-01-01T00:00:00

This is the reality in which we as web devs live. It's not commonly known behavior unless you worked with something that required a deeper knowledge of the Date internals. This is something that caused a bug in my code the other day. It was reported by users that are behind the UTC. Now, why would that be the case?

It happens because Date assumes the time zone differently based on having time specified vs. the case with no time specified. And by assuming an input in the wrong time zone it ends up with the wrong date being set internally(shifted by a difference in a client's time zone offset to the UTC).

Look at this example, where I'm running the JS on the client located in the UTC+1 zone:

Do you notice any difference? :)

It's weird, it's unexpected, it's unintuitive. But, does it have some meaningful background, maybe some well-defined standard to back it up? Also no. This is a remnant of the old JS world, an error in specification that does not adhere to the ISO 8601 standard and never will because of backward compatibility issues.

new Date('2024-01-01') should do the same as new Date('2024-01-01T00:00:00') but it doesn't. Without time explicitly being set, it assumes that the input parameter('2024-01-01') is in UTC. Now if that code runs on the client that's behind UTC, for example, a western part of the globe. If the client's time zone lags for e.g. 6 hours, the Date constructor will produce a new Date object with the date/time being set to 2023-12-31T18:00:00. On the other hand, if you pass in the 2024-01-01T00:00:00 string(notice that one also doesn't specify a time zone) it won't assume UTC but rather use your local time zone offset and you will get the date object with the exact date/time for your time zone :).

This is where the bugs come from. Date constructor assumes UTC time zone for one input format while on the other hand, it uses the local time zone for the format that has time specified. Pretty unexpected. If you try to do the same inputs using moment.js you will get the expected and consistent behavior because date libraries handle so many weird cases for us out of the box.

It was a bit hard to dig out the exact reason why it behaves like this, but I eventually found the reason on MDN page:

Also, see the mentioned post on the topic and the proposal for a solution — proposed Temporal API. But at the moment this is the situation with Temporal API:

Leaving us with plenty of reasons to still choose to work with external libraries for dates. Just like the following couple of reasons:

// 1. Months are zero-indexed, while days and years are one-indexed
const date = new Date(2022, 0, 1); // January 1, 2022

// 2. Two-digit years are interpreted as 1900-1999
const y2k = new Date(99, 0, 1); // January 1, 1999

// 3. Negative years are allowed, representing years B.C.
const ancient = new Date(-44, 2, 15); // March 15, 45 B.C.

// 4. Parsing date strings can be inconsistent across browsers and locales
const parsedDate = new Date('03/15/2022'); // May not work consistently

// 5. Daylight Saving Time can cause unexpected behavior
const dst = new Date(2021, 2, 14, 2, 30); // March 14, 2021, 03:30 (skipped hour)

By the way, please consider a bit more modern options for handling dates like Day.js or date-fns. I mentioned moment.js just because it was the easiest to reach and verify the behavior, but other than that its usage is no longer recommended.

Measure time with a higher order utility function

apisurfer — Mon, 02 Mar 2020 11:29:44 +0000

I consider closures and higher order functions to be one of the most powerful language features, if not the most powerful. Here is a 2-liner function that uses both of them. Comes in handy for testing, debugging and measuring performance of some chunks of code.

/*
* startTimer creates a function that returns time difference in milliseconds
*/
function startTimer() {
  const startTime = new Date()
  return () => new Date() - startTime
}

Example of usage:

const getTimeDifference = startTimer()

// Should output a number around 3000 after 3 seconds have passed
setTimeout(() => {
  console.log(`${getTimeDifference()} milliseconds have passed!`)
}, 3000)

This allows you to start tracking multiple events at any given time and retrieve the time difference whenever it's required.

Cheers!

takeLatest Promise util function

apisurfer — Mon, 09 Dec 2019 11:16:57 +0000

On frontend, you may have a piece of code that fires network requests very quickly, based on user interaction. Debouncing such actions becomes less and less a viable option because of user experience. Especially with advent of React.js Suspense which deals with this and many other things on a such fine low level. But what if you want to fix such behavior in just a few places, without being reliant on UI libraries. redux-saga has it's methods to battle race conditions but it's tightly related to redux actions. Native window.fetch with AbortController offers network request cancellation mechanism, but is not supported by the older browsers. Maybe there is more than just network requests you want to guard from race conditions?!

In most cases, it just boils down to how your code reacts to resolved promises.

Previously we mentioned an util function that enables cancellation of Promise's success chain. Let's just paste that code here for reference, as we will use it to construct our takeLatest(promise) util function:

const cancelable = (promise) => {
  let hasCancelled = false;

  return {
    promise: promise.then(v => {
      if (hasCancelled) {
        throw { isCancelled: true };
      }

      return v;
    }),
    cancel: () => hasCancelled = true
  }
};

Now, we'll want to create another util function that'll keep track of the previously passed in promise, cancel it if it hasn't finished yet and replace with the new one:

const createTakeLatest = () => {
  let cancelablePromise = null;

  const takeLatest = promise => {
    if (cancelablePromise) {
      cancelablePromise.cancel();
      cancelablePromise = cancelable(promise);
    } else {
      cancelablePromise = cancelable(promise);
    }

    return cancelablePromise.promise;
  };

  return takeLatest;
};

Now we can generate ourselves a tracker of sorts that receives promises, and allows only the last one to finish(if we have multiple concurrent request):

const takeLatest = createTakeLatest()
// imagine having fetchPage async function implemented to fetch a page from a server

for (let i = 0; i < 20; i++) {
  const request = fetch(`/api/someData?page=${i}`)
  takeLatest(request)
    .then(() => console.log('Page fetched'))
    .catch(error => {
      if (!error.isCancelled) {
        // handle only requests that haven't been cancelled
      } 
    })
}

In the example above, only the last request's handlers will be executed, all the rest will get cancelled and caught as errors with isCancelled flag set.

Cancelable Promise util

apisurfer — Fri, 29 Nov 2019 20:53:15 +0000

I found myself using this code and some derivatives time and time again so I decided to share. It's not written by me, and I found it on Edd Mann's blog. There are a few npm libraries that deal with promise cancellation in a similar manner, but I somehow prefer to have this few lines of source code somewhere in my util functions.

Here is the original function that wraps the native Promise and keeps a flag variable to allow us to cancel the .then chain anytime we want. Unfortunately the Promises themselves can't really be canceled.

const cancelable = (promise) => {
  let hasCancelled = false;

  return {
    promise: promise.then(v => {
      if (hasCancelled) {
        throw { isCancelled: true };
      }

      return v;
    }),
    cancel: () => hasCancelled = true
  }
};

When we call the cancelable function by giving it a promise we'll get an object that has a:

promise property, original promise extended with a single .then handler that is able to cancel out all the following .then handlers appended to it later on. Cancellation is based on a local variable hasCancelled. If the flag turns to true before the promise resolves it throws with additional information and bypasses all the latter .then handlers. We should use this property instead of our original promise and append any required .then handlers to it.
cancel method that changes the local hasCancelled flag to true

Usage example:

// mocked fetch function to simulate waiting for a result 10 seconds
const fetchResult = () => new Promise(resolve => {
  setTimeout(() => resolve('response'), 10000)
})

const {promise: result, cancel} = cancelable(fetchResult())

result.catch(error => {
  if (error.isCancelled) console.log('Promise chain cancelled!')
})
result.then(res => console.log(`Handler 1: ${res}`))
result.then(res => console.log(`Handler 2: ${res}`))
      .then(res => console.log(`Handler 3: ${res}`))

// at any point in time we can cancel all of the above success handlers by using cancel function
// catch handler can verify if cancellation is the reason of failure and do something based on it, in this case log out "Promise chain cancelled!"
cancel()

It's important to note that by using this approach we can't cancel out any handlers that were attached directly to an original promise object passed to our util function. This mechanism is only able to cancel out .then handlers appended to the returned promise. A bit weird but it's not bad once you get used to it. You can still hold a reference to both the original and derived promise.

Another note is that error with isCancelled flag ends up in the catch handler only when the original Promise eventually resolves. All of this is essentially a way for us to say: once and if this Promise resolves, skip the success handlers because we are not interested in handling this data anymore.

I'm curious to hear from you of another similar approaches you might have and why they are better/worse 🍺

Handling custom error types in Express.js

apisurfer — Wed, 27 Nov 2019 13:19:34 +0000

In 2 previous posts we explained how to create a custom error type and created a few custom HTTP errors we'll use to automatically send HTTP response to an error using Express.js error middleware and util functions. Our custom error types allow us to generically handle well-defined types of failure and auto-respond with appropriate HTTP status code and JSON data, if any is to be sent to the client.

To explain the direction we are headed, well known errors will be handled this way:

app.get('/user/me', function(req, res) {
  db.getUser(...)
    .then(user => res.json(user))
    .catch(res.respond.notFound)
    // or
    .catch(error => res.respond.notFound(error, {reason: 'User ID not found'}))
})

Notice error handler functions passed to the .catch methods. That is the API we want to construct to support automatic error handling, but also allow to send some context data alongside error in the HTTP response.

To get there, first we need to have something that will expose res.respond API for every response. Ideal job for a tiny middleware function:

function attachResponder(req, res, next) {
    res.respond = createResponder(req, res, next);
    next();
}

We probably want our middleware to run before all other request handlers to expose the respond API for all requests. So it'll need to be set before any other handlers on a Express.js Router:

app.use(attachResponder)
// ...
app.get('/user/me', function(req, res) {
// ...

Great, logic to have res.respond available on every request is here. But we haven't defined the logic behind its interface. Here it is:

function createResponder(req, res, next) {
  const responder = {
    _forwardError(error, ErrorClass = Error, data) {
      const errorMessage = error instanceof Error ? error.message : error;
      const errorToForward = new ErrorClass(errorMessage, data);
      // forwards error to an error handler middleware
      next(errorToForward);
    },

    badRequest(error, data) {
      return responder._forwardError(error, HttpBadRequest, data);
    },
    notFound(error, data) {
      return responder._forwardError(error, HttpNotFound, data);
    },
    internalServerError(error, data) {
      return responder._forwardError(error, HttpInternalServer, data);
    }
  };

  return responder;
}

Calling this function inside middleware function attaches responder object to res.respond. Responder itself exposes 3 meaningful methods: badRequest, notFound and internalServerError. All 3 can be called without parameters, only with Error instance, only with error explanation(string) or with error and additional data we want to pass in the response.
_forwardError method mainly serves for code reuse. It resolves the error type and creates custom error type with appropriate message and data. That error is then forwarded to an Express.js error handler middleware.

Express.js error handling middleware is always declared as the last middleware on an Express.js Router. It needs to be able to receive and handle all the errors previous middleware functions might have thrown. It's pretty simple to create one that just ends the response with HTTP 500 error for every error it catches:

function errorHandler(error, req, res, next) {
  res.sendStatus(httpResponseCodes.INTERNAL_SERVER_ERROR)
}

We'd attach it to an Express.js app like so:

app.use(attachResponder)
// ...
// app.get('/user/me', function(req, res) {
// ...
app.use(errorHandler)

But we don't want to respond with 500 – Internal server error every time. Especially since we have our custom error types and their subtype. We can now do all sorts of smart logic inside this handler. We can recognize our custom errors, and since all of them have a status code and a message, just respond with that information. If you don't remember the custom error types we've defined you can look them up in the previous post.

function errorHandler(error, req, res, next) {
  if (error instanceof HttpError) {
    res.status(error.statusCode).json(error.data)
  } else {
    res.sendStatus(httpResponseCodes.INTERNAL_SERVER_ERROR)
  }
}

We've reached the functional API we wanted from the start and we now have a logic that automatically processes well-defined error types and finishes the response gracefully. If we continued to add another error types that fall under the HttpError subtype it would all end up being automatically handled for us inside error handler middleware. Additional benefit of our custom errors going through the single point is that it lends itself great for logging/monitoring purposes. All other, generic errors in this case would just end up as an HTTP 500 error response.

Idea:
Responder API could be further extended to provide a means of responding to all kinds of request, even the successful ones. That is all omitted from this posts for the sake of brevity.

From custom error types to a custom error subtype

apisurfer — Tue, 26 Nov 2019 15:39:28 +0000

Previously we defined our most basic custom error class that extends the Javascript's Error prototype:

class MyError extends Error {
  constructor(message) {
    super(message)
    this.name = 'MyError'
    Error.captureStackTrace(this, MyError)
  }
}

Now let's create an error subtype that will be used to indicate certain failures for a few well known HTTP response states. MyError class and error name will be renamed to a more generic name that goes along with the context of an HTTP server — HttpError.

To keep it short, we'll pick only 3 commonly encountered HTTP status codes and create custom errors for them.

constants/httpResponseCodes.js

module.exports = {
    BAD_REQUEST: 400,
    NOT_FOUND: 404,
    INTERNAL_SERVER_ERROR: 500,
}

utils/errors.js

const responseCodes = require('../constants/httpResponseCodes.js')

class HttpError extends Error {
  constructor({ message, name, statusCode, data }) {
    super(message);
    this.name = name;
    this.statusCode = statusCode;
    this.data = data;
    Error.captureStackTrace(this, HttpError);
  }
}

class HttpBadRequest extends HttpError {
  constructor(message = 'Bad request', data) {
    super({
      message,
      name: "HttpBadRequest",
      statusCode: responseCodes.BAD_REQUEST,
      data
    });
  }
}

class HttpNotFound extends HttpError {
  constructor(message = 'Not Found', data) {
    super({
      message,
      name: "HttpNotFound",
      statusCode: responseCodes.NOT_FOUND,
      data
    });
  }
}

class HttpInternalServerError extends HttpError {
  constructor(message = 'Internal server error', data) {
    super({
      message,
      name: "HttpInternalServerError",
      statusCode: responseCodes.INTERNAL_SERVER_ERROR,
      data
    });
  }
}

module.exports = {
  HttpError,
  HttpBadRequest,
  HttpNotFound,
  HttpInternalServerError
}

We now have our custom error types and their subtype(HttpError), that will allow us to handle all of them in a generic way in the following post. A lot of code could be stripped down by using prototypal inheritance at a lower level. But it's not such a problem even if so verbose, it's very easy to follow through and the code probably won't change much once it's finished. There are libraries out there that make creating custom errors easier, but I like to have such a crucial part of the service completely independent and understandable.

Custom error types in Node.js

apisurfer — Mon, 25 Nov 2019 16:33:59 +0000

Custom error types in node can provide a clearer picture of a failure. Relying on generic errors often leaves us guessing what had happened down the chain. Custom errors can help us identify certain, well known sets of failures and even subclass them for a more generalized handler functions.

In this series of posts we'll go from constructing a simplest possible custom error(this post) to defining a few, well known HTTP errors and using them inside an Express.js HTTP server framework to craft automatic error responses.

Simplest way to create a custom error type is to just extend an Error's prototype and initialize the original Error through a constructor:

class MyError extends Error {
  constructor(message) {
    super(message)
  }
}

That's it!

The message we pass from the constructor to the "super" call is actually the same parameter you'd pass with the new Error('Something failed!'). Message is just forwarded to the same constructor to set up an error with a message and a stack trace.

There are 2 small things to fix though. If you log out the error created with MyError class:

const error = new MyError('problem')
console.log(error)

You'll notice that error type is logged as "Error":

Error: problem
    at <anonymous>:1:15

To fix this we just need to augment our error object with a "name" property inside constructor:

  constructor(message) {
    super(message)
    this.name = 'MyError'
  }

Now if we try previous example we'll see something like:

MyError: problem
    at <anonymous>:1:15

1/2 fixed. The only thing remaining is that our stack trace might include the mention of our custom error class constructor. We don't want to see an error creation in our stack frames, only the real code that caused the issue. Fix is simple, single additional line in the constructor will take care of that:

  Error.captureStackTrace(this, MyError)

This will omit all of the stack frames invoked by code inside MyError itself.

The final code is:

class MyError extends Error {
  constructor(message) {
    super(message)
    this.name = 'MyError'
    Error.captureStackTrace(this, MyError)
  }
}

In next post we'll go from custom error type to a custom error subtype that will enable us to treat all of our custom error types in a generic way.

Communicating with an iframe — postMessage bare bones example

apisurfer — Mon, 25 Nov 2019 12:14:47 +0000

I keep forgetting how communication between a main window and an iframe works because I don't use it so often. Most articles go in depth of how and why, rather than serve as a quick recap, so I'll try to do that here.

main window and an iframe can exchange data using postMessages.
data that is sent over those messages needs to be serialized
it's tricky to start communication because most of the time your aren't sure what loaded first: main window or an iframe. If you control both, it's much easier and this example will cover such use-case.
never just blindly act upon received message without checking it's origin first. Create a whitelist for allowed origins. Otherwise any website could iframe yours and try to manipulate it by sending it bogus messages

Example consists of 2 HTML files:

index.html(main window)
iframe.html(embedded page)

index.html — acts only for messages received from trusted origins, fully controls the rendering of an iframe. First sets event handlers and then sets and iframe src to load it.

<!DOCTYPE html>
<html>
  <head>
    <title>main</title>
  </head>
  <body>
    <iframe></iframe>

    <script>
      const trustedOrigins = ["http://localhost:5000"];

      const iframe = document.querySelector("iframe");
      iframe.addEventListener("load", () => {
        iframe.contentWindow.postMessage(
          JSON.stringify({ message: "this should be delivered to an iframe" })
        );
      });
      iframe.setAttribute("src", "iframe.html");

      function onMsg(msg) {
        if (!trustedOrigins.includes(msg.origin)) return;
        console.log(`Message from an iframe`, msg);
      }

      window.addEventListener("message", onMsg, false);
    </script>
  </body>
</html>

iframe.html — very similar to index.html. Logic behind trusted origins is the same, and since we definitely know this page will be the 2nd to load it only needs to listen for first message from main window and respond to it.

<!DOCTYPE html>
<html>
  <head>
    <title>iframe</title>
    <meta charset="utf-8" />
    <script>
      const trustedOrigins = ["http://localhost:5000"];

      function onMsg(msg) {
        if (!trustedOrigins.includes(msg.origin)) return;
        console.log(`Message from main window`, msg);
        parent.postMessage(
          JSON.stringify({
            message: "this should be delivered to main window"
          })
        );
      }

      window.addEventListener("message", onMsg, false);
    </script>
  </head>
  <body>
    <h1>Iframe body</h1>
  </body>
</html>

To test this out you could just paste the code to index.html and iframe.html files located in the same folder and use simple HTTP server tool. Run npm install http-server -g to install it. After that, open up a terminal instance, position yourself in the above mentioned folder containing 2 HTML files and run:

http-server -p 5000 .

This starts a static HTTP server on port 5000 and you should be able to open up http://localhost:5000, enter the browser's dev tools console and see logged out postMessages.

Note: some browser extensions might also want to talk with your iframe and it can be harder to filter them out, since they can inject code to a website and try to access your iframe from a legitimate domain. Easiest circumvention, but not perfect would be passing some kind of token or key to confirm message is coming from the right source.

Exponential backoff logic for a code scheduler

apisurfer — Sat, 23 Nov 2019 10:07:01 +0000

We have our scheduler factory from a previous post:

function createScheduler({ callback, time, callbackTimeout }) {
  let run;
  let timeoutId;
  let ticker;

  function pause(time) {
    return new Promise(resolve => {
      timeoutId = setTimeout(resolve, time);
    });
  }

  async function* cycle(time) {
    run = true;

    while (run) {
      yield pause(time);
    }
  }

  async function runPeriodically() {
    if (!ticker || !run) {
      ticker = cycle(time);
    }

    for await (let tick of ticker) {
      if (callbackTimeout) {
        await Promise.race([callback(), pause(callbackTimeout)]);
      } else {
        await callback();
      }
    }
  }

  function stop() {
    clearTimeout(timeoutId);
    run = false;
  }

  return {
    runPeriodically,
    stop
  };
}

It creates a scheduler that runs a specified function periodically in defined time intervals. Final thing we are going to add is an exponential backoff logic, for cases when callback function fails or timeouts. The feedback(error) will be provided through communication with an iterator object. In case we send an error, it'll start to prolong the cycle duration. Otherwise, it'll shorten it. To do this we'll need to:

update a generator function to keep track of current wait time and based on error received back, prolong the wait duration if error is received, shorten it otherwise
swap "for await" loop using a while loop so we can pass values back to the iterator
throw an error on a callback timeout, so we can handle it like any other error happening inside the callback itself
add new configuration parameters to a scheduler factory function so we can control the exponential backoff multiplier, and set a maximum allowed cycle duration

Since this is starting to add up and is becoming harder to follow I'll just paste the final code here and in a offer a codesandbox usage example at the end of the post so you can test it out:

Final code:

function createScheduler({
  callback,
  time,
  callbackTimeout,
  backoffMultiplier = 1.5,
  backoffMaxTime = 20000
}) {
  let run;
  let timeoutId;
  let ticker;

  function pause(time) {
    return new Promise(resolve => {
      timeoutId = setTimeout(resolve, time);
    });
  }

  async function* cycle(time) {
    let currentWaitTime = time;
    run = true;

    while (run) {
      const error = yield pause(currentWaitTime);
      if (error) {
        currentWaitTime = Math.min(
          currentWaitTime * backoffMultiplier,
          backoffMaxTime
        );
      } else {
        currentWaitTime = Math.max(currentWaitTime / backoffMultiplier, time);
      }
    }
  }

  async function runPeriodically() {
    if (!ticker || !run) {
      ticker = cycle(time);
    }

    let item = await ticker.next();

    while (!item.done) {
      try {
        if (callbackTimeout) {
          await Promise.race([
            callback(),
            pause(callbackTimeout).then(() => {
              throw new Error("Callback timeout");
            })
          ]);
        } else {
          await callback();
        }
        item = await ticker.next();
      } catch (error) {
        item = await ticker.next(error);
      }
    }
  }

  function stop() {
    clearTimeout(timeoutId);
    run = false;
  }

  return {
    runPeriodically,
    stop
  };
}

What this periodic scheduler logic allows us to do:

create an instance of a scheduler which can run an (a)sync function(callback) periodically in given time intervals
run and stop the loop whenever we see fit
runPeriodically resolves it's Promise when the loop is stopped which can be helpful
if callbackTimeout parameter is specified code will take care that waiting for callback to resolve won't go over our time budget
if callback fails or a timeout happens, the error is fed back to the iterator which increases the duration of a cycle using exponential backoff logic. If no error is returned duration is decreased one step at a time to our original specified duration

Here is a usage example where we set doSomething function to run every 2 seconds and give it 1 second of time to execute(try to uncomment the return line inside logTime function). If doSomething function fails or encounters a timeout, cycle duration is multiplied with backoffMultiplier to set a new cycle duration. And this happens until duration reaches at most backoffMaxTime number(20 seconds). If cycles go without an error, duration will be lowered using a multiplier towards the original cycle duration. setTimeout at the end kills the processing loop after 60 seconds.

Hopefully this series brought some new ideas and perspectives around working with asynchronous code and scheduling. Scheduler as it is, may not be the best and for every use-case but it serves as an example of how flexible Javascript's asynchronous syntax can be. From one-liner pause function implemented with a Promise and setTimeout to solid periodic code scheduler in just over 60 lines of code.

Timeout mechanism using Promise.race

apisurfer — Fri, 22 Nov 2019 14:28:12 +0000

So we have a scheduler factory function. Simple mechanism that runs code periodically. Here is the code:

function createScheduler({ callback, time }) {
  let run;
  let timeoutId;
  let ticker;

  function pause(time) {
    return new Promise(resolve => {
      timeoutId = setTimeout(resolve, time);
    });
  }

  async function* cycle(time) {
    run = true;

    while (run) {
      yield pause(time);
    }
  }

  async function runPeriodically() {
    if (!ticker || !run) {
      ticker = cycle(time);
    }

    for await (let tick of ticker) {
      await callback();
    }
  }

  function stop() {
    clearTimeout(timeoutId);
    run = false;
  }

  return {
    runPeriodically,
    stop
  };
}

As said in the previous post, we can't blindly await on the callback function that is being passed from outside of our code. We can't know for sure how fast or even if it'll ever finish. To guard ourself from unexpected scenarios we'll implement a timeout mechanism using Promise.race function. It allows us to race with the response from the callback function. If callback isn't resolved until some amount of time we can force-skip into a next cycle. Code inside our "for await" loop will slightly change and incorporate our pause function which will act as a reference point in time before which we expect to see some results.

So instead of blindly awaiting on a callback:

await callback();

This is how we would set a fixed 5 seconds timeout:

await Promise.race([callback(), pause(5000)]);

This way we protect our piece of code from stalling when something goes bad within the logic of a callback function. To make it more ergonomic, let's parametrize the timeout duration and update our previous code:

function createScheduler({ callback, time, callbackTimeout }) {
  let run;
  let timeoutId;
  let ticker;

  function pause(time) {
    return new Promise(resolve => {
      timeoutId = setTimeout(resolve, time);
    });
  }

  async function* cycle(time) {
    run = true;

    while (run) {
      yield pause(time);
    }
  }

  async function runPeriodically() {
    if (!ticker || !run) {
      ticker = cycle(time);
    }

    for await (let tick of ticker) {
      if (callbackTimeout) {
        await Promise.race([callback(), pause(callbackTimeout)]);
      } else {
        await callback();
      }
    }
  }

  function stop() {
    clearTimeout(timeoutId);
    run = false;
  }

  return {
    runPeriodically,
    stop
  };
}

It seems like we've covered potential pitfalls for regular use-cases, so next post will cover a bonus feature using async generators and will serve as a wrap for this series.

Implementing scheduler's stop mechanism

apisurfer — Thu, 21 Nov 2019 19:44:23 +0000

In previous post, we untangled our pause and loop mechanisms but the main flaw of not being able to stop the loop remained. Now we are going to rectify this. From previous code:

const pause = time => new Promise(resolve => setTimeout(resolve, time));

async function* cycle(time) {
  while (true) {
    yield pause(time);
  }
}

async function runPeriodically(callback, time) {
  for await (let tick of cycle(time)) {
    await callback();
  }
}

And it's usage to log current time every 2 seconds:

function logTime() {
  const time = new Date();
  console.log(time.toLocaleTimeString());
}

runPeriodically(logTime, 2000);

We'll need to transfer to a bit more complex constructs. We need to keep track of state to be able to gracefully stop. There are 2 approaches to encapsulate all the state and functionality: using some kind of factory function or a class. I'll stick with the factory function because I don't want to worry about this, new, what is public etc. Our code transforms into this:

function createScheduler({ callback, time }) {
  let run;
  let timeoutId;

  function pause(time) {
    return new Promise(resolve => {
      timeoutId = setTimeout(resolve, time);
    });
  }

  async function* cycle(time) {
    run = true;
    while (run) {
      yield pause(time);
    }
  }

  async function runPeriodically() {
    for await (let tick of cycle(time)) {
      await callback();
    }
  }

  function stop() {
    clearTimeout(timeoutId);
    run = false;
  }

  return {
    runPeriodically,
    stop
  };
}

createScheduler factory function expects object with 2 parameters, callback function that is executed at each cycle/iteration and time parameter that defines the duration of a cycle. The same parameters we previously sent to runPeriodically function. 2 local variables are used to gracefully stop the loop: run and timeoutId. When run switches to false, it's a signal to generator function to exit. Exit from the generator function in turn also causes our "for await" loop inside runPeriodically function to finish. Function that controls everything needed for a graceful stop is of course stop. It clears pending timeout(if any) and sets a flag to signal a termination of a generator's while loop. At the end of our factory function we return an object containing functions accessible from the outside code, a function to run the loop and a function to stop it.

Great! We now have a way to run and stop the loop whenever needed. But we have a new problem 😅. We probably want to handle only a single loop at any given time for a single scheduler instance. If someone called runPeriodically a couple of times in a row, this would start parallel but out-of-sync loops that share a common state used for termination. Not good! The cause of the issue is within a "for await" loop definition:

for await (let tick of cycle(time)) {
  await callback();
}

cycle(time) creates a new iterator every time runPeriodically is called and the easiest way to fix this is to simply share this iterator through a common state. Just like with termination variables, and initialize a new one only if iterator is not yet created or the previous one has finished. To put it into code:

function createScheduler({ callback, time }) {
  let run;
  let timeoutId;
  let ticker;

  function pause(time) {
    return new Promise(resolve => {
      timeoutId = setTimeout(resolve, time);
    });
  }

  async function* cycle(time) {
    run = true;

    while (run) {
      yield pause(time);
    }
  }

  async function runPeriodically() {
    if (!ticker || !run) {
      ticker = cycle(time);
    }

    for await (let tick of ticker) {
      await callback();
    }
  }

  function stop() {
    clearTimeout(timeoutId);
    run = false;
  }

  return {
    runPeriodically,
    stop
  };
}

Main features are covered. We can:

create an instance of a scheduler
define a function we want to run on every cycle(callback) and a duration of a cycle
run and stop the loop whenever we see fit
additionally, runPeriodically resolves it's Promise when the loop is stopped which can be helpful

Example of usage:

const scheduler = createScheduler({ callback: logTime, time: 2000 });
scheduler.runPeriodically();

// at any point in time we can halt the loop using
scheduler.stop()

// or restart it
scheduler.runPeriodically();

Pretty neat, but we can't know how long the callback function will execute. It's provided from somewhere outside and it's unsafe to wait for it indefinitely to finish. We need a timeout mechanism if we want to avoid our code hanging at some point because of an external function failing or taking long time to finish. Fortunately, this can be achieved in a pretty elegant way using Promise API and we'll see how in the next, shorter post 😅. Thanks for reading!

Improving our periodic code scheduler

apisurfer — Wed, 20 Nov 2019 16:05:40 +0000

Previously, we constructed a pretty simple and naive system that periodically runs a function. Not great, not terrible. Let's try to make it better one step at a time. Main drawback was that there was no way to stop it, but we'll get there. First, we are going to move some logic to an async generator. They work great with infinite streams. Our driving logic is basically an infinite stream of events that happen at a specified amount of time. We'll move the part that generates pause events to an async generator, while the loop will slightly change it's face and become a bit slicker to use, even though it might also need a refactor in the future.

From previous code:

const pause = time => new Promise(resolve => setTimeout(resolve, time))

async function runPeriodically(callback, time) {
  while (true) {
    await callback()
    await pause(time)
  }
}

And it's usage:

function logTime() {
    const time = new Date()
    console.log(time.toLocaleTimeString())
}

runPeriodically(logTime, 2000)

We move pause generation to an async generator and tweak the iterating loop:

async function* cycle(time) {
    while(true) {
        yield pause(time)
    }
}

async function runPeriodically(callback, time) {
    for await (let tick of cycle(time)) {
        await callback()
    }
}

runPeriodically function can still be used exactly the same and is still with the fundamental problem of not being able stop the loop once it's been started. But the loop now only worries about the actual code that runs on every iteration, while async generator implements rudimental logic to yield pause events. Generators offer some unique set of features that allow them to communicate back and forth with the rest of the code and that's something we'll use to construct a more robust mechanism. Upcoming posts will provide several tweaks and fixes that give greater control over this kind of code runner.