= New Jolokia JavaScript library using ES modules

This client provides the following two libraries:

* `jolokia.js`: Base library containing the `Jolokia` object definition which carries the `request()`
* `jolokia-simple.js`: Library containing the Jolokia simple API and which builds up on `jolokia.js`. It must be included after `jolokia.js` since it adds methods to the `Jolokia` object definition.

These libraries can be used directly by using `<script>` element in HTML page, but we also support _modern_ (it's hard to define "modern" in JavaScript world...) JavaScript and Jolokia JS libraries can be used as ESM modules with bundlers like https://webpack.js.org/[Webpack] or https://rollupjs.org/[Rollup].

== Changes comparing to existing jolokia.js

* no dependency on https://jquery.com/[JQuery], https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API[Fetch API] is used for requests. Switching away from `xhr`, we're dropping _synchronous AJAX_ (`xhr` has an option to perform requests in synchronous manner, but it blocks the event loop and is deprecated in modern browsers for long time already).
** `credentials` and `headers` properties (from `fetch()` options) are exposed in `Jolokia()` and `Jolokia.request()` calls (with restrictions, because some values/headers may be configured by Jolokia itself)
* no https://en.wikipedia.org/wiki/JSONP[JSONP] support
* `jolokia.request` call based on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises[Promises]
** previously, user was passing `success` and `error` options for `jolokia.request()` call and _both_ were used in successful `xhr` call (no transport error for example) - `error` was called for logical errors (when JSON returned from Jolokia contained `error` value and/or Jolokia status was not `200`, but HTTP response code was still `200`)
** both `success` and `error` callbacks passed to `jolokia.request()` were used in single callback passed with https://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings[`ajaxSettings.success`]
** for compatibility reasons we still support this _callback mode_.
** changed support for global `ajaxError`. This callback was passed as https://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings[`ajaxSettings.error`]. The name has changed to `fetchError` and the callback's signature accepts Fetch API `Response` object now and an error in case of non-HTTP errors.
** now the recommended way is to use https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API[Fetch API] where `request()` returns a promise that resolves to whatever is needed:
*** a text response, when `dataType=text`
*** a JSON response (array) by default (when `dataType=json`)
*** `undefined`, when callbacks are specified as it is with existing jolokia.js
*** Fetch API https://developer.mozilla.org/en-US/docs/Web/API/Response[Response object], when user specifies
`resolve="response"` in request options. User may further resolve it to json, text, blob, ...
* Code base is using TypeScript which is processed by https://rollupjs.org/[Rollup.js]

== Developer notes

The goal of client/javascript-esm directory is to provide a _Jolokia monorepo_ based on:

* yarn workspaces to organize interdependent modules
* https://rollupjs.org/[Rollup.js] as a bundler to provide UMD files for browsers and ES modules for browsers and other bundlers (like https://webpack.js.org/[Webpack]).
* Typescript as main langage for source an tests
* https://jestjs.io/[Jest] tests written in Typescript

The challenge is to have as clean configuration (ESLint, Rollup, tsconfig.json, jest.config.ts) as possible and IDE
should allow to work with multiple packages (`jolokia.js`, `@jolokia.js/simple`, ...) without a need to build anything.

We can't use https://www.typescriptlang.org/docs/handbook/project-references.html[Typescript project references],
because these can't be used with `noEmit: true`.

The trick is (though there may be better ones, or this one may be proved wrong) to use `exports` field of `package.json`:

[,json]
----
{
  "exports": {
    ".": {
      "types": "./dist/dts/jolokia.d.ts",
      "import": "./dist/jolokia.mjs",
      "default": "./src/jolokia.ts"
    }
  }
}
----

It is based on https://nodejs.org/docs/latest/api/packages.html#conditional-exports[Conditional exports] and has these conditions:

* `import` - for users of Jolokia installed with `npm i jolokia.js` after the package is published to NPM registry
* `default` - used when the project was not built yet (so it's used in IDE just after cloning the project)

[]
NOTE:: https://github.com/microsoft/TypeScript/issues/51862[microsoft/TypeScript#51862] mentions `development` conditional, but I'm not sure how/if it's handled at all:
+
[,json]
----
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": {
        "development": "./src",
        "default": "./dist/index.mjs"
      },
      "require": {
        "development": "./src",
        "default": "./dist/index.js"
      }
    }
  }
}
----
