@packet-net/pdn-aprs 0.1.1 → 0.3.0

package/src/deviceid.ts

@@ -3,7 +3,7 @@
 // its type code and suffix.
 
 import { MICE, MICE_LEGACY, TOCALLS, type DeviceEntry } from './deviceid-data.js';
-import type { DeviceInfo } from './types.js';
+import type { AprsData, DeviceInfo } from './types.js';
 
 export { DEVICEID_SOURCE, DEVICE_CLASSES } from './deviceid-data.js';
 
@@ -47,11 +47,30 @@ function compile(): CompiledTocall[] {
   return compiled;
 }
 
-/** The device a destination address (tocall) identifies, e.g. `APDW18` is Dire Wolf. */
+// Destinations repeat constantly (a handful of tocalls cover most traffic), and matching one means
+// trying up to every pattern in the database, so answers are remembered. The cache is bounded so a
+// stream of junk destinations cannot grow it without limit.
+const tocallCache = new Map<string, DeviceInfo | undefined>();
+const TOCALL_CACHE_LIMIT = 4096;
+
+/**
+ * The device a destination address (tocall) identifies, e.g. `APDW18` is Dire Wolf. The lookup is
+ * case-sensitive: the database lists tocalls in upper case and a destination is a callsign, so
+ * `APNl02` matches nothing (vectors rulings, A1).
+ */
 export function identifyTocall(destination: string): DeviceInfo | undefined {
-  const call = destination.split('-')[0]!.toUpperCase();
-  for (const t of compile()) if (t.regex.test(call)) return toInfo(t.entry);
-  return undefined;
+  const call = destination.split('-')[0]!;
+  if (tocallCache.has(call)) return tocallCache.get(call);
+  let found: DeviceInfo | undefined;
+  for (const t of compile()) {
+    if (t.regex.test(call)) {
+      found = Object.freeze(toInfo(t.entry));
+      break;
+    }
+  }
+  if (tocallCache.size >= TOCALL_CACHE_LIMIT) tocallCache.clear();
+  tocallCache.set(call, found);
+  return found;
 }
 
 /**
@@ -81,3 +100,8 @@ export function identifyMicE(typeCode: string | undefined, suffix: string | unde
   }
   return undefined;
 }
+
+/** The device a packet identifies: by its Mic-E type code and suffix, else by its destination. */
+export function identifyDevice(data: AprsData, destination: string): DeviceInfo | undefined {
+  return data.type === 'mic-e' ? identifyMicE(data.typeCode, data.deviceSuffix) : identifyTocall(destination);
+}

package/src/encode/common.ts

@@ -19,10 +19,26 @@ export function pad(n: number, width: number): string {
   return String(n).padStart(width, '0');
 }
 
-/** A whole number within [min, max], else refused. */
+/**
+ * The nearest whole number, halves away from zero, as the vectors' rules round wherever they say
+ * "nearest" (`Math.round` takes a half towards +infinity, so -2.5 to -2). A value within 1e-6 of a
+ * half is the half: decimal text such as 58.585 is seldom exactly that in binary, and the half the
+ * text means wins (vectors rulings, F2).
+ */
+export function nearest(value: number): number {
+  const abs = Math.abs(value);
+  const below = Math.floor(abs);
+  const n = abs - below >= 0.5 - HALF_TOLERANCE ? below + 1 : below;
+  return value < 0 ? -n : n;
+}
+
+/** How near a half, in steps, a value is taken for the half. */
+const HALF_TOLERANCE = 1e-6;
+
+/** A whole number within [min, max], else refused; a fraction is rounded to the nearest. */
 export function whole(value: number, min: number, max: number, what: string): number {
   if (!Number.isFinite(value)) refuse(`${what} is not a number`);
-  const n = Math.round(value);
+  const n = nearest(value);
   if (n < min || n > max) refuse(`${what} ${value} is out of range (${min}-${max})`);
   return n;
 }
@@ -80,8 +96,22 @@ export function base91(value: number, width: number): string {
   return out;
 }
 
