How dmidlo/get-datahash works
Main Components
• Core Module (DataHash Engine):
– The heart of the project is implemented in Get-DataHash.psm1 (and its variations in private/types/DataHash.psm1). This is where the hashing logic, normalizations (like sorting unordered collections, preserving ordered ones, handling circular references, and floating-point normalization), and field exclusion are implemented.
• Custom Type Mappers:
– The “private/types/Mappers” directory contains scripts (e.g., Mapper_PSCustomClass_DataHash.ps1) that extend the core module with custom serialization and type-mapping capabilities (leveraging LiteDB’s BsonMapper features).
• Public Interface:
– The “public” folder holds a user-facing script (Get-DataHash.ps1) which acts as an entry point to call the DataHash functions from a script or interactive session.
• External Dependency (LiteDB/BSON Serialization):
– As documented in the README, DataHash uses LiteDB’s BSON serialization (see LiteDB.xml and references in the README) to ensure consistent serialization across runs. This component ensures that PowerShell native quirks (like unordered collections or JSON issues) do not affect the hash.
• Testing and Validation Components:
– The “tests” and individual test scripts (like Constructors.Tests.ps1, ComparisonOperators.Tests.ps1, etc.) validate that the module produces stable, consistent results across various input types.
• Additional Development & Standards:
– Files like STANDARDS.md or the .vscode folder indicate coding standards and development environment configurations but are less central to the runtime architecture from an execution perspective.
Relationships and Data Flow
• Input Data (PowerShell objects) → Public Interface:
– Users pass objects to the public script or call the module’s constructors.
• Public Interface → Core Module:
– The main processes call functions within Get-DataHash.psm1 to perform the digest calculations.
• Core Module → LiteDB Serialization:
– When processing objects, the module delegates serialization tasks to LiteDB’s BSON library (illustrated by references to LiteDB.xml) to ensure precision.
• Core Module → Custom Type Mappers:
– For custom or complex objects, the engine calls the mappers found under “private/types/Mappers” to standardize object representation.
• Core Module → Output (Message Digest):
– Once all transformations and normalizations occur, the engine returns a stable message digest (the final output is then used for change tracking, caching, or auditing).
• Tests interact with all these components to ensure consistency.
Architectural Patterns and Principles
• Normalization and Determinism:
– Emphasize that the system sorts unordered collections, preserves order when needed, and applies normalization (such as IEEE 754 conversions for floats) to maintain digest stability.
• Separation of Concerns:
– Notice how the design modularizes the core hashing logic, type mapping, and external serialization. This makes it easier to test (see the comprehensive tests folder) and extend.
• Extensibility:
– By having a directory for custom mappers, the architecture supports extensions to handle additional data types without altering core logic.
• External Integration: