matssocket

MatsSocket JavaScript client library

MatsSocket is a WebSocket-based client-server solution which bridges the asynchronous message based nature of Mats³ all the way out to your end user client applications, featuring bidirectional communication. It consists of a small MatsSocketServer API which is implemented on top of the Mats³ API and JSR 356 Java API for WebSockets (which most Servlet Containers implement), as well as client libraries - for which there currently exists JavaScript and Dart/Flutter implementations.

This is the JavaScript client library for MatsSocket. Compatible with web browsers and Node.js. The client is coded using EcmaScript Modules (ESM), and bundled into USM (Universal Module Definition) modules, also minified, using Rollup.

• Native EcmaScript Modules (ESM) - use the source files directly - dist/MatsSocket.js (or lib/MatsSocket.js), and siblings.
• Native EcmaScript Modules (ESM) - bundled - dist/MatsSocket.esm.js
• Native EcmaScript Modules (ESM) - bundled, minified - dist/MatsSocket.esm.min.js
• Universal Module Definition (UMD) - bundled - dist/MatsSocket.umd.cjs and ..umd.js
• Universal Module Definition (UMD) - bundled, minified - dist/MatsSocket.umd.min.cjs and ..umd.min.js
• A ZIP-file containing the source files - dist/matssocket-<version>-js.zip

Other deliverables:

• TS type files are created in dist/ (the source files are also copied from lib/ to dist/, thus available both places)
• Map files for produced bundles are also created in dist/.
• JSDoc is provided in jsdoc/index.html.

Example

To get a gist of how this works on the client, here is a small JavaScript client code example:

// Set up the MatsSocket.
let matsSocket = new MatsSocket("TestApp", "1.2.3",
    ['wss://matssocketserver-one.example.com/matssocket',
        'wss://matssocketserver-two.example.com/matssocket']);

// Using bogus example authorization.
matsSocket.setAuthorizationExpiredCallback(function (event) {
    // Emulate that it takes some time to get new auth.
    setTimeout(function () {
        let expiry = Date.now() + 20000;
        matsSocket.setCurrentAuthorization("DummyAuth:example", expiry, 10000);
    }, 100);
});

// Perform a Request to server, which will forward the Request to a Mats endpoint, whose
// reply comes back here, resolving the returned Promise.
matsSocket.request("MatsSocketEndpoint", "TraceId_" + matsSocket.randomId(6), {
    string: "Request String",
    number: Math.E
}).then(function (messageEvent) {
    console.log("REQUEST-with-Promise resolved, i.e. REPLY from Mats Endpoint. Took "
        + messageEvent.roundTripMillis + " ms: " + JSON.stringify(messageEvent.data));
});

More examples are in the MatsSocket README.md. The JS integration tests shows all features of the MatsSocket client.

This JS Client doesn't have any dependencies, except for the WebSocket implementation provided by the environment (browser or Node.js). When running in Node.js, it expects the module ws to be available, require()'ing it dynamically.

MatsSocket code is at GitHub, with the JavaScript client library residing in the matssocket-client-javascript subproject.

For Development of the library itself, see README-development.md.

CDN

You can include the MatsSocket JS client library straight from an HTML page using a CDN. This can facilitate "buildless" web development.

For production use, you should always use a specific version (not latest/default), and you should use the integrity attribute to verify the integrity of the delivered files!

Note wrt. integrity constraint with importmaps and modulepreload: you must be very careful to use the exact same URL in the 'imports' map, as in the 'integrity' constraint map - or the preload, vs. actual import! Only exact matches are actually checked: If you have a typo in the URL, or reference a different URL, in the integrity constraint, no integrity check is performed on your import, and it will simply pass! Make sure that it kicks in by messing with the hash: You should get an error in the Console and fail to load the module.

There are examples of how to CDN-include with all three modes (UMD, ESM and importmaps) in the test server's webapp dir, the three files using_cdn_*.html - and with small examples further down.

jsDelivr

• HTML view resides at (latest): https://www.jsdelivr.com/package/npm/matssocket, specific version, e.g. 1.0.0-rc1-2025-10-04
• CDN URL (latest): https://cdn.jsdelivr.net/npm/matssocket/, specific version, e.g. 1.0.0-rc1-2025-10-04

The version property can also be dynamic tags like latest or rc, but only use this in experimentation and development, not in production! Using dynamic tags precludes the use of the integrity attribute.

• ESM minified module, latest: https://cdn.jsdelivr.net/npm/matssocket@latest/dist/MatsSocket.esm.min.js
• UMD minified module, latest: https://cdn.jsdelivr.net/npm/matssocket@latest/dist/MatsSocket.umd.min.js

You want to change the latest to a specific version, e.g. 1.0.0-rc1-2025-10-04.

In a development situation, you might want to remove the ".min" part.

UNPKG

• HTML view resides at (latest): https://app.unpkg.com/matssocket/, specific version, e.g. 1.0.0-rc1-2025-10-04

