@sachitv/safe-math-ts 0.1.0

package/esm/src/units.d.ts

@@ -0,0 +1,350 @@
+declare const quantityBrand: unique symbol;
+declare const unitTagBrand: unique symbol;
+declare const unitExprBrand: unique symbol;
+type Count = readonly unknown[];
+type UnitExponent<Numerator extends Count = Count, Denominator extends Count = Count> = {
+    readonly num: readonly [...Numerator];
+    readonly den: readonly [...Denominator];
+};
+type UnitMap = {
+    readonly [Token: string]: UnitExponent;
+};
+type EmptyUnitMap = Record<never, UnitExponent>;
+/**
+ * Internal normalized unit representation used only at the type level.
+ *
+ * Examples:
+ * - `m/s^2` => `{ factors: { m: { num: [..1], den: [] }, s: { num: [], den: [..2] } } }`
+ * - `none` => `{ factors: {} }`
+ */
+type UnitParts<Factors extends UnitMap = EmptyUnitMap> = {
+    readonly factors: Factors;
+    readonly [unitExprBrand]: Extract<keyof Factors, string>;
+};
+/**
+ * Fallback shape when a unit cannot be fully resolved at compile time.
+ *
+ * If unit string parsing fails silently (e.g. malformed tokens), the result
+ * is `UnknownUnit`, which is structurally identical for all failed parses and
+ * loses type distinctiveness. Avoid passing non-literal or malformed strings
+ * to `unit()`.
+ */
+type UnknownUnit = UnitParts<UnitMap>;
+/** Normalized compile-time unit representation. */
+export type UnitExpr = UnknownUnit;
+/** Canonical dimensionless unit representation. */
+export type Dimensionless = UnitFromString<'none'>;
+/** Prevents undesired generic widening in function signatures. */
+export type NoInfer<ValueType> = [
+    ValueType
+][ValueType extends unknown ? 0 : never];
+type ZeroExponent = UnitExponent<[], []>;
+type IsUnknownMap<Factors extends UnitMap> = string extends keyof Factors ? true : false;
+type CancelCounts<Numerator extends Count, Denominator extends Count> = Numerator extends readonly [unknown, ...infer NumTail extends unknown[]] ? Denominator extends readonly [unknown, ...infer DenTail extends unknown[]] ? CancelCounts<NumTail, DenTail> : [Numerator, Denominator] : [Numerator, Denominator];
+type ExponentFor<Factors extends UnitMap, Token extends string> = Token extends keyof Factors ? Factors[Token] : ZeroExponent;
+type IsZeroExponent<Exponent extends UnitExponent> = Exponent['num'] extends readonly [] ? Exponent['den'] extends readonly [] ? true : false : false;
+type NormalizeMap<Factors extends UnitMap> = {
+    readonly [Token in keyof Factors as Token extends string ? IsZeroExponent<Factors[Token]> extends true ? never : Token : never]: Factors[Token];
+};
+/** Normalizes a full `UnitExpr` object. */
+type NormalizeUnit<Unit extends UnitExpr> = IsUnknownMap<Unit['factors']> extends true ? UnknownUnit : UnitParts<NormalizeMap<Unit['factors']>>;
+type IsNaturalNumberText<Value extends string> = Value extends '' ? false : Value extends `-${string}` ? false : Value extends `${string}.${string}` ? false : Value extends `${string}e${string}` | `${string}E${string}` ? false : true;
+/**
+ * Parses a natural-number literal string (`'2'`) into its number literal (`2`).
+ *
+ * Returns `null` for negative/decimal/exponential forms so callers can
+ * safely fall back to opaque token handling for invalid exponents.
+ */
+type ParseNat<Value extends string> = IsNaturalNumberText<Value> extends true ? Value extends `${infer Parsed extends number}` ? `${Parsed}` extends Value ? Parsed : null : null : null;
+/** Builds `Count` tuple entries (`s^2` -> [unknown, unknown]). */
+type RepeatCount<Count extends number, Output extends unknown[] = []> = Output['length'] extends Count ? Output : RepeatCount<Count, [...Output, unknown]>;
+/**
+ * Parses one factor token:
+ * - `none` => dimensionless
+ * - `m` => m^1
+ * - `s^2` => s^2
+ */
+type ParseFactor<Factor extends string> = string extends Factor ? UnknownUnit : Factor extends '' ? UnknownUnit : Factor extends 'none' ? UnitParts<EmptyUnitMap> : Factor extends `${infer Base}^${infer ExponentText}` ? Base extends '' ? UnknownUnit : ParseNat<ExponentText> extends infer Exponent extends number ? UnitParts<{
+    readonly [Token in Base]: UnitExponent<RepeatCount<Exponent>, []>;
+}> : UnitParts<{
+    readonly [Token in Factor]: UnitExponent<[unknown], []>;
+}> : UnitParts<{
+    readonly [Token in Factor]: UnitExponent<[unknown], []>;
+}>;
+/**
+ * Splits an expression into `[term, operator, rest]`.
+ *
+ * Example:
+ * - `m/s^2` -> ['m', '/', 's^2']
+ */
+type TakeTerm<Source extends string, Current extends string = ''> = string extends Source ? [Source, '', ''] : Source extends `${infer Character}${infer Rest}` ? Character extends '*' | '/' ? [Current, Character, Rest] : TakeTerm<Rest, `${Current}${Character}`> : [Current, '', ''];
+/** Type-level unit multiplication helper. */
+export type MulUnit<LeftUnit extends UnitExpr, RightUnit extends UnitExpr> = IsUnknownMap<LeftUnit['factors']> extends true ? UnknownUnit : IsUnknownMap<RightUnit['factors']> extends true ? UnknownUnit : UnitParts<NormalizeMap<{
+    readonly [Token in keyof LeftUnit['factors'] | keyof RightUnit['factors'] as Token extends string ? Token : never]: CancelCounts<[
+        ...ExponentFor<LeftUnit['factors'], Token & string>['num'],
+        ...ExponentFor<RightUnit['factors'], Token & string>['num']
+    ], [
+        ...ExponentFor<LeftUnit['factors'], Token & string>['den'],
+        ...ExponentFor<RightUnit['factors'], Token & string>['den']
+    ]> extends [
+        infer Numerator extends Count,
+        infer Denominator extends Count
+    ] ? UnitExponent<Numerator, Denominator> : never;
+}>>;
+/** Type-level unit division helper. */
+export type DivUnit<LeftUnit extends UnitExpr, RightUnit extends UnitExpr> = IsUnknownMap<LeftUnit['factors']> extends true ? UnknownUnit : IsUnknownMap<RightUnit['factors']> extends true ? UnknownUnit : UnitParts<NormalizeMap<{
+    readonly [Token in keyof LeftUnit['factors'] | keyof RightUnit['factors'] as Token extends string ? Token : never]: CancelCounts<[
+        ...ExponentFor<LeftUnit['factors'], Token & string>['num'],
+        ...ExponentFor<RightUnit['factors'], Token & string>['den']
+    ], [
+        ...ExponentFor<LeftUnit['factors'], Token & string>['den'],
+        ...ExponentFor<RightUnit['factors'], Token & string>['num']
+    ]> extends [
+        infer Numerator extends Count,
+        infer Denominator extends Count
+    ] ? UnitExponent<Numerator, Denominator> : never;
+}>>;
+type HalfCount<Source extends Count, Output extends unknown[] = []> = Source extends readonly [unknown, unknown, ...infer Tail extends unknown[]] ? HalfCount<Tail, [...Output, unknown]> : Source extends readonly [] ? Output : never;
+type HalfFactor<Factor extends UnitExponent> = UnitExponent<HalfCount<Factor['num']>, HalfCount<Factor['den']>>;
+type HasInvalidHalf<Factors extends UnitMap> = true extends {
+    [Token in keyof Factors]: HalfCount<Factors[Token]['num']> extends never ? true : HalfCount<Factors[Token]['den']> extends never ? true : false;
+}[keyof Factors] ? true : false;
+/** Type-level square-root helper for normalized unit expressions. */
+export type SqrtUnit<Unit extends UnitExpr> = NormalizeUnit<Unit> extends infer Normalized extends UnitExpr ? IsUnknownMap<Normalized['factors']> extends true ? never : HasInvalidHalf<Normalized['factors']> extends true ? never : UnitParts<NormalizeMap<{
+    readonly [Token in keyof Normalized['factors']]: HalfFactor<Normalized['factors'][Token]>;
+}>> : never;
+/**
+ * Recursive parser:
+ * 1. Parse the next factor
+ * 2. Apply pending operator to accumulated unit
+ * 3. Continue until no operator remains
+ */
+type ParseUnitTail<Accumulated extends UnitExpr, Operator extends string, Rest extends string> = Operator extends '' ? NormalizeUnit<Accumulated> : TakeTerm<Rest> extends [
+    infer NextFactor extends string,
+    infer NextOperator extends string,
+    infer NextRest extends string
+] ? ParseFactor<NextFactor> extends infer NextUnit extends UnitExpr ? ParseUnitTail<Operator extends '*' ? MulUnit<Accumulated, NextUnit> : Operator extends '/' ? DivUnit<Accumulated, NextUnit> : Accumulated, NextOperator, NextRest> : never : never;
+/** Parses the first factor, then delegates to `ParseUnitTail`. */
+type ParseUnitExpr<Expr extends string> = TakeTerm<Expr> extends [
+    infer FirstFactor extends string,
+    infer FirstOperator extends string,
+    infer Rest extends string
+] ? ParseFactor<FirstFactor> extends infer FirstUnit extends UnitExpr ? ParseUnitTail<FirstUnit, FirstOperator, Rest> : never : never;
+/** Converts a unit expression string into a normalized compile-time unit type. */
+export type UnitFromString<Expr extends string> = ParseUnitExpr<Expr>;
+/** Compile-time token for explicitly declaring units. */
+export type UnitTag<Unit extends UnitExpr> = string & {
+    readonly [unitTagBrand]: Unit;
+};
+/**
+ * Unit-branded scalar quantity.
+ *
+ * Runtime representation is a plain number.
+ */
+export type Quantity<Unit extends UnitExpr> = number & {
+    readonly [quantityBrand]: Unit;
+};
+/**
+ * Creates a compile-time unit token.
+ *
+ * @param name Unit expression text (for example `m/s^2` or `none`).
+ * @returns Branded token used to construct unit-safe quantities.
+ */
+export declare const unit: <Expr extends string>(name: string extends Expr ? never : Expr) => UnitTag<UnitFromString<Expr>>;
+/** Shared compile-time token for the `none` (dimensionless) unit. */
+export declare const dimensionlessUnit: UnitTag<Dimensionless>;
+/**
+ * Creates a quantity from an explicit unit token and numeric value.
+ *
+ * @param unitTag Compile-time unit token.
+ * @param value Raw numeric value.
+ * @returns Branded unit-safe quantity.
+ */
+export declare const quantity: <Unit extends UnitExpr>(unitTag: UnitTag<Unit>, value: number) => Quantity<Unit>;
+/**
+ * Creates a dimensionless quantity.
+ *
+ * @param value Raw numeric value.
+ * @returns Quantity branded as `none`.
+ */
+export declare const dimensionless: (value: number) => Quantity<Dimensionless>;
+/**
+ * Unwraps a quantity to its raw numeric value.
+ *
+ * @param value Branded quantity.
+ * @returns Underlying runtime number.
+ */
+export declare const valueOf: <Unit extends UnitExpr>(value: Quantity<Unit>) => number;
+/**
+ * Adds two same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns Sum in the same unit.
+ */
+export declare const add: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => Quantity<Unit>;
+/**
+ * Subtracts two same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns Difference in the same unit.
+ */
+export declare const sub: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => Quantity<Unit>;
+/**
+ * Negates a quantity.
+ *
+ * @param value Input quantity.
+ * @returns Quantity with sign flipped.
+ */
+export declare const neg: <Unit extends UnitExpr>(value: Quantity<Unit>) => Quantity<Unit>;
+/**
+ * Computes absolute value of a quantity.
+ *
+ * @param value Input quantity.
+ * @returns Non-negative quantity in the same unit.
+ */
+export declare const abs: <Unit extends UnitExpr>(value: Quantity<Unit>) => Quantity<Unit>;
+/**
+ * Returns the smaller of two same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns Smaller quantity.
+ */
+export declare const min: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => Quantity<Unit>;
+/**
+ * Returns the larger of two same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns Larger quantity.
+ */
+export declare const max: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => Quantity<Unit>;
+/**
+ * Clamps a quantity to the inclusive range [`minValue`, `maxValue`].
+ *
+ * Unsafe variant: performs no bound-order validation.
+ *
+ * @param value Value to clamp.
+ * @param minValue Inclusive lower bound.
+ * @param maxValue Inclusive upper bound.
+ * @returns Clamped quantity.
+ */
+export declare const clampUnsafe: <Unit extends UnitExpr>(value: Quantity<Unit>, minValue: Quantity<NoInfer<Unit>>, maxValue: Quantity<NoInfer<Unit>>) => Quantity<Unit>;
+/**
+ * Clamps a quantity to the inclusive range [`minValue`, `maxValue`].
+ *
+ * Throws when `minValue > maxValue`.
+ *
+ * @param value Value to clamp.
+ * @param minValue Inclusive lower bound.
+ * @param maxValue Inclusive upper bound.
+ * @returns Clamped quantity.
+ * @throws {Error} When `minValue > maxValue`.
+ */
+export declare const clamp: <Unit extends UnitExpr>(value: Quantity<Unit>, minValue: Quantity<NoInfer<Unit>>, maxValue: Quantity<NoInfer<Unit>>) => Quantity<Unit>;
+/**
+ * Multiplies a quantity by a unitless scalar.
+ *
+ * @param value Input quantity.
+ * @param scalar Unitless scale factor.
+ * @returns Scaled quantity in the same unit.
+ */
+export declare const scale: <Unit extends UnitExpr>(value: Quantity<Unit>, scalar: number) => Quantity<Unit>;
+/**
+ * Multiplies two quantities and composes normalized unit expressions.
+ *
+ * @param left Left quantity.
+ * @param right Right quantity.
+ * @returns Product with type-level multiplied unit.
+ */
+export declare const mul: <LeftUnit extends UnitExpr, RightUnit extends UnitExpr>(left: Quantity<LeftUnit>, right: Quantity<RightUnit>) => Quantity<MulUnit<LeftUnit, RightUnit>>;
+/**
+ * Divides two quantities and composes normalized unit expressions.
+ *
+ * @param left Numerator quantity.
+ * @param right Denominator quantity.
+ * @returns Quotient with type-level divided unit.
+ */
+export declare const div: <LeftUnit extends UnitExpr, RightUnit extends UnitExpr>(left: Quantity<LeftUnit>, right: Quantity<RightUnit>) => Quantity<DivUnit<LeftUnit, RightUnit>>;
+/**
+ * Computes square root of a quantity.
+ *
+ * @param value Quantity whose unit can be square-rooted at compile time.
+ * @returns Square root with inferred root unit.
+ */
+export declare function sqrt<Unit extends UnitExpr>(value: [SqrtUnit<Unit>] extends [never] ? never : Quantity<Unit>): Quantity<SqrtUnit<Unit>>;
+/**
+ * Strict equality (`===`) for same-unit quantities.
+ *
+ * This uses exact comparison and does **not** account for floating-point
+ * rounding error. After arithmetic (e.g. `add`, `sub`, `mul`) the result
+ * may differ from the mathematically expected value by a small epsilon.
+ * Use `approxEq` when comparing quantities that have been through arithmetic.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` only when values are exactly equal.
+ */
+export declare const eq: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => boolean;
+/**
+ * Approximate equality for same-unit quantities.
+ *
+ * Returns `true` when the absolute difference is within `tolerance`
+ * (default `1e-10`).
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @param tolerance Maximum absolute difference allowed.
+ * @returns `true` when values are approximately equal.
+ */
+export declare const approxEq: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>, tolerance?: number) => boolean;
+/**
+ * Less-than comparison for same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` when `left < right`.
+ */
+export declare const lt: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => boolean;
+/**
+ * Less-than-or-equal comparison for same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` when `left <= right`.
+ */
+export declare const lte: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => boolean;
+/**
+ * Greater-than comparison for same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` when `left > right`.
+ */
+export declare const gt: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => boolean;
+/**
+ * Greater-than-or-equal comparison for same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` when `left >= right`.
+ */
+export declare const gte: <Unit extends UnitExpr>(left: Quantity<Unit>, right: Quantity<NoInfer<Unit>>) => boolean;
+/**
+ * Sums a list of same-unit quantities.
+ *
+ * @param values Input quantities with identical units.
+ * @returns Total sum in the same unit.
+ */
+export declare const sum: <Unit extends UnitExpr>(values: readonly Quantity<Unit>[]) => Quantity<Unit>;
+/**
+ * Computes average of a non-empty list of same-unit quantities.
+ *
+ * @param values Non-empty input list.
+ * @returns Arithmetic mean in the same unit.
+ */
+export declare const average: <Unit extends UnitExpr>(values: readonly [Quantity<Unit>, ...Quantity<Unit>[]]) => Quantity<Unit>;
+export {};
+//# sourceMappingURL=units.d.ts.map

