onroute-policy-engine 2.3.1 → 2.4.0

package/README.md

@@ -1,51 +1,323 @@
-A JSON-based rules engine to validate onRouteBC permit applications against commercial vehicle policy.
+# onRouteBC Policy Engine
 
+A comprehensive JSON-based rules engine for validating commercial vehicle permit applications against British Columbia's transportation policy regulations.
 
-## Synopsis
-```orbc-policy-engine``` is a library designed to compare a commercial vehicle permit application against policy expressed in JSON format, and return a list of policy violations as well as other informational policy messages related to the permit.
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7.2-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
 
-```orbc-policy-engine``` makes use of https://github.com/CacheControl/json-rules-engine for rules engine functionality. Complex rules are modeled by extending the core ```json-rules-engine``` operators and other capabilities.
+## Overview
 
-## Usage
-```js
-import Policy from 'orbc-policy-engine';
+The onRouteBC Policy Engine is a sophisticated validation library designed to ensure commercial vehicle permit applications comply with British Columbia's transportation regulations. It provides a flexible, rule-based system that can validate complex vehicle configurations, weight distributions, axle arrangements, and permit requirements.
 
-// Instantiate a new Policy object
-// policyDefinition is a JSON object of type PolicyDefinition
-const policy: Policy = new Policy(policyDefinition);
+### Key Features
 
-// Get list of all available permit types (ID and name)
-const permitTypes: Map<string, string> = policy.getPermitTypes();
+- **Comprehensive Vehicle Validation**: Validates vehicle configurations, weights, dimensions, and axle arrangements
+- **Policy-Driven Rules**: Uses JSON-based policy definitions for flexible rule configuration
+- **Bridge Formula Calculations**: Implements provincial bridge formula requirements for axle group weight limits
+- **Tire Load Validation**: Ensures tire configurations meet safety and regulatory requirements
+- **Weight Distribution Checks**: Validates proper weight distribution across vehicle axles
+- **Permit Type Support**: Handles multiple permit types including Term Oversize, Single Trip Oversize, and Motive Fuel
+- **Commodity-Based Validation**: Supports commodity-specific permit requirements
+- **Extensible Architecture**: Built on json-rules-engine with custom operators for complex validations
 
-// Get list of all available commodities (ID and name)
-const commodities: Map<string, string> = policy.getCommodities();
+## Installation
 
-// Get list of all available power unit types
-const powerUnits: Map<string, string> = policy.getPowerUnitTypes();
+```bash
+npm install onroute-policy-engine
+```
+
+## Quick Start
+
+```typescript
+import Policy from 'onroute-policy-engine';
+
+// Load your policy definition
+const policyDefinition = require('./policy-definition.json');
+
+// Create policy instance
+const policy = new Policy(policyDefinition);
+
+// Validate a permit application
+const permitApplication = {
+  permitType: 'TROS',
+  permitData: {
+    // Your permit data here
+  }
+};
+
+const results = await policy.validate(permitApplication);
+console.log(results);
+```
+
+## Core Concepts
+
+### Policy Definition
+
+The policy engine uses a JSON-based policy definition that describes:
+- **Permit Types**: Different types of permits (TROS, STOS, MFP, etc.)
+- **Vehicle Types**: Power units and trailers with their characteristics
+- **Validation Rules**: Complex rules for weight, dimension, and configuration validation
+- **Commodities**: Cargo types that affect permit requirements
+
+### Vehicle Configuration
+
+A vehicle configuration consists of:
+- **Power Units**: The primary vehicle (truck, tractor, etc.)
+- **Trailers**: Additional units being towed
+- **Axle Configurations**: Detailed axle arrangements with weights and dimensions
+
+### Validation Results
+
+The engine returns comprehensive validation results including:
+- **Policy Violations**: Specific rule violations with detailed messages
+- **Informational Messages**: Guidance and recommendations
+- **Axle Calculations**: Bridge formula and weight distribution results
+
+## API Reference
+
+### Main Policy Class
+
+```typescript
+class Policy {
+  constructor(policyDefinition: PolicyDefinition)
+  
+  // Core validation
+  validate(permitApplication: PermitApplication): Promise<ValidationResults>
+  
+  // Vehicle configuration validation
+  runAxleCalculation(
+    vehicleConfiguration: string[],
+    axleConfiguration: AxleConfiguration[],
+    licensedGVW: number
+  ): AxleCalcResults
+  
+  // Policy information
+  getPermitTypes(): Map<string, string>
+  getCommodities(permitTypeId?: string): Map<string, string>
+  getPowerUnitTypes(): Map<string, string>
+  getTrailerTypes(): Map<string, string>
+  
+  // Vehicle configuration helpers
+  getNextPermittableVehicles(
+    permitTypeId: string,
+    commodityId: string,
+    currentConfiguration: string[]
+  ): Map<string, string>
+  
+  // Weight and dimension calculations
+  getDefaultPowerUnitWeight(vehicleType: string, axleCode: number): WeightDimension[]
+  getDefaultTrailerWeight(vehicleType: string, axles: number): TrailerWeightDimension[]
+  calculateBridge(axleConfiguration: AxleConfiguration[]): BridgeCalculationResult[]
+}
+```
+
+### Key Types
+
+```typescript
+interface PermitApplication {
+  permitType: string;
+  permitData: any;
+}
+
+interface ValidationResults {
+  results: ValidationResult[];
+  summary: {
+    totalViolations: number;
+    totalWarnings: number;
+    totalInfo: number;
+  };
+}
+
+interface AxleConfiguration {
+  numberOfAxles: number;
+  numberOfTires?: number;
+  tireSize?: number;
+  axleUnitWeight: number;
+  axleSpread?: number;
+}
+```
+
+## Usage Examples
+
+### Basic Permit Validation
+
+```typescript
+import Policy from 'onroute-policy-engine';
+
+const policy = new Policy(policyDefinition);
+
+const permitApp = {
+  permitType: 'TROS',
+  permitData: {
+    vehicleConfiguration: ['TRKTRAC', 'SEMITRL'],
+    axleConfiguration: [
+      { numberOfAxles: 2, axleUnitWeight: 12000, numberOfTires: 4, tireSize: 445 },
+      { numberOfAxles: 3, axleUnitWeight: 34000, numberOfTires: 12, tireSize: 445 },
+      { numberOfAxles: 3, axleUnitWeight: 34000, numberOfTires: 12, tireSize: 445 }
+    ],
+    licensedGVW: 63500
+  }
+};
+
+const results = await policy.validate(permitApp);
+console.log(`Validation completed with ${results.violations.length} violations`);
+```
+
+### Axle Calculation Validation
+
+```typescript
+// Validate axle configuration against policy rules
+const axleResults = policy.runAxleCalculation(
+  ['TRKTRAC', 'SEMITRL'],
+  [
+    { numberOfAxles: 2, axleUnitWeight: 12000, numberOfTires: 4, tireSize: 445 },
+    { numberOfAxles: 3, axleUnitWeight: 34000, numberOfTires: 12, tireSize: 445 },
+    { numberOfAxles: 3, axleUnitWeight: 34000, numberOfTires: 12, tireSize: 445 }
+  ],
+  63500
+);
+
+console.log('Axle validation results:', axleResults.results);
+```
+
+### Getting Available Options
+
+```typescript
+// Get all available permit types
+const permitTypes = policy.getPermitTypes();
+console.log('Available permit types:', Array.from(permitTypes.entries()));
+
+// Get commodities for a specific permit type
+const commodities = policy.getCommodities('TROS');
+console.log('TROS commodities:', Array.from(commodities.entries()));
 
