@hkdigital/lib-core 0.4.56 → 0.4.58

package/dist/generic/data/util/flat-tree.js

@@ -0,0 +1,261 @@
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../../../util/expect.js';
+
+/* ------------------------------------------------------------------ Exports */
+
+/**
+ * Build a hierarchical tree from ft1 flat tree format
+ *
+ * @template {object} T
+ * @param {import('./typedef.js').FlatTree<T>} flatTree - Flat tree data
+ *
+ * @returns {T|null} reconstructed hierarchical tree or null
+ */
+export function buildTree(flatTree) {
+  expect.object(flatTree);
+
+  const { format, properties, nodes, edges } = flatTree;
+
+  if (format !== 'ft1') {
+    throw new Error(`Unsupported format: ${format}. Expected 'ft1'`);
+  }
+
+  if (!nodes || !nodes.length) {
+    return null;
+  }
+
+  if (!edges || !edges.length) {
+    return { ...nodes[0] };
+  }
+
+  if (edges.length % 3 !== 0) {
+    throw new Error('Invalid edges array: length must be multiple of 3');
+  }
+
+  // Create copies of all nodes to avoid mutating original data
+  const nodesCopy = nodes.map(node => ({ ...node }));
+
+  // Process edges in groups of 3: [from, prop, to]
+  for (let i = 0; i < edges.length; i += 3) {
+    const fromIndex = edges[i];
+    const propIndex = edges[i + 1];
+    const toIndex = edges[i + 2];
+
+    // Validate indices
+    if (fromIndex >= nodesCopy.length || toIndex >= nodesCopy.length) {
+      throw new Error(`Invalid node index in edge [${fromIndex}, ${propIndex}, ${toIndex}]`);
+    }
+
+    if (propIndex >= properties.length) {
+      throw new Error(`Invalid property index: ${propIndex}`);
+    }
+
+    const fromNode = nodesCopy[fromIndex];
+    const toNode = nodesCopy[toIndex];
+    const propertyName = properties[propIndex];
+
+    // Add child to parent's property
+    /** @type {any} */
+    const dynamicFromNode = fromNode;
+
+    if (!dynamicFromNode[propertyName]) {
+      dynamicFromNode[propertyName] = [toNode];
+    } else if (Array.isArray(dynamicFromNode[propertyName])) {
+      // Check if this node is already in the array (shared reference)
+      if (!dynamicFromNode[propertyName].includes(toNode)) {
+        dynamicFromNode[propertyName].push(toNode);
+      }
+    } else {
+      // Convert single child to array
+      dynamicFromNode[propertyName] = [dynamicFromNode[propertyName], toNode];
+    }
+  }
+
+  return nodesCopy[0];
+}
+
+/**
+ * Flatten a hierarchical tree into ft1 flat tree format
+ *
+ * @template {object} T
+ * @param {T} hierarchicalTree - Hierarchical tree with nested children
+ *
+ * @returns {import('./typedef.js').FlatTree<T>} flat tree data
+ */
+export function flattenTree(hierarchicalTree) {
+  expect.object(hierarchicalTree);
+
+  /** @type {T[]} */
+  const nodes = [];
+  
+  /** @type {number[]} */
+  const edges = [];
+  
+  /** @type {Set<string>} */
+  const propertySet = new Set();
+  
+  /** @type {WeakMap<object, number>} */
+  const objectToIndex = new WeakMap();
+
+  // First pass: collect all child-containing properties
+  const childProperties = new Set();
+  findChildProperties(hierarchicalTree, childProperties);
+
+  // Add root node (always index 0)
+  const rootCopy = extractNodeData(hierarchicalTree, childProperties);
+  nodes.push(rootCopy);
+  objectToIndex.set(hierarchicalTree, 0);
+
+  // Process children recursively
+  processChildrenFt1(
+    hierarchicalTree,
+    0,
+    nodes,
+    edges,
+    propertySet,
+    objectToIndex,
+    childProperties
+  );
+
+  // Convert property set to sorted array for consistent output
+  const properties = Array.from(propertySet).sort();
+
+  // Convert property names to indices in edges array
+  for (let i = 1; i < edges.length; i += 3) {
+    const propertyName = /** @type {string} */ (edges[i]);
+    edges[i] = properties.indexOf(propertyName);
+  }
+
+  return /** @type {import('./typedef.js').FlatTree<T>} */ ({
+    format: 'ft1',
+    properties,
+    nodes,
+    edges
+  });
+}
+
+/* ---------------------------------------------------------- Private methods */
+
+/**
+ * Extract node data excluding children properties
+ *
+ * @param {object} node - Source node
+ * @param {Set<string>} propertiesToRemove - Set of property names to remove
+ *
+ * @returns {object} node data without children properties
+ */
+function extractNodeData(node, propertiesToRemove) {
+  /** @type {any} */
+  const nodeData = { ...node };
+
+  // Remove all child-containing properties
+  for (const key of propertiesToRemove) {
+    delete nodeData[key];
+  }
+
+  return nodeData;
+}
+
+/**
+ * Find all properties that contain child objects
+ *
+ * @param {object} node - Node to analyze
+ * @param {Set<string>} childProperties - Set to collect property names
+ */
+function findChildProperties(node, childProperties) {
+  // Find array properties that contain objects (potential children)
+  for (const [key, value] of Object.entries(node)) {
+    if (Array.isArray(value) && value.length > 0) {
+      // Check if array contains objects (potential children)
+      const hasObjects = value.some(item => item && typeof item === 'object');
+      if (hasObjects) {
+        childProperties.add(key);
+      }
+    }
+  }
+
+  // Recursively check child nodes
+  for (const key of [...childProperties]) {  // Copy set to avoid modification during iteration
+    const children = node[key];
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        if (child && typeof child === 'object') {
+          findChildProperties(child, childProperties);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Recursively process children for ft1 format
+ *
+ * @param {object} parentNode - Parent node with children
+ * @param {number} parentIndex - Parent node index
+ * @param {object[]} nodes - Nodes array to populate
+ * @param {(number|string)[]} edges - Edges array to populate (mixed types temporarily)
+ * @param {Set<string>} propertySet - Set of property names
+ * @param {WeakMap<object, number>} objectToIndex - Map of objects to indices
+ * @param {Set<string>} childProperties - Set of all child-containing properties
+ */
+function processChildrenFt1(parentNode, parentIndex, nodes, edges, propertySet, objectToIndex, childProperties) {
+  // Process all child-containing properties
+  for (const property of childProperties) {
+    const children = parentNode[property];
+    
+    if (!children) {
+      continue;
+    }
+    
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        if (child && typeof child === 'object') {
+          processChildFt1(child, parentIndex, property, nodes, edges, propertySet, objectToIndex, childProperties);
+        }
+      }
+    } else if (children && typeof children === 'object') {
+      processChildFt1(children, parentIndex, property, nodes, edges, propertySet, objectToIndex, childProperties);
+    }
+  }
+}
+
+/**
+ * Process a single child node for ft1 format
+ *
+ * @param {object} child - Child node
+ * @param {number} parentIndex - Parent node index
+ * @param {string} property - Property name where this child belongs
+ * @param {object[]} nodes - Nodes array to populate
+ * @param {(number|string)[]} edges - Edges array to populate (mixed types temporarily)
+ * @param {Set<string>} propertySet - Set of property names
+ * @param {WeakMap<object, number>} objectToIndex - Map of objects to indices
+ * @param {Set<string>} childProperties - Set of all child-containing properties
+ */
+function processChildFt1(child, parentIndex, property, nodes, edges, propertySet, objectToIndex, childProperties) {
+  if (!child || typeof child !== 'object') {
+    return;
+  }
+
+  // Track property name
+  propertySet.add(property);
+
+  // Check if we've seen this object before
+  let childIndex = objectToIndex.get(child);
+  
+  if (childIndex === undefined) {
+    // First time seeing this object - add it to nodes
+    childIndex = nodes.length;
+    const childCopy = extractNodeData(child, childProperties);
+    nodes.push(childCopy);
+    objectToIndex.set(child, childIndex);
+  }
+
+  // Add edge (temporarily store property name as string, will convert to index later)
+  edges.push(parentIndex, property, childIndex);
+  
+  // If this is a new object, recursively process its children
+  if (objectToIndex.get(child) === childIndex) {
+    processChildrenFt1(child, childIndex, nodes, edges, propertySet, objectToIndex, childProperties);
+  }
+}

package/dist/generic/data/util/typedef.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Flat tree data structure in ft1 format
+ */
+export type FlatTree<T extends object> = {
+    /**
+     * - Format version ('ft1')
+     */
+    format: string;
+    /**
+     * - Array of property names used in edges
+     */
+    properties: string[];
+    /**
+     * - Array of node objects (index 0 = root)
+     */
+    nodes: T[];
+    /**
+     * - Flat array: [from, prop, to, from, prop, to, ...]
+     */
+    edges: number[];
+};

package/dist/generic/data/util/typedef.js

@@ -0,0 +1,14 @@
+/* ------------------------------------------------------------------ Typedef */
+
+/**
+ * Flat tree data structure in ft1 format
+ *
+ * @template {object} T
+ * @typedef {object} FlatTree
+ * @property {string} format - Format version ('ft1')
+ * @property {string[]} properties - Array of property names used in edges
+ * @property {T[]} nodes - Array of node objects (index 0 = root)
+ * @property {number[]} edges - Flat array: [from, prop, to, from, prop, to, ...]
+ */
+
+export {};

package/dist/generic/data.d.ts

@@ -1,2 +1,3 @@
 export { default as Selector } from "./data/classes/Selector.js";
 export { default as IterableTree } from "./data/classes/IterableTree.js";
+export { buildTree, flattenTree } from "./data/util/flat-tree.js";

package/dist/generic/data.js

@@ -1,2 +1,3 @@
 export { default as Selector } from './data/classes/Selector.js';
 export { default as IterableTree } from './data/classes/IterableTree.js';
+export { buildTree, flattenTree } from './data/util/flat-tree.js';

package/dist/util/checksum/README.md

@@ -0,0 +1,267 @@
+# CRC32 Checksum Utilities
+
+Fast, modular CRC32 implementation with support for strings, buffers, and 
+large file processing.
+
+## Features
+
+- **Standard CRC32**: IEEE 802.3 compatible (ZIP, PNG, Ethernet)
+- **CRC32C variant**: Castagnoli polynomial for improved performance
+- **Buffer support**: ArrayBuffer, DataView, Uint8Array
+- **Block processing**: Custom format for large files
+- **Zero dependencies**: Pure JavaScript implementation
+- **TypeScript ready**: Full JSDoc type annotations
+
+## Quick Start
+
+```javascript
+import { stringToCrc32 } from './stringCrc32.js';
+import { bufferToCrc32 } from './bufferCrc32.js';
+import { bufferToBlockCrc32 } from './blockCrc32.js';
+import { CRC32, CRC32C } from './crcTables.js';
+
+// String checksums (IEEE 802.3 standard)
+const crc = stringToCrc32('hello world');
+console.log(crc); // 222957957 (0xd4a1185)
+
+// Standard test vector verification
+console.log(stringToCrc32('123456789')); // 3421780262 (0xcbf43926)
+console.log(stringToCrc32('123456789', CRC32C)); // 3808858755 (0xe3069283)
+
+// Buffer checksums (standard)
+const buffer = new TextEncoder().encode('hello world');
+const bufferCrc = bufferToCrc32(buffer);
+console.log(bufferCrc); // 222957957 (same as string)
+
+// Large file processing (custom format)
+const result = bufferToBlockCrc32(buffer, 1024);
+console.log(result.checksumList); // [222957957]
+console.log(result.toBase58()); // Base58-encoded result
+```
+
+## Module Overview
+
+### `crcTables.js`
+Shared CRC table generation and constants.
+
+```javascript
+import { getCrcTable, CRC32, CRC32C } from './crcTables.js';
+
+const table = getCrcTable(CRC32); // Get lookup table
+```
+
+### `stringCrc32.js`
+String to CRC32 conversion.
+
+```javascript
+import { stringToCrc32, CRC32, CRC32C } from './stringCrc32.js';
+
+const crc = stringToCrc32('text', CRC32);  // Standard CRC32
+const crcC = stringToCrc32('text', CRC32C); // CRC32C variant
+```
+
+### `bufferCrc32.js`
+Standard buffer CRC32 - compatible with external tools.
+
+```javascript
+import { bufferToCrc32 } from './bufferCrc32.js';
+
+// Works with all buffer types
+const arrayBuffer = new ArrayBuffer(100);
+const uint8Array = new Uint8Array(100);
+const dataView = new DataView(arrayBuffer);
+
+const crc1 = bufferToCrc32(arrayBuffer);
+const crc2 = bufferToCrc32(uint8Array, 10, 50); // Offset & length
+const crc3 = bufferToCrc32(dataView);
+```
+
+### `blockCrc32.js`
+Custom block-based processing for large files.
+
+```javascript
+import { 
+  bufferToBlockCrc32, 
+  blockCrc32Iterator,
+  bufferChecksumEquals,
+  optimalBlockSize 
+} from './blockCrc32.js';
+
+// Process large buffer in blocks
+const result = bufferToBlockCrc32(largeBuffer);
+console.log(result.checksumList);  // Array of CRC32 values
+console.log(result.toBase58());    // Concatenated Base58 string
+
+// Stream processing
+for (const block of blockCrc32Iterator(buffer, 1024)) {
+  console.log(`Block at ${block.offset}: ${block.toBase58()}`);
+}
+
+// Verification
+const isValid = bufferChecksumEquals(buffer, expectedChecksum);
+```
+
+## CRC32 Variants
+
+### CRC32 (IEEE 802.3)
+- **Use case**: General purpose, file integrity
+- **Compatible with**: ZIP files, PNG images, Ethernet frames
+- **Polynomial**: `0xEDB88320` (reversed)
+- **Standard test**: `"123456789"` → `0xcbf43926` ✅
+
+### CRC32C (Castagnoli)
+- **Use case**: High-performance applications
+- **Compatible with**: iSCSI, SCTP, certain databases
+- **Polynomial**: `0x82f63b78` (reversed)
+- **Standard test**: `"123456789"` → `0xe3069283` ✅
+
+```javascript
+import { CRC32, CRC32C } from './crcTables.js';
+
+// All functions accept variant parameter
+stringToCrc32('data', CRC32);   // Default
+stringToCrc32('data', CRC32C);  // Castagnoli
+
+// Verify against standard test vectors
+console.assert(stringToCrc32('123456789', CRC32) === 0xcbf43926);
+console.assert(stringToCrc32('123456789', CRC32C) === 0xe3069283);
+```
+
+## Block Processing Details
+
+### Standard vs Block Format
+
+**Standard CRC32** (compatible):
+```
+Input:  [large file data]
+Output: 222957957 (single 32-bit value)
+```
+
+**Block CRC32** (proprietary):
+```
+Input:  [large file data split into blocks]
+Block 1: 222957957 → Base58 encoded
+Block 2: 891347246 → Base58 encoded
+Block 3: 234567890 → Base58 encoded
+Output:  [concatenated Base58 string]
+```
+
+### Block Size Selection
+
+```javascript
+// Automatic sizing
+const blockSize = optimalBlockSize(buffer);
+
+// Manual sizing
+const result = bufferToBlockCrc32(buffer, 65536); // 64KB blocks
+```
+
+**Size Guidelines:**
+- **Small files** (< 100KB): Single block
+- **Medium files** (100KB - 2MB): 100KB blocks
+- **Large files** (> 2MB): Adaptive sizing (max 20 blocks)
+
+### Use Cases
+
+**Standard CRC32:**
+- File integrity verification
+- Compatibility with external tools
+- Single checksum for entire data
+
+**Block CRC32:**
+- Large file streaming
+- Partial corruption detection
+- Progress tracking during transfer
+- Resume capability for interrupted uploads
+
+## Error Handling
+
+```javascript
+// Invalid CRC variant
+getCrcTable('invalid'); // throws "Invalid variant [invalid]"
+
+// Unsupported buffer type
+bufferToCrc32('string'); // throws "Unsupported buffer type"
+
+// All functions validate inputs and provide clear error messages
+```
+
+## Standards Compliance
+
+✅ **Verified Implementation**: Both CRC32 and CRC32C pass standard test vectors
+- CRC32 IEEE 802.3: `"123456789"` → `0xcbf43926`
+- CRC32C Castagnoli: `"123456789"` → `0xe3069283`
+
+✅ **Full Compatibility**: 
+- ZIP/PNG/Ethernet frames (CRC32)
+- iSCSI/SCTP protocols (CRC32C)
+
+## Performance Notes
+
+- **Table caching**: CRC tables generated once per variant
+- **Memory efficient**: Block processing doesn't load entire files
+- **Browser compatible**: Works in all modern browsers
+- **Standards compliant**: Verified against authoritative test vectors
+- **No dependencies**: Pure JavaScript implementation
+
+## Testing
+
+Run tests for all modules:
+
+```bash
+pnpm test:file src/lib/util/checksum/
+```
+
+Run specific test files:
+
+```bash
+pnpm test:file src/lib/util/checksum/stringCrc32.test.js
+pnpm test:file src/lib/util/checksum/bufferCrc32.test.js
+pnpm test:file src/lib/util/checksum/blockCrc32.test.js
+```
+
+## TypeScript Support
+
+All modules include comprehensive JSDoc type annotations:
+
+```javascript
+/**
+ * @param {string} str - String to calculate checksum for
+ * @param {import('./crcTables.js').CrcVariant} [variant=CRC32] - CRC variant
+ * @returns {number} Unsigned 32-bit CRC32 value
+ */
+```
+
+## Migration Guide
+
+### From Original Implementation
+
+**Old:**
+```javascript
+import { stringToCrc32 } from './crc32.js';
+```
+
+**New:**
+```javascript
+import { stringToCrc32 } from './stringCrc32.js';
+// Same API, no changes needed
+```
+
+### Adding Block Processing
+
+**Before:**
+```javascript
+// Single CRC32 for entire file
+const crc = bufferToCrc32(largeFile);
+```
+
+**After:**
+```javascript
+// Block-based processing
+const result = bufferToBlockCrc32(largeFile);
+const checksum = result.toBase58(); // Custom format
+```
+
+## License
+
+Part of HKdigital library core utilities.

package/dist/util/checksum/blockCrc32.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Calculate block-based CRC32 for buffer
+ *
+ * @param {ArrayBuffer|DataView|Uint8Array} buffer - Buffer to process
+ * @param {number} [blockSize] - Block size (auto-calculated if not provided)
+ * @param {import('./crcTables.js').CrcVariant} [variant=CRC32] - CRC variant
+ *
+ * @returns {object} Block checksum result
+ */
+export function bufferToBlockCrc32(buffer: ArrayBuffer | DataView | Uint8Array, blockSize?: number, variant?: import("./crcTables.js").CrcVariant): object;
+/**
+ * Iterate over buffer blocks and yield CRC32 for each
+ *
+ * @param {ArrayBuffer|DataView|Uint8Array} buffer - Buffer to process
+ * @param {number} [blockSize] - Block size
+ * @param {import('./crcTables.js').CrcVariant} [variant=CRC32] - CRC variant
+ *
+ * @yields {object} Block checksum with value and encoding methods
+ */
+export function blockCrc32Iterator(buffer: ArrayBuffer | DataView | Uint8Array, blockSize?: number, variant?: import("./crcTables.js").CrcVariant): Generator<{
+    value: number;
+    offset: number;
+    size: number;
+    toBase58: () => string;
+}, void, unknown>;
+/**
+ * Check if buffer checksum matches expected value
+ *
+ * @param {ArrayBuffer|DataView|Uint8Array} buffer - Buffer to verify
+ * @param {string} expectedChecksum - Expected Base58 checksum string
+ * @param {number} [blockSize] - Block size
+ * @param {import('./crcTables.js').CrcVariant} [variant=CRC32] - CRC variant
+ *
+ * @returns {boolean} True if checksums match
+ */
+export function bufferChecksumEquals(buffer: ArrayBuffer | DataView | Uint8Array, expectedChecksum: string, blockSize?: number, variant?: import("./crcTables.js").CrcVariant): boolean;
+/**
+ * Calculate optimal block size for buffer
+ *
+ * @param {ArrayBuffer|DataView|Uint8Array} buffer - Buffer to analyze
+ *
+ * @returns {number} Optimal block size
+ */
+export function optimalBlockSize(buffer: ArrayBuffer | DataView | Uint8Array): number;