🔍 Vantage: Pre-Computed Hashtable Column Indexing & Type Quality Improvements

.Jules/vantage.md

@@ -15,3 +15,5 @@
 ## 2026-05-20 - Hardening Telemetry Verification and Refining Stream Types | **Learning:** Index-based assertions in telemetry tests are brittle; using `.find()` ensures robust verification. Standardizing on `String(error)` across all API catch blocks prevents context loss during failure events. | **Action:** Refactored `chat-api.test.ts` and `github-releases.test.ts` to use search-based spy assertions, and added explicit return types to `chat-stream.ts` to resolve Astro compiler hints.
 
 ## 2026-05-24 - Comprehensive Unit Testing for Visitor Changelog Formatting | **Learning:** Single-pass Edge transformations require dedicated unit tests covering edge cases like empty inputs, internal agent filtering, and fallback formatting to prevent silent regressions in SSR release streams. | **Action:** Added `src/utils/visitor-changelog.test.ts` to test `toVisitorChangelogTitle`, `stripChangelogChrome`, `toVisitorReleaseBody`, and `toVisitorRelease`.
+
+## 2026-05-28 - Pre-Computed Hashtable Column Indexing & Type Quality Improvements | **Learning:** Building a single column index lookup map before parsing tabular API row data eliminates repeated O(N) array scans during edge execution, while explicitly testing schema functions prevents type errors in Astro 5 content collection tests. | **Action:** Refactored `parseVisitGlance` in `src/utils/visit-stats.ts` to use O(1) hashtable property lookup, updated `src/__tests__/content.config.test.ts` schema function handling, removed an unused `@ts-expect-error` in `src/utils/hire-analytics.test.ts`, and added unit tests in `src/utils/visit-stats.test.ts`.

src/__tests__/content.config.test.ts