-/** Formats a number as short text: `0.53`, `-32`, `1e-7`. */
+/**
+ * A number as plain decimal text: the shortest that reads back as the same number, with no
+ * exponent and no `+`, a `0` before a leading point and no trailing `.0` (`0.53`, `-94`, 1e61 as
+ * `1` and 61 zeros, 1e-7 as `0.0000001`; vectors rulings, F11).
+ */
 export function numberText(v: number): string {
   if (!Number.isFinite(v)) refuse('a value is not a number');
-  return String(v);
+  if (Object.is(v, -0)) return '0';
+  const shortest = String(v);
+  const m = /^(-?)([0-9])(?:\.([0-9]+))?e([+-][0-9]+)$/.exec(shortest);
+  if (!m) return shortest;
+  const sign = m[1]!;
+  const digits = m[2]! + (m[3] ?? '');
+  // The point sits after the first digit; the exponent moves it.
+  const point = 1 + Number(m[4]);
+  if (point <= 0) return `${sign}0.${'0'.repeat(-point)}${digits}`;
+  if (point >= digits.length) return sign + digits + '0'.repeat(point - digits.length);
+  return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
 }

package/src/encode/index.ts

@@ -1,7 +1,7 @@
 // The encoder: writes only what the spec allows and refuses anything else with a reason. Free
 // text is checked by decoding what was written: if the result does not read back as the same
-// data (a comment that would read as an altitude, say), a `/` delimiter is tried, and if that
-// does not help either the encoder refuses.
+// data (a comment that would read as an altitude, say), the comment is tried straight after a
+// frequency, then after a `/` delimiter, and if neither helps the encoder refuses.
 
 import { binaryToBytes, bytesToBinary, decodeUtf8 } from '../bytes.js';
 import { decodeInformation } from '../decode/index.js';
@@ -30,7 +30,7 @@ import {
   encodeThirdParty,
   encodeUserDefined,
 } from './other.js';
-import { encodeItem, encodeMicE, encodeObject, encodePositionReport, encodeWeatherReport, type CommentMode } from './position.js';
+import { DEFAULT_COMPRESSION, encodeItem, encodeMicE, encodeObject, encodePositionReport, encodeWeatherReport, type CommentMode } from './position.js';
 
 export { AprsEncodeError } from './common.js';
 
@@ -99,9 +99,12 @@ function attempt(data: AprsData, mode: CommentMode): Attempt {
       return { binary: encodeCapabilities(data) };
     case 'third-party': {
       // The original information field must not be changed (APRS12c ch. 17).
+      // An inner packet built by hand, with no information field, is encoded from its data.
       const original = data.packet.information;
-      const inner = original.length > 0 ? original : encodeInformation(data.packet.data).info;
-      return { binary: encodeThirdParty(data, bytesToBinary(inner)) };
+      const inner = data.packet.data;
+      const asReceived = original.length > 0 || (inner.type === 'unrecognized' && inner.reason === 'empty');
+      const info = asReceived ? original : encodeInformation(inner).info;
+      return { binary: encodeThirdParty(data, bytesToBinary(info)) };
     }
     case 'user-defined':
       return { binary: encodeUserDefined(data) };
@@ -114,12 +117,25 @@ function attempt(data: AprsData, mode: CommentMode): Attempt {
   }
 }
 
