ts-data-forge 1.5.2 → 2.0.1

package/README.md

@@ -7,6 +7,17 @@
 
 **ts-data-forge** is a TypeScript utility library that provides type-safe functional programming utilities with zero runtime dependencies. It aims to enhance development robustness, maintainability, and correctness by leveraging TypeScript's powerful type system.
 
+## Perfect Companion to ts-type-forge
+
+**ts-data-forge** is designed as the ideal runtime companion to [**ts-type-forge**](https://github.com/noshiro-pf/ts-type-forge), a powerful type utility library. While ts-type-forge provides compile-time type utilities for advanced TypeScript type manipulation, ts-data-forge complements it with runtime utilities that maintain the same level of type safety.
+
+Together, they form a complete TypeScript development toolkit:
+
+- **ts-type-forge**: Compile-time type utilities (type manipulation, type inference, advanced type patterns)
+- **ts-data-forge**: Runtime utilities with strong type safety (type guards, branded types, functional programming utilities)
+
+This synergy enables you to build fully type-safe applications from compile-time to runtime, ensuring type correctness throughout your entire codebase.
+
 ## Features
 
 This library offers a range of utilities, including:
@@ -155,7 +166,7 @@ const maybeValue = Optional.some(42);
 
 const doubled = Optional.map(maybeValue, (x) => x * 2);
 
-assert.strictEqual(Optional.unwrapOr(doubled, 0), 84);
+assert(Optional.unwrapOr(doubled, 0) === 84);
 
 // Result for error handling
 const success = Result.ok(42);
@@ -185,16 +196,16 @@ const handleStatus = (status: Status, data?: string): string =>
         error: 'An error occurred',
     });
 
-assert.strictEqual(handleStatus('loading'), 'Please wait...');
-assert.strictEqual(handleStatus('success', 'Hello'), 'Data: Hello');
-assert.strictEqual(handleStatus('error'), 'An error occurred');
+assert(handleStatus('loading') === 'Please wait...');
+assert(handleStatus('success', 'Hello') === 'Data: Hello');
+assert(handleStatus('error') === 'An error occurred');
 
 // Pattern matching with Result
 const processResult = (result: Result<number, string>): string =>
     Result.isOk(result) ? `Success: ${result.value}` : `Error: ${result.value}`;
 
-assert.strictEqual(processResult(Result.ok(42)), 'Success: 42');
-assert.strictEqual(processResult(Result.err('Failed')), 'Error: Failed');
+assert(processResult(Result.ok(42)) === 'Success: 42');
+assert(processResult(Result.err('Failed')) === 'Error: Failed');
 ```
 
 ### 3. Number Utilities with `Num` and Branded Number Types
@@ -205,35 +216,35 @@ The `Num` object provides safe and convenient functions for numerical operations
 import { Num } from 'ts-data-forge';
 
 // Basic conversions
-assert.strictEqual(Num.from('123'), 123);
-assert.strictEqual(Number.isNaN(Num.from('abc')), true);
+assert(Num.from('123') === 123);
+assert(Number.isNaN(Num.from('abc')));
 
 // Range checking
 const inRange = Num.isInRange(0, 10);
 
-assert.strictEqual(inRange(5), true);
-assert.strictEqual(inRange(0), true); // (inclusive lower bound)
-assert.strictEqual(inRange(10), false); // (exclusive upper bound)
+assert(inRange(5));
+assert(inRange(0)); // (inclusive lower bound)
+assert(!inRange(10)); // (exclusive upper bound)
 
 // Clamping values
 const clamp = Num.clamp(0, 100);
 
-assert.strictEqual(clamp(150), 100);
-assert.strictEqual(clamp(-10), 0);
+assert(clamp(150) === 100);
+assert(clamp(-10) === 0);
 
 // Rounding utilities
 const round2 = Num.round(2);
 
-assert.strictEqual(round2(3.14159), 3.14);
-assert.strictEqual(Num.roundAt(3.14159, 3), 3.142);
-assert.strictEqual(Num.roundToInt(3.7), 4);
+assert(round2(3.14159) === 3.14);
+assert(Num.roundAt(3.14159, 3) === 3.142);
+assert(Num.roundToInt(3.7) === 4);
 
 // Type guards
 const value = 5; // example value
 if (Num.isNonZero(value)) {
     // value is guaranteed to be non-zero
     const result = Num.div(10, value); // Safe division
-    assert.strictEqual(result, 2);
+    assert(result === 2);
 }
 ```
 
@@ -261,10 +272,10 @@ const unsigned = asUint(42); // Uint - non-negative integer
 const finite = asFiniteNumber(3.14); // FiniteNumber - finite floating-point
 const safeInt = asSafeInt(42); // SafeInt - integer in safe range
 
