@tsplc/debug 0.2.16 → 0.2.18

package/src/errors.ts

@@ -0,0 +1,3 @@
+/** What to show for a caught value: an error's message, or anything else as text. */
+export const errorMessage = (error: unknown) =>
+	error instanceof Error ? error.message : String(error);

package/src/hardware.ts

@@ -1,5 +1,5 @@
 import { type TargetRead, type TargetSample, worstQuality } from "./adapter.ts";
-import type { DeviceState } from "./api.ts";
+import type { DeviceState, Quality } from "./api.ts";
 import type { DebugDevice, DebugIo, DebugType } from "./manifest.ts";
 
 /** Driver state names that mean the connection isn't working. */
@@ -10,74 +10,102 @@ const untyped: DebugType = { kind: "scalar", iec: "ANY" };
 
 /** What a device's health is read from: the driver's own state, when the build names it. */
 export const healthReads = (device: DebugDevice): TargetRead[] => {
-  const { state, states, diagnostic, message } = device.health ?? {};
-  return [
-    ...(state
-      ? [
-          {
-            target: state,
-            type: states
-              ? { kind: "enum" as const, name: "state", members: states }
-              : { kind: "scalar" as const, iec: "DINT" },
-          },
-        ]
-      : []),
-    ...(diagnostic ? [{ target: diagnostic, type: { kind: "scalar" as const, iec: "BOOL" } }] : []),
-    ...(message ? [{ target: message, type: { kind: "scalar" as const, iec: "STRING" } }] : []),
-  ];
+	const { state, states, diagnostic, message } = device.health ?? {};
+	return [
+		...(state
+			? [
+					{
+						target: state,
+						type: states
+							? { kind: "enum" as const, name: "state", members: states }
+							: { kind: "scalar" as const, iec: "DINT" },
+					},
+				]
+			: []),
+		...(diagnostic
+			? [{ target: diagnostic, type: { kind: "scalar" as const, iec: "BOOL" } }]
+			: []),
+		...(message
+			? [{ target: message, type: { kind: "scalar" as const, iec: "STRING" } }]
+			: []),
+	];
 };
 
 /** Everything a device's page shows: its health, raw assembly bytes, bound channels and status symbols. */
 export const deviceReads = (
-  device: DebugDevice,
-  io: readonly DebugIo[],
-  typeOf: (id: string) => DebugType,
+	device: DebugDevice,
+	io: readonly DebugIo[],
+	typeOf: (id: string) => DebugType,
 ): TargetRead[] => [
-  ...healthReads(device),
-  ...device.assemblies.flatMap(({ raw, bytes }) =>
-    raw
-      ? [
-          {
-            target: raw,
-            type: { kind: "array" as const, element: "BYTE", length: bytes, lower: 0 },
-          },
-        ]
-      : [],
-  ),
-  ...io
-    .filter((binding) => binding.device === device.id)
-    .map(({ target, type }) => ({ target, type: typeOf(type) })),
-  ...Object.values(device.status ?? {}).map((target) => ({ target, type: untyped })),
+	...healthReads(device),
+	...device.assemblies.flatMap(({ raw, bytes }) =>
+		raw
+			? [
+					{
+						target: raw,
+						type: {
+							kind: "array" as const,
+							element: "BYTE",
+							length: bytes,
+							lower: 0,
+						},
+					},
+				]
+			: [],
+	),
+	...io
+		.filter((binding) => binding.device === device.id)
+		.map(({ target, type }) => ({ target, type: typeOf(type) })),
+	...Object.values(device.status ?? {}).map((target) => ({
+		target,
+		type: untyped,
+	})),
 ];
 