-/** Where the written data would read back differently: strings, booleans and which fields are present. */
-function shapeDifferences(a: unknown, b: unknown, path: string, out: string[]): void {
-  if (typeof a === 'number' && typeof b === 'number') return;
+/** Numbers that agree within 1e-9, relative to the larger (absolute below 1). */
+function sameNumber(a: number, b: number): boolean {
+  const scale = Math.max(Math.abs(a), Math.abs(b));
+  return Math.abs(a - b) <= 1e-9 * (scale >= 1 ? scale : 1);
+}
+
+/**
+ * Where the written data would read back differently: strings, booleans and which fields are
+ * present, and with `numbers` the numbers too. Numbers are left out otherwise, because a value
+ * given with more precision than the format carries is written to the format's precision.
+ */
+function shapeDifferences(a: unknown, b: unknown, path: string, out: string[], numbers: boolean): void {
+  if (typeof a === 'number' && typeof b === 'number') {
+    if (numbers && !sameNumber(a, b)) out.push(`${path.replace(/\.$/, '')} would read back as ${a}`);
+    return;
+  }
   if (Array.isArray(a) && Array.isArray(b)) {
     if (a.length !== b.length) out.push(`${path.replace(/\.$/, '')} would have ${a.length} items, not ${b.length}`);
-    else a.forEach((x, i) => shapeDifferences(x, b[i], `${path}${i}.`, out));
+    else a.forEach((x, i) => shapeDifferences(x, b[i], `${path}${i}.`, out, numbers));
     return;
   }
   if (a !== null && b !== null && typeof a === 'object' && typeof b === 'object') {
@@ -128,7 +144,7 @@ function shapeDifferences(a: unknown, b: unknown, path: string, out: string[]):
     for (const k of new Set([...Object.keys(ao), ...Object.keys(bo)])) {
       if (!(k in ao)) out.push(`${path}${k} would be lost`);
       else if (!(k in bo)) out.push(`${path}${k} would appear`);
-      else shapeDifferences(ao[k], bo[k], `${path}${k}.`, out);
+      else shapeDifferences(ao[k], bo[k], `${path}${k}.`, out, numbers);
     }
     return;
   }
@@ -140,14 +156,19 @@ function expected(data: AprsData, a: Attempt): AprsData {
   let d = data;
   if ((d.type === 'position' || d.type === 'object' || d.type === 'item') && d.compressed && a.compression) {
     if (!d.compression) d = { ...d, compression: a.compression };
-    if (d.courseDegrees !== undefined && d.speedKnots === undefined) d = { ...d, speedKnots: 0 };
   }
-  if (d.type === 'mic-e') {
-    if (d.speedKnots === undefined) d = { ...d, speedKnots: 0 };
-    if (d.courseDegrees === 0) {
-      const copy: Record<string, unknown> = { ...d };
-      delete copy.courseDegrees;
-      d = copy as unknown as AprsData;
+  if (d.type === 'mic-e' && d.speedKnots === undefined) d = { ...d, speedKnots: 0 };
+  if (d.type === 'third-party' && d.packet.information.length === 0) {
+    // An inner packet written from its data: cs values with no compression type got the default.
+    const inner = d.packet.data;
+    if ((inner.type === 'position' || inner.type === 'object' || inner.type === 'item') && inner.compressed && !inner.compression) {
+      const w = inner.weather;
+      const carries =
+        inner.courseDegrees !== undefined ||
+        inner.speedKnots !== undefined ||
+        inner.rangeMiles !== undefined ||
+        (w !== undefined && (w.windDirectionDegrees !== undefined || w.windSpeedMph !== undefined));
+      if (carries) d = { ...d, packet: { ...d.packet, data: { ...inner, compression: DEFAULT_COMPRESSION } } };
     }
   }
   return d;
@@ -162,10 +183,25 @@ function check(data: AprsData, a: Attempt): string[] {
     problems.push(`it would read back as ${decoded.data.type}`);
     return problems;
   }
-  shapeDifferences(toNeutralData(decoded.data), toNeutralData(expected(data, a)), '', problems);
+  // An NMEA sentence is written as it is, so everything read from it must be what the data says.
+  shapeDifferences(withoutInnerInfo(toNeutralData(decoded.data)), withoutInnerInfo(toNeutralData(expected(data, a))), '', problems, data.type === 'nmea');
   return problems;
 }
 
+/**
+ * A third-party packet's neutral data without its inner packet's `info` diagnostics: an info is
+ * not a defect, so an inner packet that reads back with only those is written (vectors rulings, F10).
+ */
+function withoutInnerInfo(n: Record<string, unknown>): Record<string, unknown> {
+  const packet = n.packet as Record<string, unknown> | undefined;
+  if (n.type !== 'third-party' || !packet || !Array.isArray(packet.diagnostics)) return n;
+  const kept = (packet.diagnostics as string[]).filter((d) => !d.startsWith('info:'));
+  const copy: Record<string, unknown> = { ...packet };
+  if (kept.length > 0) copy.diagnostics = kept;
+  else delete copy.diagnostics;
+  return { ...n, packet: copy };
+}
+
 /**
  * Encodes data as an information field. Mic-E also gives the destination address it computed.
  * Throws `AprsEncodeError`, with the reason, for anything the spec does not allow.
@@ -175,8 +211,9 @@ export function encodeInformation(data: AprsData): EncodedInformation {
   let problems = check(data, first);
   let chosen = first;
   if (problems.length > 0 && typeof (data as { comment?: unknown }).comment === 'string') {
-    // The comment would read as something else: try it straight after a frequency, then after a /.
-    for (const mode of ['joined', 'delimited'] as const) {
+    // The comment would read as something else: try it straight after a frequency, then after a
+    // /, then after a space.
+    for (const mode of ['joined', 'delimited', 'spaced'] as const) {
       let next: Attempt | undefined;
       try {
         next = attempt(data, mode);

package/src/encode/other.ts

@@ -2,8 +2,9 @@
 // telemetry, queries, capabilities, and the rest.
 
 import { encodeUtf8Binary } from '../bytes.js';
-import { nmeaChecksumOk } from '../decode/other.js';
-import { formatPath } from '../header.js';
+import { DIRECTED_QUERY_TYPES } from '../decode/message.js';
+import { splitNmea } from '../decode/other.js';
+import { formatPath, isAprsIsAddress } from '../header.js';
 import type {
   Ack,
   AgreloDf,
@@ -124,7 +125,10 @@ export function encodeDirectedQuery(d: DirectedQuery): string {
   let out = `:${addressee(d.addressee)}:?${d.queryType}`;
   if (d.target !== undefined) {
     if (!/^[A-Za-z0-9-]{1,9}$/.test(d.target)) refuse('a query target is one callsign');
-    out += d.target;
+    // A type the spec defines is followed straight by the target, an APRSH target padded to 9
+    // characters; any other type has no fixed length, so its target follows one space.
+    if (!DIRECTED_QUERY_TYPES.includes(d.queryType)) out += ` ${d.target}`;
+    else out += d.queryType === 'APRSH' ? d.target.padEnd(9, ' ') : d.target;
   }
   return out;
 }
@@ -150,7 +154,7 @@ export function encodeStatus(d: StatusReport): string {
   }
   out += freeText(text, 'status text');
   if (d.beam) {
-    if (!/^[0-9A-Z]$/.test(d.beam.headingCode) || !/^[0-9:;<=>?@A-K]$/.test(d.beam.powerCode))
+    if (!/^[0-9A-Z]$/.test(d.beam.headingCode) || !/^[1-9:;<=>?@A-K]$/.test(d.beam.powerCode))
       refuse('beam heading is 0-9 or A-Z, and power 1-9 or :-K');
     out += `^${d.beam.headingCode}${d.beam.powerCode}`;
   }
@@ -186,10 +190,12 @@ export function encodeRawWeather(d: RawWeather): string {
 }
 
 export function encodeNmea(d: NmeaSentence): string {
-  if (!/^[A-Z]{5},[\x20-\x7e]*$/.test(d.sentence)) refuse('not an NMEA sentence');
-  const checksum = nmeaChecksumOk(d.sentence);
-  if (checksum === false) refuse("the NMEA sentence's checksum does not match");
-  return `$${d.sentence}`;
+  const parts = splitNmea(d.sentence);
+  if (!parts || parts.rest.length > 0) refuse('not an NMEA 0183 sentence');
+  if (!parts.checksumOk) refuse("the NMEA sentence's checksum does not match");
+  const comment = d.comment ?? '';
+  if (comment.length > 0 && !parts.hasChecksum) refuse('a comment after an NMEA sentence needs the checksum that ends the sentence');
+  return `$${d.sentence}${freeText(comment, 'the comment')}`;
 }
 
 export function encodeMaidenhead(d: MaidenheadBeacon): string {
@@ -203,20 +209,36 @@ export function encodeQuery(d: Query): string {
   if (d.footprint) {
     const f = d.footprint;
     if (!(f.latitude >= -90 && f.latitude <= 90) || !(f.longitude >= -180 && f.longitude <= 180)) refuse('the footprint is out of range');
-    const coord = (v: number): string => (v < 0 ? numberText(v) : ` ${numberText(v)}`);
-    out += `${coord(f.latitude)},${numberText(f.longitude)},${pad(whole(f.radiusMiles, 0, 9999, 'radius'), 4)}`;
+    // Each value as sent, a leading space or its absence included, when that is the value (vectors
+    // rulings, E1); otherwise one that is not negative, 0 included, after a space (APRS12c ch. 15;
+    // vectors rulings, F11, F15).
+    const asSent = (text: string | undefined, v: number): string | undefined =>
+      text !== undefined && FOOTPRINT_VALUE.test(text) && Number(text) === v ? text : undefined;
+    const value = (v: number): string => (v < 0 ? numberText(v) : ` ${numberText(v)}`);
+    const lat = asSent(f.latitudeText, f.latitude) ?? value(f.latitude);
+    const lon = asSent(f.longitudeText, f.longitude) ?? value(f.longitude);
+    out += `${lat},${lon},${pad(whole(f.radiusMiles, 0, 9999, 'radius'), 4)}`;
   }
   return out;
 }
 
+/** A footprint value as a decoder reads it: a number as a telemetry value is, a positive one after at most one space. */
+const FOOTPRINT_VALUE = /^(?: ?(?:[0-9]+\.?[0-9]*|\.[0-9]+)|-(?:[0-9]+\.?[0-9]*|\.[0-9]+))$/;
+
+/** A control character: below U+0020, or U+007F. */
+const CONTROL_RE = /[\x00-\x1f\x7f]/;
+
 export function encodeCapabilities(d: Capabilities): string {
   if (d.capabilities.length === 0) refuse('capabilities need at least one item');
+  // Anything that would not read back the same (vectors interpretations.md, "Station
+  // capabilities: items, tokens and values") is refused.
   const items = d.capabilities.map((c) => {
     const token = c[0];
-    if (token.length === 0 || /[\s,=]/.test(token)) refuse('a capability token has no space, comma or =');
+    if (token.length === 0 || /[ ,=]/.test(token) || CONTROL_RE.test(token)) refuse('a capability token is not empty and has no space, control character, comma or =');
     if (c.length === 1) return token;
     const value = c[1]!;
-    if (value.includes(',') || /^\s|\s$/.test(value)) refuse('a capability value has no comma or edge spaces');
+    if (value.includes(',') || CONTROL_RE.test(value) || value.startsWith(' ') || value.endsWith(' '))
+      refuse('a capability value has no comma or control character, and does not start or end with a space');
     return `${token}=${value}`;
   });
   return '<' + encodeUtf8Binary(items.join(','));
@@ -241,7 +263,11 @@ export function encodeAgrelo(d: AgreloDf): string {
 /** The third-party header and the encapsulated packet's information field. */
 export function encodeThirdParty(d: ThirdParty, innerInfo: string): string {
   const p = d.packet;
+  // The source is 1-9 printable ASCII characters other than > and : (APRS12c ch. 17); the
+  // destination and path are APRS-IS addresses.
+  if (!/^[\x20-\x39\x3b-\x3d\x3f-\x7e]{1,9}$/.test(p.source)) refuse('a third-party source is 1-9 printable ASCII characters other than > and :');
+  if (!isAprsIsAddress(p.destination)) refuse('the third-party destination is not a valid address');
+  for (const e of p.path) if (!isAprsIsAddress(e.address)) refuse(`the third-party path entry ${JSON.stringify(e.address)} is not a valid address`);
   const header = p.path.length > 0 ? `${p.source}>${p.destination},${formatPath(p.path)}` : `${p.source}>${p.destination}`;
-  if (!/^[\x21-\x7e]+$/.test(header) || header.includes(':')) refuse('the third-party header is not printable');
   return `}${header}:${innerInfo}`;
 }