-assert.strictEqual(integer, 42);
-assert.strictEqual(unsigned, 42);
-assert.strictEqual(finite, 3.14);
-assert.strictEqual(safeInt, 42);
+assert(integer === 42);
+assert(unsigned === 42);
+assert(finite === 3.14);
+assert(safeInt === 42);
 
 // This line would cause a runtime error:
 assert.throw(() => {
@@ -274,29 +285,29 @@ assert.throw(() => {
 // Range-constrained types (16-bit, 32-bit)
 const int16 = asInt16(1000); // Int16: [-32768, 32767]
 const uint32 = asUint32(3000000000); // Uint32: [0, 4294967295]
-assert.strictEqual(int16, 1000);
-assert.strictEqual(uint32, 3000000000);
+assert(int16 === 1000);
+assert(uint32 === 3000000000);
 
 // Non-zero and positive variants
 const nonZeroInt = asNonZeroInt(5); // NonZeroInt - excludes zero
 const positiveInt = asPositiveInt(10); // PositiveInt - excludes zero and negatives
-assert.strictEqual(nonZeroInt, 5);
-assert.strictEqual(positiveInt, 10);
+assert(nonZeroInt === 5);
+assert(positiveInt === 10);
 
 // Type-safe arithmetic with automatic clamping
 const sum = Int16.add(int16, asInt16(2000)); // Int16 (3000)
 const clamped = Int16.clamp(100000); // Int16 (32767 - clamped to MAX_VALUE)
-assert.strictEqual(sum, 3000);
-assert.strictEqual(clamped, 32767);
+assert(sum === 3000);
+assert(clamped === 32767);
 
 // Safe division with non-zero types
 const ratio = NonZeroInt.div(asNonZeroInt(10), nonZeroInt); // No division by zero risk
-assert.strictEqual(ratio, 2);
+assert(ratio === 2);
 
 // Random generation within type constraints
 const randomInt16 = Int16.random(); // Int16 (random value in valid range)
-assert.strictEqual(-32768 <= randomInt16, true);
-assert.strictEqual(randomInt16 <= 32767, true);
+assert(-32768 <= randomInt16);
+assert(randomInt16 <= 32767);
 ```
 
 ### 4. Array Utilities with `Arr`
@@ -311,13 +322,13 @@ const numbers: readonly number[] = [1, 2, 3, 4, 5, 2, 3];
 // Reduction
 const sum = Arr.sum(numbers);
 
-assert.strictEqual(sum, 20);
+assert(sum === 20);
 
 // Type-safe length checking
 if (Arr.isArrayAtLeastLength(numbers, 2)) {
     // numbers is now guaranteed to have at least 2 elements
     expectType<typeof numbers, readonly [number, number, ...number[]]>('=');
-    assert.strictEqual(numbers[1], 2); // Safe access to index 1
+    assert(numbers[1] === 2); // Safe access to index 1
 }
 
 // Take first n elements
@@ -350,7 +361,7 @@ assert.deepStrictEqual(
     Optional.some({ name: 'Charlie', age: 35 } as const),
 );
 if (Optional.isSome(oldestPerson)) {
-    assert.strictEqual(oldestPerson.value.name, 'Charlie');
+    assert(oldestPerson.value.name === 'Charlie');
 }
 ```
 
@@ -367,10 +378,10 @@ const mapWithOne = originalMap.set('one', 1);
 const mapWithTwo = mapWithOne.set('two', 2);
 
 // Original map is unchanged
-assert.strictEqual(originalMap.size, 0);
+assert(originalMap.size === 0);
 assert.deepStrictEqual(mapWithTwo.get('one'), Optional.some(1));
 
-assert.strictEqual(mapWithTwo.has('three'), false);
+assert(!mapWithTwo.has('three'));
 
 // Using pipe for fluent updates
 const sequence = Arr.seq(10); // [0, 1, 2, ..., 9]
@@ -380,7 +391,7 @@ const pairs = sequence.map(
 const skipped = Arr.skip(pairs, 1); // [[1, "1"], ..., [9, "9"]]
 const idMap = IMap.create<number, string>(skipped);
 
-assert.strictEqual(idMap.size, 9);
+assert(idMap.size === 9);
 
 // Efficient batch updates with withMutations
 const idMapUpdated = idMap.withMutations([
@@ -389,15 +400,15 @@ const idMapUpdated = idMap.withMutations([
     { type: 'delete', key: 4 },
 ]);
 
-assert.strictEqual(idMapUpdated.size, 9);
+assert(idMapUpdated.size === 9);
 
 // ISet usage
 const originalSet = ISet.create<number>([]);
 const setWithItems = originalSet.add(1).add(2).add(1); // Duplicate ignored
 
-assert.strictEqual(originalSet.size, 0); // (unchanged)
-assert.strictEqual(setWithItems.has(1), true);
-assert.strictEqual(setWithItems.size, 2);
+assert(originalSet.size === 0); // (unchanged)
+assert(setWithItems.has(1));
+assert(setWithItems.size === 2);
 ```
 
 ### 6. Type Guards
@@ -430,9 +441,9 @@ if (isNonNullObject(value)) {
 }
 
 // Example usage
-assert.strictEqual(processData({ name: 'Alice' }), 'Hello, Alice!');
-assert.strictEqual(processData({ age: 30 }), undefined);
-assert.strictEqual(processData('not an object'), undefined);
+assert(processData({ name: 'Alice' }) === 'Hello, Alice!');
+assert(processData({ age: 30 }) === undefined);
+assert(processData('not an object') === undefined);
 ```
 
 ### 7. Iteration with `range`
@@ -532,7 +543,8 @@ assert.deepStrictEqual(updatedState.items, ['newItem1', 'newItem2']);
 
 **Important Notes:**
 
-- This library **only supports ESM (ES Modules)**. CommonJS is not supported.
+- This library **only supports ESM (ES Modules)** and is designed for native ESM environments. CommonJS is not supported.
+- The library uses `.mts` file extensions and proper ESM exports, making it compatible with modern Node.js ESM resolution and bundlers that support native ESM.
 - This library uses advanced TypeScript features, including branded types for enhanced type safety. Some functions require specific branded types as parameters (such as `Uint32` in `newArray`). The examples above use the small literal numeric values specifically allowed in each function for brevity, but in actual use you should use the provided type conversion functions (such as `asUint32`) or cast to the appropriate branded type, for example `as Uint32`.
 
 ## Removing `expectType` in Production