@moderta/reporting-core

Framework-independent reporting domain and application logic for Moderta reporting workflows.

This package is designed to be reused by backend services or other TypeScript projects without depending on a host backend repository, NestJS, React, databases, rendering libraries, or file generation tools.

Installation

npm install @moderta/reporting-core @moderta/api-contracts

@moderta/api-contracts owns the shared reporting contracts. This package depends on those contracts and re-exports the reporting domain surface used by reporting-core consumers.

Development

npm install
npm test
npm run typecheck
npm run build

The build output is emitted to dist/.

Architecture

Reporting-core contains pure TypeScript modules organized around reporting domain behavior:

• domain: reporting contracts, value objects, controlled vocabularies, and business rules
• application/calculations: calculation engine, pipeline, calculator registry, calculator contracts, reusable calculators, and carbon calculators
• application/definitions: report definition registry
• application/builders: semantic report builder
• shared/result: serializable result primitives for expected domain failures

All modules are deterministic and framework-neutral. They do not perform I/O, fetch data, persist records, render UI, or generate files.

Public API

Consumers import from the package root:

import {
  createCalculationEngine,
  createReportBuilder,
  createReportDefinitionRegistry,
  createScope1StationaryCombustionCalculator,
  failure,
  success,
  type CalculationInput,
  type CalculationResult,
  type ReportDefinition,
  type ReportDocument
} from "@moderta/reporting-core";

The package exposes:

• domain contracts such as ReportDefinition, ReportDocument, Metric, ReportTable, CalculationInput, CalculationContext, and CalculationResult
• controlled vocabularies such as ReportTypes, ReportSectionKinds, MetricValueTypes, AggregationTypes, and FilterOperators
• business rule primitives and report rules
• the calculation engine, pipeline, stages, and calculator registry
• reusable calculators such as createNumericSumCalculator
• Scope 1 carbon calculators for stationary combustion, mobile combustion, fugitive emissions, and process emissions
• the report definition registry
• the semantic report builder
• result primitives such as Result, success, failure, isSuccess, and isFailure

Responsibilities

Reporting-core owns:

• reporting-domain invariants and business rules
• calculation orchestration
• pure calculator implementations
• report definition registration and lookup
• semantic report document assembly
• framework-neutral error and warning propagation

Reporting-core does not own:

• HTTP controllers or clients
• database access, repositories, or migrations
• NestJS modules, providers, decorators, or dependency injection
• React components or frontend state
• HTML, PDF, Word, or Excel rendering/export
• authentication, authorization, or tenancy enforcement
• infrastructure SDK integration
• report scheduling or background jobs

How Other Packages Use It

Reporting backends should load or construct ReportDefinition objects, register them with createReportDefinitionRegistry, run calculations with createCalculationEngine, and build semantic ReportDocument objects with createReportBuilder.

Rendering packages should consume the generated ReportDocument and transform it into HTML, PDF, Word, Excel, or UI-specific output outside this package.

Shared data contract changes should be made in @moderta/api-contracts, not in reporting-core.