@hkdigital/lib-core 0.4.55 → 0.4.57

package/dist/network/http/typedef.js

@@ -71,6 +71,62 @@
  * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
  */
 
+/**
+ * @typedef {Object} JsonPutOptions
+ * @property {string|URL} url URL string or URL object for the request
+ * @property {*} body Request body (will be sent as JSON)
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {Record<string, string>} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
+/**
+ * @typedef {Object} JsonPatchOptions
+ * @property {string|URL} url URL string or URL object for the request
+ * @property {*} body Request body (will be sent as JSON)
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {Record<string, string>} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
+/**
+ * @typedef {Object} JsonDeleteOptions
+ * @property {string|URL} url URL string or URL object for the request
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {Record<string, string>} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.')
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
 /**
  * @typedef {Object} StaleInfo
  * @property {boolean} isStale Whether the response contains stale data

package/dist/services/README.md

@@ -204,22 +204,31 @@ await manager.stopAll();
 Services receive helpful utilities in their constructor options for accessing other services:
 
 ```javascript
+/**
+ * Example service that depends on other services
+ */
 class AuthService extends ServiceBase {
+  /** @type {(<T>(serviceName: string) => T)} */
+  #getService;
+
+  /** @type {() => import('$hklib-core/services/index.js').ServiceManager} */
+  #getManager;
+
   constructor(serviceName, options) {
     super(serviceName, options);
     
-    // Store service access utilities
-    this.getManager = options.getManager;   // Function to get manager (lazy)
-    this.getService = options.getService;   // Bound getService function
+    // Store service access utilities as private methods
+    this.#getService = options.getService;   // Bound getService function
+    this.#getManager = options.getManager;   // Function to get manager (lazy)
   }
   
   async authenticateUser(credentials) {
     // Access other services with full type safety and error checking
-    const database = this.getService('database');
+    const database = this.#getService('database');
     const user = await database.findUser(credentials.username);
     
-    // Access manager for advanced operations
-    const manager = this.getManager();
+    // Access manager for advanced operations when needed
+    const manager = this.#getManager();
     const health = await manager.checkHealth();
     
     return user;
@@ -227,6 +236,48 @@ class AuthService extends ServiceBase {
 }
 ```
 
+**Best Practice Pattern:**
+
+The recommended approach is to store service access functions as **private methods** using the hash prefix. This pattern:
+
+- **Keeps the API clean** - No public getService/getManager methods exposed
+- **Prevents serialization issues** - Private fields don't serialize to JSON
+- **Enforces proper encapsulation** - Service dependencies stay internal
+- **Provides type safety** - Full generic support with `this.#getService<DatabaseService>('database')`
+
+```javascript
+/**
+ * Unified service for tracking complete player data including progress and 
+ * profile matches
+ */
+export default class PlayerService extends ServiceBase {
+  
+  /** @type {(<T>(serviceName: string) => T)} */
+  #getService;
+
+  /**
+   * @param {string} serviceName
+   * @param {import('$hklib-core/services/typedef.js').ServiceOptions} [options]
+   */
+  constructor(serviceName, options) {
+    super(serviceName, options);
+
+    this.#getService = options?.getService;
+  }
+
+  async getPlayerProfile(playerId) {
+    // Access dependent services cleanly
+    const database = this.#getService('database');
+    const analytics = this.#getService('analytics');
+    
+    const profile = await database.getPlayer(playerId);
+    const stats = await analytics.getPlayerStats(playerId);
+    
+    return { ...profile, stats };
+  }
+}
+```
+
 **Service Access Methods:**
 
 ```javascript

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;

package/dist/util/checksum/blockCrc32.js

@@ -0,0 +1,174 @@
+/**
+ * Custom block-based CRC32 calculation
+ *
+ * Splits large buffers into blocks and concatenates individual CRC32 values.
+ * Creates proprietary checksum format for efficient large file processing.
+ */
+
+import { base58fromNumber } from '../bases.js';
+
+import { bufferToCrc32 } from './bufferCrc32.js';
+import { CRC32 } from './crcTables.js';
+
+/* ---------------------------------------------------------------- Constants */
+
+/** @type {number} */
+const MIN_BUFFER_BLOCK_SIZE = 100000;
+
+/** @type {number} */
+const MAX_BUFFER_BLOCKS = 20;
+
+/** @type {number} */
+const OPTIMAL_BLOCK_SIZE_FACTOR = 0.95;
+
+/* ---------------------------------------------------------------- Functions */
+
+/**
+ * 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, blockSize, variant = CRC32) {
+  if (!blockSize) {
+    blockSize = optimalBlockSize(buffer);
+  }
+
+  /** @type {number[]} */
+  const checksumList = [];
+
+  for (const block of blockCrc32Iterator(buffer, blockSize, variant)) {
+    checksumList.push(block.value);
+  }
+
+  return {
+    checksumList,
+    blockSize,
+    toBase58: () => checksumsToBase58(checksumList)
+  };
+}
+
+/**
+ * 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, blockSize, variant = CRC32) {
+  if (!blockSize) {
+    blockSize = optimalBlockSize(buffer);
+  }
+
+  const bufferLength = getBufferLength(buffer);
+
+  for (let offset = 0; offset < bufferLength; offset += blockSize) {
+    const currentBlockSize = Math.min(blockSize, bufferLength - offset);
+    
+    /** @type {number} */
+    const value = bufferToCrc32(buffer, offset, currentBlockSize, variant);
+
+    yield {
+      value,
+      offset,
+      size: currentBlockSize,
+      toBase58: () => base58fromNumber(value)
+    };
+  }
+}
+
+/**
+ * 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, 
+  expectedChecksum, 
+  blockSize, 
+  variant = CRC32
+) {
+  if (!blockSize) {
+    blockSize = optimalBlockSize(buffer);
+  }
+
+  /** @type {string} */
+  let remaining = expectedChecksum;
+
+  for (const block of blockCrc32Iterator(buffer, blockSize, variant)) {
+    const blockChecksum = block.toBase58();
+
+    if (!remaining.startsWith(blockChecksum)) {
+      return false;
+    }
+
+    remaining = remaining.slice(blockChecksum.length);
+  }
+
+  return remaining.length === 0;
+}
+
+/**
+ * Calculate optimal block size for buffer
+ *
+ * @param {ArrayBuffer|DataView|Uint8Array} buffer - Buffer to analyze
+ *
+ * @returns {number} Optimal block size
+ */
+export function optimalBlockSize(buffer) {
+  /** @type {number} */
+  const bufferByteLength = getBufferLength(buffer);
+
+  if (bufferByteLength < MIN_BUFFER_BLOCK_SIZE) {
+    return bufferByteLength;
+  }
+
+  /** @type {number} */
+  let blockSize = bufferByteLength / MAX_BUFFER_BLOCKS;
+
+  if (blockSize < MIN_BUFFER_BLOCK_SIZE) {
+    return MIN_BUFFER_BLOCK_SIZE;
+  }
+
+  return Math.ceil(
+    blockSize * OPTIMAL_BLOCK_SIZE_FACTOR + 
+    MIN_BUFFER_BLOCK_SIZE * (1 - OPTIMAL_BLOCK_SIZE_FACTOR)
+  );
+}
+
+/* ------------------------------------------------------- Internal functions */
+
+/**
+ * Get buffer length safely for different buffer types
+ *
+ * @param {ArrayBuffer|DataView|Uint8Array} buffer - Buffer to measure
+ *
+ * @returns {number} Buffer length in bytes
+ */
+function getBufferLength(buffer) {
+  if (buffer instanceof ArrayBuffer || buffer instanceof DataView) {
+    return buffer.byteLength;
+  }
+  return buffer.length;
+}
+
+/**
+ * Convert checksum array to concatenated Base58 string
+ *
+ * @param {number[]} checksumList - Array of CRC32 values
+ *
+ * @returns {string} Concatenated Base58 string
+ */
+function checksumsToBase58(checksumList) {
+  return checksumList.map(crc => base58fromNumber(crc)).join('');
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Calculate standard CRC32 for buffer
+ *
+ * @param {ArrayBuffer|DataView|Uint8Array} buffer - Buffer to checksum
+ * @param {number} [byteOffset=0] - Start offset in buffer
+ * @param {number} [byteLength] - Number of bytes to process
+ * @param {import('./crcTables.js').CrcVariant} [variant=CRC32] - CRC variant
+ *
+ * @returns {number} Unsigned 32-bit CRC32 value
+ */
+export function bufferToCrc32(buffer: ArrayBuffer | DataView | Uint8Array, byteOffset?: number, byteLength?: number, variant?: import("./crcTables.js").CrcVariant): number;