# @rickosborne/rebound Tools for working with bounded numbers. For example: - RGB values: \[0,255\] for both integers and real numbers - Hues: \[0,360), also int and real - Chroma: \[0,1\] - And other non-color-related things. Built on top of: - [@rickosborne/foundation](https://www.npmjs.com/package/@rickosborne/foundation) for data structures and general helpers - [@rickosborne/guard](https://www.npmjs.com/package/@rickosborne/guard) for TypeScript guards - [@rickosborne/typical](https://www.npmjs.com/package/@rickosborne/typical) for helper TypeScript type definitions ## Usage Install via your favorite package manager. Each package supports CommonJS `require`, ESM `import`, and TypeScript usage. You also have a choice: barrel imports or direct imports. Barrel imports mean you're going to require/import everything from the same package-level namespace: ```typescript // CommonJS const { isPlainObject, isListOf } = require("@rickosborne/guard"); // ESM / TypeScript import { isPlainObject, isListOf } from "@rickosborne/guard"; ``` Implications: - Nice and simple. - Your build system needs to do tree-shaking well ... or you'll end up adding the entire package even if you only import two functions. The other option is to use direct imports: ```typescript // CommonJS const { isPlainObject } = require("@rickosborne/guard/is-object"); const { isListOf } = require("@rickosborne/guard/is-list-of"); // ESM / TypeScript import { isPlainObject } from "@rickosborne/guard/is-object.js"; import { isListOf } from "@rickosborne/guard/is-list-of.js"; ``` Implications: - You (probably) don't have to worry about tree-shaking as your build (likely) ends up with only the functions you need. If you're using a modern build system, there aren't any strong reasons to prefer one way over the other. It's really just down to your personal preference. ### A quick note about file extensions Do you need to use file extensions? And if so, which extensions? Honestly ... this is a dumpster fire question. It really comes down to your own setup and configuration. Within each package itself: - The CommonJS files all have `.cjs` extensions. - The ESM files all have `.mjs` extensions. - Node subpath exports have been set up to send `.js` imports to the `.cjs` (via `require`) or `.mjs` (via `import`) files, depending on your setup. So, in theory, the only extension which _won't_ work would be `.ts` because the source isn't included. If you run into a problem with a particular configuration, file a GitHub issue with: - Your `tsconfig.json`'s `module`, `moduleResolution`, and `target` settings. - Your `package.json`'s `type` and `imports` settings. - An example of another package which imports correctly for you. ## License This package is licensed as [CC-BY-NC-SA-4.0] unless otherwise noted. That is, Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International. [CC-BY-NC-SA-4.0]: https://creativecommons.org/licenses/by-nc-sa/4.0/ *** ## API ### Classes #### Bound ```typescript class Bound ``` #### EmptyRange ```typescript class EmptyRange extends RangeBase ``` #### IntegerRange ```typescript class IntegerRange extends NumberRange ``` #### NumberRange ```typescript abstract class NumberRange extends RangeBase implements CheckedBounds, RangeLike ``` #### RangeBase ```typescript abstract class RangeBase implements RangeLike ``` #### RealRange ```typescript class RealRange extends NumberRange ``` #### Rebound ```typescript class Rebound implements TypedCheckedBounds ``` #### ReboundBuilder ```typescript class ReboundBuilder ``` #### StringRange ```typescript class StringRange extends RangeBase ``` ### Functions #### addTypedProperties ```typescript addTypedProperties: >(target: T, bounds: Bounds, typeName: string, fnName: string) => T & TypedCheckedBounds ``` #### assertBounded ```typescript function assertBounded(guard: If, GuardExact>, errorProvider: OutOfBoundsErrorProvider, ifPresent: IfPresent, value: unknown, name?: string | undefined): asserts value is IfIfPresent; ``` #### assertForBounds ```typescript function assertForBounds(guard: If, GuardExact>, errorProvider: OutOfBoundsErrorProvider, ifPresent: IfPresent, fnName?: string): If, AssertExact>; ``` #### assertSameBounds ```typescript function assertSameBounds(left: TypedCheckedBounds, right: TypedCheckedBounds, errorSupplier?: undefined | ((mismatchedKeys: (keyof TypedCheckedBounds)[], left: TypedCheckedBounds, right: TypedCheckedBounds) => Error)): void; ``` #### boundComparator ```typescript boundComparator: (a: Bound | Unbounded, b: Bound | Unbounded) => number ``` #### boundedFromNumber ```typescript function boundedFromNumber(guard: GuardExact, errorProvider: OutOfBoundsErrorProvider, ifPresent: IfPresent, value: number | undefined | null, name?: string | undefined): If; ``` #### boundedIntFromNumber ```typescript function boundedIntFromNumber(isLowerInc: IsLowerInc, lower: Lower, upper: Upper, isUpperInc: IsUpperInc, ifPresent: IfPresent, errorProvider: OutOfBoundsErrorProvider, strategy: ToInt, value: number | undefined | null, name?: string | undefined): If; ``` #### checkMissing ```typescript function checkMissing(config: Partial>): asserts config is BoundsConfig; ``` #### effectiveRange ```typescript effectiveRange: (bounds: CheckedBounds) => number ``` Calculate the effective range for a given bounds. That is, take into account the inclusivity of the lower and upper bounds. #### fromNumberForBounds ```typescript function fromNumberForBounds(guard: GuardExact, errorProvider: OutOfBoundsErrorProvider, ifPresent: IfPresent, fnName?: string): If, FromNumber>; ``` #### guardForBounds ```typescript function guardForBounds, N extends number, IfPresent extends boolean>(bounds: Bounds, typeName: string, fnName: string, ifPresent: IfPresent): If, GuardExact>; ``` Generate a guard for the branded number type matching the given spec. #### ifIfPresent ```typescript ifIfPresent: (ifPresent: IfPresent, t: T, u: U) => If ``` #### int255From01 ```typescript function int255From01(value: Real01): Int255; ``` Convert a [Real01](#api-real01) to an [Int255](#api-int255). #### int255From01 ```typescript function int255From01(value: undefined): undefined; ``` #### integerFrom ```typescript function integerFrom(typeName: string, bounds: CheckedBoundsConfig & { label: string; }, errorProvider: OutOfBoundsErrorProvider, ifPresent: IfPresent, strategy?: IntStrategy, fnName?: string): If, ConvertTo>; ``` #### integerGenerator ```typescript function integerGenerator(bounds: CheckedBounds, options?: IntegerGeneratorOptions): Generator; ``` #### randomBounded ```typescript randomBounded: (typeName: string, label: string, isLowerInc: boolean, lower: number, isInt: boolean, upper: number, isUpperInc: boolean, rng?: ({ float01(): number; range(low: number, high: number): number; }), fnName?: string) => RandomBounded ``` #### rangeFromChecked ```typescript rangeFromChecked: (config: CheckedBounds) => BoundsLabel> ``` #### rangeFromConfig ```typescript rangeFromConfig: >(config: Config) => BoundsLabel ``` #### real01From255 ```typescript function real01From255(value: number | Int255 | Real255): Real01; ``` Convert a [Real255](#api-real255) or [Int255](#api-int255) to a [Real01](#api-real01). #### real01From255 ```typescript function real01From255(value: undefined): undefined; ``` #### real01From255 ```typescript function real01From255(value: number | Int255 | Real255 | undefined): Real01 | undefined; ``` #### real255From01 ```typescript real255From01: (value: Real01) => Real255 ``` Convert a [Real01](#api-real01) to a [Real255](#api-real255). #### sameBounds ```typescript sameBounds: (left: TypedCheckedBounds, right: TypedCheckedBounds) => boolean ``` #### scaleBounded ```typescript scaleBounded: (inputBounds: TypedCheckedBounds, outputBounds: TypedCheckedBounds, ifPresent: IfPresent, fnName?: string) => If, ScaleExact> ``` #### validateBounded ```typescript validateBounded: (isLowerInc: IsLowerInc, lower: Lower, isInt: IsInt, upper: Upper, isUpperInc: IsUpperInc, ifPresent: IfPresent, value: unknown) => value is IfIfPresent> ``` ### Interfaces #### AnyBoundsConfig ```typescript export interface AnyBoundsConfig ``` #### AssertExact ```typescript export interface AssertExact extends TypedCheckedBounds ``` #### AssertIfPresent ```typescript export interface AssertIfPresent extends TypedCheckedBounds ``` #### BoundIsInclusive ```typescript export interface BoundIsInclusive ``` #### BoundsConfig ```typescript export interface BoundsConfig extends AnyBoundsConfig ``` #### BoundsWithRange ```typescript export interface BoundsWithRange>, LowerInc extends LowerInEx, Lower extends number, Int extends NumberSet, Upper extends number, UpperInc extends UpperInEx> extends BoundsConfig ``` #### CheckedBounds ```typescript export interface CheckedBounds ``` #### CheckedBoundsConfig ```typescript export interface CheckedBoundsConfig ``` #### ConvertIfPresentTo ```typescript export interface ConvertIfPresentTo extends ConvertTo ``` #### ConvertTo ```typescript export interface ConvertTo extends TypedCheckedBounds ``` #### DefinedBounds ```typescript export interface DefinedBounds ``` #### DefinedFromChecked ```typescript export interface DefinedFromChecked extends DefinedBounds ``` #### DefinedFromCheckedConfig ```typescript export interface DefinedFromCheckedConfig extends DefinedFromChecked ``` #### FromNumber ```typescript export interface FromNumber extends TypedCheckedBounds ``` #### FromNumberIfPresent ```typescript export interface FromNumberIfPresent extends FromNumber ``` #### GuardExact ```typescript export interface GuardExact extends TypedCheckedBounds ``` #### GuardIfPresent ```typescript export interface GuardIfPresent extends TypedCheckedBounds ``` #### IntegerGeneratorOptions ```typescript export interface IntegerGeneratorOptions ``` #### NumberSetIsInt ```typescript export interface NumberSetIsInt ``` #### RandomBounded ```typescript export interface RandomBounded extends TypedCheckedBounds ``` #### RangedBounds ```typescript export interface RangedBounds extends DefinedBounds ``` #### RangeLike ```typescript export interface RangeLike ``` #### ReboundAllowUndef ```typescript export interface ReboundAllowUndef ``` #### Rebounded ```typescript export interface Rebounded>, LowerInc extends LowerInEx, Lower extends number, Int extends NumberSet, Upper extends number, UpperInc extends UpperInEx> ``` Nice, short, human-readable signature which will show up in the IDE. #### ReboundedFromChecked ```typescript export interface ReboundedFromChecked extends Rebounded>, LowerInExFrom, Lower, NumberSetFrom, Upper, UpperInExFrom> ``` #### ReboundedFromConfig ```typescript export interface ReboundedFromConfig extends Rebounded>, LowerInc, Lower, Int, Upper, UpperInc> ``` #### ReboundFnOptions ```typescript export interface ReboundFnOptions ``` #### ReboundRandomOptions ```typescript export interface ReboundRandomOptions ``` #### ReboundToIntOptions ```typescript export interface ReboundToIntOptions extends ReboundFnOptions ``` #### ResolvedFnOptions ```typescript export interface ResolvedFnOptions extends Required ``` #### ResolvedToIntOptions ```typescript export interface ResolvedToIntOptions extends Required ``` #### ScaleExact ```typescript export interface ScaleExact extends TypedCheckedBounds ``` #### ScaleIfPresent ```typescript export interface ScaleIfPresent extends TypedCheckedBounds ``` #### TypedBounds ```typescript export interface TypedBounds extends RangedBounds ``` #### TypedCheckedBounds ```typescript export interface TypedCheckedBounds extends CheckedBounds ``` ### TypeAliases #### BoundedNumber ```typescript type BoundedNumber = Bounds extends BoundsConfig ? (number & ReboundedFromConfig) : Bounds extends CheckedBoundsConfig ? (number & ReboundedFromChecked) : never; ``` Brand a number type with a type-generated explanation of its bounds, so that it can only accept other numbers with the exact same bounds. #### BoundsLabel ```typescript type BoundsLabel = `${C extends { lowerInc: infer LowerInc extends LowerInEx; } ? LowerInc : never}${C extends { lower: NegInfinity; } ? NegInfinityLabel : C extends { lower: infer Lower extends number; } ? number extends Lower ? never : `${Lower}` : never}${C extends { int: infer Int extends NumberSet; } ? Int extends IntegerSet ? ".." : "," : never}${C extends { upper: PosInfinity; } ? PosInfinityLabel : C extends { upper: infer Upper extends number; } ? number extends Upper ? never : `${Upper}` : never}${C extends { upperInc: infer UpperInc extends UpperInEx; } ? UpperInc : never}`; ``` #### BoundType ```typescript type BoundType = typeof BOUND_GT | typeof BOUND_GTE | typeof BOUND_LT | typeof BOUND_LTE; ``` #### If ```typescript type If = IfPresent extends true ? T : U; ``` #### IfIfPresent ```typescript type IfIfPresent = IfPresent extends true ? (T | null | undefined) : T; ``` #### InfinityBound ```typescript type InfinityBound = number & { infinity: string; }; ``` #### Int255 ```typescript type Int255 = typeof int255.numberType; ``` An integer in the range [0,255]. #### Int360 ```typescript type Int360 = typeof int360.numberType; ``` An integer in the range [0,360). #### IntegerSet ```typescript type IntegerSet = "int"; ``` #### IntStrategy ```typescript type IntStrategy = typeof ROUND | typeof CEIL | typeof TRUNC | typeof FLOOR | ((value: number) => number); ``` #### IsBounded ```typescript type IsBounded = N extends { [BOUNDS]: object; } ? true : false; ``` Helper for checking if you're dealing with a [BoundedNumber](#api-boundednumber). #### IsFinite ```typescript type IsFinite = N extends { [BOUNDS]: { lower: infer Lower extends number; upper: infer Upper extends number; }; } ? Lower extends InfinityBound ? false : Upper extends InfinityBound ? false : true : never; ``` Whether the number has defined bounds (neither upper nor lower is infinite). #### IsInclusive ```typescript type IsInclusive = BoundIsInclusive[Inc]; ``` #### IsInfinite ```typescript type IsInfinite = N extends { [BOUNDS]: { lower: infer Lower extends number; upper: infer Upper extends number; }; } ? Lower extends InfinityBound ? true : Upper extends InfinityBound ? true : false : never; ``` Whether the number has infinite bounds, either upper or lower. #### IsIntegersOnly ```typescript type IsIntegersOnly = N extends { [BOUNDS]: { int: IntegerSet; }; } ? true : false; ``` Extract whether the number only accepts integers. #### IsIntFrom ```typescript type IsIntFrom = NumberSetIsInt[Int]; ``` #### LowerBound ```typescript type LowerBound = N extends { [BOUNDS]: { lower: infer Lower extends number; }; } ? Lower : never; ``` Extract the value for the lower bound. #### LowerBoundIsInc ```typescript type LowerBoundIsInc = N extends { [BOUNDS]: { lowerInc: infer LowerInc extends LowerInEx; }; } ? LowerInc extends LowerInclusive ? true : false : never; ``` Extract whether the lower bound is inclusive (true) or exclusive (false). #### LowerExclusive ```typescript type LowerExclusive = "("; ``` #### LowerInclusive ```typescript type LowerInclusive = "["; ``` #### LowerInEx ```typescript type LowerInEx = LowerInclusive | LowerExclusive; ``` #### LowerInExFrom ```typescript type LowerInExFrom = boolean extends B ? never : true extends B ? LowerInclusive : LowerExclusive; ``` #### NegInfinity ```typescript type NegInfinity = number & { infinity: NegInfinityLabel; }; ``` #### NegInfinityLabel ```typescript type NegInfinityLabel = "-∞"; ``` #### NumberSet ```typescript type NumberSet = IntegerSet | RealSet; ``` #### NumberSetFrom ```typescript type NumberSetFrom = boolean extends B ? never : true extends B ? IntegerSet : RealSet; ``` #### OutOfBoundsErrorProvider ```typescript type OutOfBoundsErrorProvider = (value: unknown, name?: string | undefined) => Error; ``` #### PosInfinity ```typescript type PosInfinity = number & { infinity: PosInfinityLabel; }; ``` #### PosInfinityLabel ```typescript type PosInfinityLabel = "+∞"; ``` #### Real01 ```typescript type Real01 = typeof real01.numberType; ``` A real number in the range [0,1]. #### Real255 ```typescript type Real255 = typeof real255.numberType; ``` A real number in the range [0,255]. #### Real360 ```typescript type Real360 = typeof real360.numberType; ``` A number in the range [0,360). #### RealSet ```typescript type RealSet = "real"; ``` #### ReboundConfigBuilder ```typescript type ReboundConfigBuilder = { readonly config: BoundsConfig; } & IsCompleteConfig extends true ? { build(): Rebound>>; } : ((number extends Lower ? { fromExclusive(value: L): ReboundConfigBuilder; fromInclusive(value: L): ReboundConfigBuilder; fromNegInfinity(): ReboundConfigBuilder, NegInfinity, Int, Upper, UpperInc>; fromValue(value: L, inclusive: LI): ReboundConfigBuilder, L, Int, Upper, UpperInc>; } : object) & (NumberSet extends Int ? { intOnly(int: IR): ReboundConfigBuilder, Upper, UpperInc>; integers(): ReboundConfigBuilder; reals(): ReboundConfigBuilder; } : object) & (number extends Upper ? { toExclusive(value: U): ReboundConfigBuilder; toInclusive(value: U): ReboundConfigBuilder; toPosInfinity(): ReboundConfigBuilder>; toValue(value: U, inclusive: UI): ReboundConfigBuilder>; } : object)); ``` #### ToInt ```typescript type ToInt = (this: void, value: number, name?: string | undefined) => N; ``` #### Unbound ```typescript type Unbound = IsBounded extends true ? number : N; ``` You could also just cast to `number`, but this provides a nice explicit and hard-to-miss visual. It is also helpful in downstream type definitions where you need the bound types to be fungible. #### Unbounded ```typescript type Unbounded = typeof unbounded; ``` #### UpperBound ```typescript type UpperBound = N extends { [BOUNDS]: { upper: infer Upper extends number; }; } ? Upper : never; ``` Extract the value for the upper bound. #### UpperBoundIsInc ```typescript type UpperBoundIsInc = N extends { [BOUNDS]: { upperInc: infer UpperInc extends UpperInEx; }; } ? UpperInc extends UpperInclusive ? true : false : never; ``` Extract whether the lower bound is inclusive (true) or exclusive (false). #### UpperExclusive ```typescript type UpperExclusive = ")"; ``` #### UpperInclusive ```typescript type UpperInclusive = "]"; ``` #### UpperInEx ```typescript type UpperInEx = UpperInclusive | UpperExclusive; ``` #### UpperInExFrom ```typescript type UpperInExFrom = boolean extends B ? never : true extends B ? UpperInclusive : UpperExclusive; ``` ### Variables #### assertInt255 ```typescript assertInt255: import("./assert-bounded.js").AssertExact ``` #### assertInt360 ```typescript assertInt360: import("./assert-bounded.js").AssertExact ``` #### assertReal01 ```typescript assertReal01: import("./assert-bounded.js").AssertExact ``` #### assertReal255 ```typescript assertReal255: import("./assert-bounded.js").AssertExact ``` #### assertReal360 ```typescript assertReal360: import("./assert-bounded.js").AssertExact ``` #### BOUND_GT ```typescript BOUND_GT = ">" ``` #### BOUND_GTE ```typescript BOUND_GTE = ">=" ``` #### BOUND_LT ```typescript BOUND_LT = "<" ``` #### BOUND_LTE ```typescript BOUND_LTE = "<=" ``` #### BOUND_TYPES ```typescript BOUND_TYPES: Readonly ``` #### BOUNDS ```typescript BOUNDS: unique symbol ``` #### boundTypeComparator ```typescript boundTypeComparator: Comparator ``` #### boundTypeComparisonIsValid ```typescript boundTypeComparisonIsValid: Readonly boolean>> ``` #### CEIL ```typescript CEIL = "ceil" ``` #### FLOOR ```typescript FLOOR = "floor" ``` #### INT_SET ```typescript INT_SET: IntegerSet ``` #### int255 ```typescript int255: Rebound> ``` #### int360 ```typescript int360: Rebound> ``` #### isInt255 ```typescript isInt255: import("./guard-bounded.js").GuardExact> ``` #### isInt360 ```typescript isInt360: import("./guard-bounded.js").GuardExact> ``` #### isReal01 ```typescript isReal01: import("./guard-bounded.js").GuardExact> ``` #### isReal255 ```typescript isReal255: import("./guard-bounded.js").GuardExact> ``` #### isReal360 ```typescript isReal360: import("./guard-bounded.js").GuardExact> ``` #### LOWER_EX ```typescript LOWER_EX: LowerExclusive ``` #### LOWER_IN ```typescript LOWER_IN: LowerInclusive ``` #### REAL_SET ```typescript REAL_SET: RealSet ``` #### real01 ```typescript real01: Rebound> ``` #### real255 ```typescript real255: Rebound> ``` #### real360 ```typescript real360: Rebound> ``` #### ROUND ```typescript ROUND = "round" ``` #### toInt255 ```typescript toInt255: import("./from-number-bounded.js").FromNumberIfPresent> ``` #### toInt360 ```typescript toInt360: import("./from-number-bounded.js").FromNumberIfPresent> ``` #### toReal01 ```typescript toReal01: import("./from-number-bounded.js").FromNumberIfPresent> ``` #### toReal255 ```typescript toReal255: import("./from-number-bounded.js").FromNumberIfPresent> ``` #### toReal360 ```typescript toReal360: import("./from-number-bounded.js").FromNumberIfPresent> ``` #### TRUNC ```typescript TRUNC = "trunc" ``` #### TYPED_BOUNDS_KEYS ```typescript TYPED_BOUNDS_KEYS: (keyof TypedBounds)[] ``` #### TYPED_CHECKED_BOUNDS_KEYS ```typescript TYPED_CHECKED_BOUNDS_KEYS: (keyof TypedCheckedBounds)[] ``` #### unbounded ```typescript unbounded: unique symbol ``` #### UPPER_EX ```typescript UPPER_EX: UpperExclusive ``` #### UPPER_IN ```typescript UPPER_IN: UpperInclusive ```