@liphium/neoroute-ts 0.1.0

package/examples/web_socket_client/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "web_socket_example",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "How to use the WebSocket client from neoroute-ts",
+	"main": "index.ts",
+	"scripts": {
+		"start": "node --loader ts-node/esm src/main.ts"
+	},
+	"dependencies": {
+		"@liphium/neoroute-ts": "workspace:*"
+	},
+	"keywords": [],
+	"author": "",
+	"private": "true",
+	"packageManager": "pnpm@10.32.1",
+	"devDependencies": {
+		"@types/node": "^26.0.1"
+	}
+}

package/examples/web_socket_client/src/main.ts

@@ -0,0 +1,72 @@
+import {
+	newPromiseWithResolver,
+	Receiver,
+	WebSocketTransporter,
+} from '@liphium/neoroute-ts';
+import { registerReceiver } from './receiver.js';
+import * as readline from 'node:readline';
+import { sendEchoRequest, sendSubmitPunRequest } from './requests.js';
+
+async function main() {
+	const { resolve, reject, promise } = newPromiseWithResolver<void>();
+	const r = new Receiver({
+		errorHandler: (err: Error) => {
+			console.log('error with receiver', err);
+			reject(err);
+		},
+		requestTimeout: 1000, // time.Second * 1 in Millisekunden
+	});
+
+	registerReceiver(r);
+
+	const t = new WebSocketTransporter(r, {
+		onOpen: () => {
+			resolve();
+		},
+	});
+
+	try {
+		t.connect('ws://localhost:6121/');
+		await promise;
+		console.log('Connected to server.');
+	} catch (err) {
+		console.error(`failed to connect to server: ${err}`);
+		process.exit(1);
+	}
+
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+		prompt: '',
+	});
+
+	console.log('Type exit to quit the program.');
+	console.log('Type "Pun " followed by a pun to submit it to the server.');
+	console.log(
+		'Type "Echo " followed by a message to receive a echo message from the server.',
+	);
+
+	rl.on('line', (line) => {
+		const input = line.trim();
+
+		if (input.startsWith('Pun ')) {
+			const pun = input.slice(4);
+			console.log('Sending pun to server');
+			sendSubmitPunRequest(r, pun);
+		} else if (input.startsWith('Echo ')) {
+			const msg = input.slice(5);
+			console.log('Sending echo to server');
+			sendEchoRequest(r, msg);
+		} else if (input === 'exit') {
+			t.close();
+			rl.close();
+		}
+	});
+
+	rl.on('close', () => {
+		console.log('Connection closed');
+		process.exit(0);
+	});
+}
+
+main();

package/examples/web_socket_client/src/messages.ts

@@ -0,0 +1,22 @@
+// Outgoing
+
+export interface EchoRequest {
+	message: string;
+}
+
+export interface SubmitPunRequest {
+	pun: string;
+}
+
+// Response
+
+export interface EchoResponse {
+	requestNumber: number;
+	message: string;
+}
+
+// Event
+
+export interface NewPunEvent {
+	pun: string;
+}

package/examples/web_socket_client/src/receiver.ts

@@ -0,0 +1,8 @@
+import { Receiver, Ctx } from '@liphium/neoroute-ts';
+import { type NewPunEvent } from './messages.js';
+
+export function registerReceiver(receiver: Receiver): void {
+	receiver.receive('new_pun_submitted', (_: Ctx, req: NewPunEvent) => {
+		console.log(`A new pun was submitted by someone, it is ${req.pun}`);
+	});
+}

package/examples/web_socket_client/src/requests.ts

@@ -0,0 +1,51 @@
+import { Receiver, UserError } from '@liphium/neoroute-ts';
+import {
+	type SubmitPunRequest,
+	type EchoRequest,
+	type EchoResponse,
+} from './messages.js';
+
+export async function sendSubmitPunRequest(
+	receiver: Receiver,
+	pun: string,
+): Promise<void> {
+	try {
+		const requestPayload: SubmitPunRequest = { pun: pun };
+
+		// sendOk throws an error if it fails, otherwise it's successful
+		const res = await receiver.sendOk<SubmitPunRequest>(
+			'submit_pun',
+			requestPayload,
+		);
+		if (res instanceof UserError) {
+			console.log("Couldn't submit pun because:", res.message);
+			return;
+		}
+
+		console.log('Pun submitted successfully!');
+	} catch (err) {
+		console.log('Failed to send submit pun request:', err);
+	}
+}
+
+export async function sendEchoRequest(
+	receiver: Receiver,
+	message: string,
+): Promise<void> {
+	try {
+		const requestPayload: EchoRequest = { message: message };
+
+		const res = await receiver.send<EchoResponse, EchoRequest>(
+			'echo',
+			requestPayload,
+		);
+		if (res instanceof UserError) {
+			console.log('Echo failed because:', res.message);
+			return;
+		}
+
+		console.log(`Received ${res.requestNumber}. echo: ${res.message}`);
+	} catch (err) {
+		console.log('Failed to send echo request:', err);
+	}
+}

