@classytic/labs 0.3.0 → 0.5.0

package/dist/networking/subnet.mjs

@@ -1,84 +0,0 @@
-import { ipv4ToInt } from "./ip.mjs";
-
-//#region src/networking/subnet.ts
-/**
-* Subnetting, reduced to the one question it actually answers.
-*
-* "Are these two addresses on the same network?" is the whole of it, and the answer is mechanical:
-* compare the first `prefix` bits. Same, and the two can talk directly. Different, and everything
-* has to go through a router. Every other subnetting fact (mask, network address, broadcast, usable
-* count) falls out of where that boundary sits.
-*
-* Students drown here because it is taught in dotted decimal, where the boundary is invisible. In
-* binary it is a vertical line, and the moment it crosses the first differing bit the answer flips.
-* That is the thing to show.
-*/
-const intToIpv4 = (value) => [
-	24,
-	16,
-	8,
-	0
-].map((shift) => value >>> shift & 255).join(".");
-/** The mask for a prefix, as a 32-bit unsigned value. /0 is all zeros. */
-const maskFor = (prefix) => prefix <= 0 ? 0 : prefix >= 32 ? 4294967295 : 4294967295 << 32 - prefix >>> 0;
-/** The 32 bits of an address, flagged by which side of the prefix boundary they fall. */
-function bitsOf(address, prefix) {
-	const value = ipv4ToInt(address);
-	if (value == null) return null;
-	return Array.from({ length: 32 }, (_, index) => ({
-		value: value >>> 31 - index & 1,
-		network: index < prefix
-	}));
-}
-function describe(address, prefix) {
-	const value = ipv4ToInt(address);
-	const bits = bitsOf(address, prefix);
-	if (value == null || !bits || prefix < 0 || prefix > 32) return null;
-	const mask = maskFor(prefix);
-	const network = (value & mask) >>> 0;
-	const broadcast = (network | ~mask >>> 0) >>> 0;
-	const total = 2 ** (32 - prefix);
-	const usableHosts = total > 2 ? total - 2 : 0;
-	return {
-		address,
-		prefix,
-		mask: intToIpv4(mask),
-		network: intToIpv4(network),
-		broadcast: intToIpv4(broadcast),
-		firstUsable: usableHosts ? intToIpv4(network + 1) : null,
-		lastUsable: usableHosts ? intToIpv4(broadcast - 1) : null,
-		usableHosts,
-		bits
-	};
-}
-/** Do two addresses share a network under this prefix? */
-function sameNetwork(a, b, prefix) {
-	const left = ipv4ToInt(a);
-	const right = ipv4ToInt(b);
-	if (left == null || right == null) return null;
-	const mask = maskFor(prefix);
-	return (left & mask) >>> 0 === (right & mask) >>> 0;
-}
-/**
-* The index (0-based from the left) of the first bit where two addresses differ, or -1 when they
-* are identical. This is the number the whole lab turns on: any prefix at or below it puts the two
-* on the same network, and any prefix above it separates them.
-*/
-function firstDifferingBit(a, b) {
-	const left = ipv4ToInt(a);
-	const right = ipv4ToInt(b);
-	if (left == null || right == null) return -1;
-	for (let index = 0; index < 32; index++) {
-		const shift = 31 - index;
-		if ((left >>> shift & 1) !== (right >>> shift & 1)) return index;
-	}
-	return -1;
-}
-/** The largest prefix that still keeps both addresses together. */
-function widestSharedPrefix(a, b) {
-	const differing = firstDifferingBit(a, b);
-	return differing === -1 ? 32 : differing;
-}
-
-//#endregion
-export { bitsOf, describe, firstDifferingBit, sameNetwork, widestSharedPrefix };

package/dist/networking/switch.mjs