@@ -29,7 +29,12 @@ describe('content.config', () => {
 
   it('validates flags fixture against schema', async () => {
     const { schema } = collections.flags;
-    const result = schema.safeParse(flagsFixture);
+    expect(schema).toBeDefined();
+    const rawSchema =
+      typeof schema === 'function' ? schema({ image: (() => z.any()) as never }) : schema;
+    if (!rawSchema) throw new Error('Schema is undefined');
+
+    const result = rawSchema.safeParse(flagsFixture);
     expect(result.success).toBe(true);
 
     if (result.success) {
@@ -41,6 +46,11 @@ describe('content.config', () => {
 
   it('validates work schema with sample data', () => {
     const { schema } = collections.work;
+    expect(schema).toBeDefined();
+    const rawSchema =
+      typeof schema === 'function' ? schema({ image: (() => z.any()) as never }) : schema;
+    if (!rawSchema) throw new Error('Schema is undefined');
+
     const sampleWork = {
       title: 'Sample Work',
       description: 'A sample description',
@@ -49,7 +59,7 @@ describe('content.config', () => {
       img: '/assets/sample.jpg',
       img_alt: 'Sample alt text',
     };
-    const result = schema.safeParse(sampleWork);
+    const result = rawSchema.safeParse(sampleWork);
     expect(result.success).toBe(true);
     if (result.success) {
       expect(result.data.title).toBe(sampleWork.title);

src/utils/hire-analytics.test.ts

@@ -30,8 +30,7 @@ describe('hire-analytics', () => {
   });
 
   it('does not throw when dataLayer is missing', () => {
-    // @ts-expect-error -- dataLayer is optional on Window
-    delete window.dataLayer;
+    (window as { dataLayer?: unknown }).dataLayer = undefined;
     expect(() => trackHireEvent('linkedin_click', 'contact_cta')).not.toThrow();
   });
 

src/utils/visit-stats.test.ts

@@ -102,6 +102,28 @@ describe('parseVisitGlance', () => {
     });
   });
 
+  it('reads a reordered columns array row using O(1) hashtable mapping', () => {
+    const glance = parseVisitGlance({
+      columns: [
+        null,
+        'unique_visitors',
+        'pageviews_7d',
+        'pageviews',
+        'unique_visitors_7d',
+        'first_seen',
+      ],
+      results: [['ignore', 12, 20, 94, 8, '2026-08-14T07:03:00.000Z']],
+    });
+    expect(glance).toEqual({
+      pageviews: 94,
+      uniqueVisitors: 12,
+      firstSeen: '2026-08-14T07:03:00.000Z',
+      pageviews7d: 20,
+      uniqueVisitors7d: 8,
+      ...emptyPeriods,
+    });
+  });
+
   it('parses a zero row so the API can fail-open', () => {
     expect(
       parseVisitGlance({

src/utils/visit-stats.ts

@@ -45,20 +45,26 @@ function asIsoTimestamp(raw: unknown): string | null {
   return d.toISOString();
 }
 
+/**
+ * Optimization (⚡ Bolt / Technical Standard):
+ * Pre-computes O(1) column index hashtable lookup map before reading fields,
+ * replacing repeated O(N) array scans per response field.
+ */
 function valueFromRow(
   row: unknown,
-  columns: string[] | undefined,
+  columnMap: Record<string, number> | undefined,
   key: string,
   index: number
 ): unknown {
   if (row && typeof row === 'object' && !Array.isArray(row) && key in row) {
     return (row as Record<string, unknown>)[key];
   }
-  if (Array.isArray(row) && columns) {
-    const colIndex = columns.indexOf(key);
-    if (colIndex >= 0) return row[colIndex];
+  if (Array.isArray(row)) {
+    if (columnMap && key in columnMap) {
+      return row[columnMap[key]];
+    }
+    return row[index];
   }
-  if (Array.isArray(row)) return row[index];
   return undefined;
 }
 
@@ -76,26 +82,31 @@ export function parseVisitGlance(payload: unknown): VisitGlance | null {
   if (!Array.isArray(results) || results.length === 0) return null;
 
   const columns = (payload as { columns?: unknown }).columns;
-  const columnNames = Array.isArray(columns)
-    ? columns.filter((c): c is string => typeof c === 'string')
-    : undefined;
+  let columnMap: Record<string, number> | undefined;
+  if (Array.isArray(columns)) {
+    columnMap = {};
+    for (let i = 0; i < columns.length; i++) {
+      const col = columns[i];
+      if (typeof col === 'string') {
+        columnMap[col] = i;
+      }
+    }
+  }
 
   const row = results[0];
-  const pageviews = asFiniteNumber(valueFromRow(row, columnNames, 'pageviews', 0));
-  const uniqueVisitors = asFiniteNumber(valueFromRow(row, columnNames, 'unique_visitors', 1));
-  const firstSeen = asIsoTimestamp(valueFromRow(row, columnNames, 'first_seen', 2));
-  const pageviews7d = asFiniteNumber(valueFromRow(row, columnNames, 'pageviews_7d', 3));
-  const uniqueVisitors7d = asFiniteNumber(valueFromRow(row, columnNames, 'unique_visitors_7d', 4));
-  const unique1d = asFiniteNumber(valueFromRow(row, columnNames, 'unique_visitors_1d', 5));
-  const unique1dPrev = asFiniteNumber(valueFromRow(row, columnNames, 'unique_visitors_1d_prev', 6));
-  const unique7dPrev = asFiniteNumber(valueFromRow(row, columnNames, 'unique_visitors_7d_prev', 7));
-  const unique30d = asFiniteNumber(valueFromRow(row, columnNames, 'unique_visitors_30d', 8));
-  const unique30dPrev = asFiniteNumber(
-    valueFromRow(row, columnNames, 'unique_visitors_30d_prev', 9)
-  );
-  const unique365d = asFiniteNumber(valueFromRow(row, columnNames, 'unique_visitors_365d', 10));
+  const pageviews = asFiniteNumber(valueFromRow(row, columnMap, 'pageviews', 0));
+  const uniqueVisitors = asFiniteNumber(valueFromRow(row, columnMap, 'unique_visitors', 1));
+  const firstSeen = asIsoTimestamp(valueFromRow(row, columnMap, 'first_seen', 2));
+  const pageviews7d = asFiniteNumber(valueFromRow(row, columnMap, 'pageviews_7d', 3));
+  const uniqueVisitors7d = asFiniteNumber(valueFromRow(row, columnMap, 'unique_visitors_7d', 4));
+  const unique1d = asFiniteNumber(valueFromRow(row, columnMap, 'unique_visitors_1d', 5));
+  const unique1dPrev = asFiniteNumber(valueFromRow(row, columnMap, 'unique_visitors_1d_prev', 6));
+  const unique7dPrev = asFiniteNumber(valueFromRow(row, columnMap, 'unique_visitors_7d_prev', 7));
+  const unique30d = asFiniteNumber(valueFromRow(row, columnMap, 'unique_visitors_30d', 8));
+  const unique30dPrev = asFiniteNumber(valueFromRow(row, columnMap, 'unique_visitors_30d_prev', 9));
+  const unique365d = asFiniteNumber(valueFromRow(row, columnMap, 'unique_visitors_365d', 10));
   const unique365dPrev = asFiniteNumber(
-    valueFromRow(row, columnNames, 'unique_visitors_365d_prev', 11)
+    valueFromRow(row, columnMap, 'unique_visitors_365d_prev', 11)
   );
 
   if (