The version property can also be dynamic tags like latest or rc, but only use this in experimentation and development, not in production! Using dynamic tags precludes the use of the integrity attribute. Note that UNPKG's tags-based URLs redirects to the specific tagged version (as opposed to jsDelivr, which just directly serves the tagged version)

• ESM minified module, latest: https://unpkg.com/matssocket@latest/dist/MatsSocket.esm.min.js
• UMD minified module, latest: https://unpkg.com/matssocket@latest/dist/MatsSocket.umd.min.js

You want to change the latest to a specific version, e.g. 1.0.0-rc1-2025-10-04.

In a development situation, you might want to remove the ".min" part.

esm.sh

Esm.sh is only for modern ESM <script type="module"> projects - no UMD! It is powered by Cloudflare. Esm.sh does not have an HTML view of the package.

The version property can be dynamic tags like latest or rc, but only use this in experimentation and development, not in production!

Esm.sh doesn't yet support Subresource Integrity (SRI): It uses an indirection solution, where the target file is a shim that again refers to a different import (open the URLs below directly in a browser and see!), and it rewrites the target resource, thus you cannot calculate the hash independently. Evidently this is worked on!

• 'latest': https://esm.sh/matssocket
• 'rc': https://esm.sh/matssocket@rc
• Specific version: https://esm.sh/matssocket@1.0.0-rc1-2025-10-04
• Specific file: https://esm.sh/matssocket@rc/dist/MatsSocket.esm.js, but this doesn't give you the non-minified version as you might have hoped; As mentioned, esm.sh rewrites the targets!

Inclusion in HTML

Exemplified with the jsDelivr CDN. You must choose the version, and find the hash for the integrity attribute.

To get the integrity hash, a quick way is to first just use a wrong hash, e.g. "sha384-xyz". Both Firefox and Chrome will in the dev console error log show the hash it calculated and compared with (based on the prefix you used, e.g. "sha384-" or "sha256-"). Remember to add the prefix! For a bit of extra paranoia, you should verify that the hashes are the same for jsDelivr and UNPKG. (As mentioned above, esm.sh doesn't support SRI)

(If you drop the version, or specify latest, you will get the latest stable version, which will change over time - and you cannot use the integrity attribute. Only for experimentation and development! You could also then drop the ".min" part of the filename to directly get the full files, which might aid debugging.)

Inclusion using UMD:

<script src="https://cdn.jsdelivr.net/npm/matssocket@1.0.0-2025-10-27/dist/MatsSocket.umd.min.js"
        integrity="sha384-+UxNRizq/ZpH48ilqcv7NHJZkt6G7XLz4lJudukoRRO3XeUqhw3/Wac/WY2iSbaa"
        crossorigin="anonymous"></script>

<script>
    let matsSocket = new matssocket.MatsSocket("TestApp", "1.2.3", ['ws://localhost:8080/matssocket']);
    // ...
</script>

Inclusion using ESM - note the use of modulepreload to be able to use the integrity attribute.

Note that the URL in the modulepreload must match the URL in the integrity attribute, otherwise the import will just slide through without being checked.

<link rel="modulepreload"
      href="https://cdn.jsdelivr.net/npm/matssocket@1.0.0-2025-10-27/dist/MatsSocket.esm.min.js"
      integrity="sha384-ECJ2VSOkdXM4imJBt8wb0DroKD6HoESrVC+PG4/TiFB0bjCgl1IAJiV2HFfkMW2Z"
      crossorigin="anonymous">

<script type="module">
    import * as matssocket from "https://cdn.jsdelivr.net/npm/matssocket@1.0.0-2025-10-27/dist/MatsSocket.esm.min.js";
    // .. or use named imports: import { MatsSocket } from "....."

    // Either directly here, or in additional <script type="module"> blocks:
    let matsSocket = new matssocket.MatsSocket("TestApp", "1.2.3", ['ws://localhost:8080/matssocket']);
    // ...
</script>

.. or ESM via import maps (highly recommended).

Note that the URL in the imports map must match the URL in the integrity attribute, otherwise the import will just slide through without being checked.

<script type="importmap">
{
  "imports": {
    "matssocket": "https://cdn.jsdelivr.net/npm/matssocket@1.0.0-2025-10-27/dist/MatsSocket.esm.min.js"
  },
  "integrity": {
    "https://cdn.jsdelivr.net/npm/matssocket@1.0.0-2025-10-27/dist/MatsSocket.esm.min.js":
      "sha384-ECJ2VSOkdXM4imJBt8wb0DroKD6HoESrVC+PG4/TiFB0bjCgl1IAJiV2HFfkMW2Z"
  }
}
</script>

<script type="module">
    import * as matssocket from "matssocket";
    // .. or use named imports: import { MatsSocket } from "matssocket"

    // Either directly here, or in additional <script type="module"> blocks:
    let matsSocket = new matssocket.MatsSocket("TestApp", "1.2.3", ['ws://localhost:8080/matssocket']);
    // ...
</script>