effect 4.0.0 → 4.0.2

package/src/ByteSize.ts

@@ -3,6 +3,7 @@
  *
  * Decimal units use powers of 1,000 and binary units use powers of 1,024.
  *
+ * @stability unstable
  * @since 4.0.0
  */
 import * as BI from "./BigInt.ts"
@@ -24,6 +25,7 @@ const binaryBase = BigInt(1024)
 /**
  * Represents an exact, non-negative number of bytes.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -40,6 +42,7 @@ export type ByteSize = Brand.Branded<bigint, typeof TypeId>
  *
  * @see {@link fromString} for external strings and fractional quantities
  * @see {@link fromStringUnsafe} for throwing string validation
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -75,6 +78,7 @@ type InputUnit =
 /**
  * Canonical decimal byte unit symbols.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -94,6 +98,7 @@ export type DecimalUnit =
 /**
  * Canonical binary byte unit symbols.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -111,6 +116,7 @@ export type BinaryUnit =
 /**
  * Canonical decimal and binary byte unit symbols.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -119,6 +125,7 @@ export type Unit = DecimalUnit | BinaryUnit
 /**
  * Options controlling compact byte-size formatting.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -179,6 +186,7 @@ const make = (value: bigint): ByteSize => value as ByteSize
 /**
  * The byte size containing zero bytes.
  *
+ * @stability unstable
  * @category constants
  * @since 4.0.0
  */
