feat(Replace): Implement replace

Replaces postcode in body of text, return any matches and updated corpus

Author: cblanc

README.md

@@ -127,10 +127,10 @@ if (postcode.valid) {
 If you're just after a single value, you can import a single method.
 
 ```javascript
-# Validation
+// Validation
 isValid("Sw1A 2aa");      // => true
 
-# Formatting
+// Formatting
 toNormalised("Sw1A 2aa");  // => "SW1A 2AA"
 toOutcode("Sw1A 2aa");     // => "SW1A"
 toIncode("Sw1A 2aa");      // => "2AA"
@@ -140,9 +140,25 @@ toSubDistrict("Sw1A 2aa"); // => "SW1A"
 toSector("Sw1A 2aa");      // => "SW1A 2"
 toUnit("Sw1A 2aa");        // => "AA"
 
-# Replacement
-match("The PM and her no.2 live at SW1A2AA and SW1A 2AB"); // => ["SW1A2AA", "SW1A 2AB"]
+// Match
+// Retrieve valid postcodes in a body of text
+const matches = match("The PM and her no.2 live at SW1A2aa and SW1A 2AB"); // => ["SW1A2aa", "SW1A 2AB"]
+
+// Perform transformations like normalisation postcodes using `.map` and `toNormalised`
+matches.map(toNormalised); // => ["SW1A 2AA", "SW1A 2AB"]
+
+// No matches yields empty array
+match("Some London outward codes are SW1A, NW1 and E1"); // => []
+
+// Replace
+// Replace postcodes in a body of text
 replace("The PM and her no.2 live at SW1A2AA and SW1A 2AB");  // => { match: ["SW1A2AA", "SW1A 2AB"], result: "The PM and her no.2 live at  and " }
+
+// Add custom replacement
+replace("The PM lives at SW1A 2AA", "Downing Street"); // => { match: ["SW1A 2AA"], result: "The PM lives at Downing Street" };
+
+// No match
+replace("Some London outward codes are SW1A, NW1 and E1"); // => { match: [], result: "Some London outward codes are SW1A, NW1 and E1" }
 ```
 
 ## Version 5.0.0

lib/index.ts

@@ -296,3 +296,24 @@ export const parse = (postcode: string): ValidPostcode | InvalidPostcode => {
  */
 export const match = (corpus: string): string[] =>
   corpus.match(POSTCODE_CORPUS_REGEX) || [];
+
+interface ReplaceResult {
+  /**
+   * List of matching postcodes found intext
+   */
+  match: string[];
+  /**
+   * Body of text with postcodes replaced (with empty string by default)
+   */
+  result: string;
+}
+
+/**
+ * Replaces postcodes in a body of text with a string
+ *
+ * By default the replacement string is empty string `""`
+ */
+export const replace = (corpus: string, replaceWith = ""): ReplaceResult => ({
+  match: match(corpus),
+  result: corpus.replace(POSTCODE_CORPUS_REGEX, replaceWith),
+});

test/unit.ts

@@ -2,7 +2,7 @@ import { assert } from "chai";
 import * as Postcode from "../lib/index";
 import { loadFixtures, TestMethod } from "./util/helper";
 
-const { match } = Postcode;
+const { match, toNormalised, replace } = Postcode;
 
 const testMethod: TestMethod = (options) => {
   const { tests, method } = options;
@@ -129,11 +129,47 @@ describe("Unit parsing", () => {
 describe("match", () => {
   it("returns matching postcodes", () => {
     const corpus = `SW1A2Aa is the residence of the Prime Minister. SW1a 2AB is the residence of her no.2. SW1A   1AA is where the queen lives. They are located in the SW1A outcode`;
-    assert.deepEqual(match(corpus), ["SW1A2Aa", "SW1a 2AB", "SW1A   1AA"]);
+    const result = match(corpus);
+    assert.deepEqual(result, ["SW1A2Aa", "SW1a 2AB", "SW1A   1AA"]);
+    assert.deepEqual(result.map(toNormalised), [
+      "SW1A 2AA",
+      "SW1A 2AB",
+      "SW1A 1AA",
+    ]);
   });
 
   it("returns an empty array if no match", () => {
     const corpus = `SW1 NW1 E1 E2`;
     assert.deepEqual(match(corpus), []);
   });
 });
+
+describe("replace", () => {
+  it("replaces text and returns matching postcodes", () => {
+    const corpus = `SW1A2Aa is the residence of the Prime Minister. SW1a 2AB is the residence of her no.2. SW1A   1AA is where the queen lives. They are located in the SW1A outcode`;
+    const { match, result } = replace(corpus);
+    assert.deepEqual(match, ["SW1A2Aa", "SW1a 2AB", "SW1A   1AA"]);
+    assert.equal(
+      result,
+      ` is the residence of the Prime Minister.  is the residence of her no.2.  is where the queen lives. They are located in the SW1A outcode`
+    );
+  });
+
+  it("replaces postcode with custom string", () => {
+    const corpus = `SW1A2Aa is the residence of the Prime Minister. SW1a 2AB is the residence of her no.2. SW1A   1AA is where the queen lives. They are located in the SW1A outcode`;
+    const replaceWith = "POSTCODE";
+    const { match, result } = replace(corpus, replaceWith);
+    assert.deepEqual(match, ["SW1A2Aa", "SW1a 2AB", "SW1A   1AA"]);
+    assert.equal(
+      result,
+      `POSTCODE is the residence of the Prime Minister. POSTCODE is the residence of her no.2. POSTCODE is where the queen lives. They are located in the SW1A outcode`
+    );
+  });
+
+  it("returns an empty array if no match", () => {
+    const corpus = `SW1 NW1 E1 E2`;
+    const { match, result } = replace(corpus);
+    assert.deepEqual(match, []);
+    assert.deepEqual(result, corpus);
+  });
+});