@e04/ft8ts 0.0.2 → 0.0.3

package/src/ft8/decode.ts

@@ -13,6 +13,7 @@ import {
 } from "../util/constants.js";
 import { decode174_91 } from "../util/decode174_91.js";
 import { fftComplex, nextPow2 } from "../util/fft.js";
+import type { HashCallBook } from "../util/hashcall.js";
 import { unpack77 } from "../util/unpack_jt77.js";
 
 export interface DecodedMessage {
@@ -34,6 +35,14 @@ export interface DecodeOptions {
 	depth?: number;
 	/** Maximum candidates to process */
 	maxCandidates?: number;
+	/**
+	 * Hash call book for resolving hashed callsigns.
+	 * When provided, decoded standard callsigns are saved into the book,
+	 * and hashed callsigns (e.g. `<...>`) are resolved from it.
+	 * Pass the same instance across multiple `decode` calls to accumulate
+	 * callsign knowledge over time.
+	 */
+	hashCallBook?: HashCallBook;
 }
 
 /**
@@ -50,6 +59,7 @@ export function decode(
 	const syncmin = options.syncMin ?? 1.2;
 	const depth = options.depth ?? 2;
 	const maxCandidates = options.maxCandidates ?? 300;
+	const book = options.hashCallBook;
 
 	// Resample to 12000 Hz if needed
 	let dd: Float64Array;
@@ -77,7 +87,7 @@ export function decode(
 	const seenMessages = new Set<string>();
 
 	for (const cand of candidates) {
-		const result = ft8b(dd, cxRe, cxIm, cand.freq, cand.dt, sbase, depth);
+		const result = ft8b(dd, cxRe, cxIm, cand.freq, cand.dt, sbase, depth, book);
 		if (!result) continue;
 
 		if (seenMessages.has(result.msg)) continue;
@@ -312,17 +322,18 @@ interface Ft8bResult {
 }
 
 function ft8b(
-	dd0: Float64Array,
+	_dd0: Float64Array,
 	cxRe: Float64Array,
 	cxIm: Float64Array,
 	f1: number,
 	xdt: number,
 	_sbase: Float64Array,
 	depth: number,
+	book: HashCallBook | undefined,
 ): Ft8bResult | null {
 	const NFFT2 = 3200;
 	const NP2 = 2812;
-	const NFFT1_LONG = 192000;
+	const _NFFT1_LONG = 192000;
 	const fs2 = SAMPLE_RATE / NDOWN;
 	const dt2 = 1.0 / fs2;
 	const twopi = 2 * Math.PI;
@@ -541,7 +552,7 @@ function ft8b(
 	if (i3v === 0 && n3v === 2) return null;
 
 	// Unpack
-	const { msg, success } = unpack77(message77);
+	const { msg, success } = unpack77(message77, book);
 	if (!success || msg.trim().length === 0) return null;
 
 	// Estimate SNR

package/src/index.ts

@@ -1,2 +1,3 @@
 export { type DecodedMessage, type DecodeOptions, decode as decodeFT8 } from "./ft8/decode.js";
 export { encode as encodeFT8 } from "./ft8/encode.js";
+export { HashCallBook } from "./util/hashcall.js";

package/src/util/hashcall.ts

@@ -0,0 +1,110 @@
+/**
+ * Hash call table – TypeScript port of the hash call storage from packjt77.f90
+ *
+ * In FT8, nonstandard callsigns are transmitted as hashes (10-, 12-, or 22-bit).
+ * When a full callsign is decoded from a standard message, it is stored in this
+ * table so that future hashed references to it can be resolved.
+ *
+ * Mirrors Fortran: save_hash_call, hash10, hash12, hash22, ihashcall
+ */
+
+import { C38 } from "./constants.js";
+
+const MAGIC = 47055833459n;
+const MAX_HASH22_ENTRIES = 1000;
+
+function ihashcall(c0: string, m: number): number {
+	const s = c0.padEnd(11, " ").slice(0, 11).toUpperCase();
+	let n8 = 0n;
+	for (let i = 0; i < 11; i++) {
+		const j = C38.indexOf(s[i] ?? " ");
+		n8 = 38n * n8 + BigInt(j < 0 ? 0 : j);
+	}
+	const prod = BigInt.asUintN(64, MAGIC * n8);
+	return Number(prod >> BigInt(64 - m)) & ((1 << m) - 1);
+}
+
+/**
+ * Maintains a callsign ↔ hash lookup table for resolving hashed FT8 callsigns.
+ *
+ * Usage:
+ * ```ts
+ * const book = new HashCallBook();
+ * const decoded = decodeFT8(samples, sampleRate, { hashCallBook: book });
+ * // `book` now contains callsigns learned from decoded messages.
+ * // Subsequent calls reuse the same book to resolve hashed callsigns:
+ * const decoded2 = decodeFT8(samples2, sampleRate, { hashCallBook: book });
+ * ```
+ *
+ * You can also pre-populate the book with known callsigns:
+ * ```ts
+ * book.save("W9XYZ");
+ * book.save("PJ4/K1ABC");
+ * ```
+ */
+export class HashCallBook {
+	private readonly calls10 = new Map<number, string>();
+	private readonly calls12 = new Map<number, string>();
+	private readonly hash22Entries: { hash: number; call: string }[] = [];
+
+	/**
+	 * Store a callsign in all three hash tables (10, 12, 22-bit).
+	 * Strips angle brackets if present. Ignores `<...>` and blank/short strings.
+	 */
+	save(callsign: string): void {
+		let cw = callsign.trim().toUpperCase();
+		if (cw === "" || cw === "<...>") return;
+		if (cw.startsWith("<")) cw = cw.slice(1);
+		const gt = cw.indexOf(">");
+		if (gt >= 0) cw = cw.slice(0, gt);
+		cw = cw.trim();
+		if (cw.length < 3) return;
+
+		const n10 = ihashcall(cw, 10);
+		if (n10 >= 0 && n10 <= 1023) this.calls10.set(n10, cw);
+
+		const n12 = ihashcall(cw, 12);
+		if (n12 >= 0 && n12 <= 4095) this.calls12.set(n12, cw);
+
+		const n22 = ihashcall(cw, 22);
+		const existing = this.hash22Entries.findIndex((e) => e.hash === n22);
+		if (existing >= 0) {
+			this.hash22Entries[existing]!.call = cw;
+		} else {
+			if (this.hash22Entries.length >= MAX_HASH22_ENTRIES) {
+				this.hash22Entries.pop();
+			}
+			this.hash22Entries.unshift({ hash: n22, call: cw });
+		}
+	}
+
+	/** Look up a callsign by its 10-bit hash. Returns `null` if not found. */
+	lookup10(n10: number): string | null {
+		if (n10 < 0 || n10 > 1023) return null;
+		return this.calls10.get(n10) ?? null;
+	}
+
+	/** Look up a callsign by its 12-bit hash. Returns `null` if not found. */
+	lookup12(n12: number): string | null {
+		if (n12 < 0 || n12 > 4095) return null;
+		return this.calls12.get(n12) ?? null;
+	}
+
+	/** Look up a callsign by its 22-bit hash. Returns `null` if not found. */
+	lookup22(n22: number): string | null {
+		const entry = this.hash22Entries.find((e) => e.hash === n22);
+		return entry?.call ?? null;
+	}
+
+	/** Number of entries in the 22-bit hash table. */
+	get size(): number {
+		return this.hash22Entries.length;
+	}
+
+	/** Remove all stored entries. */
+	clear(): void {
+		this.calls10.clear();
+		this.calls12.clear();
+		this.hash22Entries.length = 0;
+	}
+}

package/src/util/unpack_jt77.ts

@@ -9,6 +9,7 @@
  */
 
 import { A1, A2, A3, A4, C38, FTALPH, MAX22, MAXGRID4, NTOKENS } from "./constants.js";
+import type { HashCallBook } from "./hashcall.js";
 
 function bitsToUint(bits: number[], start: number, len: number): number {
 	let val = 0;
@@ -18,7 +19,7 @@ function bitsToUint(bits: number[], start: number, len: number): number {
 	return val;
 }
 
-function unpack28(n28: number): { call: string; success: boolean } {
+function unpack28(n28: number, book: HashCallBook | undefined): { call: string; success: boolean } {
 	if (n28 < 0 || n28 >= 268435456) return { call: "", success: false };
 
 	if (n28 === 0) return { call: "DE", success: true };
@@ -31,7 +32,6 @@ function unpack28(n28: number): { call: string; success: boolean } {
 	}
 
 	if (n28 >= 1003 && n28 < NTOKENS) {
-		// CQ with 4-letter directed call
 		let m = n28 - 1003;
 		let chars = "";
 		for (let i = 3; i >= 0; i--) {
@@ -45,7 +45,9 @@ function unpack28(n28: number): { call: string; success: boolean } {
 	}
 
 	if (n28 >= NTOKENS && n28 < NTOKENS + MAX22) {
-		// Hashed call – we don't have a hash table, so show <...>
+		const n22 = n28 - NTOKENS;
+		const resolved = book?.lookup22(n22);
+		if (resolved) return { call: `<${resolved}>`, success: true };
 		return { call: "<...>", success: true };
 	}
 
@@ -127,8 +129,11 @@ function unpackText77(bits71: number[]): string {
 
 /**
  * Unpack a 77-bit FT8 message into a human-readable string.
+ *
+ * When a {@link HashCallBook} is provided, hashed callsigns are resolved from
+ * the book, and newly decoded standard callsigns are saved into it.
  */
-export function unpack77(bits77: number[]): { msg: string; success: boolean } {
+export function unpack77(bits77: number[], book?: HashCallBook): { msg: string; success: boolean } {
 	const n3 = bitsToUint(bits77, 71, 3);
 	const i3 = bitsToUint(bits77, 74, 3);
 
@@ -148,8 +153,8 @@ export function unpack77(bits77: number[]): { msg: string; success: boolean } {
 		const ir = bits77[58]!;
 		const igrid4 = bitsToUint(bits77, 59, 15);
 
-		const { call: call1, success: ok1 } = unpack28(n28a);
-		const { call: call2Raw, success: ok2 } = unpack28(n28b);
+		const { call: call1, success: ok1 } = unpack28(n28a, book);
+		const { call: call2Raw, success: ok2 } = unpack28(n28b, book);
 		if (!ok1 || !ok2) return { msg: "", success: false };
 
 		let c1 = call1;
@@ -164,6 +169,8 @@ export function unpack77(bits77: number[]): { msg: string; success: boolean } {
 		if (c2.indexOf("<") < 0) {
 			if (ipb === 1 && i3 === 1 && c2.length >= 3) c2 += "/R";
 			if (ipb === 1 && i3 === 2 && c2.length >= 3) c2 += "/P";
+			// Save the "from" call (call_2) into the hash book
+			if (book && c2.length >= 3) book.save(c2);
 		}
 
 		if (igrid4 <= MAXGRID4) {
@@ -191,6 +198,7 @@ export function unpack77(bits77: number[]): { msg: string; success: boolean } {
 
 	if (i3 === 4) {
 		// Type 4: One nonstandard call
+		const n12 = bitsToUint(bits77, 0, 12);
 		let n58 = 0n;
 		for (let i = 0; i < 58; i++) {
 			n58 = n58 * 2n + BigInt(bits77[12 + i] ?? 0);
@@ -199,7 +207,6 @@ export function unpack77(bits77: number[]): { msg: string; success: boolean } {
 		const nrpt = bitsToUint(bits77, 71, 2);
 		const icq = bits77[73]!;
 
-		// Decode n58 to 11-char string using C38 alphabet
 		const c11chars: string[] = [];
 		let remain = n58;
 		for (let i = 10; i >= 0; i--) {
@@ -209,13 +216,15 @@ export function unpack77(bits77: number[]): { msg: string; success: boolean } {
 		}
 		const c11 = c11chars.join("").trim();
 
-		const call3 = "<...>"; // We don't have a hash table for n12
+		const resolved = book?.lookup12(n12);
+		const call3 = resolved ? `<${resolved}>` : "<...>";
 
 		let call1: string;
 		let call2: string;
 		if (iflip === 0) {
 			call1 = call3;
 			call2 = c11;
+			if (book) book.save(c11);
 		} else {
 			call1 = c11;
 			call2 = call3;