@@ -218,6 +226,7 @@ const fromQuantity = (quantity: number | bigint, unit: UnitInfo): ByteSize => {
  * bigint arithmetic, including above the safe integer range.
  *
  * @see {@link fromString} for non-throwing validation
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -245,6 +254,7 @@ export const fromStringUnsafe = (input: string): ByteSize => {
  * as `fromStringUnsafe`.
  *
  * @see {@link fromStringUnsafe} for throwing validation
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -253,6 +263,7 @@ export const fromString: (input: string) => Option.Option<ByteSize> = Option.lif
 /**
  * Decodes a trusted input into a byte size and throws for invalid input.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -272,6 +283,7 @@ export const fromInputUnsafe = (input: Input): ByteSize => {
 /**
  * Decodes an input into a byte size, returning `None` for invalid input.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -280,6 +292,7 @@ export const fromInput: (input: Input) => Option.Option<ByteSize> = Option.liftT
 /**
  * Creates a byte size from a non-negative byte count.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -292,6 +305,7 @@ const unitConstructor = (symbol: Unit) => (value: number | bigint): ByteSize =>
 /**
  * Creates a decimal kilobyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -299,6 +313,7 @@ export const kilobytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a decimal megabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -306,6 +321,7 @@ export const megabytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a decimal gigabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -313,6 +329,7 @@ export const gigabytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a decimal terabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -320,6 +337,7 @@ export const terabytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a decimal petabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -327,6 +345,7 @@ export const petabytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a decimal exabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -334,6 +353,7 @@ export const exabytes: (value: number | bigint) => ByteSize = unitConstructor("E
 /**
  * Creates a decimal zettabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -341,6 +361,7 @@ export const zettabytes: (value: number | bigint) => ByteSize = unitConstructor(
 /**
  * Creates a decimal yottabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -348,6 +369,7 @@ export const yottabytes: (value: number | bigint) => ByteSize = unitConstructor(
 /**
  * Creates a decimal ronnabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -355,6 +377,7 @@ export const ronnabytes: (value: number | bigint) => ByteSize = unitConstructor(
 /**
  * Creates a decimal quettabyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -362,6 +385,7 @@ export const quettabytes: (value: number | bigint) => ByteSize = unitConstructor
 /**
  * Creates a binary kibibyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -369,6 +393,7 @@ export const kibibytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a binary mebibyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -376,6 +401,7 @@ export const mebibytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a binary gibibyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -383,6 +409,7 @@ export const gibibytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a binary tebibyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -390,6 +417,7 @@ export const tebibytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a binary pebibyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -397,6 +425,7 @@ export const pebibytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a binary exbibyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -404,6 +433,7 @@ export const exbibytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a binary zebibyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -411,6 +441,7 @@ export const zebibytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Creates a binary yobibyte value.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -419,6 +450,7 @@ export const yobibytes: (value: number | bigint) => ByteSize = unitConstructor("
 /**
  * Checks whether a value is a byte size.
  *
+ * @stability unstable
  * @category guards
  * @since 4.0.0
  */
@@ -427,6 +459,7 @@ export const isByteSize = (input: unknown): input is ByteSize => typeof input ==
 /**
  * Checks whether a byte size is zero.
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -435,6 +468,7 @@ export const isZero = (self: ByteSize): boolean => self === bigint0
 /**
  * Returns the exact byte count as a bigint.
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -443,6 +477,7 @@ export const toBigInt = (self: ByteSize): bigint => self
 /**
  * Converts a byte size to a safe integer, returning `None` when it is too large.
  *
+ * @stability unstable
  * @category converting
  * @since 4.0.0
  */
@@ -451,6 +486,7 @@ export const toNumber: (self: ByteSize) => Option.Option<number> = BI.toNumber
 /**
  * Converts a byte size to a safe integer and throws when it is too large.
  *
+ * @stability unstable
  * @category unsafe
  * @since 4.0.0
  */
@@ -460,6 +496,7 @@ export const toNumberUnsafe = (self: ByteSize): number =>
 /**
  * Converts a byte size to an approximate number of the specified unit.
  *
+ * @stability unstable
  * @category converting
  * @since 4.0.0
  */
@@ -467,6 +504,7 @@ export const toUnit: {
   /**
    * Converts a byte size to an approximate number of the specified unit.
    *
+   * @stability unstable
    * @category converting
    * @since 4.0.0
    */
@@ -474,6 +512,7 @@ export const toUnit: {
   /**
    * Converts a byte size to an approximate number of the specified unit.
    *
+   * @stability unstable
    * @category converting
    * @since 4.0.0
    */
@@ -483,6 +522,7 @@ export const toUnit: {
 /**
  * Provides an order for byte sizes.
  *
+ * @stability unstable
  * @category instances
  * @since 4.0.0
  */
@@ -491,6 +531,7 @@ export const Order: order.Order<ByteSize> = BI.Order
 /**
  * Provides an equivalence for byte sizes.
  *
+ * @stability unstable
  * @category instances
  * @since 4.0.0
  */
@@ -499,6 +540,7 @@ export const Equivalence: Equ.Equivalence<ByteSize> = BI.Equivalence
 /**
  * Returns whether a byte size is in an inclusive range.
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -506,6 +548,7 @@ export const between: {
   /**
    * Returns whether a byte size is in an inclusive range.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -513,6 +556,7 @@ export const between: {
   /**
    * Returns whether a byte size is in an inclusive range.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -522,6 +566,7 @@ export const between: {
 /**
  * Returns the smaller byte size.
  *
+ * @stability unstable
  * @category ordering
  * @since 4.0.0
  */
@@ -529,6 +574,7 @@ export const min: {
   /**
    * Returns the smaller byte size.
    *
+   * @stability unstable
    * @category ordering
    * @since 4.0.0
    */
@@ -536,6 +582,7 @@ export const min: {
   /**
    * Returns the smaller byte size.
    *
+   * @stability unstable
    * @category ordering
    * @since 4.0.0
    */
@@ -545,6 +592,7 @@ export const min: {
 /**
  * Returns the larger byte size.
  *
+ * @stability unstable
  * @category ordering
  * @since 4.0.0
  */
@@ -552,6 +600,7 @@ export const max: {
   /**
    * Returns the larger byte size.
    *
+   * @stability unstable
    * @category ordering
    * @since 4.0.0
    */
@@ -559,6 +608,7 @@ export const max: {
   /**
    * Returns the larger byte size.
    *
+   * @stability unstable
    * @category ordering
    * @since 4.0.0
    */
@@ -568,6 +618,7 @@ export const max: {
 /**
  * Constrains a byte size to an inclusive range.
  *
+ * @stability unstable
  * @category ordering
  * @since 4.0.0
  */
@@ -575,6 +626,7 @@ export const clamp: {
   /**
    * Constrains a byte size to an inclusive range.
    *
+   * @stability unstable
    * @category ordering
    * @since 4.0.0
    */
@@ -582,6 +634,7 @@ export const clamp: {
   /**
    * Constrains a byte size to an inclusive range.
    *
+   * @stability unstable
    * @category ordering
    * @since 4.0.0
    */
@@ -591,6 +644,7 @@ export const clamp: {
 /**
  * Checks whether the first byte size is less than the second.
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -598,6 +652,7 @@ export const isLessThan: {
   /**
    * Checks whether the first byte size is less than the second.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -605,6 +660,7 @@ export const isLessThan: {
   /**
    * Checks whether the first byte size is less than the second.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -614,6 +670,7 @@ export const isLessThan: {
 /**
  * Checks whether the first byte size is at most the second.
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -621,6 +678,7 @@ export const isLessThanOrEqualTo: {
   /**
    * Checks whether the first byte size is at most the second.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -628,6 +686,7 @@ export const isLessThanOrEqualTo: {
   /**
    * Checks whether the first byte size is at most the second.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -637,6 +696,7 @@ export const isLessThanOrEqualTo: {
 /**
  * Checks whether the first byte size is greater than the second.
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -644,6 +704,7 @@ export const isGreaterThan: {
   /**
    * Checks whether the first byte size is greater than the second.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -651,6 +712,7 @@ export const isGreaterThan: {
   /**
    * Checks whether the first byte size is greater than the second.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -660,6 +722,7 @@ export const isGreaterThan: {
 /**
  * Checks whether the first byte size is at least the second.
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -667,6 +730,7 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Checks whether the first byte size is at least the second.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -674,6 +738,7 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Checks whether the first byte size is at least the second.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -683,6 +748,7 @@ export const isGreaterThanOrEqualTo: {
 /**
  * Checks whether two byte sizes contain the same count.
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -690,6 +756,7 @@ export const equals: {
   /**
    * Checks whether two byte sizes contain the same count.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -697,6 +764,7 @@ export const equals: {
   /**
    * Checks whether two byte sizes contain the same count.
    *
+   * @stability unstable
    * @category predicates
    * @since 4.0.0
    */
@@ -706,6 +774,7 @@ export const equals: {
 /**
  * Adds two byte sizes exactly.
  *
+ * @stability unstable
  * @category math
  * @since 4.0.0
  */
@@ -713,6 +782,7 @@ export const sum: {
   /**
    * Adds two byte sizes exactly.
    *
+   * @stability unstable
    * @category math
    * @since 4.0.0
    */
@@ -720,6 +790,7 @@ export const sum: {
   /**
    * Adds two byte sizes exactly.
    *
+   * @stability unstable
    * @category math
    * @since 4.0.0
    */
@@ -729,6 +800,7 @@ export const sum: {
 /**
  * Subtracts byte sizes, returning `None` on underflow.
  *
+ * @stability unstable
  * @category math
  * @since 4.0.0
  */
@@ -736,6 +808,7 @@ export const subtract: {
   /**
    * Subtracts byte sizes, returning `None` on underflow.
    *
+   * @stability unstable
    * @category math
    * @since 4.0.0
    */
@@ -743,6 +816,7 @@ export const subtract: {
   /**
    * Subtracts byte sizes, returning `None` on underflow.
    *
+   * @stability unstable
    * @category math
    * @since 4.0.0
    */
@@ -755,6 +829,7 @@ export const subtract: {
 /**
  * Subtracts byte sizes and throws on underflow.
  *
+ * @stability unstable
  * @category unsafe
  * @since 4.0.0
  */
@@ -762,6 +837,7 @@ export const subtractUnsafe: {
   /**
    * Subtracts byte sizes and throws on underflow.
    *
+   * @stability unstable
    * @category unsafe
    * @since 4.0.0
    */
@@ -769,6 +845,7 @@ export const subtractUnsafe: {
   /**
    * Subtracts byte sizes and throws on underflow.
    *
+   * @stability unstable
    * @category unsafe
    * @since 4.0.0
    */
@@ -786,6 +863,7 @@ const scalar = (input: number | bigint, positive: boolean): bigint | undefined =
 /**
  * Multiplies a byte size by a non-negative integer scalar.
  *
+ * @stability unstable
  * @category math
  * @since 4.0.0
  */
@@ -793,6 +871,7 @@ export const times: {
   /**
    * Multiplies a byte size by a non-negative integer scalar.
    *
+   * @stability unstable
    * @category math
    * @since 4.0.0
    */
@@ -800,6 +879,7 @@ export const times: {
   /**
    * Multiplies a byte size by a non-negative integer scalar.
    *
+   * @stability unstable
    * @category math
    * @since 4.0.0
    */
@@ -812,6 +892,7 @@ export const times: {
 /**
  * Divides a byte size by a positive integer, discarding any remainder.
  *
+ * @stability unstable
  * @category math
  * @since 4.0.0
  */
@@ -819,6 +900,7 @@ export const divide: {
   /**
    * Divides a byte size by a positive integer, discarding any remainder.
    *
+   * @stability unstable
    * @category math
    * @since 4.0.0
    */
@@ -826,6 +908,7 @@ export const divide: {
   /**
    * Divides a byte size by a positive integer, discarding any remainder.
    *
+   * @stability unstable
    * @category math
    * @since 4.0.0
    */
@@ -855,6 +938,7 @@ const formatWithUnit = (value: bigint, unit: UnitInfo, precision: number, traili
 /**
  * Formats a byte size with canonical decimal or binary unit symbols.
  *
+ * @stability unstable
  * @category converting
  * @since 4.0.0
  */
@@ -880,6 +964,7 @@ export const format = (self: ByteSize, options: FormatOptions = {}): string => {
 /**
  * Reducer that sums byte sizes from zero.
  *
+ * @stability unstable
  * @category math
  * @since 4.0.0
  */
@@ -888,6 +973,7 @@ export const ReducerSum: Reducer.Reducer<ByteSize> = BI.ReducerSum as any
 /**
  * Combiner that keeps the largest byte size.
  *
+ * @stability unstable
  * @category math
  * @since 4.0.0
  */
@@ -896,6 +982,7 @@ export const CombinerMax: Combiner.Combiner<ByteSize> = BI.CombinerMax as any
 /**
  * Combiner that keeps the smallest byte size.
  *
+ * @stability unstable
  * @category math
  * @since 4.0.0
  */