docs: overhaul README and provide new usage examples

The README.md has been completely rewritten. Also the `example`
directory has been renamed to `examples` and its content
has been replaced with a more structured and practical set of scripts.

examples/02-error-handling.js

@@ -0,0 +1,14 @@
+import { pingJava } from "../index.js";
+
+const offlineServer = "this.server.does.not.exist";
+const port = 12345;
+
+console.log(`Pinging an offline server: ${offlineServer}:${port}`);
+
+try {
+	// We set a short timeout to fail faster.
+	const data = await pingJava(offlineServer, { port, timeout: 500 });
+	console.log("Success!?", data);
+} catch (error) {
+	console.error("Caught expected error:", error.message);
+}