pgds-utils

This utils package can be used for various purposes. It is a collection of utility functions that can be used in any project withing the PGDS platform.

Usage

Install pgds-utils as an npm module and save it to your package.json file as a development dependency:

npm install @pdgs/utils

Unit conversion

Converts a value between the given units or by type and measurement system.

Functions

import { getDisplayValue, convertValueByUnitAndMeasurementSystem, getDisplayUnit } from "@pgds/utils/unitConversion";

/**
 * Converts a value from one measurement system to another based on the unit.
 *
 * @param value value to convert
 * @param unit unit of the value
 * @param from measurement system of the value
 * @param to measurement system to convert to
 * @returns converted value based on the unit and measurement system
 */
convertValueByUnitAndMeasurementSystem(value: number, unit: SupportedUnit, from: MeasurementSystem, to: MeasurementSystem): number;

/**
 * @param value in the metric system
 * @param unit unit in metric system
 * @param to measurement system to convert to
 * @returns  formatted string with rounded value and unit label
 */
getDisplayValue(value: number,unit: SupportedUnit | string, to: MeasurementSystem): string;

/**
 * Returns the unit label based on the unit and measurement system.
 *
 * E.g.
 * ```
 * const unit = getDisplayUnit(SupportedUnit.Celsius, MeasurementSystem.Imperial);
 * console.log(unit); // "°F"
 *
 * const unit = getDisplayUnit(SupportedUnit.Celsius, MeasurementSystem.Metric);
 * console.log(unit); // "°C"
 *
 * const unit = getDisplayUnit("Bar", MeasurementSystem.Metric);
 * console.log(unit); // "Bar"
 * ```
 * @param unit can be SupportedUnit or custom string
 * @param measurementSystem
 * @returns the display label for the unit, if supported, otherwise returns the unit as is.
 */
getDisplayUnit(unit: SupportedUnit | string, measurementSystem: MeasurementSystem): string;

Calculations

Calculates derived values based on the state and product (derived value) capabilities. Available calculations are:

• AbsoluteHumidity
• MixingRatio
• DewPoint
• SpecificHumidity
• Wme

Functions

import { calculateDerivedValue } from "@pgds/utils/calculations";

calculateDerivedValue(state: any, capability: any): string;

Constants

import {
  MeasurementSystem,
  SupportedDerivedValues,
  SupportedUnit,
} from "@pgds/utils/constants";

/**
 * Measurement systems used in the platform
 */
enum MeasurementSystem;

/**
 * Supported derived values that can be calculated
 */
enum SupportedDerivedValues;

/**
 * Supported units that can be converted and displayed
 */
enum SupportedUnit;

Logging

Utils for logging in a consistent manner. Will pick up the request id from the request context (by the provided useReqStore function from @pgds/api-interface) if available.

// app.ts
import { setupLogger } from "@pgds/utils/logging";
import { useReqStore } from "@pgds/api-interface";

setupLogger("things-api", { useReqStore });

// Anywhere in a service
import { logger } from "@pgds/utils/logging";

logger.info("Hello world", { hello: "world" });

Output will be:

2023-10-01T12:00:00.000Z  INFO  things-api:  Hello world  { hello: "world" } (req_id=1234567890)

configs

• LOG_LEVEL - see https://github.com/trentm/node-bunyan?tab=readme-ov-file#levels. Default is info, meaning it will log everything from info and above (i.e. info, warn, error, fatal).

Dependencies

You need to run node version 22 or higher.

Publishing

Prerequisites:

• You have to be part of the @hiotlabs organization on npm
• You have to be logged in to npm

Then, in root, run:

// Check out any untracked/ignored files (e.g. previously built files) ⚠ Do not do this unless you have committed any changes you want to keep ⚠
yarn clean

// Install dependencies
yarn install

// Build
yarn build

// Make sure tests pass
yarn test

// Publish
npm publish --access public

// Or pack (for testing)
npm pack

Adding new directories to the project (@pgds/utils)

• Create folder
• Add index.ts file in the folder
  • This file will be responsible for exporting functions.
• Add one entry for .js, .js.map and .d.ts for the folder to package.json's files array, e.g. utils/**/*.js, utils/**/*.js.map and utils/**/*.d.ts

  "files": [
    "**/*.d.ts",
    "./index.js",
    "lib/**/*.js",
    "lib/**/*.js.map",
    "lib/**/*.d.ts",
    "errors/**/*.js",
    "errors/**/*.js.map",
    "errors/**/*.d.ts",
    "constants/**/*.js",
    "constants/**/*.js.map",
    "constants/**/*.d.ts",
    "utils/**/*.js",
    "utils/**/*.js.map",
    "utils/**/*.d.ts"
  ],