Fundraising data validations

This internal CRUKorg package provides regular expressions to validate commonly collected supporter data in fundraising products, ensuring the data meets the minimum requirements for downstream systems.

The motivation for creating this package is to standardise these validation rules to avoid duplicated interpretation of them in multiple products and minimise risks of passing invalid data downstream. This package is designed to be used in frontend forms and on backend services accepting any payloads of data to be sent downstream.

Usage

To install the package locally

1. Run npm install @crukorg/fundraising-data-validations in your terminal.
2. Import the relevant schema into your validation files, e.g.

import { supporterSchema } from "@crukorg/fundraising-data-validations";

const isValidFirstName =
  supporterSchema.firstName.allowedCharacters.regex.test(inputFirstName);

if (!isValidFirstName) {
  return supporterSchema.firstName.allowedCharacters.errorMessage;
}

Zod example:

import { z } from "zod";
import { supporterSchema } from "@cruk/fundraising-data-validations";

const isValidSupporter = z
  .object({
    firstName: z
      .string()
      .trim()
      .regex(
        supporterSchema.firstName.minMaxLength?.regex,
        supporterSchema.firstName.minMaxLength?.errorMessage,
      )
      .regex(
        supporterSchema.firstName.allowedCharacters.regex,
        supporterSchema.firstName.allowedCharacters.errorMessage,
      ),
  })
  .required({
    firstName: supporterSchema.firstName.isRequired?.required,
  });

try {
  isValidSupporter.parse(inputSupporter);
} catch (error) {
  if (error instanceof ZodError) {
    const errorMessages = prettifyError(error);
    console.error(errorMessages);
  }
}

1. You may add additional, stricter rules on top of these validations, but these rules should form the foundation of any validations for form data.

Required and optional validation

Each field has several rules available for use. In each case, required and allowedCharacters regexes are the minimum required rules. Most of the fields also have a minMaxLength rule, the only current exception being the createdAt field.

• firstName and lastName: forbiddenSubstrings should be enforced.
• phoneNumber: forbiddenSubstrings are optional depending on if your validation requires phoneNumber to be a landline.
• dateOfBirth: only the YYYY-MM-DD format is validated by this package. Semantic checks such as "must be in the past" or age-based rules (e.g. 18+) are intentionally out of scope and must be applied by consumers on top of this foundation.

Limitations

• The regular expressions are written to be language agnostic, but they have only been tested in TypeScript applications.
• The regular expressions are compatible with AWS tools that allow regular expressions for string comparison, such as Step Functions, since allowed regex in AWS have some limitations.

Transformations

[!IMPORTANT] The following data transformation must be handled by the products, as they is not included in the validations package to minimise friction to the user journey.

firstName

• remove whitespace before or after a hyphen or an apostrophe, e.g. " - " is converted to "-"
• must be in Proper Case

lastName

• remove whitespace before or after a hyphen or an apostrophe, e.g. " - " is converted to "-"

email

• must be in lowercase

phoneNumber / mobileNumber

• remove whitespace

address lines

• replace comma with space
• must be no duplicates across lines

postcode

• must be UPPERCASE