+/** A reading that is no longer good says nothing current, fault or not. */
+const healthState = (quality: Quality, faulted: boolean) => {
+	if (quality !== "good") {
+		return "stale";
+	}
+	return faulted ? "fault" : "ok";
+};
+
 const health = (
-  device: DebugDevice,
-  value: (target: string) => TargetSample | undefined,
+	device: DebugDevice,
+	value: (target: string) => TargetSample | undefined,
 ): DeviceState["health"] => {
-  const { state, states, diagnostic, message } = device.health ?? {};
-  if (!state && !diagnostic) return { state: "unknown", quality: "unavailable" };
-  const stateSample = state ? value(state) : undefined;
-  const diagnosticSample = diagnostic ? value(diagnostic) : undefined;
-  const messageSample = message ? value(message) : undefined;
-  const quality = worstQuality([
-    ...(state ? [stateSample] : []),
-    ...(diagnostic ? [diagnosticSample] : []),
-  ]);
-  const number = typeof stateSample?.value === "number" ? stateSample.value : undefined;
-  // The login names enum members the manifest may not list.
-  const name =
-    Object.entries(states ?? {}).find(([, member]) => member === number)?.[0] ??
-    (typeof stateSample?.value === "string" ? stateSample.value : undefined);
-  const faulted =
-    diagnosticSample?.value === true || (name !== undefined && faultyState.test(name));
-  return {
-    state: quality !== "good" ? "stale" : faulted ? "fault" : "ok",
-    ...(number !== undefined && { value: number }),
-    ...(name && { name }),
-    ...(typeof diagnosticSample?.value === "boolean" && { diagnostic: diagnosticSample.value }),
-    ...(typeof messageSample?.value === "string" && { message: messageSample.value }),
-    quality,
-  };
+	const { state, states, diagnostic, message } = device.health ?? {};
+	if (!state && !diagnostic) {
+		return { state: "unknown", quality: "unavailable" };
+	}
+	const stateSample = state ? value(state) : undefined;
+	const diagnosticSample = diagnostic ? value(diagnostic) : undefined;
+	const messageSample = message ? value(message) : undefined;
+	const quality = worstQuality([
+		...(state ? [stateSample] : []),
+		...(diagnostic ? [diagnosticSample] : []),
+	]);
+	const number =
+		typeof stateSample?.value === "number" ? stateSample.value : undefined;
+	// The login names enum members the manifest may not list.
+	const name =
+		Object.entries(states ?? {}).find(([, member]) => member === number)?.[0] ??
+		(typeof stateSample?.value === "string" ? stateSample.value : undefined);
+	const faulted =
+		diagnosticSample?.value === true ||
+		(name !== undefined && faultyState.test(name));
+	return {
+		state: healthState(quality, faulted),
+		...(number !== undefined && { value: number }),
+		...(name && { name }),
+		...(typeof diagnosticSample?.value === "boolean" && {
+			diagnostic: diagnosticSample.value,
+		}),
+		...(typeof messageSample?.value === "string" && {
+			message: messageSample.value,
+		}),
+		quality,
+	};
 };
 
 /**
@@ -85,41 +113,44 @@ const health = (
  * is "unknown" unless the manifest names the driver's own state.
  */
 export const deviceState = (
-  device: DebugDevice,
-  io: readonly DebugIo[],
-  value: (target: string) => TargetSample | undefined,
+	device: DebugDevice,
+	io: readonly DebugIo[],
+	value: (target: string) => TargetSample | undefined,
 ): DeviceState => ({
-  id: device.id,
-  health: health(device, value),
-  assemblies: device.assemblies.map(({ direction, address, raw }) => {
-    const sample = raw ? value(raw) : undefined;
-    return {
-      direction,
-      ...(address && { address }),
-      bytes:
-        Array.isArray(sample?.value) &&
-        sample.value.every((byte): byte is number => typeof byte === "number")
-          ? sample.value
-          : null,
-      quality: sample?.quality ?? "unavailable",
-    };
-  }),
-  channels: io.flatMap((binding) =>
-    binding.device === device.id && binding.channel
-      ? [
-          {
-            id: binding.channel,
-            path: binding.path,
-            value: value(binding.target)?.value ?? null,
-            quality: value(binding.target)?.quality ?? "unavailable",
-          },
-        ]
-      : [],
-  ),
-  status: Object.fromEntries(
-    Object.entries(device.status ?? {}).map(([label, target]) => [
-      label,
-      { value: value(target)?.value ?? null, quality: value(target)?.quality ?? "unavailable" },
-    ]),
-  ),
+	id: device.id,
+	health: health(device, value),
+	assemblies: device.assemblies.map(({ direction, address, raw }) => {
+		const sample = raw ? value(raw) : undefined;
+		return {
+			direction,
+			...(address && { address }),
+			bytes:
+				Array.isArray(sample?.value) &&
+				sample.value.every((byte): byte is number => typeof byte === "number")
+					? sample.value
+					: null,
+			quality: sample?.quality ?? "unavailable",
+		};
+	}),
+	channels: io.flatMap((binding) =>
+		binding.device === device.id && binding.channel
+			? [
+					{
+						id: binding.channel,
+						path: binding.path,
+						value: value(binding.target)?.value ?? null,
+						quality: value(binding.target)?.quality ?? "unavailable",
+					},
+				]
+			: [],
+	),
+	status: Object.fromEntries(
+		Object.entries(device.status ?? {}).map(([label, target]) => [
+			label,
+			{
+				value: value(target)?.value ?? null,
+				quality: value(target)?.quality ?? "unavailable",
+			},
+		]),
+	),
 });

