Wsync JS client

by Oscar Alberto Quijano Xacur

Table of contents

Introduction

Wsync is an API that makes the server epoch time in milliseconds available to clients. This can be used to synchronize actions on different computers. An example of application are synchronized countdowns, this is, countdowns in which each second changes at the same time in all the clients.

The wsync JavaScript client provides two main functionalities through two classes, ServerDate and CountdownDeadlineElem. The first one provides a method to get the server time on the client side which the second one uses to implement synchronized countdowns. There is also an option of including a countdown in a website without writing JavaScript code.

There is a publicly available wsync server at wsync.net that also provides the JavaScript files we use in this document. If you prefer to run your own wsync server you can find instructions in the server documentation and you can find the JavaScript files in the client git repository.

ServerDate

The class ServerDate provided in the file wsync.js connects to the wsync server and estimates the time difference between the local time and the server time and it uses that offset to compute the server time at any moment without the need of a new connection.

You can run your own server, or use the publicly available one wsync.net.

When instantiating ServerDate, there are two optional parameters.

  1. The first argument is the update interval in minutes. This is, once the offset has been computed, how long to wait to recompute it. The default value is null which means that the offset is computed only once and it is never updated.
  2. The second one is the URL of the wsync server to connect to, if not provided the default value is the public wsync server "wss://wsync.net".

The following example instantiates a server date object in the variable sdate using the default public server and updates the offset every 15 minutes. Note that it needs to run inside a JavaScript module. 

import {ServerDate} from "https://wsync.net/wsync.js";
var sdate=new ServerDate(15);

Defining actions after syncing succeeds or fails

Server date objects have a property called sync_promise, which is a promise that resolves when the offset is first calculated or rejects if it is not obtained in more than 5 seconds. This promise only applies for getting an offset the first time, no promise exist for further connection attempts.

You can either use await to wait for syncing or use the .then() and .catch() promise methods. The example below shows different alerts for each case. 

import {ServerDate} from "https://wsync.net/wsync.js";
var sdate=new ServerDate();
sdate.then(()=> alert("An offset has been obtained"),
()=> alert("Could not get an offset"));

Obtaining the server time

Once the offset has been computed you can use the method get() to estimate the server time. For this purpose it does not crate a new connection, it uses the offset to correct the local time in order to estimate it. The offset itself is saved in the attribute offset

The server time is provided as the number of milliseconds elapsed since the midnight at the beginning of January 1, 1970, UTC. The following example shows an alert with this information after obtaining the offset. 

import {ServerDate} from "https://wsync.net/wsync.js";
var sdate=new ServerDate();
await sdate.sync_promise;
var server_time=sdate.get();
var offset=sdate.offset;
var message=`The current server time is ${server_time} and it has an offset of ${offset} from your local time.`;
alert(message);

Countdowns

In the introduction it is mentioned that having the server time available on the client side can be used to synchronize events between different computers. An example of this are synchronized countdowns.

Countdowns in wsync need to be defined and activated.

Defining a countdown

You can define a countdown with the following two steps:

  1. Define the countdown deadline. You do this by adding the attribute data-wsync-countdown-end to an html element. It's value should be the countdown deadline in date time string format. The countdown is written to the inner HTML of the element with this attribute.
  2. Define countdown message (optional). You can define a message to appear when the countdown is over. You can set this message by adding the attribute data-wsync-countdown-message whose value should be the message to show. If this attribute is not used 00:0 will be shown after the deadline.

The html below defines a div element with a countdown for tonight at midnight in your browser timezone. It is followed by a running countdown activated with the same code.

<div data-wsync-countdown-end="2025-04-05T00:00:00.000Z"></div>

Activate countdowns without writing a single line of JavaScript

You can activate all the countdowns in a HTML document by importing the start_countdowns.js script towards the end of your body. 

<script type="module" src="https://wsync.net/start_countdowns.js"></script>

This first creates a ServerDate object that is used to synchronize all the countdowns found in a website. The object uses the default wsync server wsync.net and its offset is never updated after it is obtained the first time. To select a different server and update interval you can use the element attributes data-wsync-server-date-url and data-wsync-server-date-update-interval. If you have more than one countdown on the same website you only need to use these attributes on one of them.

For example, if you would like to use your own wsync server that you are running at say "wss://wsync_server_example.com" and you would like to update the offset every half an hour for a countdown that finishes tonight at midnight you would do 

<div data-wsync-countdown-end="2025-04-05T00:00:00.000Z"
     data-wsync-server-date-url="wss://wsync_server_example.com"
     data-wsync-server-date-update-interval=30></div>

Activate a countdown with JavaScript

To start a countdown with JavaScript you need to import the class CountdownDeadlineElem from the module coutdown.js. To create a instance of this class the only required argument is an HTML element that defines a countdown. It has two additional optional arguments, a ServerDate (if not provided a new one is created) and the update interval of the countdown in milliseconds (if not provided 50 is used).

The following example shows how to activate a countdown for midnight tonight using JavaScript.

<div id="midnight" data-wsync-countdown-end="2025-04-05T00:00:00.000Z"></div>
<script type="module" >
	  import {CountdownDeadlineElem} from "https://wsync.net/countdown.js";
	  var countdown_elem=document.querySelector("#midnight");
	  var midnight_countdown=new CountdownDeadlineElem(countdown_elem);
</script>

The example below does the same than the previous block but we pass optional second and third arguments. 

<script type="module" >
	  import {CountdownDeadlineElem} from "https://wsync.net/countdown.js";
	  import {ServerDate} from "https://wsync.net/wsync.js";
	  var countdown_elem=document.querySelector("#midnight");
	  var server_date = new ServerDate();
	  var midnight_countdown=new CountdownDeadlineElem(countdown_elem,server_date,100);	  
</script>

Countdown over event

After a countdown reaches zero, either it will show the string 00:0 or the message declared with the attribute data-wsync-countdown-message. You can add additional reactions when a countdown is over by adding handlers to the event "countdown-over". This event bubbles up so you can listen to it from any parent element of the countdown.

The example below defines a handler that defines an alert when the midnight countdown is over. 

<div id="midnight" data-wsync-countdown-end="2025-04-05T00:00:00.000Z"></div>
<script type="module">
  document.addEventListener("countdown-over",
			    (event)=>{alert("Time is over!")});
</script>

Examples

ServerDate

The example below gets the server date, local date and the offset between them. Then it shows the information in an alert window. It needs to run inside a JavaScript module.

import {ServerDate} from "https://wsync.net/wsync.js";
/*New server date object*/
var sdate=new ServerDate();
/*Wait for sync*/
var synced=await sdate.sync_promise;
/*Get epoch from server*/
var server_epoch= sdate.get();
/*Convert to ISO 8601*/
var server_date=new Date(server_epoch).toISOString();
/*Get local time*/
var local_date=new Date().toISOString();
/*Get offset between local time and server*/
var offset=sdate.offset;
/*Show alert showing server time, local time and offset*/
alert(`Server time:\n${server_date}\n\nLocal time:\n${local_date}\n\nOffset:\n${offset}`);