@cfasim-ui/shared 0.9.3 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/shared",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "type": "module",
   "description": "Shared utilities for cfasim-ui",
   "license": "Apache-2.0",

package/src/ModelOutput.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { ModelOutput } from "./ModelOutput.js";
+import { ModelOutput, DATE_MISSING, isoDate } from "./ModelOutput.js";
 import type {
   ModelOutputWire,
   ModelOutputsWire,
@@ -207,3 +207,20 @@ describe("transfer protocol with ModelOutputs", () => {
     expect(unwrapResponse(response)).toBe("hello");
   });
 });
+
+describe("date columns", () => {
+  it("decodes days since the epoch to ISO strings and CSV", () => {
+    const output = new ModelOutput(
+      3,
+      [{ name: "when", type: "date" }],
+      [new Uint32Array([0, 20458, DATE_MISSING])],
+    );
+    expect(output.dates("when")).toEqual(["1970-01-01", "2026-01-05", null]);
+    expect(isoDate(20465)).toBe("2026-01-12");
+    expect(isoDate(0)).toBe("1970-01-01");
+    expect(isoDate(2_932_897)).toBe("10000-01-01");
+    expect(isoDate(4_000_000_000)).toBeNull();
+    expect(modelOutputToCSV(output)).toBe("when\n1970-01-01\n2026-01-05\n");
+    expect(() => output.dates("nope")).toThrow();
+  });
+});

package/src/ModelOutput.ts

