justair-library

Overview

@justair/justair-library is the shared internal npm package installed across all JustAir backend and Lambda services. It is the source of truth for all Mongoose schemas and models, the database connection class, the Winston/Datadog logger factory, and shared enums.

Consuming services: JustAirService, Public-API-Service, JustAirUserService, JustAirNotificationService, CalculateAQIService, Processing-Engine, MonitorUpdateLambda, MonitorUpdateCoordinator, calcaqi-fan-scheduler.

Prerequisites

You must be a member of the JustAir organization on npmjs.org to install this package.

Installation

npm install @justair/justair-library

Authenticate with your npm access token if needed:

npm set //registry.npmjs.org/:_authToken=YOUR_ACCESS_TOKEN

Usage

import { Monitors, Measurements, createLoggerInstance, Database } from '@justair/justair-library';

Constants

The library exposes two entry points — one for Node.js services (models + constants) and one constants-only entry for browser environments like JustAir-Client.

Backend services

import { PARAMETERS, HEAVY_METALS } from '@justair/justair-library';

// Use .id for string comparisons and DB queries
measurements.find({ parameter: PARAMETERS.PM2_5.id });

// Use .label for user-facing display
console.log(PARAMETERS.PM2_5.label); // "PM₂.₅"

// Use .type to filter by category
const gases = Object.values(PARAMETERS).filter(p => p.type === 'Gas');

// Access health data for a sample parameter
console.log(HEAVY_METALS.AS.rfc);     // 0.03
console.log(HEAVY_METALS.AS.impacts); // "Short-term exposure..."

JustAir-Client (browser)

Use the constants-only entry point — no Mongoose dependency:

import { PARAMETERS, HEAVY_METALS } from '@justair/justair-library/constants';

New sample parameters in 5.0.0

The following parameters were added to HEAVY_METALS and are now included in sampleParametersEnum. Consuming services that display or filter sample parameters (UI dropdowns, notification thresholds, reporting) should be updated to handle these values:

| id | Name | |---|---| | BE | Beryllium | | CO | Cobalt | | MN | Manganese | | SE | Selenium |

Object shape

Each constant is an object with the following fields:

| Field | Type | Description | |---|---|---| | id | string | System-facing identifier stored in the database (e.g. "PM2_5") | | label | string | Short user-facing name with Unicode subscripts (e.g. "PM₂.₅") | | name | string | Full descriptive name (e.g. "Particulate Matter 2.5 (PM₂.₅)") | | unit | string | Measurement unit (e.g. "µg/m³") | | type | string | Category: "Particulate Matter", "Gas", "Volatile Organic Compound", "Weather", "Heavy Metal", "Heavy Metal - Essential Nutrient" | | rfc | number \| null | EPA IRIS chronic inhalation reference concentration (µg/m³) | | origin | string \| null | Description of pollution source | | impacts | string \| null | Human health impact description |

Development Workflow

Testing locally (fast iteration)

For rapid local development without waiting for CI:

1. Build and pack:

   npm run build
   npm pack

   This creates a .tgz file (e.g., justair-justair-library-5.0.0.tgz).

2. Install in a consuming service:

   npm install /path/to/justair-library/justair-justair-library-5.0.0.tgz

   Or use npm link for live development:

   # In the justair-library directory
   npm link
   
   # In your consuming service directory
   npm link @justair/justair-library

3. Unlink when done:

   # In your consuming service directory
   npm unlink @justair/justair-library
   
   # In the justair-library directory
   npm unlink

Testing against a published alpha

For validating changes against the actual published artifact before merging:

1. Push your changes to your JA-* branch — CI automatically publishes an alpha version tagged @alpha with your commit SHA (e.g. 4.9.2-alpha.a1b2c3d)

2. In the consuming service, install the alpha:

   npm install @justair/justair-library@alpha

3. When done testing, revert to the stable version:

   npm install @justair/justair-library@latest

Publishing

Publishing is fully automated — do not publish manually.

| Event | Result | |---|---| | Push to JA-* branch (src changes) | Publishes @alpha pre-release | | Merge to master (src changes) | Publishes @latest stable release |

Before merging, bump the version in package.json according to semver:

• patch — bug fixes, internal changes
• minor — new exports, new optional schema fields
• major — breaking changes (removed exports, required fields without defaults, renamed fields)

See CLAUDE.md for the full schema change and versioning policy.

Contributing

All PRs require approval from the library owners (see CODEOWNERS). Every PR is automatically reviewed by Claude with library-specific rules enforced — breaking changes block merge.

License

This project is licensed under the MIT License.