ts-data-forge 1.0.0 → 1.0.1

package/dist/number/enum/uint8.mjs

@@ -0,0 +1,251 @@
+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({
+    integerOrSafeInteger: 'SafeInteger',
+    MIN_VALUE: 0,
+    MAX_VALUE: 255,
+    typeNameInMessage,
+});
+/**
+ * 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) => 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) => 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+castTypeImpl(x);
+/**
+ * Clamps a number to the Uint8 range [0, 255].
+ * @param a - The number to clamp
+ * @returns The clamped value as Uint8
+ */
+const clamp = (a) => 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) => 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) => 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, y) => 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, y) => 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, y) => 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, y) => 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, y) => 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, max) => 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.
+ */
+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
+ * ```
+ */
+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)
+ * ```
+ */
+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,
+};
+
+export { Uint8, asUint8, isUint8 };
+//# sourceMappingURL=uint8.mjs.map

package/dist/number/enum/uint8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"uint8.mjs","sources":["../../../src/number/enum/uint8.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA,MAAM,iBAAiB,GAAG,uCAAuC;AAEjE,MAAM,EACJ,SAAS,EACT,SAAS,EACT,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,SAAS,GACjB,GAAG,mBAAmB,CAAC,kBAAkB,CAAC,mBAAmB,CAAiB;AAC7E,IAAA,oBAAoB,EAAE,aAAa;AACnC,IAAA,SAAS,EAAE,CAAC;AACZ,IAAA,SAAS,EAAE,GAAG;IACd,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;;;;;;;;;;;;;;;AAkBG;AACH,MAAM,EAAE,GAAG,CAAC,CAAS,KAAiB,MAAM,CAAC,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;AAqBG;AACH,MAAM,QAAQ,GAAG,CAAC,CAAS;AACzB;AACA,YAAY,CAAC,CAAC,CAAU;AAE1B;;;;AAIG;AACH,MAAM,KAAK,GAAG,CAAC,CAAS,KAAY,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAE1D;;;;;;;;;;;AAWG;AACH,MAAM,IAAI,GAAG,CAAC,GAAG,MAAwB,KACvC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;AAE/B;;;;AAIG;AACH,MAAM,IAAI,GAAG,CAAC,GAAG,MAAwB,KACvC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;AAE/B;;;;;AAKG;AACH,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,KAAY,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;AAExD;;;;;AAKG;AACH,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,KAAY,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AAEvD;;;;;AAKG;AACH,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,KAAY,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AAEvD;;;;;AAKG;AACH,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,KAAY,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AAEvD;;;;;AAKG;AACH,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAoB,KAAY,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE/E;;;;;AAKG;AACH,MAAM,MAAM,GAAG,CAAC,GAAU,EAAE,GAAU,KACpC,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AAE5D;;;;AAIG;AACI,MAAM,OAAO,GAAG;AAEvB;;;;;;;;;;;;;AAaG;AACI,MAAM,OAAO,GAAG;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACI,MAAM,KAAK,GAAG;AACnB;;;;AAIG;IACH,EAAE;AAEF;;;AAGG;IACH,SAAS;AAET;;;AAGG;IACH,SAAS;AAET;;;;AAIG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;AAIG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;AAIG;IACH,KAAK;AAEL;;;;;AAKG;IACH,MAAM;AAEN;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;;;;;"}

package/dist/number/index.d.mts

@@ -0,0 +1,5 @@
+export * from './branded-types/index.mjs';
+export * from './enum/index.mjs';
+export * from './num.mjs';
+export * from './refined-number-utils.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/number/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/number/index.mts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,4BAA4B,CAAC"}

package/dist/number/index.mjs

@@ -0,0 +1,31 @@
+export { FiniteNumber, asFiniteNumber, isFiniteNumber } from './branded-types/finite-number.mjs';
+export { Int, asInt, isInt } from './branded-types/int.mjs';
+export { Int16, asInt16, isInt16 } from './branded-types/int16.mjs';
+export { Int32, asInt32, isInt32 } from './branded-types/int32.mjs';
+export { NonNegativeFiniteNumber, asNonNegativeFiniteNumber, isNonNegativeFiniteNumber } from './branded-types/non-negative-finite-number.mjs';
+export { NonNegativeInt16, asNonNegativeInt16, isNonNegativeInt16 } from './branded-types/non-negative-int16.mjs';
+export { NonNegativeInt32, asNonNegativeInt32, isNonNegativeInt32 } from './branded-types/non-negative-int32.mjs';
+export { NonZeroFiniteNumber, asNonZeroFiniteNumber, isNonZeroFiniteNumber } from './branded-types/non-zero-finite-number.mjs';
+export { NonZeroInt, asNonZeroInt, isNonZeroInt } from './branded-types/non-zero-int.mjs';
+export { NonZeroInt16, asNonZeroInt16, isNonZeroInt16 } from './branded-types/non-zero-int16.mjs';
+export { NonZeroInt32, asNonZeroInt32, isNonZeroInt32 } from './branded-types/non-zero-int32.mjs';
+export { NonZeroSafeInt, asNonZeroSafeInt, isNonZeroSafeInt } from './branded-types/non-zero-safe-int.mjs';
+export { NonZeroUint16, asNonZeroUint16, isNonZeroUint16 } from './branded-types/non-zero-uint16.mjs';
+export { NonZeroUint32, asNonZeroUint32, isNonZeroUint32 } from './branded-types/non-zero-uint32.mjs';
+export { PositiveFiniteNumber, asPositiveFiniteNumber, isPositiveFiniteNumber } from './branded-types/positive-finite-number.mjs';
+export { PositiveInt, asPositiveInt, isPositiveInt } from './branded-types/positive-int.mjs';
+export { PositiveInt16, asPositiveInt16, isPositiveInt16 } from './branded-types/positive-int16.mjs';
+export { PositiveInt32, asPositiveInt32, isPositiveInt32 } from './branded-types/positive-int32.mjs';
+export { PositiveSafeInt, asPositiveSafeInt, isPositiveSafeInt } from './branded-types/positive-safe-int.mjs';
+export { PositiveUint16, asPositiveUint16, isPositiveUint16 } from './branded-types/positive-uint16.mjs';
+export { PositiveUint32, asPositiveUint32, isPositiveUint32 } from './branded-types/positive-uint32.mjs';
+export { SafeInt, asSafeInt, isSafeInt } from './branded-types/safe-int.mjs';
+export { SafeUint, asSafeUint, isSafeUint } from './branded-types/safe-uint.mjs';
+export { Uint, asUint, isUint } from './branded-types/uint.mjs';
+export { Uint16, asUint16, isUint16 } from './branded-types/uint16.mjs';
+export { Uint32, asUint32, isUint32 } from './branded-types/uint32.mjs';
+export { Int8, asInt8, isInt8 } from './enum/int8.mjs';
+export { Uint8, asUint8, isUint8 } from './enum/uint8.mjs';
+export { Num } from './num.mjs';
+export { TsVerifiedInternals } from './refined-number-utils.mjs';
+//# sourceMappingURL=index.mjs.map

package/dist/number/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}