Merge pull request #87 from bcgov/test

Promote test to main

Author: ty2k

.github/workflows/graphemes_api_build.yaml

@@ -55,10 +55,10 @@ jobs:
 
       # Use the GHCR builder action
       - name: Build and push Docker image to GHCR
-        uses: bcgov-nr/action-builder-ghcr@ace71f7a527ca6fc43c15c7806314be5a4579d2c # v.2.3.0
+        uses: bcgov-nr/action-builder-ghcr@fd17bc1cbb16a60514e0df3966d42dff9fc232bc # v4.0.0
         with:
           package: graphemes-api
-          tag: ${{ env.tag }}
+          tags: ${{ env.tag }}
           triggers: graphemes-api/**
           build_context: ./graphemes-api
           build_file: ./graphemes-api/Dockerfile

graphemes-api/package-lock.json

@@ -13,20 +13,24 @@
     "test": "npx vitest"
   },
   "dependencies": {
+    "any-ascii": "^0.3.2",
+    "cors": "^2.8.5",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
     "express-rate-limit": "^7.5.0",
+    "js-levenshtein-esm": "^2.0.0",
     "knex": "^3.1.0",
     "pg": "^8.16.0",
-    "zod": "^3.25.7"
+    "zod": "^3.25.28"
   },
   "devDependencies": {
     "@eslint/js": "^9.27.0",
+    "@types/cors": "^2.8.18",
     "@types/express": "^5.0.2",
-    "@types/node": "^22.15.20",
+    "@types/node": "^22.15.21",
     "@types/supertest": "^6.0.3",
     "eslint": "^9.27.0",
-    "globals": "^16.1.0",
+    "globals": "^16.2.0",
     "nodemon": "^3.1.9",
     "prettier": "^3.5.3",
     "supertest": "^7.1.1",

graphemes-api/package.json

@@ -1,6 +1,7 @@
 import dotenv from "dotenv";
 dotenv.config();
 import express from "express";
+import cors from "cors";
 import rateLimit from "express-rate-limit";
 
 import router from "./routes/index.js";
@@ -20,6 +21,7 @@ const limiter = rateLimit({
 
 // Middleware
 app.use(express.json());
+app.use(cors());
 app.use(limiter);
 
 // Routes

graphemes-api/src/index.ts

@@ -1,8 +1,10 @@
 import { Router } from "express";
 
 import languagesRouter from "./languages/index.js";
+import matchRouter from "./match/index.js";
 
 const v1Router = Router();
 v1Router.use("/languages", languagesRouter);
+v1Router.use("/match", matchRouter);
 
 export default v1Router;

graphemes-api/src/routes/api/v1/index.ts

@@ -0,0 +1,46 @@
+import { Router } from "express";
+
+import compareValues from "../../../../utils/compareValues.js";
+
+const matchRouter = Router();
+
+matchRouter.post("/", async (req, res) => {
+  // Check the request body for values to be compared (`value1` and `value2`).
+  if (!req.body || Object.keys(req.body).length === 0) {
+    res.status(400).json({
+      error: "Bad Request",
+      message: "Request body is required",
+      statusCode: 400,
+    });
+    return;
+  }
+
+  if (!req.body.value1 || !req.body.value2) {
+    res.status(400).json({
+      error: "Bad Request",
+      message: "Request body requires values",
+      statusCode: 400,
+    });
+    return;
+  }
+
+  const { value1, value2, threshold } = req.body;
+
+  // Check for numeric threshold value and default to 0.9 if one isn't present.
+  const numericThreshold = parseFloat(threshold);
+  const comparison = compareValues(
+    value1,
+    value2,
+    !isNaN(numericThreshold) ? numericThreshold : 0.9
+  );
+
+  res.status(200).json({
+    value1: comparison.comparisonValue1,
+    value2: comparison.comparisonValue2,
+    threshold: comparison.threshold,
+    ratio: comparison.ratio,
+    isMatch: comparison.isMatch,
+  });
+});
+
+export default matchRouter;

graphemes-api/src/routes/api/v1/match/index.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+
+import compareValues from "./compareValues.js";
+
+describe("compareValues()", () => {
+  // Ratio of 0.5714285714285714, not a match given the default threshold 0.9
+  const resultWithDefaultThreshold = compareValues("kitten", "sitting");
+  it("returns an object with the expected keys", () => {
+    const keys = Object.keys(resultWithDefaultThreshold);
+    expect(keys.length).toBe(5);
+    expect(keys.includes("comparisonValue1")).toBeTruthy();
+    expect(keys.includes("comparisonValue2")).toBeTruthy();
+    expect(keys.includes("threshold")).toBeTruthy();
+    expect(keys.includes("ratio")).toBeTruthy();
+    expect(keys.includes("isMatch")).toBeTruthy();
+  });
+  it("reports the default threshold value used when one isn't passed", () => {
+    expect(resultWithDefaultThreshold.threshold).toBe(0.9);
+  });
+  it("reports the Levenshtein ratio of the values being compared", () => {
+    expect(resultWithDefaultThreshold.ratio.toFixed(2)).toBe("0.57");
+  });
+  it("reports an accurate boolean isMatch for the values being compared", () => {
+    expect(resultWithDefaultThreshold.isMatch).toBeFalsy();
+  });
+
+  // Ratio of 0.5714285714285714, a match given the specific threshold 0.5
+  const resultWithSpecificThreshold = compareValues("kitten", "sitting", 0.5);
+  it("reports the specified threshold value used when one is passed", () => {
+    expect(resultWithSpecificThreshold.threshold).toBe(0.5);
+  });
+  it("reports an accurate boolean isMatch for the values being compared with a low enough threshold", () => {
+    expect(resultWithSpecificThreshold.isMatch).toBeTruthy();
+  });
+
+  // Specific BC Parks names with known match booleans
+  const resultParks1 = compareValues("Aa Tlein Teix’i", "A Téix'gi Aan Tlein");
+  it("is not a match for: Aa Tlein Teix’i, A Téix'gi Aan Tlein", () => {
+    expect(resultParks1.isMatch).toBeFalsy();
+  });
+  const resultParks2 = compareValues("Hakai LÚxvbálís", "Hakai Lúxvbálís");
+  it("is a match for: Hakai LÚxvbálís, Hakai Lúxvbálís", () => {
+    expect(resultParks2.isMatch).toBeTruthy();
+  });
+  const resultsParks3 = compareValues("Ẁaẁley", "Ẁaẁaƛ");
+  it("is not a match for: Ẁaẁley, Ẁaẁaƛ", () => {
+    expect(resultsParks3.isMatch).toBeFalsy();
+  });
+  const resultsParks4 = compareValues("Xʷakʷəᕈnaxdəᕈma", "Xʷak̓ʷəʔnaxdəʔma");
+  it("is not a match for: Xʷakʷəᕈnaxdəᕈma, Xʷak̓ʷəʔnaxdəʔma", () => {
+    expect(resultsParks4.isMatch).toBeFalsy();
+  });
+  const resultsPark5 = compareValues("ɂNacinuxʷ", "ʔNacinuxʷ");
+  it("is a match for: ɂNacinuxʷ, ʔNacinuxʷ", () => {
+    expect(resultsPark5.isMatch).toBeTruthy();
+  });
+
+  it("whitespace is trimmed as expected", () => {
+    const result = compareValues("dog", "     dog          ");
+    expect(result.comparisonValue1).toBe("dog");
+    expect(result.comparisonValue2).toBe("dog");
+    expect(result.ratio).toBe(1);
+    expect(result.isMatch).toBeTruthy();
+  });
+});

graphemes-api/src/utils/compareValues.test.ts

@@ -0,0 +1,50 @@
+import anyAscii from "any-ascii";
+import levenshteinDistance from "js-levenshtein-esm";
+
+import levenshteinRatio from "./levenshtein-ratio.js";
+
+interface ComparisonDetails {
+  /** First string value for comparison. */
+  comparisonValue1: string;
+  /** Second string value for comparison. */
+  comparisonValue2: string;
+  /** Levenshtein ratio threshold to check for a match. */
+  threshold: number;
+  /** Levenshtein ratio to compare to the threshold. */
+  ratio: number;
+  /** Whether the strings match based on the given threshold. */
+  isMatch: boolean;
+}
+
+/**
+ * Given two strings to compare and an optional Levenshtein threshold (which
+ * defaults to `0.9`), returns an object containing a `ratio` number and
+ * `isMatch` boolean indicating whether the strings are considered to be a match.
+ */
+export default function compareValues(
+  value1: string,
+  value2: string,
+  threshold: number = 0.9
+): ComparisonDetails {
+  // Trim whitespace from the ends of the input values and cast to uppercase.
+  const capitalizedValue1 = value1.trim().toUpperCase();
+  const capitalizedValue2 = value2.trim().toUpperCase();
+
+  // Convert uppercase values to ASCII.
+  const ascii1 = anyAscii(capitalizedValue1);
+  const ascii2 = anyAscii(capitalizedValue2);
+
+  // Calculate Levenshtein distance of the ASCII values.
+  const distance = levenshteinDistance(ascii1, ascii2);
+
+  // Calculate Levenshtein ratio given the distance.
+  const ratio = levenshteinRatio(ascii1, ascii2, distance);
+
+  return {
+    comparisonValue1: value1.trim(),
+    comparisonValue2: value2.trim(),
+    threshold,
+    ratio,
+    isMatch: ratio >= threshold,
+  };
+}