@uk-open-data-connectors/uk-sources 0.1.0 → 0.1.2

package/dist/ukhsaDashboard.js

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { UkSourceParseError } from './errors.js';
+import { httpGet } from './http.js';
+import { readFixtureJson } from './fixtures.js';
+/**
+ * The UK Health Security Agency data dashboard API. Keyless, published under
+ * the Open Government Licence v3.
+ */
+export const UKHSA_DASHBOARD_SOURCE_ID = 'ukhsa-dashboard';
+/** Root of the UKHSA data dashboard API. */
+export const UKHSA_DASHBOARD_API_BASE_URL = 'https://api.ukhsa-dashboard.data.gov.uk';
+/**
+ * The metric the adapter reads: new HIV diagnoses in England, a country-level
+ * annual series the dashboard publishes with real counts.
+ */
+export const UKHSA_DASHBOARD_METRIC_PATH = '/themes/infectious_disease/sub_themes/bloodborne/topics/HIV' +
+    '/geography_types/Nation/geographies/England/metrics/HIV_cases_newDiagnoses';
+/** How many metric points the adapter asks for per page by default. */
+export const UKHSA_DASHBOARD_PAGE_SIZE = 10;
+const UKHSA_METRIC_POINT_SCHEMA = z.object({
+    theme: z.string(),
+    sub_theme: z.string(),
+    topic: z.string(),
+    geography_type: z.string(),
+    geography: z.string(),
+    geography_code: z.string().nullable().optional(),
+    metric: z.string(),
+    metric_group: z.string().nullable().optional(),
+    stratum: z.string().nullable().optional(),
+    sex: z.string(),
+    age: z.string(),
+    year: z.number(),
+    month: z.number().nullable().optional(),
+    epiweek: z.number().nullable().optional(),
+    date: z.string(),
+    metric_value: z.number().nullable().optional(),
+    in_reporting_delay_period: z.boolean(),
+});
+const UKHSA_METRIC_PAGE_SCHEMA = z.object({
+    count: z.number(),
+    results: z.array(UKHSA_METRIC_POINT_SCHEMA),
+});
+/**
+ * Builds the metric URL for one page size.
+ *
+ * @param pageSize - how many metric points to ask for
+ * @returns the metric endpoint URL
+ */
+export function buildUkhsaMetricUrl(pageSize) {
+    return `${UKHSA_DASHBOARD_API_BASE_URL}${UKHSA_DASHBOARD_METRIC_PATH}?page_size=${pageSize}`;
+}
+/**
+ * Parses a UKHSA dashboard metric payload.
+ *
+ * @param payload - the raw JSON body from the metric endpoint
+ * @returns the page of metric points plus the API's total count
+ */
+export function parseUkhsaMetricPoints(payload) {
+    const parsed = UKHSA_METRIC_PAGE_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UkSourceParseError('ukhsa-dashboard', parsed.error.message);
+    }
+    return {
+        totalCount: parsed.data.count,
+        points: parsed.data.results.map((point) => ({
+            theme: point.theme,
+            subTheme: point.sub_theme,
+            topic: point.topic,
+            geographyType: point.geography_type,
+            geography: point.geography,
+            geographyCode: point.geography_code ?? '',
+            metric: point.metric,
+            metricGroup: point.metric_group ?? '',
+            stratum: point.stratum ?? '',
+            sex: point.sex,
+            age: point.age,
+            year: point.year,
+            month: point.month ?? null,
+            epiweek: point.epiweek ?? null,
+            date: point.date,
+            metricValue: point.metric_value ?? null,
+            inReportingDelayPeriod: point.in_reporting_delay_period,
+        })),
+    };
+}
+/**
+ * Sums one page of UKHSA metric points.
+ *
+ * @param page - a page from {@link parseUkhsaMetricPoints}
+ * @returns point counts, the date range on the page, and the latest value
+ */
+export function summarizeUkhsaMetricPoints(page) {
+    let firstDate = '';
+    let lastDate = '';
+    let latestValue = null;
+    for (const point of page.points) {
+        if (firstDate === '' || point.date < firstDate) {
+            firstDate = point.date;
+        }
+        if (point.date >= lastDate) {
+            lastDate = point.date;
+            latestValue = point.metricValue;
+        }
+    }
+    return {
+        pointCount: page.points.length,
+        totalCount: page.totalCount,
+        firstDate,
+        lastDate,
+        latestValue,
+    };
+}
+/**
+ * Reads one page of UKHSA dashboard metric points.
+ *
+ * @param options - page size and an optional fetch implementation
+ * @returns the page of metric points the endpoint returns
+ */
+export async function fetchUkhsaMetricPoints(options = {}) {
+    const { pageSize = UKHSA_DASHBOARD_PAGE_SIZE, fetchImpl = globalThis.fetch } = options;
+    const response = await httpGet('ukhsa-dashboard', buildUkhsaMetricUrl(pageSize), { fetchImpl });
+    return parseUkhsaMetricPoints(await response.json());
+}
+/** UK Health Security Agency data dashboard metric points, keyless. */
+export const ukhsaDashboardAdapter = {
+    id: UKHSA_DASHBOARD_SOURCE_ID,
+    name: 'UK Health Security Agency data dashboard',
+    auth: 'none',
+    description: 'New HIV diagnoses in England, as annual counts from the UKHSA dashboard.',
+    fetchLive: (options) => fetchUkhsaMetricPoints(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: parseUkhsaMetricPoints,
+    loadFixture: () => parseUkhsaMetricPoints(readFixtureJson('ukhsa-dashboard-2026-10-05.json')),
+};
+//# sourceMappingURL=ukhsaDashboard.js.map

package/dist/ukhsaDashboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ukhsaDashboard.js","sourceRoot":"","sources":["../src/ukhsaDashboard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uk-open-data-connectors/uk-sources",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -31,10 +31,10 @@
   "devDependencies": {
     "@uk-open-data-connectors/config-eslint": "*",
     "@uk-open-data-connectors/config-typescript": "*",
-    "@types/node": "22.20.4",
+    "@types/node": "22.20.5",
     "eslint": "9.39.5",
     "typescript": "6.0.3",
-    "vitest": "3.2.7"
+    "vitest": "5.0.3"
   },
   "dependencies": {
     "zod": "3.25.76"
@@ -42,5 +42,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "description": "Uniform TypeScript adapters for UK public data sources"
+  "description": "Uniform TypeScript adapters for UK public data sources",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/olitreadwell/uk-open-data-connectors.git"
+  },
+  "homepage": "https://github.com/olitreadwell/uk-open-data-connectors#readme",
+  "bugs": {
+    "url": "https://github.com/olitreadwell/uk-open-data-connectors/issues"
+  }
 }