package/src/http.ts

@@ -11,76 +11,95 @@ const heartbeatMs = 5000;
 const encoder = new TextEncoder();
 
 const json = (body: unknown, status = 200) =>
-  Response.json(body, { status, headers: { "Cache-Control": "no-store" } });
+	Response.json(body, { status, headers: { "Cache-Control": "no-store" } });
 
 const list = (value: string | null) =>
-  (value ?? "")
-    .split(",")
-    .map((item) => item.trim())
-    .filter(Boolean);
+	(value ?? "")
+		.split(",")
+		.map((item) => item.trim())
+		.filter(Boolean);
 
 export const loadManifest = async (file: string) =>
-  debugManifest.parse(JSON.parse(await readFile(file, "utf8")));
+	debugManifest.parse(JSON.parse(await readFile(file, "utf8")));
 
 /** What a stream's page shows, from its query. */
 const interest = (search: URLSearchParams): Interest => {
-  const jobs = list(search.get("jobs")).map(Number);
-  if (!jobs.every(Number.isInteger)) throw new DebugError("jobs must be job ids", 400);
-  return {
-    watch: list(search.get("watch")),
-    jobs,
-    health: list(search.get("health")),
-    devices: list(search.get("devices")),
-  };
+	const jobs = list(search.get("jobs")).map(Number);
+	if (!jobs.every(Number.isInteger)) {
+		throw new DebugError("jobs must be job ids", 400);
+	}
+	return {
+		watch: list(search.get("watch")),
+		jobs,
+		health: list(search.get("health")),
+		devices: list(search.get("devices")),
+	};
 };
 
 /** Every stream event, plus samples of the watched paths and states of the shown jobs and devices. */
 const stream = (debug: Debugger, { watch, ...shown }: Interest) => {
-  // Refuse a watch that matches too much before the stream starts.
-  debug.paths.expand(watch);
-  let stop = () => {};
-  return new Response(
-    new ReadableStream<Uint8Array>({
-      start: (controller) => {
-        let open = true;
-        const write = (text: string) => {
-          if (open) controller.enqueue(encoder.encode(text));
-        };
-        const send = ({ event, data }: StreamMessage) =>
-          write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
-        send({ event: "session", data: debug.session() });
-        const latest = new Map<string, { sample: Sample; sentAt: number }>();
-        const sendSample = (sample: Sample) => {
-          latest.set(sample.path, { sample, sentAt: Date.now() });
-          send({ event: "sample", data: sample });
-        };
-        const unsubscribe = debug.subscribe(send);
-        const unwatch = debug.watch(watch, sendSample);
-        const unshow = debug.show(shown);
-        const heartbeat = setInterval(() => write(": keepalive\n\n"), heartbeatMs);
-        // Over OPC UA, samples come only on change. While the session holds, an unchanged value
-        // is still current, so it is sent again each interval; clients mark samples stale by their age.
-        const { intervalMs } = debug.session().reading;
-        const refresh = setInterval(() => {
-          if (debug.session().connection.state !== "connected") return;
-          const now = Date.now();
-          for (const { sample, sentAt } of latest.values())
-            if (now - sentAt >= intervalMs)
-              sendSample({ ...sample, receivedAt: new Date(now).toISOString() });
-        }, intervalMs);
-        stop = () => {
-          open = false;
-          clearInterval(heartbeat);
-          clearInterval(refresh);
-          unsubscribe();
-          unwatch();
-          unshow();
-        };
-      },
-      cancel: () => stop(),
-    }),
-    { headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-store" } },
-  );
+	// Refuse a watch that matches too much before the stream starts.
+	debug.paths.expand(watch);
+	let stop = () => {};
+	return new Response(
+		new ReadableStream<Uint8Array>({
+			start: (controller) => {
+				let open = true;
+				const write = (text: string) => {
+					if (open) {
+						controller.enqueue(encoder.encode(text));
+					}
+				};
+				const send = ({ event, data }: StreamMessage) =>
+					write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+				send({ event: "session", data: debug.session() });
+				const latest = new Map<string, { sample: Sample; sentAt: number }>();
+				const sendSample = (sample: Sample) => {
+					latest.set(sample.path, { sample, sentAt: Date.now() });
+					send({ event: "sample", data: sample });
+				};
+				const unsubscribe = debug.subscribe(send);
+				const unwatch = debug.watch(watch, sendSample);
+				const unshow = debug.show(shown);
+				const heartbeat = setInterval(
+					() => write(": keepalive\n\n"),
+					heartbeatMs,
+				);
+				// Over OPC UA, samples come only on change. While the session holds, an unchanged value
+				// is still current, so it is sent again each interval; clients mark samples stale by their age.
+				const { intervalMs } = debug.session().reading;
+				const refresh = setInterval(() => {
+					if (debug.session().connection.state !== "connected") {
+						return;
+					}
+					const now = Date.now();
+					for (const { sample, sentAt } of latest.values()) {
+						if (now - sentAt >= intervalMs) {
+							sendSample({
+								...sample,
+								receivedAt: new Date(now).toISOString(),
+							});
+						}
+					}
+				}, intervalMs);
+				stop = () => {
+					open = false;
+					clearInterval(heartbeat);
+					clearInterval(refresh);
+					unsubscribe();
+					unwatch();
+					unshow();
+				};
+			},
+			cancel: () => stop(),
+		}),
+		{
+			headers: {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-store",
+			},
+		},
+	);
 };
 
 /**
@@ -88,68 +107,80 @@ const stream = (debug: Debugger, { watch, ...shown }: Interest) => {
  * the host mounts them. There is no route that writes to the controller; hosts authenticate.
  */
 export const createDebugHandler =
-  (debug: Debugger, log: (message: string) => void) =>
-  async (request: Request, route: string): Promise<Response> => {
-    const { searchParams } = new URL(request.url);
-    const key = `${request.method} ${route}`;
-    try {
-      switch (key) {
-        case "GET /":
-          return new Response((await loadUi()).html, {
-            headers: { "Content-Type": "text/html; charset=utf-8" },
-          });
-        case "GET /ui.js":
-          return new Response((await loadUi()).script, {
-            headers: { "Content-Type": "text/javascript; charset=utf-8" },
-          });
-        case "GET /api/session":
-          return json(debug.session());
-        case "GET /api/manifest":
-          return json(debug.manifest);
-        case "GET /api/stream":
-          return stream(debug, interest(searchParams));
-        case "GET /api/values":
-          return json(await debug.values(list(searchParams.get("paths"))));
-        case "GET /api/jobs":
-          return json(debug.jobs());
-        case "GET /api/hardware":
-          return json(debug.hardware());
-        case "GET /api/timeline":
-          return json(debug.timeline(searchParams.get("since") ?? undefined));
-        case "GET /api/watch":
-          return json(debug.watchGroups());
-        case "PUT /api/watch":
-          return json(await debug.saveWatchGroups(watchGroupsSchema.parse(await request.json())));
-      }
-      return json({ error: `No route ${key}` }, 404);
-    } catch (error) {
-      if (error instanceof DebugError) return json({ error: error.message }, error.status);
-      // RangeError: a watch matches too many values; SyntaxError: a body isn't JSON.
-      if (error instanceof RangeError || error instanceof SyntaxError)
-        return json({ error: error.message }, 400);
-      if (error instanceof z.ZodError) return json({ error: z.prettifyError(error) }, 400);
-      log(`${key} failed: ${error instanceof Error ? error.stack : String(error)}`);
-      return json({ error: "The debugger failed; see its log" }, 500);
-    }
-  };
+	(debug: Debugger, log: (message: string) => void) =>
+	async (request: Request, route: string): Promise<Response> => {
+		const { searchParams } = new URL(request.url);
+		const key = `${request.method} ${route}`;
+		try {
+			switch (key) {
+				case "GET /":
+					return new Response((await loadUi()).html, {
+						headers: { "Content-Type": "text/html; charset=utf-8" },
+					});
+				case "GET /ui.js":
+					return new Response((await loadUi()).script, {
+						headers: { "Content-Type": "text/javascript; charset=utf-8" },
+					});
+				case "GET /api/session":
+					return json(debug.session());
+				case "GET /api/manifest":
+					return json(debug.manifest);
+				case "GET /api/stream":
+					return stream(debug, interest(searchParams));
+				case "GET /api/values":
+					return json(await debug.values(list(searchParams.get("paths"))));
+				case "GET /api/jobs":
+					return json(debug.jobs());
+				case "GET /api/hardware":
+					return json(debug.hardware());
+				case "GET /api/timeline":
+					return json(debug.timeline(searchParams.get("since") ?? undefined));
+				case "GET /api/watch":
+					return json(debug.watchGroups());
+				case "PUT /api/watch":
+					return json(
+						await debug.saveWatchGroups(
+							watchGroupsSchema.parse(await request.json()),
+						),
+					);
+			}
+			return json({ error: `No route ${key}` }, 404);
+		} catch (error) {
+			if (error instanceof DebugError) {
+				return json({ error: error.message }, error.status);
+			}
+			// RangeError: a watch matches too many values; SyntaxError: a body isn't JSON.
+			if (error instanceof RangeError || error instanceof SyntaxError) {
+				return json({ error: error.message }, 400);
+			}
+			if (error instanceof z.ZodError) {
+				return json({ error: z.prettifyError(error) }, 400);
+			}
+			log(
+				`${key} failed: ${error instanceof Error ? error.stack : String(error)}`,
+			);
+			return json({ error: "The debugger failed; see its log" }, 500);
+		}
+	};
 
 /**
  * Serves the debugger on 127.0.0.1 without a token. Requests that name another host are refused,
  * so no website can reach it by rebinding a domain name to 127.0.0.1.
  */
 export const serveDebugger = (
-  debug: Debugger,
-  options: { port: number; log: (message: string) => void },
+	debug: Debugger,
+	options: { port: number; log: (message: string) => void },
 ) => {
-  const handle = createDebugHandler(debug, options.log);
-  return Bun.serve({
-    hostname: "127.0.0.1",
-    port: options.port,
-    fetch: (request) => {
-      const host = request.headers.get("host")?.replace(/:\d+$/, "");
-      if (host !== "127.0.0.1" && host !== "localhost")
-        return json({ error: "Use http://127.0.0.1 or http://localhost" }, 403);
-      return handle(request, new URL(request.url).pathname);
-    },
-  });
+	const handle = createDebugHandler(debug, options.log);
+	return Bun.serve({
+		hostname: "127.0.0.1",
+		port: options.port,
+		fetch: (request) => {
+			const host = request.headers.get("host")?.replace(/:\d+$/, "");
+			if (host !== "127.0.0.1" && host !== "localhost") {
+				return json({ error: "Use http://127.0.0.1 or http://localhost" }, 403);
+			}
+			return handle(request, new URL(request.url).pathname);
+		},
+	});
 };

package/src/index.ts

@@ -1,8 +1,38 @@
-export type * from "./api.ts";
-export type { Connection, TargetAdapter, TargetRead, TargetSample } from "./adapter.ts";
-export { createDebugger, DebugError, type Debugger, type DebuggerOptions } from "./debugger.ts";
+export type {
+	ApiResponses,
+	AppRecord,
+	ConnectionState,
+	DeviceState,
+	Interest,
+	JobState,
+	Quality,
+	RequestTrace,
+	Sample,
+	Session,
+	StreamEvents,
+	TimelineEntry,
+	TraceEvent,
+	WatchGroups,
+} from "./api.ts";
+export type {
+	Connection,
+	TargetAdapter,
+	TargetRead,
+	TargetSample,
+} from "./adapter.ts";
+export {
+	createDebugger,
+	DebugError,
+	type Debugger,
+	type DebuggerOptions,
+} from "./debugger.ts";
 export { createDebugHandler, loadManifest, serveDebugger } from "./http.ts";
 export { createLoginAdapter, LoginUnavailable, noLogin } from "./login.ts";
 export { createOpcUaAdapter, opcUaConnection } from "./opcua.ts";
-export { createPaths, type PathNode, type Paths, type ResolvedPath } from "./paths.ts";
+export {
+	createPaths,
+	type PathNode,
+	type Paths,
+	type ResolvedPath,
+} from "./paths.ts";
 export { timelineEntries } from "./timeline.ts";