-// Get list of all available trailer types
-const trailers: Map<string, string> = policy.getTrailerTypes();
+// Get valid next vehicles for a configuration
+const nextVehicles = policy.getNextPermittableVehicles(
+  'STOS',
+  'IMCONTN',
+  ['TRKTRAC']
+);
+console.log('Valid next vehicles:', Array.from(nextVehicles.entries()));
+```
+
+## Policy Check Rules
+
+The engine implements several key validation rules:
+
+1. **Bridge Formula Check**: Validates axle group weights based on axle spacing
+2. **Number of Wheels Per Axle**: Ensures valid tire counts per axle unit
+3. **Permittable Weight Check**: Validates axle unit weights against limits
+4. **Minimum Steer Axle Weight**: Ensures proper front axle weight distribution
+5. **Minimum Drive Axle Weight**: Validates drive axle weight requirements
+6. **Maximum Tire Load**: Checks tire load capacity based on size and quantity
+
+For detailed information about these rules, see [Policy Check Rules Documentation](./docs/policy-check-rules.md).
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- TypeScript 5.7+
+- npm or yarn
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/bcgov/onroutebc-policy-engine.git
+cd onroutebc-policy-engine
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Run linting
+npm run lint
+```
+
+### Project Structure
+
+```
+src/
+├── enum/                 # Enumerations and constants
+├── helper/              # Helper functions and utilities
+├── types/               # TypeScript type definitions
+├── _examples/           # Usage examples and demos
+├── _test/               # Test data and configurations
+├── policy-engine.ts     # Main policy engine implementation
+├── validation-result.ts # Validation result types
+└── index.ts            # Public API exports
+```
 
