OC Hash Builder

1.0.5 · active · verified Sun Apr 19

oc-hash-builder is a utility library within the OpenComponents (OC) ecosystem, designed to provide deterministic hashing capabilities. Its primary role is to generate consistent hashes for component-related data, configurations, and content, which is crucial for OpenComponents' internal mechanisms such as caching, component identification, and versioning. As of version 1.0.5, it represents a stable initial release. The library's release cadence is likely tied to the broader OpenComponents project, focusing on stability and integration rather than frequent, independent updates. A key differentiator is its purpose-built nature for the OpenComponents framework, ensuring compatibility and adherence to OC's specific requirements for managing and deploying micro-frontends. It ships with TypeScript types, facilitating its use in modern JavaScript and TypeScript projects.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'buildHash')
```
cause Attempting to import `buildHash` (or similar) from `oc-hash-builder` using CommonJS `require()` syntax when the package is primarily ESM, or vice-versa.

fix If using Node.js with ESM, ensure your `package.json` has `"type": "module"` or use `.mjs` extension, and use `import { buildHash } from 'oc-hash-builder';`. For CommonJS, try `const { buildHash } = require('oc-hash-builder');` (though ESM is more likely preferred).
```
Hash mismatch for identical component configurations.
```
cause The hashing function might be sensitive to property order in objects or other minor differences (e.g., whitespace in strings, differing number types) that are semantically identical but produce different serialized forms.

fix Inspect the `oc-hash-builder`'s documentation or source for details on how it handles object serialization. Ensure inputs are consistently formatted (e.g., sorted object keys, normalized whitespace) before hashing. If hashing custom classes, ensure a consistent serialization method like `toJSON()` is implemented if the hash builder relies on it.

Warnings

gotcha Deterministic hashing is crucial. If the library processes objects, ensure it handles property order consistently (e.g., by sorting keys) to produce identical hashes for logically equivalent inputs.
Fix: Always use stable versions and verify output if relying on hash stability across different environments or code changes. Avoid manually changing the input structure if order-dependent hashing is suspected.
deprecated Older hashing algorithms like SHA-1 are cryptographically weak and deprecated for security-sensitive contexts. While `oc-hash-builder`'s primary use might be for unique identification rather than cryptographic security, using stronger algorithms like SHA-256 is a best practice. The OpenComponents ecosystem has shown awareness of SHA-1 deprecation in related projects (e.g., openclaw shifted to SHA-256).
Fix: Check the underlying hashing algorithm used by `oc-hash-builder`. If it's SHA-1, consider contributing or requesting an update to SHA-256 or a stronger algorithm for new versions, especially if the hashes are used in security-relevant ways. If you need cryptographic strength, use a dedicated crypto library.
gotcha Hashing mutable objects can lead to inconsistent hashes if the object changes after being hashed, breaking cache integrity or component identification. The hash should represent a fixed state.
Fix: Always hash immutable data structures or create a deep copy of mutable objects before hashing them. Ensure that once an object is hashed and its hash is used as an identifier, the object itself is not modified.

Install

npm install oc-hash-builder npm
yarn add oc-hash-builder yarn
pnpm add oc-hash-builder pnpm

Imports

buildHash
wrong:
```
const buildHash = require('oc-hash-builder');
```
correct:
```
import { buildHash } from 'oc-hash-builder';
```
Assumed named export based on common utility patterns and TypeScript types. ESM is preferred.
HashBuilder
```
import { HashBuilder } from 'oc-hash-builder';
```
If the utility is exposed as a class for more complex scenarios or configuration.
default
```
import hashBuilder from 'oc-hash-builder';
```
Possible default export for a simpler, direct hashing function if no specific configurations are needed.

Quickstart

Demonstrates how to use `oc-hash-builder` to create deterministic hashes for objects and strings, which is critical for identifying and caching OpenComponents artifacts.

import { buildHash } from 'oc-hash-builder';

// Example 1: Hashing a simple object
const componentConfig = {
  name: 'my-component',
  version: '1.0.0',
  dependencies: ['lodash@4.17.21'],
  settings: {
    env: 'production'
  }
};
const configHash = buildHash(componentConfig);
console.log(`Hash for component config: ${configHash}`);

// Example 2: Hashing a string (e.g., component template content)
const templateContent = `<div>Hello, {{name}}!</div>`;
const contentHash = buildHash(templateContent);
console.log(`Hash for template content: ${contentHash}`);

// Example 3: Ensuring deterministic hashing
const sameConfigDifferentOrder = {
  settings: {
    env: 'production'
  },
  dependencies: ['lodash@4.17.21'],
  name: 'my-component',
  version: '1.0.0'
};
const orderIndependentHash = buildHash(sameConfigDifferentOrder);
console.log(`Hash for reordered config (should be same): ${orderIndependentHash}`);

// In a real OpenComponents context, this might be used internally or exposed
// via a plugin system for ensuring component integrity and cache keys.
// For instance, during component publishing or rendering lifecycle.

view raw JSON →