@@ -1,4 +1,8 @@
-export type ColumnType = "i32" | "u32" | "f64" | "bool" | "enum";
+export type ColumnType = "i32" | "u32" | "f64" | "bool" | "enum" | "date";
+
+/** Value of a `date` column with no date (`DATE_MISSING` on the Python side). */
+export const DATE_MISSING = 0xffffffff;
+const DAY_MS = 86_400_000;
 
 export interface ColumnDescriptor {
   name: string;
@@ -20,17 +24,27 @@ export interface ModelOutputsWire {
   outputs: Record<string, ModelOutputWire>;
 }
 
-const COLUMN_TYPE_TO_CTOR: Record<
+export const COLUMN_TYPE_TO_CTOR: Record<
   ColumnType,
-  new (buffer: ArrayBuffer) => TypedColumn
+  { new (buffer: ArrayBuffer): TypedColumn; BYTES_PER_ELEMENT: number }
 > = {
   f64: Float64Array,
   i32: Int32Array,
   u32: Uint32Array,
   bool: Uint8Array,
   enum: Uint32Array,
+  date: Uint32Array,
 };
 
+/** ISO `yyyy-mm-dd` for a `date` column value (days since 1970-01-01). */
+export function isoDate(days: number): string | null {
+  const date = new Date(days * DAY_MS);
+  if (days === DATE_MISSING || Number.isNaN(date.getTime())) return null;
+  // Not toISOString, which writes years past 9999 as "+010000".
+  const pad = (n: number, width = 2) => String(n).padStart(width, "0");
+  return `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+}
+
 export class ModelOutput {
   readonly length: number;
   readonly columns: readonly ColumnDescriptor[];
@@ -66,6 +80,14 @@ export class ModelOutput {
     return desc.enumLabels[index];
   }
 
+  /** A `date` column as ISO strings (`null` where the date is missing). */
+  dates(columnName: string): (string | null)[] {
+    if (this.descriptor(columnName).type !== "date") {
+      throw new Error(`Column ${columnName} is not a date`);
+    }
+    return Array.from(this.column(columnName), isoDate);
+  }
+
   get names(): string[] {
     return this.columns.map((c) => c.name);
   }

package/src/csv.ts

@@ -1,4 +1,5 @@
 import type { ModelOutput } from "./ModelOutput.js";
+import { isoDate } from "./ModelOutput.js";
 
 export function modelOutputToCSV(output: ModelOutput): string {
   const header = output.names.join(",");
@@ -10,6 +11,8 @@ export function modelOutputToCSV(output: ModelOutput): string {
       const val = output.buffers[c][r];
       if (desc.type === "enum") {
         cells.push(desc.enumLabels![val as number]);
+      } else if (desc.type === "date") {
+        cells.push(isoDate(val as number) ?? "");
       } else if (desc.type === "bool") {
         cells.push(val ? "true" : "false");
       } else {

package/src/decodeModelOutputs.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { decodeModelOutputs } from "./decodeModelOutputs.js";
+
+// Shared protocol fixtures, written by the Python reference implementation.
+// (__dirname rather than import.meta.url: happy-dom gives the latter an http scheme.)
+const FIXTURES = resolve(__dirname, "../../../cfasim-model-py/tests/fixtures");
+
+function fixtureBuffer(name: string): ArrayBuffer {
+  const bytes = readFileSync(resolve(FIXTURES, name));
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+}
+
+const expected = JSON.parse(
+  readFileSync(resolve(FIXTURES, "sample.columns.json"), "utf8"),
+) as Record<string, Record<string, number[]>>;
+
+describe("decodeModelOutputs", () => {
+  it("decodes the shared fixture into ModelOutput tables", () => {
+    const outputs = decodeModelOutputs(fixtureBuffer("sample.cfasim"));
+    expect(Object.keys(outputs).sort()).toEqual(["empty", "series"]);
+    for (const [table, columns] of Object.entries(expected)) {
+      for (const [name, values] of Object.entries(columns)) {
+        expect(Array.from(outputs[table].column(name))).toEqual(values);
+      }
+    }
+    expect(outputs.series.column("time")).toBeInstanceOf(Float64Array);
+    expect(outputs.series.column("delta")).toBeInstanceOf(Int32Array);
+    expect(outputs.series.column("count")).toBeInstanceOf(Uint32Array);
+    expect(outputs.series.column("flag")).toBeInstanceOf(Uint8Array);
+    const status = outputs.series.column("status");
+    expect(outputs.series.label("status", status[1])).toBe("R");
+    expect(outputs.empty.length).toBe(0);
+  });
+
+  it("matches the committed header", () => {
+    const buf = fixtureBuffer("sample.cfasim");
+    const headerLength = new DataView(buf).getUint32(0, true);
+    const header = JSON.parse(
+      new TextDecoder().decode(new Uint8Array(buf, 4, headerLength)),
+    );
+    const dataStart = 4 + headerLength;
+    const committed = JSON.parse(
+      readFileSync(resolve(FIXTURES, "sample.header.json"), "utf8"),
+    );
+    expect(header).toEqual(committed);
+    expect(dataStart % 8).toBe(0);
+  });
+
+  it("rejects truncated and malformed files", () => {
+    const buf = fixtureBuffer("sample.cfasim");
+    expect(() => decodeModelOutputs(buf.slice(0, buf.byteLength - 4))).toThrow(
+      /truncated/,
+    );
+    expect(() => decodeModelOutputs(buf.slice(0, 2))).toThrow(/truncated/);
+    const bad = new Uint8Array(buf.slice(0));
+    const text = new TextDecoder().decode(bad.subarray(4, 24));
+    const idx = 4 + text.indexOf('"version":1') + '"version":'.length;
+    bad[idx] = "2".charCodeAt(0);
+    expect(() => decodeModelOutputs(bad.buffer as ArrayBuffer)).toThrow(
+      /version/,
+    );
+  });
+});

package/src/decodeModelOutputs.ts

@@ -0,0 +1,80 @@
+import type { ColumnDescriptor } from "./ModelOutput.js";
+import { COLUMN_TYPE_TO_CTOR, ModelOutput } from "./ModelOutput.js";
+
+/**
+ * Header of a `.cfasim` outputs file. The file is a little-endian u32 header
+ * length, a UTF-8 JSON header (space-padded to an 8-byte boundary), then the
+ * raw column buffers; `byteOffsets` are relative to the start of the buffers.
+ */
+export interface ModelOutputsFileTable {
+  length: number;
+  columns: ColumnDescriptor[];
+  byteOffsets: number[];
+  /** Unpadded byte length per column. */
+  byteLengths: number[];
+}
+
+export interface ModelOutputsFileHeader {
+  version: number;
+  outputs: Record<string, ModelOutputsFileTable>;
+}
+
+function readModelOutputsHeader(buffer: ArrayBuffer): {
+  header: ModelOutputsFileHeader;
+  dataStart: number;
+} {
+  if (buffer.byteLength < 4) {
+    throw new Error("outputs file is truncated (no header length)");
+  }
+  const headerLength = new DataView(buffer).getUint32(0, true);
+  const dataStart = 4 + headerLength;
+  if (dataStart > buffer.byteLength) {
+    throw new Error("outputs file is truncated (header)");
+  }
+  const text = new TextDecoder().decode(
+    new Uint8Array(buffer, 4, headerLength),
+  );
+  const header = JSON.parse(text) as ModelOutputsFileHeader;
+  if (header.version !== 1) {
+    throw new Error(`unsupported outputs file version ${header.version}`);
+  }
+  return { header, dataStart };
+}
+
+/**
+ * Decode a `.cfasim` outputs file (as served by `GET /api/runs/{id}/outputs`
+ * or read from disk) into named `ModelOutput` tables. Column buffers are
+ * copied out of `buffer`, so the file bytes can be released afterwards.
+ */
+export function decodeModelOutputs(
+  buffer: ArrayBuffer,
+): Record<string, ModelOutput> {
+  const { header, dataStart } = readModelOutputsHeader(buffer);
+  const result: Record<string, ModelOutput> = {};
+  for (const [name, table] of Object.entries(header.outputs)) {
+    const buffers = table.columns.map((col, i) => {
+      const bpe = COLUMN_TYPE_TO_CTOR[col.type]?.BYTES_PER_ELEMENT;
+      if (bpe === undefined) {
+        throw new Error(`column ${col.name} has unknown type ${col.type}`);
+      }
+      const start = dataStart + table.byteOffsets[i];
+      const bytes = table.byteLengths[i];
+      if (bytes !== table.length * bpe) {
+        throw new Error(
+          `column ${col.name} has ${bytes} bytes for ${table.length} rows`,
+        );
+      }
+      if (start + bytes > buffer.byteLength) {
+        throw new Error(`outputs file is truncated (column ${col.name})`);
+      }
+      return buffer.slice(start, start + bytes);
+    });
+    result[name] = ModelOutput.fromWire({
+      __modelOutput: true,
+      length: table.length,
+      columns: table.columns,
+      buffers,
+    });
+  }
+  return result;
+}

package/src/index.ts

@@ -5,7 +5,7 @@ export {
   unwrapResponse,
 } from "./transferUtils.js";
 export type { TransferableResponse } from "./transferUtils.js";
-export { ModelOutput } from "./ModelOutput.js";
+export { ModelOutput, isoDate, DATE_MISSING } from "./ModelOutput.js";
 export type {
   ColumnDescriptor,
   ColumnType,
@@ -14,6 +14,11 @@ export type {
   ModelOutputsWire,
 } from "./ModelOutput.js";
 export { modelOutputToCSV } from "./csv.js";
+export { decodeModelOutputs } from "./decodeModelOutputs.js";
+export type {
+  ModelOutputsFileHeader,
+  ModelOutputsFileTable,
+} from "./decodeModelOutputs.js";
 export { describeWorkerError, MESSAGEERROR_TEXT } from "./workerError.js";
 export { formatNumber, isNumberFormat } from "./formatNumber.js";
 export type { NumberFormat, NumberFormatPreset } from "./formatNumber.js";