@@ -1,155 +0,0 @@
-//#region src/networking/switch.ts
-const linkUp = (port) => port.enabled && !!port.device;
-const portOf = (state, mac) => state.table.find((entry) => entry.mac === mac)?.port;
-const deviceName = (state, mac) => state.ports.find((port) => port.device?.mac === mac)?.device?.name ?? mac;
-/**
-* Send one frame in through `fromPort` and resolve what the switch does with it.
-*
-* Pure: returns the next state rather than mutating, so a lesson can step forward and back.
-*/
-function sendFrame(state, fromPort, dstMac) {
-	const events = [];
-	const ingress = state.ports.find((port) => port.id === fromPort);
-	const srcMac = ingress?.device?.mac ?? "";
-	if (!ingress || !ingress.enabled) {
-		events.push({
-			type: "drop",
-			reason: "port-down",
-			message: `Port ${fromPort} is disabled, so nothing can enter through it.`
-		});
-		return {
-			events,
-			next: state,
-			delivered: [],
-			flooded: false
-		};
-	}
-	if (!ingress.device) {
-		events.push({
-			type: "drop",
-			reason: "no-link",
-			message: `Port ${fromPort} has nothing plugged into it.`
-		});
-		return {
-			events,
-			next: state,
-			delivered: [],
-			flooded: false
-		};
-	}
-	events.push({
-		type: "ingress",
-		port: fromPort,
-		srcMac,
-		dstMac,
-		message: `A frame from ${ingress.device.name} arrives on port ${fromPort}, addressed to ${deviceName(state, dstMac)}.`
-	});
-	const known = state.table.find((entry) => entry.mac === srcMac);
-	const relearned = !!known && known.port !== fromPort;
-	const table = [...state.table.filter((entry) => entry.mac !== srcMac), {
-		mac: srcMac,
-		port: fromPort
-	}].sort((a, b) => a.port - b.port || a.mac.localeCompare(b.mac));
-	if (!known || relearned) events.push({
-		type: "learn",
-		mac: srcMac,
-		port: fromPort,
-		relearned,
-		message: relearned ? `${ingress.device.name} has moved. The table now says port ${fromPort}.` : `Learned: ${ingress.device.name} is reachable through port ${fromPort}.`
-	});
-	const next = {
-		ports: state.ports,
-		table
-	};
-	const target = portOf(next, dstMac);
-	if (target === fromPort) {
-		events.push({
-			type: "drop",
-			reason: "same-port",
-			message: `The destination is on the port the frame arrived from, so the switch does not send it back out.`
-		});
-		return {
-			events,
-			next,
-			delivered: [],
-			flooded: false
-		};
-	}
-	if (target !== void 0 && linkUp(state.ports.find((port) => port.id === target))) {
-		events.push({
-			type: "forward",
-			port: target,
-			message: `The table knows this address, so the frame goes out of port ${target} only. No other device sees it.`
-		});
-		return {
-			events,
-			next,
-			delivered: [target],
-			flooded: false
-		};
-	}
-	const flooded = next.ports.filter((port) => port.id !== fromPort && linkUp(port)).map((port) => port.id);
-	events.push({
-		type: "flood",
-		ports: flooded,
-		message: flooded.length ? `This address is not in the table, so the switch floods: out of every connected port except ${fromPort}.` : `This address is not in the table, and no other port has a link, so there is nowhere to flood.`
-	});
-	return {
-		events,
-		next,
-		delivered: flooded,
-		flooded: true
-	};
-}
-/** Toggle a port up or down. A port going down forgets what was learned through it. */
-function setPortEnabled(state, portId, enabled) {
-	return {
-		ports: state.ports.map((port) => port.id === portId ? {
-			...port,
-			enabled
-		} : port),
-		table: enabled ? state.table : state.table.filter((entry) => entry.port !== portId)
-	};
-}
-/** Clear the forwarding table, which returns the switch to the day it was unboxed. */
-const clearTable = (state) => ({
-	ports: state.ports,
-	table: []
-});
-const MACS = [
-	"AA:01",
-	"BB:02",
-	"CC:03",
-	"DD:04",
-	"EE:05",
-	"FF:06",
-	"11:07",
-	"22:08"
-];
-const NAMES = [
-	"Laptop",
-	"Desktop",
-	"Printer",
-	"Server",
-	"Phone",
-	"Camera",
-	"NAS",
-	"TV"
-];
-/** A switch with `size` ports, the first `connected` of them holding a device. */
-function makeSwitch(size = 8, connected = 4) {
-	return {
-		ports: Array.from({ length: size }, (_, index) => ({
-			id: index + 1,
-			enabled: true,
-			device: index < connected ? {
-				name: NAMES[index],
-				mac: MACS[index]
-			} : void 0
-		})),
-		table: []
-	};
-}
-
-//#endregion
-export { clearTable, linkUp, makeSwitch, sendFrame, setPortEnabled };

