Node.js: arupcompute-connect-node

To contribute and / or report bugs go to the arupcompute-connect-node GitHub repo.

Prerequisites

Authenticate to the GitHub node package registry

arupcompute-connect-node is hosted on the (private) arup-group GitHub package regsitry. In order to install it you must authenticate to the GitHub node package registry using an SSO enabled Personal Access Token.

We recommend that you follow the below instructions (described in more detail here) to authenticate by adding your personal access token to ~/.npmrc. This will carry over to any other Arup projects using the registry, so you won't need to keep logging in manually on the CLI each time.

1. Generate a personal access token here and select the read:packages scope.
2. Copy the generated token somewhere so you don't lose it.
3. Enable the token for SSO here by clicking "Enable SSO" and then "Authorize" next to arup-group
4. Create a file in your home directory* called .npmrc (or edit it if you already have one) and add a single line: //npm.pkg.github.com/:_authToken=TOKEN (replace TOKEN with your own token from step 1).

*For Windows users, your home directory is usually C:\Users\firstname.lastname, and on macos / linux you can use the ~ alias (i.e. touch ~/.npmrc would create the necessary file)

Installation

After authenticating as described above arupcompute-connect-node can be installed via npm:

npm install @arup-group/arupcompute-connect-node

Example usage

This example uses TypeScript but if you need to use in a JavaScript project you can just omit the types.

1. Create an ArupCompute service

src/services/arupCompute.ts

import {
  ArupCompute,
  ArupComputeConfig,
} from "@arup-group/arupcompute-connect-node";

const config: ArupComputeConfig = {
  tenant_id: process.env.AAD_TENANT_ID,
  client_id: process.env.AAD_CLIENT_ID,
  client_secret: process.env.AAD_ARUPCOMPUTE_CLIENT_SECRET,
  resource: process.env.ARUPCOMPUTE_RESOURCE,
  client: process.env.ARUPCOMPUTE_CLIENT,
};

export default new ArupCompute(config);

The Node.js client assumes you are using the client_credentials auth flow (described in the API section of these docs under the Client Secret Flow section). Follow the instructions there to register an application for API access and create the required client secret.

• AAD_TENANT_ID is the Azure Active Directory (AAD) tenant ID for Arup
• AAD_CLIENT_ID is the client ID for your AAD application
• AAD_ARUPCOMPUTE_CLIENT_SECRET is the client secret you created on your AAD application
• ARUPCOMPUTE_RESOURCE is the resource uri of the ArupCompute API on Azure (i.e. api://<arup_compute_api_id>)
• ARUPCOMPUTE_CLIENT is a string used by ArupCompute to identify where the request originates from. You can set it to something descriptive like "My application name".

2. Use it

src/calculations/sumTwoNumbers.ts

import AC from "src/services/arupCompute";
import { CalcRecord } from "@arup-group/arupcompute-connect-node";

// The calculation input types for the calculation you are executing on ArupCompute
type Sum = {
  ID: string;
  A: number;
  B: number;
};

const inputs: Sum = {
    ID: "The calculation ID"
    A: 2
    B: 2
}

const sumTwoNumbers = async ({ID,A,B}: Sum): Promise<number> => {

    const answer: CalcRecord = await AC.compute<Sum>(
        {
          // The ArupCompute calculation ID
          // (get this from the ArupCompute API)
          calcId: 485985,
          body: { ID, A, B },
        },
        // The below 'options' object is optional
        // If you set parseKatexSymbols to true,
        // the arupComputeReport_HTML will be piped
        // through katex to make it easier to render
        // any math symbols. Just be sure to inlcude
        // the necessary css and fonts (see the katex docs)
        {
          parseKatexSymbols: true,
        },
    );

    const output = JSON.parse(answer.output)
    return output.arupComputeReport_HTML

}


export default sumTwoNumbers;

ArupCompute calcRecords

The AC.compute() method used in the snippet above sends a POST request to the /calcRecords endpoint on ArupCompute.

The documentation for that endpoint can be found here.

Note from the documentation that the body expects the calculation inputs as a JSON object, but there are also a series of optional query parameters.

The query parameters can each be added to your request in the the same way as the calcId from the above snippet. For example:

// somewhere in an async function...
  const answer: CalcRecord = await AC.compute<Sum>(
    {
      calcId: 485985,              // required
      client: 'my app',            // default: ''
      jobNumber: 'the job number', // default: ''
      isBatch: false,              // default: false
      resultType: 'mini',          // default: 'simple'
      body: { ID, A, B },
    },
  );
//...