-// Get list of all valid commodities for a given permit type
-const commodities: Map<string, string> = policy.getCommodities(permitTypeId);
+### Building
 
-// Get list of all vehicle types valid to be added to a configuration,
-// by permit type and commodity. Requires supplying the vehicles already
-// added to the configuration, or empty array if starting from scratch
-const allowableVehicles: Map<string, string> = policy.getNextPermittableVehicles(
-  permitTypeId, 
-  commodityId, 
-  currentConfiguration);
+```bash
+# Clean build
+npm run clean-build
 
-// Validate a permit application against policy
-// permitApplication is a JSON object of type PermitApplication
-// A PermitApplication is the standard permitData object wrapped
-// in an object with a permitType key. For example:
-// {
-//   permitType: 'TROS',
-//   permitData: { ... }
-// }
-// Note this is an async call due to the reliance on json-rules-engine
-const results: ValidationResults = await policy.validate(permitApplication);
+# Development build
+npm run build
 ```
 
+## Documentation
+
+- [Policy Configuration Reference](./docs/policy-configuration-reference.md) - Detailed policy definition format
+- [Validation Result Reference](./docs/validation-result-reference.md) - Understanding validation results
+- [Basic Client-Server Flow](./docs/basic-client-server-flow.md) - Integration patterns
+- [Policy Check Rules](./docs/policy-check-rules.md) - Detailed explanation of validation rules
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Commit your changes (`git commit -m 'Add new feature'`)
+4. Push to the branch (`git push origin feature/new-feature`)
+5. Open a Pull Request
+
+### Code Style
+
+- Follow TypeScript best practices
+- Use ESLint and Prettier for code formatting
+- Write comprehensive tests for new features
+- Update documentation for API changes
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test -- validate-tros.spec.ts
+```
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+For questions, issues, or contributions:
+
+- **Issues**: [GitHub Issues](https://github.com/bcgov/onroutebc-policy-engine/issues)
+- **Documentation**: Check the [docs](./docs/) directory
+- **Examples**: See [src/_examples](./src/_examples/) for usage examples
+
+## Related Projects
+
+- [json-rules-engine](https://github.com/CacheControl/json-rules-engine) - Core rules engine functionality
+- [onRouteBC](https://onroutebc.gov.bc.ca/) - British Columbia's commercial vehicle permitting system
+
+---
+
+**Note**: This policy engine is specifically designed for British Columbia's commercial vehicle regulations. Ensure compliance with local regulations when adapting for other jurisdictions.

package/dist/policy-engine.d.ts

@@ -341,4 +341,23 @@ export declare class Policy {
      * // Returns: ['TRKTRAC']
      */
     getSimplifiedVehicleConfiguration(vehicleDetails: PermitVehicleDetails, vehicleConfiguration: VehicleConfiguration): string[];
+    /**
+     * Given a commodity and selected power unit subtype for a permit type,
+     * return whether or not axle units can be added to the power unit.
+     * @param permitType The permit type
+     * @param commodityId The commodity id
+     * @param powerUnitSubtype The id representing the power unit subtype
+     * @returns true if the axle units can be added to the power unit, false otherwise
+     */
+    canAddAxleUnitsToPowerUnit(permitTypeId: string, commodityId?: string | null, powerUnitSubtype?: string | null): boolean;
+    /**
+     * Given a commodity, selected power unit and trailer subtype for a permit type,
+     * return whether or not axle units can be added to the trailer.
+     * @param permitType The permit type
+     * @param commodityId The commodity id
+     * @param powerUnitSubtype The id representing the power unit subtype
+     * @param trailerSubtype The id representing the trailer subtype
+     * @returns true if the axle units can be added to the trailer, false otherwise
+     */
+    canAddAxleUnitsToTrailer(permitTypeId: string, commodityId?: string | null, powerUnitSubtype?: string | null, trailerSubtype?: string | null): boolean;
 }

package/dist/policy-engine.js

@@ -858,5 +858,72 @@ class Policy {
     getSimplifiedVehicleConfiguration(vehicleDetails, vehicleConfiguration) {
         return (0, vehicles_helper_1.getSimplifiedVehicleConfigurationHelper)(vehicleDetails, vehicleConfiguration);
     }
+    /**
+     * Given a commodity and selected power unit subtype for a permit type,
+     * return whether or not axle units can be added to the power unit.
+     * @param permitType The permit type
+     * @param commodityId The commodity id
+     * @param powerUnitSubtype The id representing the power unit subtype
+     * @returns true if the axle units can be added to the power unit, false otherwise
+     */
+    canAddAxleUnitsToPowerUnit(permitTypeId, commodityId, powerUnitSubtype) {
+        if (!permitTypeId || !commodityId || !powerUnitSubtype) {
+            throw new Error('Missing permitTypeId and/or commodityId and/or powerUnitSubtype');
+        }
+        const permitType = this.getPermitTypeDefinition(permitTypeId);
+        if (!permitType) {
+            throw new Error(`Invalid permit type: '${permitTypeId}'`);
+        }
+        if (!permitType.commodityRequired) {
+            // If commodity is not required, this method cannot check whether or not
+            // axle units can be added, since they will not be configured.
+            throw new Error(`Permit type '${permitTypeId}' does not require a commodity`);
+        }
+        const commodity = this.getCommodityDefinition(commodityId);
+        if (!commodity) {
+            throw new Error(`Invalid commodity type: '${commodityId}'`);
+        }
+        const powerUnit = commodity.powerUnits.find(pu => pu.type === powerUnitSubtype);
+        if (!powerUnit) {
+            throw new Error(`Invalid power unit: '${powerUnitSubtype}'`);
+        }
+        return Boolean(powerUnit.canAddAxleUnits);
+    }
+    /**
+     * Given a commodity, selected power unit and trailer subtype for a permit type,
+     * return whether or not axle units can be added to the trailer.
+     * @param permitType The permit type
+     * @param commodityId The commodity id
+     * @param powerUnitSubtype The id representing the power unit subtype
+     * @param trailerSubtype The id representing the trailer subtype
+     * @returns true if the axle units can be added to the trailer, false otherwise
+     */
+    canAddAxleUnitsToTrailer(permitTypeId, commodityId, powerUnitSubtype, trailerSubtype) {
+        if (!permitTypeId || !commodityId || !powerUnitSubtype || !trailerSubtype) {
+            throw new Error('Missing permitTypeId, commodityId, powerUnitSubtype, and/or trailerSubtype');
+        }
+        const permitType = this.getPermitTypeDefinition(permitTypeId);
+        if (!permitType) {
+            throw new Error(`Invalid permit type: '${permitTypeId}'`);
+        }
+        if (!permitType.commodityRequired) {
+            // If commodity is not required, this method cannot check whether or not
+            // axle units can be added, since they will not be configured.
+            throw new Error(`Permit type '${permitTypeId}' does not require a commodity`);
+        }
+        const commodity = this.getCommodityDefinition(commodityId);
+        if (!commodity) {
+            throw new Error(`Invalid commodity type: '${commodityId}'`);
+        }
+        const powerUnit = commodity.powerUnits.find(pu => pu.type === powerUnitSubtype);
+        if (!powerUnit) {
+            throw new Error(`Invalid power unit: '${powerUnitSubtype}'`);
+        }
+        const trailer = powerUnit.trailers.find(trailer => trailer.type === trailerSubtype);
+        if (!trailer) {
+            throw new Error(`Invalid trailer: '${trailerSubtype}'`);
+        }
+        return Boolean(trailer.canAddAxleUnits);
+    }
 }
 exports.Policy = Policy;

package/dist/types/vehicle.d.ts

@@ -22,6 +22,8 @@ export type VehicleDimensions = Vehicle & {
     trailers: Array<TrailerDimensions>;
     /** Array of weight dimensions for this power unit (optional) */
     weightDimensions?: Array<PowerUnitWeightDimension>;
+    /** Whether or not axle units can be added for this power unit (optional) */
+    canAddAxleUnits?: boolean;
 };
 /**
  * Trailer with booster/jeep configuration and dimension capabilities
@@ -40,4 +42,6 @@ export type TrailerDimensions = Vehicle & {
     weightDimensions?: Array<TrailerWeightDimension>;
     /** Whether weight is permittable for this trailer (optional) */
     weightPermittable?: boolean;
+    /** Whether or not axle units can be added for this trailer (optional) */
+    canAddAxleUnits?: boolean;
 };

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "v2.3.1";
+export declare const version = "v2.4.0";

package/dist/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // Generated by genversion.
-exports.version = 'v2.3.1';
+exports.version = 'v2.4.0';

package/package.json

@@ -91,5 +91,5 @@
     ],
     "testEnvironment": "node"
   },
-  "version": "v2.3.1"
+  "version": "v2.4.0"
 }