cal-vals

cal-vals is an npm package designed to manage changing values over time. It provides a robust and traceable way to handle values whose changes are fully auditable and can be recalculated for any given point in time. This library is particularly useful for scenarios where historical data tracking and value regeneration are critical.

The library supports two types of values:

• Additive Values: Numeric values where changes are tracked as additions or subtractions. Each operation is logged, and the cumulative value can be recalculated at any point in time.
• Fixed Values: String values where changes replace the previous value. The full history of changes is preserved, and the value at a specific point in time can be restored.

Features

• Time-based Value Management: Track how values change over time.
• Traceability: Fully trace and audit all changes to a value.
• Regeneration: Recalculate the value of a variable at any specific point in time.
• Model-Driven Design: Built around a flexible and extensible model structure.
• CalVal Class: Centralized functionality for managing and auditing value changes.

Installation

npm install cal-vals

Usage

Importing the Library

const { CalVal, Model } = require('cal-vals');

Defining a Model

The Model class allows you to define the structure of your data.

const myModel = new Model({
    name: 'exampleModel',
    fields: ['field1', 'field2', 'field3']
});

Using the CalVal Class

The CalVal class provides all the functionality for managing and auditing value changes.

const calVal = new CalVal(myModel);

// Add a value with a timestamp
calVal.addValue('field1', 100, new Date('2023-01-01'));

// Update the value at a later time
calVal.addValue('field1', 150, new Date('2023-02-01'));

// Retrieve the value at a specific point in time
const valueAtTime = calVal.getValue('field1', new Date('2023-01-15'));
console.log(valueAtTime); // Output: 100

// Audit all changes to a field
const auditLog = calVal.getAuditLog('field1');
console.log(auditLog);

API Reference

Model

• Constructor: new Model(config)
  • config: An object defining the model's name and fields.
• Methods:
  • getFields(): Returns the list of fields in the model.

CalVal

• Constructor: new CalVal(model)
  • model: An instance of the Model class.
• Methods:
  • addValue(field, value, timestamp): Adds or updates a value for a specific field at a given timestamp.
  • getValue(field, timestamp): Retrieves the value of a field at a specific timestamp.
  • getAuditLog(field): Returns the audit log of all changes for a specific field.

Use Cases

• Financial Applications: Track and audit changes in financial data over time.
• Versioned Data: Manage historical versions of data in a traceable way.
• Auditing Systems: Ensure full traceability and accountability for value changes.

Contributing

Contributions are welcome! Please submit a pull request or open an issue on the GitHub repository.

License

This project is licensed under the TBD.

Acknowledgments

Special thanks to all contributors and users who have supported the development of this library.