package/dist/networking/vlan.mjs

@@ -1,100 +0,0 @@
-//#region src/networking/vlan.ts
-const isLive = (port) => port.enabled && !!port.device;
-/** Ports in the same VLAN as `portId`, excluding itself. */
-function domainOf(state, portId) {
-	const source = state.ports.find((port) => port.id === portId);
-	if (!source) return [];
-	return state.ports.filter((port) => port.id !== portId && port.vlan === source.vlan && isLive(port)).map((port) => port.id);
-}
-/** A broadcast reaches its own VLAN and stops there. Routing does not change that. */
-function broadcastFrom(state, portId) {
-	const source = state.ports.find((port) => port.id === portId);
-	if (!source || !isLive(source)) return {
-		reached: [],
-		blocked: [],
-		message: `Port ${portId} has no live device to send from.`
-	};
-	const reached = domainOf(state, portId);
-	const blocked = state.ports.filter((port) => port.id !== portId && isLive(port) && port.vlan !== source.vlan).map((port) => port.id);
-	const vlanName = state.vlans.find((vlan) => vlan.id === source.vlan)?.name ?? `VLAN ${source.vlan}`;
-	return {
-		reached,
-		blocked,
-		message: blocked.length ? `The broadcast reaches every live port in ${vlanName} and stops. ${blocked.length} live port${blocked.length > 1 ? "s are" : " is"} in another VLAN and never sees it.` : `The broadcast reaches every live port in ${vlanName}.`
-	};
-}
-/**
-* Directed traffic between two ports. Within a VLAN the switch forwards it. Across VLANs it needs
-* a layer-3 interface, and that interface is where a policy would sit.
-*/
-function sendBetween(state, fromPort, toPort) {
-	const source = state.ports.find((port) => port.id === fromPort);
-	const target = state.ports.find((port) => port.id === toPort);
-	if (!source || !target || !isLive(source) || !isLive(target)) return {
-		delivered: false,
-		viaRouter: false,
-		message: "Both ends need a live device."
-	};
-	if (source.vlan === target.vlan) return {
-		delivered: true,
-		viaRouter: false,
-		message: `Same VLAN, so the switch forwards it directly. Nothing outside the VLAN is involved.`
-	};
-	if (!state.routing) return {
-		delivered: false,
-		viaRouter: false,
-		message: `Different VLANs and no layer-3 interface, so there is no path at all. The switch will not carry it.`
-	};
-	return {
-		delivered: true,
-		viaRouter: true,
-		message: `Different VLANs, so it goes up to the layer-3 interface and back down. Every crossing passes that one point, which is where a rule can be applied.`
-	};
-}
-function setPortVlan(state, portId, vlan) {
-	return {
-		...state,
-		ports: state.ports.map((port) => port.id === portId ? {
-			...port,
-			vlan
-		} : port)
-	};
-}
-const setRouting = (state, routing) => ({
-	...state,
-	routing
-});
-/** How many separate broadcast domains this switch is currently carrying. */
-const domainCount = (state) => new Set(state.ports.filter(isLive).map((port) => port.vlan)).size;
-const NAMES = [
-	"Sales",
-	"Finance",
-	"Reception",
-	"Store",
-	"Server A",
-	"Server B",
-	"Kiosk",
-	"Camera"
-];
-/** Eight ports, the first `connected` holding a device, split evenly across two VLANs. */
-function makeVlanSwitch(connected = 6) {
-	return {
-		vlans: [{
-			id: 10,
-			name: "VLAN 10"
-		}, {
-			id: 20,
-			name: "VLAN 20"
-		}],
-		routing: false,
-		ports: Array.from({ length: 8 }, (_, index) => ({
-			id: index + 1,
-			vlan: index < 4 ? 10 : 20,
-			enabled: true,
-			device: index < connected ? { name: NAMES[index] } : void 0
-		}))
-	};
-}
-
-//#endregion
-export { broadcastFrom, domainCount, isLive, makeVlanSwitch, sendBetween, setPortVlan, setRouting };

package/dist/networking/vpn.mjs