package/examples/web_socket_client/tsconfig.json

@@ -0,0 +1,44 @@
+{
+	// Visit https://aka.ms/tsconfig to read more about this file
+	"compilerOptions": {
+		// File Layout
+		"rootDir": "./src",
+		"outDir": "./dist",
+
+		// Environment Settings
+		// See also https://aka.ms/tsconfig/module
+		"module": "nodenext",
+		"target": "esnext",
+		"types": ["node"],
+		// For nodejs:
+		// "lib": ["esnext"],
+		// "types": ["node"],
+		// and npm install -D @types/node
+
+		// Other Outputs
+		"sourceMap": true,
+		"declaration": true,
+		"declarationMap": true,
+
+		// Stricter Typechecking Options
+		"noUncheckedIndexedAccess": true,
+		"exactOptionalPropertyTypes": true,
+
+		// Style Options
+		// "noImplicitReturns": true,
+		// "noImplicitOverride": true,
+		// "noUnusedLocals": true,
+		// "noUnusedParameters": true,
+		// "noFallthroughCasesInSwitch": true,
+		// "noPropertyAccessFromIndexSignature": true,
+
+		// Recommended Options
+		"strict": true,
+		"jsx": "react-jsx",
+		"verbatimModuleSyntax": true,
+		"isolatedModules": true,
+		"noUncheckedSideEffectImports": true,
+		"moduleDetection": "force",
+		"skipLibCheck": true,
+	},
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@liphium/neoroute-ts",
+  "version": "0.1.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "directory": "https://github.com/Liphium/neoroute-ts.git"
+  },
+  "homepage": "https://github.com/Liphium/neoroute-ts#readme",
+  "bugs": {
+    "url": "https://github.com/Liphium/neoroute-ts/issues"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "description": "Talk to neoroute servers.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "prettier": "^3.9.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "format": "prettier --write .",
+    "check": "prettier --check ."
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+packages:
+  - '.'
+  - 'examples/*'
+allowBuilds:
+  esbuild: set this to true or false

package/readme.md

@@ -0,0 +1,49 @@
+# Neoroute-TS
+
+## Examples
+
+This repository contains two interactive command-line examples to test the `@liphium/neoroute-client` TypeScript library. These clients are designed to communicate with a local Neoroute Go server running on port `6121`.
+
+### Prerequisites
+
+Before running the examples, ensure you have the following ready:
+
+1. **Node.js** (v18 or higher recommended).
+2. The corresponding **[Neoroute Example Server](https://github.com/Liphium/neoroute/tree/main/examples)** must be running locally (`go run .`).
+3. The main library (`@liphium/neoroute-ts-client`) must be built. If you make changes to the core library, simply run `npm run build` in the base directory. The examples use a local symlink and will automatically use the updated build.
+
+---
+
+### 1. WebSocket Client (`examples/web_socket_client`)
+
+This client tests the persistent WebSocket connection, event listening, and basic request/response flows.
+
+#### Setup & Run
+
+Navigate to the WebSocket client directory and install the dependencies:
+
+```bash
+cd examples/web_socket_client
+npm install
+npx tsx src/main.ts
+```
+
+---
+
+### 2. HTTP Client (`examples/http_client`)
+
+This client tests the stateless HTTP transporter, routing groups, and middleware authentication (token validation via URL parameters).
+
+#### Setup & Run
+
+Navigate to the WebSocket client directory and install the dependencies:
+
+```bash
+cd examples/http_client
+npm install
+npx tsx src/main.ts
+```
+
+## Development Note
+
+Both clients use `tsx` to execute the TypeScript files directly without a manual compilation step.

package/src/client.ts

@@ -0,0 +1,17 @@
+export class Ctx {
+	private _data: Uint8Array;
+	private _name: string;
+
+	constructor(data: Uint8Array, name: string) {
+		this._data = data;
+		this._name = name;
+	}
+
+	public data(): Uint8Array {
+		return this._data;
+	}
+
+	public name(): string {
+		return this._name;
+	}
+}

package/src/config.ts

@@ -0,0 +1,4 @@
+export interface Config {
+	errorHandler: (error: Error) => void;
+	requestTimeout?: number;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './interfaces.js';
+export * from './config.js';
+export * from './logger.js';
+export * from './client.js';
+
+export * from './sender.js';
+export * from './receiver.js';
+export * from './util.js';
+
+export * from './user_error.js';
+
+export * from './transporter/transporter_http.js';
+export * from './transporter/transporter_websocket.js';

package/src/interfaces.ts

@@ -0,0 +1,31 @@
+// Incoming messages
+
+export enum MessageType {
+	Response,
+	Event,
+}
+
+export interface Message {
+	type: MessageType; // Response or event
+	data: Uint8Array;
+}
+
+export interface Event {
+	name: string;
+	data: Uint8Array;
+}
+
+export interface Response {
+	id: number;
+	has_data: boolean;
+	error: boolean;
+	data: Uint8Array;
+}
+
+// Outgoing messages
+
+export interface Request {
+	id: number;
+	route: string;
+	data: Uint8Array;
+}

package/src/logger.ts

@@ -0,0 +1,18 @@
+export interface Logger {
+	debug(msg: string, ...args: any[]): void;
+	info(msg: string, ...args: any[]): void;
+	warn(msg: string, ...args: any[]): void;
+	error(msg: string, ...args: any[]): void;
+}
+
+// Default logger falls back to the standard console
+export let logger: Logger = {
+	debug: console.debug,
+	info: console.info,
+	warn: console.warn,
+	error: console.error,
+};
+
+export function setLogger(l: Logger) {
+	logger = l;
+}

package/src/receiver.ts

@@ -0,0 +1,56 @@
+import { decode } from '@msgpack/msgpack';
+import { Ctx } from './client.js';
+import type { Config } from './config.js';
+import { Sender } from './sender.js';
+import { type Event, MessageType, type Message } from './interfaces.js';
+import { logger } from './logger.js';
+
+export class Receiver extends Sender {
+	private receiver: Map<string, (c: Ctx) => void> = new Map();
+
+	constructor(config: Config) {
+		super(config);
+	}
+
+	protected override handleOther(message: Message): void {
+		if (message.type === MessageType.Event) {
+			this.handleEvent(message.data);
+		} else {
+			super.handleOther(message);
+		}
+	}
+
+	private handleEvent(eventBytes: Uint8Array): void {
+		let ev: Event;
+		try {
+			ev = decode(eventBytes) as Event;
+		} catch (error) {
+			logger.info('failed to unmarshal event', error);
+			return;
+		}
+
+		const receiverFunc = this.receiver.get(ev.name);
+		if (!receiverFunc) {
+			logger.info('received event for non existing receiver', ev.name);
+			return;
+		}
+
+		const c = new Ctx(ev.data, ev.name);
+		receiverFunc(c);
+	}
+
+	/// Handle receiving of an event. Only one handleFunc can exist at the same time.
+	public receive<E>(
+		eventName: string,
+		handleFunc: (c: Ctx, data: E) => void,
+	): void {
+		this.receiver.set(eventName, (c: Ctx) => {
+			try {
+				const data = decode(c.data()) as E;
+				handleFunc(c, data);
+			} catch (error) {
+				logger.info('failed to unmarshal event data', error);
+			}
+		});
+	}
+}

package/src/sender.ts

@@ -0,0 +1,203 @@
+import { decode, encode } from '@msgpack/msgpack';
+import {
+	type Message,
+	type Response,
+	type Request,
+	MessageType,
+} from './interfaces.js';
+import { logger } from './logger.js';
+import type { Config } from './config.js';
+import {
+	marshalRequestData,
+	unmarshalResponseData,
+	withTimeout,
+} from './util.js';
+import { UserError } from './user_error.js';
+
+export class Sender {
+	private config: Config;
+	private sendFunc?: (data: Uint8Array) => Promise<void>;
+	private requestId: number = 0;
+
+	// Maps a request ID to a resolve function to fulfill the promise
+	private waiters: Map<number, (resp: Response) => void> = new Map();
+
+	constructor(config: Config) {
+		this.config = config;
+		if (!this.config.requestTimeout) {
+			this.config.requestTimeout = 5000; // default timeout 5 seconds
+		}
+	}
+
+	public getRequestId(): number {
+		this.requestId++;
+		return this.requestId;
+	}
+
+	public setSendFunc(sendFunc: (data: Uint8Array) => Promise<void>): void {
+		this.sendFunc = sendFunc;
+	}
+
+	public handle(reqData: Uint8Array): void {
+		let message: Message;
+		try {
+			message = decode(reqData) as Message;
+		} catch (error) {
+			logger.info('failed to unmarshal message', error);
+			return;
+		}
+
+		if (message.type === MessageType.Response) {
+			this.handleResponse(message.data);
+		} else {
+			this.handleOther(message);
+		}
+	}
+
+	public handleResponse(respBytes: Uint8Array): void {
+		let resp: Response;
+		try {
+			resp = decode(respBytes) as Response;
+		} catch (error) {
+			logger.info('failed to unmarshal response', error);
+			return;
+		}
+
+		if (resp.id === -1 && resp.error) {
+			const decoder = new TextDecoder();
+			this.config.errorHandler(new Error(decoder.decode(resp.data)));
+			return;
+		}
+
+		const resolveFunc = this.waiters.get(resp.id);
+		if (!resolveFunc) {
+			logger.info('received response for non existing waiter', resp.id);
+			return;
+		}
+
+		resolveFunc(resp);
+	}
+
+	protected handleOther(message: Message): void {
+		logger.info('received unsupported message type', message.type);
+	}
+
+	public removeResponseWaiter(requestId: number): void {
+		this.waiters.delete(requestId);
+	}
+
+	private async sendRequest(
+		route: string,
+		reqData: Uint8Array,
+		wantResponse: boolean,
+	): Promise<{ promise: Promise<Response>; reqId: number }> {
+		const reqId = this.getRequestId();
+
+		if (!this.sendFunc) {
+			throw new Error('sendFunc is not set');
+		}
+
+		const req: Request = {
+			id: reqId,
+			route: route,
+			data: reqData,
+		};
+
+		let reqBytes: Uint8Array;
+		try {
+			reqBytes = encode(req);
+		} catch (err) {
+			throw new Error(`failed to marshal request: ${err}`);
+		}
+
+		let respPromise: Promise<Response> = Promise.resolve({} as Response);
+		if (wantResponse) {
+			respPromise = new Promise<Response>((resolve) => {
+				this.waiters.set(reqId, resolve);
+			});
+		}
+
+		await this.sendFunc(reqBytes);
+		return { promise: respPromise, reqId: reqId };
+	}
+
+	public getConfig(): Config {
+		return this.config;
+	}
+
+	/// Internal helper for making send functions easier to write.
+	private async sendInternal<RQ, RS>(
+		route: string,
+		req: RQ,
+		waitForResponse: boolean,
+		hasResponse: boolean,
+	): Promise<RS | UserError | undefined> {
+		const { promise: respPromise, reqId } = await this.sendRequest(
+			route,
+			req != undefined ? marshalRequestData<RQ>(req) : new Uint8Array(),
+			true,
+		);
+
+		// When we want to wait for response, properly serialize it
+		if (waitForResponse) {
+			const timeout = this.config.requestTimeout ?? 5000;
+			const res = await withTimeout(respPromise, timeout);
+			this.removeResponseWaiter(reqId);
+
+			if (res.error) {
+				const decoder = new TextDecoder();
+				return new UserError(decoder.decode(res.data));
+			}
+
+			if (hasResponse) {
+				return unmarshalResponseData<RS>(res.data);
+			} else {
+				return undefined;
+			}
+		} else {
+			// Otherwise signal that nothing will be waited for
+			return undefined;
+		}
+	}
+
+	public send<RS, RQ>(route: string, req: RQ): Promise<RS | UserError> {
+		return this.sendInternal<RQ, RS>(route, req, true, true) as Promise<
+			RS | UserError
+		>;
+	}
+
+	public sendOk<RQ>(route: string, req: RQ): Promise<UserError> {
+		return this.sendInternal<RQ, unknown>(
+			route,
+			req,
+			true,
+			false,
+		) as Promise<UserError>;
+	}
+
+	public async sendOkNoRequest(route: string): Promise<UserError> {
+		return this.sendInternal(
+			route,
+			undefined,
+			false,
+			false,
+		) as Promise<UserError>;
+	}
+
+	public async sendNoRequest<RS>(route: string): Promise<RS | UserError> {
+		return this.sendInternal<undefined, RS>(
+			route,
+			undefined,
+			true,
+			true,
+		) as Promise<RS | UserError>;
+	}
+
+	public async sendNoResponse<RQ>(route: string, req: RQ): Promise<void> {
+		await this.sendInternal<RQ, undefined>(route, req, false, false);
+	}
+
+	public async sendPing(route: string): Promise<void> {
+		await this.sendInternal(route, undefined, false, false);
+	}
+}