ts-data-forge 1.0.0

package/src/number/enum/uint8.mts

@@ -0,0 +1,293 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+const typeNameInMessage = 'an non-negative integer less than 256';
+
+const {
+  MIN_VALUE,
+  MAX_VALUE,
+  random: randomImpl,
+  is: isImpl,
+  castType: castTypeImpl,
+  clamp: clampImpl,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<Uint16, 0, 255>({
+  integerOrSafeInteger: 'SafeInteger',
+  MIN_VALUE: 0,
+  MAX_VALUE: 255,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Type guard that checks if a value is an 8-bit unsigned integer.
+ *
+ * A Uint8 is an unsigned integer in the range [0, 255], representing
+ * values that fit in exactly 8 bits of memory (1 byte).
+ *
+ * @param x - The number to check
+ * @returns `true` if x is a valid Uint8, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * is(100);   // true
+ * is(0);     // true (minimum value)
+ * is(255);   // true (maximum value)
+ * is(256);   // false (exceeds max)
+ * is(-1);    // false (negative)
+ * is(5.5);   // false (not integer)
+ * ```
+ */
+const is = (x: number): x is Uint8 => isImpl(x);
+
+/**
+ * Casts a number to a Uint8 branded type.
+ *
+ * This function validates that the input is within the Uint8 range [0, 255]
+ * and is an integer, then returns it with the Uint8 brand.
+ *
+ * @param x - The number to convert
+ * @returns The number as a Uint8 branded type
+ * @throws {TypeError} If x is not a valid 8-bit unsigned integer
+ *
+ * @example
+ * ```typescript
+ * const byte = castType(200);    // Uint8
+ * const zero = castType(0);      // Uint8 (minimum)
+ * const max = castType(255);     // Uint8 (maximum)
+ *
+ * // These throw TypeError:
+ * // castType(256);              // Exceeds maximum
+ * // castType(-1);               // Negative value
+ * // castType(1.5);              // Not an integer
+ * ```
+ */
+const castType = (x: number): Uint8 =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  castTypeImpl(x) as Uint8;
+
+/**
+ * Clamps a number to the Uint8 range [0, 255].
+ * @param a - The number to clamp
+ * @returns The clamped value as Uint8
+ */
+const clamp = (a: number): Uint8 => castType(clampImpl(a));
+
+/**
+ * Returns the minimum value from a list of Uint8 values.
+ *
+ * @param values - The Uint8 values to compare (at least one required)
+ * @returns The smallest value as a Uint8
+ *
+ * @example
+ * ```typescript
+ * min_(asUint8(50), asUint8(30), asUint8(100)); // Uint8 (30)
+ * min_(asUint8(0), asUint8(255));               // Uint8 (0)
+ * ```
+ */
+const min_ = (...values: readonly Uint8[]): Uint8 =>
+  castType(Math.min(...values));
+
+/**
+ * Returns the maximum of the given Uint8 values.
+ * @param values - The Uint8 values to compare
+ * @returns The maximum value
+ */
+const max_ = (...values: readonly Uint8[]): Uint8 =>
+  castType(Math.max(...values));
+
+/**
+ * Raises x to the power of y, clamped to Uint8 range.
+ * @param x - The base
+ * @param y - The exponent
+ * @returns x^y clamped to [0, 255]
+ */
+const pow = (x: Uint8, y: Uint8): Uint8 => clamp(x ** y);
+
+/**
+ * Adds two Uint8 values, clamped to Uint8 range.
+ * @param x - First operand
+ * @param y - Second operand
+ * @returns x + y clamped to [0, 255]
+ */
+const add = (x: Uint8, y: Uint8): Uint8 => clamp(x + y);
+
+/**
+ * Subtracts two Uint8 values, clamped to Uint8 range.
+ * @param x - First operand
+ * @param y - Second operand
+ * @returns x - y clamped to [0, 255]
+ */
+const sub = (x: Uint8, y: Uint8): Uint8 => clamp(x - y);
+
+/**
+ * Multiplies two Uint8 values, clamped to Uint8 range.
+ * @param x - First operand
+ * @param y - Second operand
+ * @returns x * y clamped to [0, 255]
+ */
+const mul = (x: Uint8, y: Uint8): Uint8 => clamp(x * y);
+
+/**
+ * Divides two Uint8 values, clamped to Uint8 range.
+ * @param x - The dividend
+ * @param y - The divisor (cannot be 0)
+ * @returns ⌊x / y⌋ clamped to [0, 255]
+ */
+const div = (x: Uint8, y: Exclude<Uint8, 0>): Uint8 => clamp(Math.floor(x / y));
+
+/**
+ * Generates a random Uint8 value within the specified range.
+ * @param min - The minimum value (inclusive)
+ * @param max - The maximum value (inclusive)
+ * @returns A random Uint8 between min and max
+ */
+const random = (min: Uint8, max: Uint8): Uint8 =>
+  castType(randomImpl(castTypeImpl(min), castTypeImpl(max)));
+
+/**
+ * Checks if a number is a Uint8 (8-bit unsigned integer in the range [0, 255]).
+ * @param value The value to check.
+ * @returns `true` if the value is a Uint8, `false` otherwise.
+ */
+export const isUint8 = is;
+
+/**
+ * Casts a number to a Uint8 type.
+ * @param value The value to cast.
+ * @returns The value as a Uint8 type.
+ * @throws {TypeError} If the value is not a valid 8-bit unsigned integer.
+ * @example
+ * ```typescript
+ * const x = asUint8(255); // Uint8
+ * const y = asUint8(0); // Uint8
+ * // asUint8(-1); // throws TypeError
+ * // asUint8(256); // throws TypeError
+ * // asUint8(1.5); // throws TypeError
+ * ```
+ */
+export const asUint8 = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for 8-bit unsigned integers.
+ *
+ * All operations automatically clamp results to the valid Uint8 range [0, 255].
+ * This ensures that all arithmetic maintains the 8-bit unsigned integer constraint,
+ * with negative results clamped to 0 and overflow results clamped to MAX_VALUE.
+ *
+ * @example
+ * ```typescript
+ * const a = asUint8(200);
+ * const b = asUint8(100);
+ *
+ * // Arithmetic operations with automatic clamping
+ * const sum = Uint8.add(a, b);       // Uint8 (255 - clamped to MAX_VALUE)
+ * const diff = Uint8.sub(a, b);      // Uint8 (100)
+ * const reverseDiff = Uint8.sub(b, a); // Uint8 (0 - clamped to MIN_VALUE)
+ * const product = Uint8.mul(a, b);   // Uint8 (255 - clamped due to overflow)
+ *
+ * // Range operations
+ * const clamped = Uint8.clamp(-10);     // Uint8 (0)
+ * const minimum = Uint8.min(a, b);      // Uint8 (100)
+ * const maximum = Uint8.max(a, b);      // Uint8 (200)
+ *
+ * // Utility operations
+ * const random = Uint8.random(asUint8(50), asUint8(150)); // Uint8 (random value in [50, 150])
+ * const power = Uint8.pow(asUint8(2), asUint8(7)); // Uint8 (128)
+ * ```
+ */
+export const Uint8 = {
+  /**
+   * Type guard to check if a value is a Uint8.
+   * @param value The value to check.
+   * @returns `true` if the value is an 8-bit unsigned integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for an 8-bit unsigned integer.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum value for an 8-bit unsigned integer.
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the larger of the given Uint8 values.
+   * @param values The Uint8 values to compare.
+   * @returns The maximum value as a Uint8.
+   */
+  max: max_,
+
+  /**
+   * Returns the smaller of the given Uint8 values.
+   * @param values The Uint8 values to compare.
+   * @returns The minimum value as a Uint8.
+   */
+  min: min_,
+
+  /**
+   * Clamps a number to the Uint8 range.
+   * @param value The number to clamp.
+   * @returns The value clamped to [0, 255] as a Uint8.
+   */
+  clamp,
+
+  /**
+   * Generates a random Uint8 value within the specified range.
+   * @param min The minimum value (inclusive).
+   * @param max The maximum value (inclusive).
+   * @returns A random Uint8 between min and max.
+   */
+  random,
+
+  /**
+   * Raises a Uint8 to the power of another Uint8.
+   * @param a The base Uint8.
+   * @param b The exponent Uint8.
+   * @returns `a ** b` clamped to [0, 255] as a Uint8.
+   */
+  pow,
+
+  /**
+   * Adds two Uint8 values.
+   * @param a The first Uint8.
+   * @param b The second Uint8.
+   * @returns `a + b` clamped to [0, 255] as a Uint8.
+   */
+  add,
+
+  /**
+   * Subtracts one Uint8 from another.
+   * @param a The minuend Uint8.
+   * @param b The subtrahend Uint8.
+   * @returns `a - b` clamped to [0, 255] as a Uint8 (minimum 0).
+   */
+  sub,
+
+  /**
+   * Multiplies two Uint8 values.
+   * @param a The first Uint8.
+   * @param b The second Uint8.
+   * @returns `a * b` clamped to [0, 255] as a Uint8.
+   */
+  mul,
+
+  /**
+   * Divides one Uint8 by another using floor division.
+   * @param a The dividend Uint8.
+   * @param b The divisor Uint8 (cannot be 0).
+   * @returns `⌊a / b⌋` clamped to [0, 255] as a Uint8.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof Uint8,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    Uint16,
+    'int' | 'non-negative' | 'range'
+  >
+>('=');

package/src/number/enum/uint8.test.mts

@@ -0,0 +1,164 @@
+import { expectType } from '../../expect-type.mjs';
+import { Uint8, asUint8, isUint8 } from './uint8.mjs';
+
+describe('Uint8', () => {
+  describe('isUint8', () => {
+    test.each([
+      { value: 0, expected: true },
+      { value: 128, expected: true },
+      { value: 255, expected: true },
+      { value: -1, expected: false },
+      { value: 256, expected: false },
+      { value: 1.5, expected: false },
+      { value: Number.NaN, expected: false },
+      { value: Number.POSITIVE_INFINITY, expected: false },
+      { value: Number.NEGATIVE_INFINITY, expected: false },
+    ])('isUint8($value) should return $expected', ({ value, expected }) => {
+      expect(isUint8(value)).toBe(expected);
+    });
+  });
+
+  describe('asUint8', () => {
+    test.each([
+      { value: 0, expected: 0 },
+      { value: 128, expected: 128 },
+      { value: 255, expected: 255 },
+    ])('asUint8($value) should return $expected', ({ value, expected }) => {
+      expect(asUint8(value)).toBe(expected);
+    });
+
+    test.each([
+      { value: -1, name: '-1' },
+      { value: 256, name: '256' },
+      { value: 1.5, name: '1.5' },
+      { value: Number.NaN, name: 'NaN' },
+      { value: Number.POSITIVE_INFINITY, name: 'Infinity' },
+      { value: Number.NEGATIVE_INFINITY, name: '-Infinity' },
+    ])('asUint8($name) should throw TypeError', ({ value }) => {
+      expect(() => asUint8(value)).toThrow(TypeError);
+    });
+  });
+
+  describe('Uint8.is', () => {
+    test('should be the same as isUint8', () => {
+      expect(Uint8.is).toBe(isUint8);
+    });
+  });
+
+  describe('Uint8.MIN_VALUE', () => {
+    test('should be 0', () => {
+      expect(Uint8.MIN_VALUE).toBe(0);
+      expectType<typeof Uint8.MIN_VALUE, 0>('=');
+    });
+  });
+
+  describe('Uint8.MAX_VALUE', () => {
+    test('should be 255', () => {
+      expect(Uint8.MAX_VALUE).toBe(255);
+      expectType<typeof Uint8.MAX_VALUE, 255>('=');
+    });
+  });
+
+  describe('Uint8.clamp', () => {
+    test.each([
+      { value: -100, expected: 0 },
+      { value: 0, expected: 0 },
+      { value: 128, expected: 128 },
+      { value: 255, expected: 255 },
+      { value: 300, expected: 255 },
+      { value: 1.5, expected: 2 },
+    ])('Uint8.clamp($value) should return $expected', ({ value, expected }) => {
+      expect(Uint8.clamp(value)).toBe(expected);
+    });
+  });
+
+  describe('Uint8.min', () => {
+    test('should return minimum value', () => {
+      expect(Uint8.min(100, 50, 10)).toBe(10);
+      expect(Uint8.min(1, 2, 3)).toBe(1);
+    });
+  });
+
+  describe('Uint8.max', () => {
+    test('should return maximum value', () => {
+      expect(Uint8.max(100, 50, 10)).toBe(100);
+      expect(Uint8.max(1, 2, 3)).toBe(3);
+    });
+  });
+
+  describe('Uint8.add', () => {
+    test.each([
+      { x: 10, y: 20, expected: 30 },
+      { x: 200, y: 100, expected: 255 }, // clamped to max
+      { x: 100, y: 50, expected: 150 },
+    ] as const)(
+      'Uint8.add($x, $y) should return $expected',
+      ({ x, y, expected }) => {
+        expect(Uint8.add(x, y)).toBe(expected);
+      },
+    );
+  });
+
+  describe('Uint8.sub', () => {
+    test.each([
+      { x: 30, y: 10, expected: 20 },
+      { x: 10, y: 30, expected: 0 }, // clamped to min
+      { x: 200, y: 50, expected: 150 },
+    ] as const)(
+      'Uint8.sub($x, $y) should return $expected',
+      ({ x, y, expected }) => {
+        expect(Uint8.sub(x, y)).toBe(expected);
+      },
+    );
+  });
+
+  describe('Uint8.mul', () => {
+    test.each([
+      { x: 5, y: 10, expected: 50 },
+      { x: 20, y: 20, expected: 255 }, // clamped to max
+      { x: 100, y: 2, expected: 200 },
+    ] as const)(
+      'Uint8.mul($x, $y) should return $expected',
+      ({ x, y, expected }) => {
+        expect(Uint8.mul(x, y)).toBe(expected);
+      },
+    );
+  });
+
+  describe('Uint8.div', () => {
+    test.each([
+      { x: 100, y: 2, expected: 50 },
+      { x: 100, y: 3, expected: 33 }, // floor division
+      { x: 255, y: 5, expected: 51 },
+    ] as const)(
+      'Uint8.div($x, $y) should return $expected',
+      ({ x, y, expected }) => {
+        expect(Uint8.div(x, y)).toBe(expected);
+      },
+    );
+  });
+
+  describe('Uint8.pow', () => {
+    test.each([
+      { x: 2, y: 3, expected: 8 },
+      { x: 4, y: 4, expected: 255 }, // clamped to max
+      { x: 10, y: 2, expected: 100 },
+    ] as const)(
+      'Uint8.pow($x, $y) should return $expected',
+      ({ x, y, expected }) => {
+        expect(Uint8.pow(x, y)).toBe(expected);
+      },
+    );
+  });
+
+  describe('Uint8.random', () => {
+    test('should generate value within range', () => {
+      const min = 10;
+      const max = 50;
+      const result = Uint8.random(min, max);
+      expect(result).toBeGreaterThanOrEqual(min);
+      expect(result).toBeLessThanOrEqual(max);
+      expect(Number.isInteger(result)).toBe(true);
+    });
+  });
+});

package/src/number/index.mts

@@ -0,0 +1,4 @@
+export * from './branded-types/index.mjs';
+export * from './enum/index.mjs';
+export * from './num.mjs';
+export * from './refined-number-utils.mjs';