package/esm/src/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/src/units.ts"],"names":[],"mappings":"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"}

package/esm/src/units.js

@@ -0,0 +1,219 @@
+/**
+ * Casts a raw number into a branded quantity.
+ *
+ * @param value Raw numeric scalar.
+ * @returns Branded quantity of the requested unit type.
+ */
+const asQuantity = (value) => value;
+/**
+ * Creates a compile-time unit token.
+ *
+ * @param name Unit expression text (for example `m/s^2` or `none`).
+ * @returns Branded token used to construct unit-safe quantities.
+ */
+export const unit = (name) => name;
+/** Shared compile-time token for the `none` (dimensionless) unit. */
+export const dimensionlessUnit = unit('none');
+/**
+ * Creates a quantity from an explicit unit token and numeric value.
+ *
+ * @param unitTag Compile-time unit token.
+ * @param value Raw numeric value.
+ * @returns Branded unit-safe quantity.
+ */
+export const quantity = (unitTag, value) => {
+    void unitTag;
+    return asQuantity(value);
+};
+/**
+ * Creates a dimensionless quantity.
+ *
+ * @param value Raw numeric value.
+ * @returns Quantity branded as `none`.
+ */
+export const dimensionless = (value) => asQuantity(value);
+/**
+ * Unwraps a quantity to its raw numeric value.
+ *
+ * @param value Branded quantity.
+ * @returns Underlying runtime number.
+ */
+export const valueOf = (value) => value;
+/**
+ * Adds two same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns Sum in the same unit.
+ */
+export const add = (left, right) => asQuantity(left + right);
+/**
+ * Subtracts two same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns Difference in the same unit.
+ */
+export const sub = (left, right) => asQuantity(left - right);
+/**
+ * Negates a quantity.
+ *
+ * @param value Input quantity.
+ * @returns Quantity with sign flipped.
+ */
+export const neg = (value) => asQuantity(-value);
+/**
+ * Computes absolute value of a quantity.
+ *
+ * @param value Input quantity.
+ * @returns Non-negative quantity in the same unit.
+ */
+export const abs = (value) => asQuantity(Math.abs(value));
+/**
+ * Returns the smaller of two same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns Smaller quantity.
+ */
+export const min = (left, right) => asQuantity(Math.min(left, right));
+/**
+ * Returns the larger of two same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns Larger quantity.
+ */
+export const max = (left, right) => asQuantity(Math.max(left, right));
+/**
+ * Clamps a quantity to the inclusive range [`minValue`, `maxValue`].
+ *
+ * Unsafe variant: performs no bound-order validation.
+ *
+ * @param value Value to clamp.
+ * @param minValue Inclusive lower bound.
+ * @param maxValue Inclusive upper bound.
+ * @returns Clamped quantity.
+ */
+export const clampUnsafe = (value, minValue, maxValue) => max(minValue, min(value, maxValue));
+/**
+ * Clamps a quantity to the inclusive range [`minValue`, `maxValue`].
+ *
+ * Throws when `minValue > maxValue`.
+ *
+ * @param value Value to clamp.
+ * @param minValue Inclusive lower bound.
+ * @param maxValue Inclusive upper bound.
+ * @returns Clamped quantity.
+ * @throws {Error} When `minValue > maxValue`.
+ */
+export const clamp = (value, minValue, maxValue) => {
+    if (minValue > maxValue) {
+        throw new Error('minValue must be <= maxValue');
+    }
+    return clampUnsafe(value, minValue, maxValue);
+};
+/**
+ * Multiplies a quantity by a unitless scalar.
+ *
+ * @param value Input quantity.
+ * @param scalar Unitless scale factor.
+ * @returns Scaled quantity in the same unit.
+ */
+export const scale = (value, scalar) => asQuantity(value * scalar);
+/**
+ * Multiplies two quantities and composes normalized unit expressions.
+ *
+ * @param left Left quantity.
+ * @param right Right quantity.
+ * @returns Product with type-level multiplied unit.
+ */
+export const mul = (left, right) => asQuantity(left * right);
+/**
+ * Divides two quantities and composes normalized unit expressions.
+ *
+ * @param left Numerator quantity.
+ * @param right Denominator quantity.
+ * @returns Quotient with type-level divided unit.
+ */
+export const div = (left, right) => asQuantity(left / right);
+export function sqrt(value) {
+    return asQuantity(Math.sqrt(value));
+}
+/**
+ * Strict equality (`===`) for same-unit quantities.
+ *
+ * This uses exact comparison and does **not** account for floating-point
+ * rounding error. After arithmetic (e.g. `add`, `sub`, `mul`) the result
+ * may differ from the mathematically expected value by a small epsilon.
+ * Use `approxEq` when comparing quantities that have been through arithmetic.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` only when values are exactly equal.
+ */
+export const eq = (left, right) => left === right;
+/**
+ * Approximate equality for same-unit quantities.
+ *
+ * Returns `true` when the absolute difference is within `tolerance`
+ * (default `1e-10`).
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @param tolerance Maximum absolute difference allowed.
+ * @returns `true` when values are approximately equal.
+ */
+export const approxEq = (left, right, tolerance = 1e-10) => Math.abs(left - right) <= tolerance;
+/**
+ * Less-than comparison for same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` when `left < right`.
+ */
+export const lt = (left, right) => left < right;
+/**
+ * Less-than-or-equal comparison for same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` when `left <= right`.
+ */
+export const lte = (left, right) => left <= right;
+/**
+ * Greater-than comparison for same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` when `left > right`.
+ */
+export const gt = (left, right) => left > right;
+/**
+ * Greater-than-or-equal comparison for same-unit quantities.
+ *
+ * @param left Left operand.
+ * @param right Right operand with the same unit as `left`.
+ * @returns `true` when `left >= right`.
+ */
+export const gte = (left, right) => left >= right;
+/**
+ * Sums a list of same-unit quantities.
+ *
+ * @param values Input quantities with identical units.
+ * @returns Total sum in the same unit.
+ */
+export const sum = (values) => {
+    let total = 0;
+    for (const value of values) {
+        total += value;
+    }
+    return asQuantity(total);
+};
+/**
+ * Computes average of a non-empty list of same-unit quantities.
+ *
+ * @param values Non-empty input list.
+ * @returns Arithmetic mean in the same unit.
+ */
+export const average = (values) => asQuantity(sum(values) / values.length);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@sachitv/safe-math-ts",
+  "version": "0.1.0",
+  "description": "A zero-dependency Deno/TypeScript 3D math library with strict compile-time safety.",
+  "homepage": "https://github.com/sachitv/safe-math-ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sachitv/safe-math-ts.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/sachitv/safe-math-ts/issues"
+  },
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "types": "./esm/mod.d.ts"
+    }
+  },
+  "scripts": {},
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^20.9.0"
+  },
+  "_generatedBy": "dnt@dev"
+}