@@ -1,118 +0,0 @@
-//#region src/networking/vpn.ts
-const OBSERVERS = [
-	{
-		id: "wifi",
-		name: "The café Wi-Fi",
-		short: "Café Wi-Fi",
-		where: "anyone else on the same network, including whoever runs it"
-	},
-	{
-		id: "isp",
-		name: "Your internet provider",
-		short: "Your provider",
-		where: "every packet you send crosses their equipment"
-	},
-	{
-		id: "gateway",
-		name: "The VPN provider",
-		short: "VPN provider",
-		where: "the far end of the tunnel, where the wrapping comes off"
-	},
-	{
-		id: "website",
-		name: "The website",
-		short: "The website",
-		where: "the machine you are actually talking to"
-	}
-];
-const YOU = "You";
-const GATEWAY = "VPN gateway";
-const SITE = "example.com";
-const CIPHER = "unreadable";
-/** Watchers that exist in this setup. Without a tunnel there is no gateway to watch. */
-const observersFor = (setup) => OBSERVERS.filter((observer) => observer.id !== "gateway" || setup.vpn);
-function observe(id, setup) {
-	const observer = OBSERVERS.find((item) => item.id === id);
-	if (!observer || id === "gateway" && !setup.vpn) return null;
-	if (id === "website") return {
-		observer,
-		from: {
-			value: setup.vpn ? GATEWAY : YOU,
-			hidden: false
-		},
-		to: {
-			value: SITE,
-			hidden: false
-		},
-		contents: {
-			value: "your request, in full",
-			hidden: false
-		},
-		verdict: setup.vpn ? "Sees a request arriving from the VPN gateway rather than from you, and reads it in full. It has to: it is the one answering." : "Sees your own address and reads the request in full. HTTPS protects it from everyone in between, never from the far end."
-	};
-	if (setup.vpn) {
-		if (id === "gateway") return {
-			observer,
-			from: {
-				value: YOU,
-				hidden: false
-			},
-			to: {
-				value: SITE,
-				hidden: false
-			},
-			contents: setup.https ? {
-				value: CIPHER,
-				hidden: true
-			} : {
-				value: "your request, in full",
-				hidden: false
-			},
-			verdict: setup.https ? "Knows who you are and every site you ask for, but HTTPS still keeps the contents from them. This is the trade: your provider stopped seeing this and they started." : "Knows who you are, every site you ask for, and everything you send. Without HTTPS you have simply changed which company watches you."
-		};
-		return {
-			observer,
-			from: {
-				value: YOU,
-				hidden: false
-			},
-			to: {
-				value: GATEWAY,
-				hidden: false
-			},
-			contents: {
-				value: CIPHER,
-				hidden: true
-			},
-			verdict: "Can tell you are using a VPN and nothing else. Which sites you visit is inside the wrapping, so it is not available here at any price."
-		};
-	}
-	return {
-		observer,
-		from: {
-			value: YOU,
-			hidden: false
-		},
-		to: {
-			value: SITE,
-			hidden: false
-		},
-		contents: setup.https ? {
-			value: CIPHER,
-			hidden: true
-		} : {
-			value: "your request, in full",
-			hidden: false
-		},
-		verdict: setup.https ? "Sees which sites you visit and when, but not what you asked for or what came back." : "Sees which sites you visit and can read every word of it."
-	};
-}
-/** Every watcher's view of one setup, which is where the pattern shows up. */
-const surveyOf = (setup) => observersFor(setup).map((observer) => observe(observer.id, setup)).filter((sighting) => sighting !== null);
-/** Watchers who can name the site being visited. The count is the honest summary of a setup. */
-const canSeeDestination = (setup) => surveyOf(setup).filter((sighting) => !sighting.to.hidden && sighting.to.value === SITE).map((sighting) => sighting.observer.id);
-/** Watchers who can read what you actually sent. */
-const canReadContents = (setup) => surveyOf(setup).filter((sighting) => !sighting.contents.hidden).map((sighting) => sighting.observer.id);
-
-//#endregion
-export { OBSERVERS, canReadContents, canSeeDestination, observe, observersFor };

package/dist/physics/alternating-current/core.d.mts

