@helioslx/core 0.2.0

package/examples/full-frame-fade.ts

@@ -0,0 +1,25 @@
+import { createSacnSource, SLOT_COUNT } from "@helioslx/core";
+import { RecordingTransport } from "@helioslx/core/testing";
+
+const source = createSacnSource({
+	transport: new RecordingTransport(),
+	ownsTransport: true,
+});
+
+try {
+	const frame = new Uint8Array(SLOT_COUNT);
+	frame[0] = 255;
+	frame[1] = 128;
+	frame[2] = 64;
+
+	const snapshot = await source.universe(1).write(frame, {
+		durationMs: 2_000,
+	});
+
+	console.info(
+		`Scheduled fade for universe ${snapshot.universe} with ${snapshot.activeTransitions} active transitions.`,
+	);
+	// write schedules the fade; it does not wait for the duration to elapse.
+} finally {
+	await source.close();
+}

package/examples/graceful-shutdown.ts

@@ -0,0 +1,19 @@
+import { createSacnSource } from "@helioslx/core";
+import { RecordingTransport } from "@helioslx/core/testing";
+
+const source = createSacnSource({
+	transport: new RecordingTransport(),
+	ownsTransport: true,
+	onStop: () => {
+		console.info("Scheduler paused.");
+	},
+	onClose: () => {
+		console.info("Source closed.");
+	},
+});
+
+await source.universe(1).setChannels({ 1: 255 });
+
+// stop() pauses; close() is final teardown (also used by Node process handlers).
+await source.stop();
+await source.close();

package/examples/quickstart.ts

@@ -0,0 +1,30 @@
+import { createSacnSource } from "@helioslx/core/node";
+
+const iface = process.env.SACN_INTERFACE;
+const source = createSacnSource({
+	name: "Helios quickstart",
+	transportOptions: {
+		// Use the local IPv4 address on your lighting network.
+		...(iface === undefined ? {} : { iface }),
+	},
+});
+
+const universe = source.universe(1, {
+	priority: 100,
+	sourceName: "demo",
+});
+
+try {
+	await universe.fadeChannels(
+		{
+			1: 255,
+			2: 128,
+		},
+		{ durationMs: 10_000 },
+	);
+
+	console.info("Output is running. Press Ctrl-C to stop.");
+} catch (error) {
+	await source.close();
+	throw error;
+}

package/examples/redis.ts

@@ -0,0 +1,30 @@
+import { createSacnSource } from "@helioslx/core";
+import { RedisOutputStore } from "@helioslx/core/redis";
+import { NodeSacnTransport } from "@helioslx/core/node";
+
+const store = new RedisOutputStore({
+	// Uses REDIS_URL when present; otherwise defaults to local Redis.
+	...(process.env.REDIS_URL === undefined
+		? {}
+		: { url: process.env.REDIS_URL }),
+});
+
+const source = createSacnSource({
+	transport: new NodeSacnTransport({
+		sourceName: "Helios Redis example",
+		...(process.env.SACN_INTERFACE === undefined
+			? {}
+			: { iface: process.env.SACN_INTERFACE }),
+	}),
+	store,
+	ownsTransport: true,
+	ownsStore: true,
+});
+
+try {
+	await source.universe(1).fadeChannels({ 1: 255 }, { durationMs: 500 });
+} finally {
+	// The source closes the store; this store owns its internally-created
+	// Redis client by default.
+	await source.close();
+}

package/examples/sparse-channels.ts

@@ -0,0 +1,23 @@
+import { createSacnSource } from "@helioslx/core";
+import { RecordingTransport } from "@helioslx/core/testing";
+
+const source = createSacnSource({
+	transport: new RecordingTransport(),
+	ownsTransport: true,
+});
+
+const universe = source.universe(1);
+
+try {
+	await universe.transition([
+		{ channel: 1, value: 255, durationMs: 1_000 },
+		{ channel: 10, value: 64, durationMs: 2_000 },
+		{ channel: 512, value: 128, durationMs: 3_000 },
+	]);
+
+	await universe.fadeChannels({ 1: 0 }, { durationMs: 250 });
+
+	console.info(await universe.get());
+} finally {
+	await source.close();
+}

package/examples/viewer-subscription.ts

