@@ -1,185 +1,207 @@
-# EID Runtime Exceptions and Utilities for Javascript
+# EID Runtime Exceptions and Utilities for JavaScript/TypeScript
 
-[![Build Status](https://travis-ci.org/wavesoftware/javascript-eid-exceptions.svg?branch=master)](https://travis-ci.org/wavesoftware/javascript-eid-exceptions) [![Coverage Status](https://coveralls.io/repos/wavesoftware/javascript-eid-exceptions/badge.svg?branch=master&service=github)](https://coveralls.io/github/wavesoftware/javascript-eid-exceptions?branch=master) [![npm](https://img.shields.io/npm/v/eid.js.svg)](https://www.npmjs.com/package/eid.js) [![Bower](https://img.shields.io/bower/v/eid.js.svg)]()
+[![CI](https://github.com/wavesoftware/javascript-eid-exceptions/actions/workflows/ci.yml/badge.svg)](https://github.com/wavesoftware/javascript-eid-exceptions/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/eid.js.svg)](https://www.npmjs.com/package/eid.js)
 
-This small library holds a set of exceptions and utilities that implements idea of fast, reusable, error codes that can be simply thrown fast in case of unpredictable and unrecoverable application failure. It is meant to be used for application bugs.
+A small, zero-dependency library for [defensive programming](https://en.wikipedia.org/wiki/Defensive_programming) in JavaScript and TypeScript. It provides reusable Exception IDs (EIDs), precondition checks, and standardized error handling for fail-fast detection of programming errors.
 
-## Idea
+Instead of writing ad-hoc validation with generic `Error` messages, you assign a unique, permanent ID to each check site. When a bug reaches production, the ID links the error page (or log entry) directly to the line of code that failed.
 
-The idea is to use a set of simple runtime exceptions. They should always take the Exception ID (Eid) object in the making. This eid object will then be reported when displaying or logging that exception. It can also be viewed on the professional fatal error window of the application as a bug reference. EidRuntimeExceptions contains also additional unique ID to distinguish each single exception from others with same Eid. This approach simplifies the management of exceptions in the application and allows developers to focus on functionalities rather than coming up with the correct statement for the exception.
+## How it works
 
-This approach is best to use with tools and plugins like:
+Every exception takes an `Eid` object that combines two identifiers:
 
- * [EidGenerator for Netbeans IDE](http://plugins.netbeans.org/plugin/53137/exception-id-eid-generator)
- * [Generating Exception Id number in Intellij IDEA with Live Templates](https://github.com/wavesoftware/java-eid-exceptions/wiki/Generating%20Exception%20Id%20number%20in%20Intellij%20IDEA%20with%20Live%20Templates)
+- A **static ID** (e.g. `"20260714:120000"`) -- a permanent label inserted by the developer at the throw site.
+- A **unique ID** (e.g. `<a3f7x1>`) -- generated at runtime to distinguish individual occurrences.
 
-Example:
+When the exception is logged or displayed on an error page, both IDs appear together. Support teams search by the static ID to find the code path, and by the unique ID to pinpoint the exact occurrence.
 
-```js
-var cause = 'A extra message';
-throw new EidIllegalStateException("20150721:100554", cause);
+```typescript
+import { EidIllegalStateException } from "eid.js";
+
+throw new EidIllegalStateException("20260714:120000", "An extra message");
 ```
 
-Example log:
+Output:
 
 ```
-ERROR 2016-01-11T22:48:42.445 EidIllegalStateException: [20150721:100554]<rww5y3> A extra message - Error
-    at http://localhost:3000/browser/toplevel/eid.min.js:1:3959
-    at Object.i.3.../eid (http://localhost:3000/browser/toplevel/eid.min.js:1:4211)
-    at r (http://localhost:3000/browser/toplevel/eid.min.js:1:254)
-    at http://localhost:3000/browser/toplevel/eid.min.js:1:305
-    at http://localhost:3000/browser/toplevel/eid.min.js:1:536
-    at Object.i.1.../../lib/eid (http://localhost:3000/browser/toplevel/eid.min.js:1:974)
-    at r (http://localhost:3000/browser/toplevel/eid.min.js:1:254)
-    at t (http://localhost:3000/browser/toplevel/eid.min.js:1:421)
-    at http://localhost:3000/browser/toplevel/eid.min.js:1:438
+EidIllegalStateException: [20260714:120000]<a3f7x1> An extra message
+    at Object.<anonymous> (/app/src/service.ts:42:11)
 ```
 
+Static IDs can be generated using [Live Templates in IntelliJ IDEA](https://github.com/wavesoftware/java-eid-exceptions/wiki/Generating%20Exception%20Id%20number%20in%20Intellij%20IDEA%20with%20Live%20Templates).
 
-## Caution
+## Intended use
 
-This classes shouldn't be used in any public API or library. It is designed to be used for in-house development of end user applications which will report bugs in standardized error pages or post them to issue tracker.
+This library is not intended for public APIs or shared libraries. It is designed for in-house, end-user applications that report bugs through standardized error pages or issue trackers.
 
-## NPM
+## Installation
 
 ```bash
-npm install eid.js --save
+npm install eid.js
 ```
 
-## Bower
+### ESM (recommended)
 
-```bash
-bower install eid.js --save
+```typescript
+import { Eid, EidPreconditions, EidIllegalStateException } from "eid.js";
 ```
 
-### `EidPreconditions` class
+### CommonJS
+
+```javascript
+const { Eid, EidPreconditions, EidIllegalStateException } = require("eid.js");
+```
 
-#### General use
+### Browser (IIFE)
 
-`EidPreconditions` class consists static methods that help to use Eid in a method or constructor. This is solely for convenience purposes. Use them to check whether method or constructor was invoked correctly (whether its preconditions have been met). These methods generally accept a `boolean` expression which is expected to be `true` (or in the case of `checkNotNull`, an object reference which is expected to be non-null). When `false` (or `null`) is passed instead, the `EidPreconditions` method throws an unchecked exception, which helps the calling method communicate to its caller that that caller has made a mistake.
+```html
+<script src="https://unpkg.com/eid.js/dist/index.global.js"></script>
+<script>
+  const { Eid, EidPreconditions } = window.Eid;
+</script>
+```
 
-Each method accepts a EID string or Eid object, which is designed to ease of use and provide strict ID for given exception usage. This approach speed up development of large application and helps support teams by giving both static and random ID for each possible bug that could occur.
+## Error cause support
 
-Each example uses static import:
+All Eid exceptions support the standard ES2022 `Error.cause` property, preserving the original error and its full stack trace:
 
-```js
-// nodejs
-var EidPreconditions = require('eid.js').preconditions;
+```typescript
+import { EidRuntimeException } from "eid.js";
 
-// browser using bower using toplevel version
-var EidPreconditions = window.Eid.preconditions;
+try {
+  riskyOperation();
+} catch (err) {
+  throw new EidRuntimeException("20260714:120000", "operation failed", err);
+  // The original error is available via .cause
+}
 ```
 
-#### `checkArgument` method
+`tryToExecute` chains the caught error as `cause` automatically:
 
-`checkArgument` method should be used to check argument of the method, and validate it in technical terms (not business terms).
+```typescript
+import { EidPreconditions } from "eid.js";
 
-Example:
-
-```js
-// [..]
-function sqrt(value) {
-  checkArgument(value >= 0.0, "20150718:012333");
-  // if ok, calculate the square root
-}
+const result = EidPreconditions.tryToExecute(() => {
+  return JSON.parse(untrustedInput);
+}, "20260714:120100");
+// If JSON.parse throws, the SyntaxError is available via .cause
 ```
 
-In this example, `checkArgument` throws an `EidIllegalArgumentException` to indicate that developer made an error in its call to `sqrt`.
+## `EidPreconditions`
 
-#### `checkState` method
+A collection of static methods for validating preconditions. Each method accepts an EID string (or an `Eid` object) and throws a typed Eid exception when the check fails.
 
-`checkState` method should be used to check state of the class in given moment, and validate it in technical terms (not business terms).
+### `checkArgument`
 
-Example:
+Validates a method argument in technical terms (not business rules).
 
-```js
-checkState(a >= 3.14 && b < 0., "20150721:115016");
+```typescript
+import { EidPreconditions } from "eid.js";
+
+function sqrt(value: number): number {
+  EidPreconditions.checkArgument(value >= 0.0, "20150718:012333");
+  return Math.sqrt(value);
+}
 ```
 
-#### `checkNotNull` method
+Throws `EidIllegalArgumentException` if `value` is negative.
 
-`checkNotNull` method should be used to check if given non null argument is actually `null`
+### `checkState`
 
-Example:
+Validates the internal state of an object at a given moment.
 
-```js
-var nonNullUserName = checkNotNull(userName, "20150721:115515");
+```typescript
+EidPreconditions.checkState(a >= 3.14 && b < 0, "20150721:115016");
 ```
 
-#### `checkElementIndex` method
+### `checkNotNull`
 
-`checkElementIndex` method can be used to test parameters of an array, before being used
+Ensures that a reference is not `null`.
 
-```js
-checkElementIndex(index, list.length, "20150721:115749");
+```typescript
+const nonNullUserName = EidPreconditions.checkNotNull(userName, "20150721:115515");
 ```
 
-#### Formatted message support
+### `checkElementIndex`
+
+Validates that an index is within bounds of an array or list.
+
+```typescript
+EidPreconditions.checkElementIndex(index, list.length, "20150721:115749");
+```
 
-There have been added additional `message` to method descriptors for `checkArgument`, `checkState`, `checkNotNull` and `checkElementIndex` method. Those method's parameter can sometimes be used to pass additional information to exceptions that will be displayed in log files.
+### Optional message
 
-For example:
+All check methods accept an optional `message` parameter with additional context for the exception:
 
-```js
-checkState(transation.isValid(), "20151119:120238", "Invalid transaction: " + transaction);
+```typescript
+EidPreconditions.checkState(
+  transaction.isValid(),
+  "20151119:120238",
+  `Invalid transaction: ${transaction}`
+);
 ```
 
-Will produce output similar to;
+Output:
 
 ```
-EidIllegalStateException: [20151119:120238]<xf4j1l> => Invalid transaction: <Transaction id=null, buyer=null, products=[]>
+EidIllegalStateException: [20151119:120238]<xf4j1l> Invalid transaction: <Transaction id=null, buyer=null, products=[]>
 ```
 
-#### Functional try to execute blocks
+### `tryToExecute`
 
-You can use functional blocks to handle operations, that are intended to operate properly. This approach simplify the code and makes it more readable. It's also good way to deal with untested, uncovered `catch` blocks. It's easy and gives developers nice way of dealing with countless operations that suppose to work as intended.
+Wraps a block of code that is expected to succeed. If it throws, the error is re-thrown as an `EidRuntimeException` with the original error preserved as `cause`.
 
-Example:
+```typescript
+import { EidPreconditions } from "eid.js";
+import { readFileSync } from "node:fs";
 
-```js
-var content = EidPreconditions.tryToExecute(function() {
-  var fs = require('fs');
-  return fs.readFileSync('project.properties');
+const content = EidPreconditions.tryToExecute(() => {
+  return readFileSync("project.properties", "utf-8");
 }, "20150718:121521");
 ```
 
-#### Logging
+### Logging
+
+The `Eid` object provides a `makeLogMessage` method for structured log output. Use `%s` as a format specifier:
 
-Eid object can also be useful in logging. That are `makeLogMessage` method provided to do that. Message formatting is done using equivalent of Java's `String.format(String, Object[])` method.
-For example:
+```typescript
+import { Eid } from "eid.js";
 
-```js
 log.debug(new Eid("20151119:121814").makeLogMessage("REST request received: %s", request));
 ```
 
-will unfold to something similar to:
+Output:
 
 ```
-2017-01-08T16:45:34,334 DEBUG [20151119:121814]<d1afca> REST request received: <RestRequest user=<User id=345> flow=ShowLastTransactions step=Confirm>
+[20151119:121814]<d1afca> => REST request received: <RestRequest user=<User id=345>>
 ```
 
-###Contributing
+## Contributing
 
 Contributions are welcome!
 
-To contribute, follow the standard [git flow](http://danielkummer.github.io/git-flow-cheatsheet/) of:
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Open a Pull Request
 
-1. Fork it
-1. Create your feature branch (`git checkout -b feature/my-new-feature`)
-1. Commit your changes (`git commit -am 'Add some feature'`)
-1. Push to the branch (`git push origin feature/my-new-feature`)
-1. Create new Pull Request
-
-Even if you can't contribute code, if you have an idea for an improvement please open an [issue](https://github.com/wavesoftware/javascript-eid-exceptions/issues).
+If you have an idea for an improvement, please open an [issue](https://github.com/wavesoftware/javascript-eid-exceptions/issues).
 
 ## Requirements
 
-* NodeJS >= 0.10
-* Any modern browser, supported by browserify.
-
+* Node.js >= 20
+* TypeScript >= 5.0 (optional, types are included)
 
-### Releases
+## Releases
 
+- 2.0.0
+  - Full rewrite to TypeScript
+  - ESM + CommonJS + IIFE browser bundle
+  - ES2022 `Error.cause` support
+  - Vitest test suite, Biome linting, GitHub Actions CI
+  - Dropped: Bower, Gulp, Travis CI, Node < 20
 - 1.0.0
-  - initial release
-  - library ported from Java version
+  - Initial release
+  - Library ported from Java version