@buildcanada/charts 0.1.0

package/src/explorer/urlMigrations/LegacyCovidUrlMigration.ts

@@ -0,0 +1,144 @@
+import * as _ from "lodash-es"
+import { legacyToCurrentGrapherUrl } from "../../grapher/index.js"
+import { QueryParams, Url } from "../../utils/index.js"
+import { EXPLORERS_ROUTE_FOLDER } from "../ExplorerConstants.js"
+import { ExplorerUrlMigrationSpec } from "./ExplorerUrlMigrations.js"
+
+const covidMetricFromLegacyQueryParams = (queryParams: QueryParams) => {
+    if (queryParams.casesMetric) {
+        return "Confirmed cases"
+    } else if (queryParams.deathsMetric) {
+        return "Confirmed deaths"
+    } else if (queryParams.cfrMetric) {
+        return "Case fatality rate"
+    } else if (queryParams.testsMetric) {
+        return "Tests"
+    } else if (queryParams.testsPerCaseMetric) {
+        return "Tests per confirmed case"
+    } else if (queryParams.positiveTestRate) {
+        return "Share of positive tests"
+    } else if (queryParams.vaccinationsMetric) {
+        return "Vaccinations"
+    }
+    return undefined
+}
+
+const legacyIntervalToNewValue = {
+    daily: "New per day",
+    weekly: "Weekly",
+    total: "Cumulative",
+    smoothed: "7-day rolling average",
+    biweekly: "Biweekly",
+    weeklyChange: "Weekly change",
+    biweeklyChange: "Biweekly change",
+}
+
+const covidIntervalFromLegacyQueryParams = (queryParams: QueryParams) => {
+    let legacyInterval: string | undefined = undefined
+
+    // Early on, the query string was a few booleans like dailyFreq=true.
+    // Now it is a single 'interval'. This transformation is for backward compat.
+    if (queryParams.interval) {
+        legacyInterval = queryParams.interval
+    } else if (queryParams.totalFreq) {
+        legacyInterval = "total"
+    } else if (queryParams.dailyFreq) {
+        legacyInterval = "daily"
+    } else if (queryParams.smoothing) {
+        legacyInterval = "smoothed"
+    }
+
+    if (legacyInterval) {
+        return legacyIntervalToNewValue[
+            legacyInterval as keyof typeof legacyIntervalToNewValue
+        ]
+    }
+
+    return undefined
+}
+
+const boolParamToString = (bool: boolean | string | undefined) =>
+    bool === "true" || bool === "false" ? bool : bool ? "true" : "false"
+
+const legacyToCurrentCovidQueryParams = (
+    queryParams: QueryParams,
+    baseQueryParams: QueryParams = {}
+): QueryParams => {
+    const restQueryParams = _.omit(
+        {
+            ...baseQueryParams,
+            ...queryParams,
+        },
+        "casesMetric",
+        "deathsMetric",
+        "cfrMetric",
+        "testsMetric",
+        "testsPerCaseMetric",
+        "positiveTestRate",
+        "vaccinationsMetric",
+        "interval",
+        "smoothing",
+        "totalFreq",
+        "dailyFreq",
+        "aligned",
+        "perCapita"
+    )
+
+    const urlContainsMetric = !!covidMetricFromLegacyQueryParams(queryParams)
+
+    // For the following params, use the modern query param if it exists, otherwise
+    // fall back to trying to convert the legacy one.
+    const explorerQueryParams: QueryParams = {
+        Metric:
+            queryParams.Metric ??
+            baseQueryParams.Metric ??
+            covidMetricFromLegacyQueryParams(queryParams) ??
+            covidMetricFromLegacyQueryParams(baseQueryParams),
+        Interval:
+            queryParams.Interval ??
+            baseQueryParams.Interval ??
+            covidIntervalFromLegacyQueryParams(queryParams) ??
+            covidIntervalFromLegacyQueryParams(baseQueryParams),
+        "Align outbreaks": boolParamToString(
+            queryParams["Align outbreaks"] ??
+                baseQueryParams["Align outbreaks"] ??
+                (urlContainsMetric
+                    ? queryParams.aligned
+                    : baseQueryParams.aligned)
+        ),
+        "Relative to Population": boolParamToString(
+            queryParams["Relative to Population"] ??
+                baseQueryParams["Relative to Population"] ??
+                (urlContainsMetric
+                    ? queryParams.perCapita
+                    : baseQueryParams.perCapita)
+        ),
+    }
+
+    return {
+        ...restQueryParams,
+        ...explorerQueryParams,
+    }
+}
+
+export const legacyCovidMigrationSpec: ExplorerUrlMigrationSpec = {
+    explorerSlug: "covid",
+    migrateUrl: (url, baseQueryStr) => {
+        // Migrate the Grapher query params in both URLs
+        const [explorerUrl, baseUrl] = [
+            url,
+            Url.fromQueryStr(baseQueryStr),
+        ].map(legacyToCurrentGrapherUrl)
+
+        return explorerUrl
+            .setQueryParams(
+                legacyToCurrentCovidQueryParams(
+                    explorerUrl.queryParams,
+                    baseUrl.queryParams
+                )
+            )
+            .update({
+                pathname: `/${EXPLORERS_ROUTE_FOLDER}/covid`,
+            })
+    },
+}

package/src/explorer/urlMigrations/readme.md

@@ -0,0 +1,39 @@
+# Explorer URL migrations
+
+URLs contain technical debt we can never get rid of.
+
+The goals of this module are to:
+
+1. **Keep legacy Explorer URL migrations in one place**, so that we can more easily see and compare the flows of each migration.
+2. **Keep Explorer URL migrations simple**, so that we don't need to understand the details – just run one function on your URL and it's up to date.
+
+There's a mix of cases where we need to migrate URLs:
+
+- User visits old path with old URL params (e.g. legacy COVID explorer)
+- User visits new path with old URL params (e.g. old CO2 & Energy explorers)
+- Authors embed Grapher that is redirected to an Explorer view (we do this for old COVID charts)
+- Authors embed Explorer that has old URL params (since URLs are in the Wordpress database, we cannot easily replace all. Even if we do, it isn't robust – authors occasionally use the revert option.)
+
+(Also note that embeds are iframeless – if they were `<iframe>` it would be simpler.)
+
+## How are Explorer URLs migrated?
+
+In order:
+
+1. **Apply Explorer redirects** `(Url, baseQueryStr) → Url` ([`ExplorerRedirects.ts`](../../explorerAdminServer/ExplorerRedirects.ts))
+
+    This is done **server-side** for Grapher → Explorer redirects and LegacyCovidExplorer → GridCovidExplorer.
+
+    Because each Grapher redirects to a different Explorer configuration, there is a `baseQueryStr` baked into `ExplorerPage` and used as a parameter in the redirect.
+
+    The redirect is done client-side with `window.history.replaceState()`, based on the **baked specification** ([`ExplorerPageUrlMigrationSpec.ts`](./ExplorerPageUrlMigrationSpec.ts)).
+
+2. **Apply Explorer migrations** `(Url) → Url` ([`ExplorerUrlMigrations.ts`](./ExplorerUrlMigrations.ts))
+
+    This is how we handle Explorer query param changes on **client-side** (e.g. in the old CO2 and Energy explorers).
+
+    Because the old & new Explorers are on the same path, we can't bake a redirect spec – the URL migration logic has to be fully in the client-side bundle.
+
+## Regrets
+
+This could've been simpler if all redirects were done client-side, without baking redirect specifications on `ExplorerPage`. One downside is that the redirect `baseQueryStr` would need to be in the client-side bundle.