@@ -0,0 +1,38 @@
+import { ViewerService } from "@helioslx/core";
+import { NodeSacnReceiver } from "@helioslx/core/node";
+
+const viewer = new ViewerService({
+  receiver: new NodeSacnReceiver(),
+  ownsReceiver: true,
+  streamCapacity: 16,
+});
+
+await viewer.start();
+await viewer.setSelectedUniverses([1, 2]);
+
+const unsubscribe = viewer.subscribe((packet) => {
+  console.info(
+    `Universe ${packet.universe} channel 1=${packet.values[0]} ` +
+      `from ${packet.source.sourceName ?? packet.source.cid}`,
+  );
+});
+
+// Async streams are bounded and coalesce queued packets by universe.
+const stream = viewer.packets(8);
+const consume = (async (): Promise<void> => {
+  for await (const packet of stream) {
+    console.info(`Stream received universe ${packet.universe}`);
+  }
+})();
+
+const close = async (): Promise<void> => {
+  unsubscribe();
+  stream.close();
+  await consume;
+  await viewer.close();
+};
+
+process.once("SIGINT", () => void close());
+process.once("SIGTERM", () => void close());
+
+console.info("Watching universes 1 and 2. Press Ctrl-C to stop.");

package/examples/viewer-tui.ts

@@ -0,0 +1,201 @@
+import {
+	MAX_UNIVERSE,
+	MIN_UNIVERSE,
+	SLOT_COUNT,
+	ViewerService,
+	type ViewerPacket,
+} from "@helioslx/core";
+import { NodeSacnReceiver } from "@helioslx/core/node";
+
+const COLUMNS = 32;
+const ROWS = SLOT_COUNT / COLUMNS;
+const ESC = "\x1b";
+const HIDE_CURSOR = `${ESC}[?25l`;
+const SHOW_CURSOR = `${ESC}[?25h`;
+const CLEAR_HOME = `${ESC}[2J${ESC}[H`;
+const RESET = `${ESC}[0m`;
+
+const clampUniverse = (value: number): number =>
+	Math.min(MAX_UNIVERSE, Math.max(MIN_UNIVERSE, value));
+
+const parseUniverse = (raw: string): number => {
+	const value = Number(raw);
+	if (!Number.isInteger(value) || value < MIN_UNIVERSE || value > MAX_UNIVERSE) {
+		throw new Error(
+			`Universe must be an integer between ${MIN_UNIVERSE} and ${MAX_UNIVERSE}.`,
+		);
+	}
+	return value;
+};
+
+const pad = (value: number, width: number): string =>
+	String(value).padStart(width, "0");
+
+const intensityStyle = (value: number): string => {
+	if (value <= 0) return `${ESC}[2m`;
+	if (value < 64) return `${ESC}[90m`;
+	if (value < 128) return `${ESC}[37m`;
+	if (value < 192) return `${ESC}[97m`;
+	return `${ESC}[1;97m`;
+};
+
+const formatAge = (receivedAt: number, now: number): string => {
+	const ageMs = Math.max(0, now - receivedAt);
+	if (ageMs < 1_000) return `${ageMs}ms`;
+	if (ageMs < 60_000) return `${(ageMs / 1_000).toFixed(1)}s`;
+	return `${Math.floor(ageMs / 60_000)}m`;
+};
+
+const iface = process.env.SACN_INTERFACE;
+const startUniverse = parseUniverse(
+	process.argv[2] ?? process.env.SACN_UNIVERSE ?? "1",
+);
+
+const viewer = new ViewerService({
+	receiver: new NodeSacnReceiver({
+		...(iface === undefined ? {} : { iface }),
+	}),
+	ownsReceiver: true,
+});
+
+const latest = new Map<number, ViewerPacket>();
+let universe = startUniverse;
+let closed = false;
+let redrawPending = false;
+let selecting: Promise<void> = Promise.resolve();
+let unsubscribe: () => void = () => undefined;
+
+const render = (): void => {
+	if (closed || !process.stdout.isTTY) return;
+
+	const now = Date.now();
+	const packet = latest.get(universe);
+	const telemetry = viewer.getTelemetry();
+	const lines: string[] = [];
+
+	lines.push(`Helios viewer  universe ${universe}`);
+	if (packet) {
+		const source = packet.source.sourceName ?? packet.source.cid;
+		lines.push(
+			`source ${source}  pri ${packet.source.priority}  seq ${packet.source.sequence}  age ${formatAge(packet.receivedAt, now)}  packets ${telemetry.packetsReceived}`,
+		);
+	} else {
+		lines.push(`waiting for packets…  packets ${telemetry.packetsReceived}`);
+	}
+	lines.push("");
+
+	const values = packet?.values;
+	for (let row = 0; row < ROWS; row += 1) {
+		const startChannel = row * COLUMNS + 1;
+		const cells: string[] = [`${pad(startChannel, 3)}`];
+		for (let column = 0; column < COLUMNS; column += 1) {
+			const index = row * COLUMNS + column;
+			const value = values?.[index] ?? 0;
+			cells.push(`${intensityStyle(value)}${pad(value, 3)}${RESET}`);
+		}
+		lines.push(cells.join(" "));
+	}
+
+	lines.push("");
+	lines.push("←/→ or h/l  universe ±1    [/]  ±10    q  quit");
+
+	process.stdout.write(`${CLEAR_HOME}${HIDE_CURSOR}${lines.join("\n")}\n`);
+};
+
+const scheduleRedraw = (): void => {
+	if (redrawPending || closed) return;
+	redrawPending = true;
+	setImmediate(() => {
+		redrawPending = false;
+		render();
+	});
+};
+
+const selectUniverse = (next: number): void => {
+	const clamped = clampUniverse(next);
+	if (clamped === universe) return;
+	universe = clamped;
+	scheduleRedraw();
+	selecting = selecting
+		.then(async () => {
+			if (closed) return;
+			await viewer.setSelectedUniverses([universe]);
+		})
+		.catch((error: unknown) => {
+			if (!closed) {
+				process.stderr.write(
+					`Failed to select universe ${universe}: ${String(error)}\n`,
+				);
+			}
+		});
+};
+
+function restoreTerminal(): void {
+	if (process.stdin.isTTY) {
+		process.stdin.setRawMode(false);
+		process.stdin.pause();
+	}
+	process.stdin.off("data", onKey);
+	process.stdout.write(SHOW_CURSOR);
+}
+
+async function close(): Promise<void> {
+	if (closed) return;
+	closed = true;
+	unsubscribe();
+	process.off("SIGINT", onSignal);
+	process.off("SIGTERM", onSignal);
+	process.stdout.off("resize", scheduleRedraw);
+	restoreTerminal();
+	await selecting;
+	await viewer.close();
+}
+
+function onSignal(): void {
+	void close();
+}
+
+function onKey(chunk: Buffer): void {
+	const key = chunk.toString("utf8");
+	if (key === "q" || key === "\u0003") {
+		void close();
+		return;
+	}
+	if (key === "\u001b[D" || key === "h") {
+		selectUniverse(universe - 1);
+		return;
+	}
+	if (key === "\u001b[C" || key === "l") {
+		selectUniverse(universe + 1);
+		return;
+	}
+	if (key === "[") {
+		selectUniverse(universe - 10);
+		return;
+	}
+	if (key === "]") {
+		selectUniverse(universe + 10);
+	}
+}
+await viewer.start();
+await viewer.setSelectedUniverses([universe]);
+
+unsubscribe = viewer.subscribe((packet) => {
+	latest.set(packet.universe, packet);
+	if (packet.universe === universe) scheduleRedraw();
+});
+
+process.once("SIGINT", onSignal);
+process.once("SIGTERM", onSignal);
+process.stdout.on("resize", scheduleRedraw);
+
+if (!process.stdin.isTTY || !process.stdout.isTTY) {
+	console.error("viewer-tui requires an interactive TTY.");
+	await close();
+	process.exitCode = 1;
+} else {
+	process.stdin.setRawMode(true);
+	process.stdin.resume();
+	process.stdin.on("data", onKey);
+	render();
+}

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@helioslx/core",
+  "version": "0.2.0",
+  "description": "TypeScript toolkit for sending and observing sACN (E1.31) from Node.js",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "import": "./dist/redis.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helioslx/core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/helioslx/core/issues"
+  },
+  "homepage": "https://github.com/helioslx/docs#readme",
+  "keywords": [
+    "sacn",
+    "e1.31",
+    "dmx",
+    "lighting",
+    "udp"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "check": "npm run typecheck && npm test && npm run build && npm run test:examples",
+    "test:examples": "tsc --ignoreConfig --noEmit --strict --exactOptionalPropertyTypes --noUncheckedIndexedAccess --skipLibCheck --target ES2023 --module NodeNext --moduleResolution NodeNext --types node examples/*.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@elysiajs/node": "^1.4.5",
+    "@elysiajs/openapi": "^1.4.15",
+    "@types/node": "latest",
+    "@vitest/coverage-v8": "^4.1.10",
+    "elysia": "^1.4.29",
+    "redis": "^6.1.0",
+    "sacn": "^4.6.2",
+    "tsdown": "latest",
+    "typescript": "latest",
+    "vitest": "latest"
+  },
+  "peerDependencies": {
+    "@elysiajs/node": "^1.4.5",
+    "@elysiajs/openapi": "^1.4.15",
+    "elysia": "^1.4.29",
+    "redis": "^6.1.0",
+    "sacn": "^4.6.2"
+  },
+  "peerDependenciesMeta": {
+    "@elysiajs/node": {
+      "optional": true
+    },
+    "@elysiajs/openapi": {
+      "optional": true
+    },
+    "elysia": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    },
+    "sacn": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0"
+}