@@ -1,162 +0,0 @@
-//#region src/physics/alternating-current/core.d.ts
-/**
- * Alternating currents (Cambridge International A Level Physics 9702, chapter 21).
- *
- * A sinusoidal supply v(t) = V0 sin(2 pi f t) drives a resistor R, so i(t) = v(t) / R. Three
- * ideas live here, and only the middle one is hard:
- *
- *   period and peak   T = 1/f, and v and i share the same shape because R is constant
- *   r.m.s.            V_rms = V0 / sqrt(2), DEFINED by equal heating, not by averaging v
- *   rectification     one diode keeps half the wave, a bridge folds the whole wave up, and a
- *                     capacitor across the load turns the ripple into a nearly steady line
- *
- * The r.m.s. part is the reason this file exists. The mean of v over a whole cycle is zero, so
- * averaging the wave tells a learner nothing. What is NOT zero is the mean of v squared, because
- * squaring makes every value positive. Power is v squared over R, so the mean of v squared is
- * what sets the heating. Take the root of that mean and you have the steady d.c. voltage that
- * would heat the same resistor at the same rate: root, of the mean, of the square.
- *
- * `meanSquareFromPeak` returns the exact answer V0^2 / 2. `meanSquareByIntegration` returns the
- * SAME number by adding up v^2 across one period with Simpson's rule, reading nothing from the
- * algebra. The lab draws the integrated value, so the horizontal line on the graph is a measured
- * mean and not a formula redrawn as a line.
- *
- * Everything here is pure, deterministic and React-free, so it can be tested directly.
- */
-interface AcSupply {
-  /** Peak (maximum) voltage V0, in volts. */
-  peakVoltageV: number;
-  /** Frequency f, in hertz. */
-  frequencyHz: number;
-  /** Load resistance R, in ohms. */
-  resistanceOhm: number;
-}
-/** One diode keeps the positive halves; a bridge of four folds the negative halves up. */
-type RectifierMode = 'half' | 'full';
-/** Period of the supply, T = 1 / f, in seconds. */
-declare function acPeriodS(frequencyHz: number): number;
-/** v(t) = V0 sin(2 pi f t), in volts. */
-declare function acVoltageAt(supply: AcSupply, t: number): number;
-/** i(t) = v(t) / R, in amperes. In phase with v, because a resistor has no phase shift. */
-declare function acCurrentAt(supply: AcSupply, t: number): number;
-/** The r.m.s. value of a SINUSOID from its peak: peak / sqrt(2). Works for volts and amps. */
-declare function rmsFromPeak(peak: number): number;
-/** The mean of v^2 over a whole cycle, from the algebra: V0^2 / 2. */
-declare function meanSquareFromPeak(peak: number): number;
-/**
- * The integral of v^2 over ONE whole period, in V^2 s, by Simpson's rule.
- *
- * This is the honest route to the mean square: no identity for sin^2 is used anywhere. The exact
- * answer is V0^2 T / 2, and Simpson's rule on a smooth periodic function reaches it to far more
- * figures than the lab ever prints. `intervals` is rounded up to an even number, as Simpson's
- * rule requires.
- */
-declare function integrateSquareOverPeriod(peakVoltageV: number, frequencyHz: number, intervals?: number): number;
-/** The mean of v^2 over one period, measured by integration: (integral over T) / T. */
-declare function meanSquareByIntegration(peakVoltageV: number, frequencyHz: number, intervals?: number): number;
-/**
- * Mean power delivered to R, in watts.
- *
- * P_mean = V_rms^2 / R = V0^2 / (2 R), which is exactly HALF the peak power. This single number
- * is what r.m.s. is for: a steady d.c. supply of V_rms volts across the same R delivers it too.
- */
-declare function meanAcPowerW(supply: AcSupply): number;
-interface AcState {
-  /** Period T = 1/f, s. */
-  periodS: number;
-  peakVoltageV: number;
-  /** I0 = V0 / R, A. */
-  peakCurrentA: number;
-  /** V_rms = V0 / sqrt(2), V. */
-  rmsVoltageV: number;
-  /** I_rms = I0 / sqrt(2) = V_rms / R, A. */
-  rmsCurrentA: number;
-  /** Mean of v^2 over a cycle, measured by integration, V^2. */
-  meanSquareVoltageV2: number;
-  /** Mean of v^2 from the algebra, V0^2 / 2, V^2. The two agree; the lab shows both. */
-  meanSquareExactV2: number;
-  /** Mean power into R, W. */
-  meanPowerW: number;
-  /** Peak power into R, V0^2 / R, W. Twice the mean. */
-  peakPowerW: number;
-}
-/** Everything the lab reads off one supply driving one resistor. */
-declare function acState(supply: AcSupply): AcState;
-interface WavePoint {
-  /** Time, s. */
-  t: number;
-  /** Supply voltage, V. */
-  v: number;
-  /** Current in R, A. */
-  i: number;
-}
-/** The supply sampled over whole cycles. Deterministic: the same input gives the same points. */
-declare function acWaveTrace(supply: AcSupply, cycles?: number, samplesPerCycle?: number): WavePoint[];
-/** What the diodes let through: half-wave keeps v when positive, full-wave folds it up. */
-declare function rectify(v: number, mode: RectifierMode): number;
-/**
- * Mean of the rectified output over a whole cycle, with no smoothing capacitor.
- *
- * Half-wave gives V0 / pi (0.318 V0), because half the cycle is flat zero. Full-wave gives
- * 2 V0 / pi (0.637 V0). Neither is V_rms: this is a mean HEIGHT, not a heating value.
- */
-declare function meanRectifiedVoltage(peakVoltageV: number, mode: RectifierMode): number;
-/** The ripple repeats once per cycle after one diode, twice per cycle after a bridge. */
-declare function rippleFrequencyHz(frequencyHz: number, mode: RectifierMode): number;
-interface RectifiedPoint {
-  /** Time, s. */
-  t: number;
-  /** Supply voltage before the diodes, V. */
-  input: number;
-  /** Diode output with no capacitor, V. */
-  rectified: number;
-  /** Voltage across the load with the smoothing capacitor fitted, V. */
-  output: number;
-}
-interface RectifiedTrace {
-  points: RectifiedPoint[];
-  /** Largest output voltage in the last whole cycle, V. */
-  maxV: number;
-  /** Smallest output voltage in the last whole cycle, V. */
-  minV: number;
-  /** Peak-to-peak ripple in the last whole cycle, V. */
-  rippleV: number;
-  /** Mean output over the last whole cycle, V. */
-  meanV: number;
-  /** How often the output dips, Hz. */
-  rippleFrequencyHz: number;
-  /** Time constant R C, s. Compare it with the period: large R C means small ripple. */
-  timeConstantS: number;
-}
-interface RectifiedInput {
-  supply: AcSupply;
-  /** Smoothing capacitance across the load, farads. Zero means no capacitor. */
-  capacitanceF: number;
-  rectifier: RectifierMode;
-  cycles?: number;
-  samplesPerCycle?: number;
-}
-/**
- * The load voltage after rectification, with an ideal peak-detector capacitor.
- *
- * The model is the one a textbook draws: while the rectified wave is above the capacitor
- * voltage the diodes conduct and the capacitor follows the wave up; once the wave falls away
- * the diodes stop conducting and the capacitor discharges through R, decaying by
- * exp(-dt / RC) each step. So the output is
- *
- *   v_out(t) = max( rectified(t), v_out(t - dt) * exp(-dt / RC) )
- *
- * With no capacitor RC is zero, the decay factor is zero, and the output is the bare rectified
- * wave. Charging is instantaneous here (ideal diodes, no series resistance), so the trace is in
- * its steady state from the first peak onward, which is why the ripple and the mean are measured
- * over the LAST whole cycle. Nothing random and nothing clock-based: same input, same trace.
- */
-declare function acRectifiedTrace({
-  supply,
-  capacitanceF,
-  rectifier,
-  cycles,
-  samplesPerCycle
-}: RectifiedInput): RectifiedTrace;
-//#endregion
-export { AcState, AcSupply, RectifiedInput, RectifiedPoint, RectifiedTrace, RectifierMode, WavePoint, acCurrentAt, acPeriodS, acRectifiedTrace, acState, acVoltageAt, acWaveTrace, integrateSquareOverPeriod, meanAcPowerW, meanRectifiedVoltage, meanSquareByIntegration, meanSquareFromPeak, rectify, rippleFrequencyHz, rmsFromPeak };