OC-Digital function library

Beta Usage

1. increment the package version and add -beta.0 (e.g. 2.0.6 => 2.0.7-beta.0)
   1. if you need to make further iterations increment and publish use -beta.1, -beta.2 and so on
   2. you can use this all in one command for the above - npm version 2.0.7-beta.0
2. publish the component library with command - npm publish --tag beta
3. pin the version in the receiving library to "=2.0.7-beta.0" and run npm install
4. once happy with the changes remove -beta.0 part and part and publish function library
   1. update the version in the receiving library to "^2.0.7"

Building and publishing

To publish new version:

1. Login to npm using npm login
2. Increment the version in package.json (using semantic versioning)
3. Run npm install (this is needed to update the package-lock.json)
4. Commit changes to Git (git commit -m "Version x.x.x")
5. Publish to NPM npm publish. Subsequently it will build the library to build folder and push it's contents to the npm.

Local Usage

You can override the remote library in favour of that on your machine, however few steps are required:

In the root of component library:

1. install npm install and build npm run build component library
2. run npm link

In the receiving project:

1. run npm link data-library
2. Invoke your lambda function.

When finished with adjustments you need to unlink local component library with:
npm unlink data-library

Peer Dependencies

The aim would be to keep this module as small as possible so as to ensure that we can still edit functions in the AWS Lambda console as this massively speeds up development (There would also be an effect on performance though we have not measured this yet). Therefore when it came to requiring the use of aws appsync and graphql for the generate graphql client shared function we could not have this as a proper dependency as we immediately went over the limit for editing in line on the console.

The choice was made to specify these as peer dependencies and include them in a layer alongside the function that uses this export. This was done because each of those functions already had appsync as a layer. and the frontend would tree shake out any need for it.

It may be the case that in the future we want more dependencies if these start to become too large we can look into turning this repo into a mono repo that would deploy singular responsabilty modules akin to the AWS SDK v3

Code standards

We want to keep the code in this function library to a high standard, so these checks are in place for PRs:

• all functions must be documented (put a /** */ tsdoc comment before the function definition)
• all functions must be fully unit tested. Every branch of logic must be tested (code coverage).
• no eslint errors

If your function throws any errors, please document them in the tsdoc comment so that callers can handle them correctly.

If you add a RegExp constant, please add a unit test with some examples to make sure the RegExp is doing what you expect. Try put edge cases in the tests where appropriate. See NiRegex as an example.

Versioning

This package uses semantic versioning.

To summarise the above link:

• The version is in the format MAJOR.MINOR.PATCH.
• If you make a breaking change (ie previously valid usage of the package no longer works), increment the MAJOR version.
• If you add a new function or add additional parameters to an existing function, increment the MINOR version.
• If you make an internal change that doesn't affect the usage of the package (ie changing docs), increment the PATCH version.

Testing tables

When unit testing a function, where possible, try to use a testing table for testing different cases. This reduces duplicate code and makes it clear at a glance what is being tested. For extensive examples, see the capitalise function and the data api auth lambda.

describe("demonstrate testing table", () => {
  const testCases = [
    ["first test case", "expected output 1"],
    ["second test case", "expected output 2"],
  ];

  test.each(testCases)("functionBeingTested('%s') === '%s'", (input, expected) => {
    expect(functionBeingTested(input)).toBe(expected);
  });
});

Depending on the function and the various inputs used, you can add a value to the array for describing the test case which you use in the test name using string interpolation %s.

See https://jestjs.io/docs/api#1-testeachtablename-fn-timeout for official documentation on testing tables.