@synnaxlabs/x 0.42.3 → 0.44.0

package/src/telem/telem.ts

@@ -10,11 +10,13 @@
 import { z } from "zod";
 
 import { math } from "@/math";
-import { type Stringer } from "@/primitive";
+import { primitive } from "@/primitive";
 import { type bounds } from "@/spatial";
 
+/** Time zone specification when working with time stamps. */
 export type TZInfo = "UTC" | "local";
 
+/** Different string formats for time stamps. */
 export type TimeStampStringFormat =
   | "ISO"
   | "ISODate"
@@ -26,7 +28,20 @@ export type TimeStampStringFormat =
   | "shortDate"
   | "dateTime";
 
-export type DateComponents = [number?, number?, number?];
+const dateComponentsZ = z.union([
+  z.tuple([z.int()]),
+  z.tuple([z.int(), z.int().min(1).max(12)]),
+  z.tuple([z.int(), z.int().min(1).max(12), z.int().min(1).max(31)]),
+]);
+
+/**
+ * A triple of numbers representing a date.
+ *
+ * @param year - The year.
+ * @param month - The month.
+ * @param day - The day.
+ */
+export type DateComponents = z.infer<typeof dateComponentsZ>;
 
 const remainder = <T extends TimeStamp | TimeSpan>(
   value: T,
@@ -52,7 +67,7 @@ const remainder = <T extends TimeStamp | TimeSpan>(
 };
 
 /**
- * Represents a UTC timestamp. Synnax uses a nanosecond precision int64 timestamp.
+UTC timestamp. Synnax uses a nanosecond precision int64 timestamp.
  *
  * @param value - The timestamp value to parse. This can be any of the following:
  *
@@ -72,21 +87,19 @@ const remainder = <T extends TimeStamp | TimeSpan>(
  * @example ts = new TimeStamp([2021, 1, 1]).add(1 * TimeSpan.HOUR) // 1/1/2021 at 1am UTC
  * @example ts = new TimeStamp("2021-01-01T12:30:00Z") // 1/1/2021 at 12:30pm UTC
  */
-export class TimeStamp implements Stringer {
-  /** The underlying value for the time stamp */
-  private readonly value: bigint;
-  /** Makes sure JSON encodes the value and not the class. */
-  readonly encodeValue = true;
-
+export class TimeStamp
+  extends primitive.ValueExtension<bigint>
+  implements primitive.Stringer
+{
   constructor(value?: CrudeTimeStamp, tzInfo: TZInfo = "UTC") {
-    if (value == null) this.value = TimeStamp.now().valueOf();
+    if (value == null) super(TimeStamp.now().valueOf());
     else if (value instanceof Date)
-      this.value = BigInt(value.getTime()) * TimeStamp.MILLISECOND.valueOf();
+      super(BigInt(value.getTime()) * TimeStamp.MILLISECOND.valueOf());
     else if (typeof value === "string")
-      this.value = TimeStamp.parseDateTimeString(value, tzInfo).valueOf();
-    else if (Array.isArray(value)) this.value = TimeStamp.parseDate(value);
+      super(TimeStamp.parseDateTimeString(value, tzInfo).valueOf());
+    else if (Array.isArray(value)) super(TimeStamp.parseDate(value));
     else {
-      let offset: bigint = BigInt(0);
+      let offset = 0n;
       if (value instanceof Number) value = value.valueOf();
       if (tzInfo === "local") offset = TimeStamp.utcOffset.valueOf();
       if (typeof value === "number")
@@ -96,7 +109,7 @@ export class TimeStamp implements Stringer {
           if (value === Infinity) value = TimeStamp.MAX;
           else value = TimeStamp.MIN;
         }
-      this.value = BigInt(value.valueOf()) + offset;
+      super(BigInt(value.valueOf()) + offset);
     }
   }
 
@@ -108,6 +121,10 @@ export class TimeStamp implements Stringer {
       .valueOf();
   }
 
+  /**
+   * @returns the primitive value of the TimeStamp. Overrides standard JS valueOf()
+   * method.
+   */
   valueOf(): bigint {
     return this.value;
   }
@@ -138,6 +155,13 @@ export class TimeStamp implements Stringer {
     ).valueOf();
   }
 
+  /**
+   * Formats the TimeStamp as a string in the specified format.
+   *
+   * @param format - The format to use for the string representation.
+   * @param tzInfo - The timezone to use when creating the string representation.
+   * @returns A string representation of the TimeStamp in the specified format.
+   */
   fString(format: TimeStampStringFormat = "ISO", tzInfo: TZInfo = "UTC"): string {
     switch (format) {
       case "ISODate":
@@ -176,6 +200,7 @@ export class TimeStamp implements Stringer {
     return `${month} ${day}`;
   }
 
+  /** @returns The UTC offset for the time zone of the machine. */
   static get utcOffset(): TimeSpan {
     return new TimeSpan(
       BigInt(new Date().getTimezoneOffset()) * TimeStamp.MINUTE.valueOf(),
@@ -246,7 +271,7 @@ export class TimeStamp implements Stringer {
    * @returns True if the TimeStamp represents the unix epoch, false otherwise.
    */
   get isZero(): boolean {
-    return this.valueOf() === BigInt(0);
+    return this.valueOf() === 0n;
   }
 
   /**
@@ -352,7 +377,7 @@ export class TimeStamp implements Stringer {
     return Number(this.valueOf()) / Number(TimeStamp.MILLISECOND.valueOf());
   }
 
-  /** @returns the floating point number of microseconds since the unix epoch */
+  /** @returns the floating point number of microseconds since the unix epoch. */
   get microseconds(): number {
     return Number(this.valueOf()) / Number(TimeStamp.MICROSECOND.valueOf());
   }
@@ -368,7 +393,7 @@ export class TimeStamp implements Stringer {
 
   /** @returns the integer year that the timestamp corresponds to. */
   get year(): number {
-    return this.date().getFullYear();
+    return this.date().getUTCFullYear();
   }
 
   /**
@@ -377,7 +402,7 @@ export class TimeStamp implements Stringer {
    */
   setYear(year: number): TimeStamp {
     const d = this.date();
-    d.setFullYear(year);
+    d.setUTCFullYear(year);
     return new TimeStamp(d);
   }
 
@@ -430,7 +455,7 @@ export class TimeStamp implements Stringer {
 
   /** @returns the integer minute that the timestamp corresponds to within its hour. */
   get minute(): number {
-    return this.date().getMinutes();
+    return this.date().getUTCMinutes();
   }
 
   /**
@@ -448,7 +473,7 @@ export class TimeStamp implements Stringer {
    * minute.
    */
   get second(): number {
-    return this.date().getSeconds();
+    return this.date().getUTCSeconds();
   }
 
   /**
@@ -466,7 +491,7 @@ export class TimeStamp implements Stringer {
    * its second.
    */
   get millisecond(): number {
-    return this.date().getMilliseconds();
+    return this.date().getUTCMilliseconds();
   }
 
   /**
@@ -475,7 +500,7 @@ export class TimeStamp implements Stringer {
    */
   setMillisecond(millisecond: number): TimeStamp {
     const d = this.date();
-    d.setMilliseconds(millisecond);
+    d.setUTCMilliseconds(millisecond);
     return new TimeStamp(d);
   }
 
@@ -504,6 +529,12 @@ export class TimeStamp implements Stringer {
     return this.truncate(TimeSpan.DAY).equals(TimeStamp.now().truncate(TimeSpan.DAY));
   }
 
+  /**
+   * Truncates the TimeStamp to the nearest multiple of the given span.
+   *
+   * @param span - The TimeSpan to truncate to.
+   * @returns A new TimeStamp that is truncated to the nearest multiple of the given span.
+   */
   truncate(span: TimeSpan | TimeStamp): TimeStamp {
     return this.sub(this.remainder(span));
   }
@@ -517,7 +548,12 @@ export class TimeStamp implements Stringer {
     return new TimeStamp(new Date());
   }
 
-  /** @returns the maximum value of all the timestamps. */
+  /**
+   * Finds the maximum timestamp among the provided timestamps.
+   *
+   * @param timestamps - The timestamps to compare.
+   * @returns The maximum (latest) timestamp from the input.
+   */
   static max(...timestamps: CrudeTimeStamp[]): TimeStamp {
     let max = TimeStamp.MIN;
     for (const ts of timestamps) {
@@ -527,7 +563,12 @@ export class TimeStamp implements Stringer {
     return max;
   }
 
-  /** @returns the minimum value of all the timestamps. */
+  /**
+   * Finds the minimum timestamp among the provided timestamps.
+   *
+   * @param timestamps - The timestamps to compare.
+   * @returns The minimum (earliest) timestamp from the input.
+   */
   static min(...timestamps: CrudeTimeStamp[]): TimeStamp {
     let min = TimeStamp.MAX;
     for (const ts of timestamps) {
@@ -537,7 +578,12 @@ export class TimeStamp implements Stringer {
     return min;
   }
 
-  /** @returns a new TimeStamp n nanoseconds after the unix epoch */
+  /**
+   * Creates a TimeStamp representing the given number of nanoseconds.
+   *
+   * @param value - The number of nanoseconds.
+   * @returns A TimeStamp representing the given number of nanoseconds.
+   */
   static nanoseconds(value: number, tzInfo: TZInfo = "UTC"): TimeStamp {
     return new TimeStamp(value, tzInfo);
   }
@@ -604,24 +650,45 @@ export class TimeStamp implements Stringer {
 
   /** A zod schema for validating timestamps */
   static readonly z = z.union([
+    z.instanceof(TimeStamp),
     z.object({ value: z.bigint() }).transform((v) => new TimeStamp(v.value)),
     z.string().transform((n) => new TimeStamp(BigInt(n))),
-    z.instanceof(Number).transform((n) => new TimeStamp(n)),
     z.number().transform((n) => new TimeStamp(n)),
-    z.instanceof(TimeStamp),
+    z.bigint().transform((n) => new TimeStamp(n)),
+    z.date().transform((d) => new TimeStamp(d)),
+    z.custom<TimeSpan>((v) => v instanceof TimeSpan).transform((v) => new TimeStamp(v)),
+    dateComponentsZ.transform((v) => new TimeStamp(v)),
   ]);
+
+  /**
+   * Sorts two timestamps.
+   *
+   * @param a - The first timestamp.
+   * @param b - The second timestamp.
+   * @returns A number indicating the order of the two timestamps (positive if a is
+   * greater than b, negative if a is less than b, and 0 if they are equal).
+   */
+  static sort(a: TimeStamp, b: TimeStamp): number {
+    return Number(a.valueOf() - b.valueOf());
+  }
 }
 
 /** TimeSpan represents a nanosecond precision duration. */
-export class TimeSpan implements Stringer {
-  private readonly value: bigint;
-  readonly encodeValue = true;
-
+export class TimeSpan
+  extends primitive.ValueExtension<bigint>
+  implements primitive.Stringer
+{
   constructor(value: CrudeTimeSpan) {
     if (typeof value === "number") value = Math.trunc(value.valueOf());
-    this.value = BigInt(value.valueOf());
+    super(BigInt(value.valueOf()));
   }
 
+  /**
+   * Creates a TimeSpan representing the given number of seconds.
+   *
+   * @param span - The number of seconds.
+   * @returns A TimeSpan representing the given number of seconds.
+   */
   static fromSeconds(span: CrudeTimeSpan): TimeSpan {
     if (span instanceof TimeSpan) return span;
     if (span instanceof Rate) return span.period;
@@ -630,6 +697,12 @@ export class TimeSpan implements Stringer {
     return new TimeSpan(span);
   }
 
+  /**
+   * Creates a TimeSpan representing the given number of milliseconds.
+   *
+   * @param span - The number of milliseconds.
+   * @returns A TimeSpan representing the given number of milliseconds.
+   */
   static fromMilliseconds(span: CrudeTimeSpan): TimeSpan {
     if (span instanceof TimeSpan) return span;
     if (span instanceof Rate) return span.period;
@@ -638,40 +711,81 @@ export class TimeSpan implements Stringer {
     return new TimeSpan(span);
   }
 
-  encode(): string {
-    return this.value.toString();
-  }
-
+  /**
+   * @returns the primitive value of the TimeSpan. Overrides standard JS valueOf()
+   * method.
+   */
   valueOf(): bigint {
     return this.value;
   }
 
+  /**
+   * Checks if the TimeSpan is less than another TimeSpan.
+   *
+   * @param other - The TimeSpan to compare against.
+   * @returns True if the TimeSpan is less than the other TimeSpan, false otherwise.
+   */
   lessThan(other: CrudeTimeSpan): boolean {
     return this.valueOf() < new TimeSpan(other).valueOf();
   }
 
+  /**
+   * Checks if the TimeSpan is greater than another TimeSpan.
+   *
+   * @param other - The TimeSpan to compare against.
+   * @returns True if the TimeSpan is greater than the other TimeSpan, false otherwise.
+   */
   greaterThan(other: CrudeTimeSpan): boolean {
     return this.valueOf() > new TimeSpan(other).valueOf();
   }
 
+  /**
+   * Checks if the TimeSpan is less than or equal to another TimeSpan.
+   *
+   * @param other - The TimeSpan to compare against.
+   * @returns True if the TimeSpan is less than or equal to the other TimeSpan, false otherwise.
+   */
   lessThanOrEqual(other: CrudeTimeSpan): boolean {
     return this.valueOf() <= new TimeSpan(other).valueOf();
   }
 
+  /**
+   * Checks if the TimeSpan is greater than or equal to another TimeSpan.
+   *
+   * @param other - The TimeSpan to compare against.
+   * @returns True if the TimeSpan is greater than or equal to the other TimeSpan, false otherwise.
+   */
   greaterThanOrEqual(other: CrudeTimeSpan): boolean {
     return this.valueOf() >= new TimeSpan(other).valueOf();
   }
 
+  /**
+   * Calculates the remainder of the TimeSpan when divided by another TimeSpan.
+   *
+   * @param divisor - The TimeSpan to divide by.
+   * @returns A new TimeSpan representing the remainder.
+   */
   remainder(divisor: TimeSpan): TimeSpan {
     return remainder(this, divisor);
   }
 
+  /**
+   * Truncates the TimeSpan to the nearest multiple of the given span.
+   *
+   * @param span - The TimeSpan to truncate to.
+   * @returns A new TimeSpan that is truncated to the nearest multiple of the given span.
+   */
   truncate(span: TimeSpan): TimeSpan {
     return new TimeSpan(
       BigInt(Math.trunc(Number(this.valueOf() / span.valueOf()))) * span.valueOf(),
     );
   }
 
+  /**
+   * Returns a string representation of the TimeSpan.
+   *
+   * @returns A string representation of the TimeSpan.
+   */
   toString(): string {
     const totalDays = this.truncate(TimeSpan.DAY);
     const totalHours = this.truncate(TimeSpan.HOUR);
@@ -699,21 +813,27 @@ export class TimeSpan implements Stringer {
     return str.trim();
   }
 
+  /**
+   * Multiplies the TimeSpan by a scalar value.
+   *
+   * @param value - The scalar value to multiply by.
+   * @returns A new TimeSpan that is this TimeSpan multiplied by the provided value.
+   */
   mult(value: number): TimeSpan {
     return new TimeSpan(this.valueOf() * BigInt(value));
   }
 
-  /** @returns the decimal number of days in the timespan */
+  /** @returns the decimal number of days in the TimeSpan. */
   get days(): number {
     return Number(this.valueOf()) / Number(TimeSpan.DAY.valueOf());
   }
 
-  /** @returns the decimal number of hours in the timespan */
+  /** @returns the decimal number of hours in the TimeSpan. */
   get hours(): number {
     return Number(this.valueOf()) / Number(TimeSpan.HOUR.valueOf());
   }
 
-  /** @returns the decimal number of minutes in the timespan */
+  /** @returns the decimal number of minutes in the TimeSpan. */
   get minutes(): number {
     return Number(this.valueOf()) / Number(TimeSpan.MINUTE.valueOf());
   }
@@ -728,10 +848,12 @@ export class TimeSpan implements Stringer {
     return Number(this.valueOf()) / Number(TimeSpan.MILLISECOND.valueOf());
   }
 
+  /** @returns The number of microseconds in the TimeSpan. */
   get microseconds(): number {
     return Number(this.valueOf()) / Number(TimeSpan.MICROSECOND.valueOf());
   }
 
+  /** @returns The number of nanoseconds in the TimeSpan. */
   get nanoseconds(): number {
     return Number(this.valueOf());
   }
@@ -742,7 +864,7 @@ export class TimeSpan implements Stringer {
    * @returns True if the TimeSpan represents a zero duration, false otherwise.
    */
   get isZero(): boolean {
-    return this.valueOf() === BigInt(0);
+    return this.valueOf() === 0n;
   }
 
   /**
@@ -876,17 +998,18 @@ export class TimeSpan implements Stringer {
   static readonly z = z.union([
     z.object({ value: z.bigint() }).transform((v) => new TimeSpan(v.value)),
     z.string().transform((n) => new TimeSpan(BigInt(n))),
-    z.instanceof(Number).transform((n) => new TimeSpan(n)),
     z.number().transform((n) => new TimeSpan(n)),
     z.instanceof(TimeSpan),
   ]);
 }
 
 /** Rate represents a data rate in Hz. */
-export class Rate extends Number implements Stringer {
+export class Rate
+  extends primitive.ValueExtension<number>
+  implements primitive.Stringer
+{
   constructor(value: CrudeRate) {
-    if (value instanceof Number) super(value.valueOf());
-    else super(value);
+    super(value.valueOf());
   }
 
   /** @returns a pretty string representation of the rate in the format "X Hz". */
@@ -973,13 +1096,15 @@ export class Rate extends Number implements Stringer {
   /** A zod schema for validating and transforming rates */
   static readonly z = z.union([
     z.number().transform((n) => new Rate(n)),
-    z.instanceof(Number).transform((n) => new Rate(n)),
     z.instanceof(Rate),
   ]);
 }
 
 /** Density represents the number of bytes in a value. */
-export class Density extends Number implements Stringer {
+export class Density
+  extends primitive.ValueExtension<number>
+  implements primitive.Stringer
+{
   /**
    * Creates a Density representing the given number of bytes per value.
    *
@@ -988,14 +1113,25 @@ export class Density extends Number implements Stringer {
    * @returns A Density representing the given number of bytes per value.
    */
   constructor(value: CrudeDensity) {
-    if (value instanceof Number) super(value.valueOf());
-    else super(value);
+    super(value.valueOf());
   }
 
+  /**
+   * Calculates the number of values in the given Size.
+   *
+   * @param size - The Size to calculate the value count from.
+   * @returns The number of values in the given Size.
+   */
   length(size: Size): number {
     return size.valueOf() / this.valueOf();
   }
 
+  /**
+   * Calculates a Size representing the given number of values.
+   *
+   * @param sampleCount - The number of values in the Size.
+   * @returns A Size representing the given number of values.
+   */
   size(sampleCount: number): Size {
     return new Size(sampleCount * this.valueOf());
   }
@@ -1016,7 +1152,6 @@ export class Density extends Number implements Stringer {
   /** A zod schema for validating and transforming densities */
   static readonly z = z.union([
     z.number().transform((n) => new Density(n)),
-    z.instanceof(Number).transform((n) => new Density(n)),
     z.instanceof(Density),
   ]);
 }
@@ -1028,7 +1163,7 @@ export class Density extends Number implements Stringer {
  * @property start - A TimeStamp representing the start of the range.
  * @property end - A Timestamp representing the end of the range.
  */
-export class TimeRange implements Stringer {
+export class TimeRange implements primitive.Stringer {
   /**
    * The starting TimeStamp of the TimeRange.
    *
@@ -1140,10 +1275,20 @@ export class TimeRange implements Stringer {
     return startDist <= delta.valueOf() && endDist <= delta.valueOf();
   }
 
+  /**
+   * Returns a string representation of the TimeRange.
+   *
+   * @returns A string representation of the TimeRange.
+   */
   toString(): string {
     return `${this.start.toString()} - ${this.end.toString()}`;
   }
 
+  /**
+   * Returns a pretty string representation of the TimeRange.
+   *
+   * @returns A pretty string representation of the TimeRange.
+   */
   toPrettyString(): string {
     return `${this.start.fString("preciseDate")} - ${this.span.toString()}`;
   }
@@ -1182,8 +1327,20 @@ export class TimeRange implements Stringer {
     return overlapDuration.greaterThanOrEqual(delta);
   }
 
+  /**
+   * Checks if the TimeRange contains the given TimeRange or TimeStamp.
+   *
+   * @param other - The TimeRange or TimeStamp to check if it is contained in the TimeRange.
+   * @returns True if the TimeRange contains the given TimeRange or TimeStamp.
+   */
   contains(other: TimeRange): boolean;
 
+  /**
+   * Checks if the TimeRange contains the given TimeStamp.
+   *
+   * @param ts - The TimeStamp to check if it is contained in the TimeRange.
+   * @returns True if the TimeRange contains the given TimeStamp.
+   */
   contains(ts: CrudeTimeStamp): boolean;
 
   contains(other: TimeRange | CrudeTimeStamp): boolean {
@@ -1192,6 +1349,17 @@ export class TimeRange implements Stringer {
     return this.start.beforeEq(other) && this.end.after(other);
   }
 
+  /**
+   * Returns a new TimeRange that is bound by the given TimeRange.
+   *
+   * @param other - The TimeRange to bound by.
+   * @returns A new TimeRange that is bound by the given TimeRange.
+   * @example
+   * const range = new TimeRange(new TimeStamp(1000), new TimeStamp(2000));
+   * const other = new TimeRange(new TimeStamp(1500), new TimeStamp(2500));
+   * const bounded = range.boundBy(other);
+   * console.log(bounded); // TimeRange(1500, 2000)
+   */
   boundBy(other: TimeRange): TimeRange {
     const next = new TimeRange(this.start, this.end);
     if (other.start.after(this.start)) next.start = other.start;
@@ -1224,41 +1392,41 @@ export class TimeRange implements Stringer {
       .transform((v) => new TimeRange(v.start, v.end)),
     z.instanceof(TimeRange),
   ]);
-}
-
-export const sortTimeRange = (a: TimeRange, b: TimeRange): -1 | 0 | 1 => {
-  if (a.start.before(b.start)) return -1;
-  if (a.start.after(b.start)) return 1;
-  if (a.end.before(b.end)) return -1;
-  if (a.end.after(b.end)) return 1;
-  return 0;
-};
-
-/** DataType is a string that represents a data type. */
-export class DataType implements Stringer {
-  readonly value: string;
-  readonly encodeValue = true;
 
-  valueOf(): string {
-    return this.value;
+  /**
+   * Sorts two time ranges. The range with the earlier start time is considered less than
+   * the range with the later start time. If the start times are equal, the range with the
+   * earlier end time is considered less than the range with the later end time.
+   *
+   * @param a - The first time range.
+   * @param b - The second time range.
+   * @returns A number indicating the order of the two time ranges. This number is
+   * positive if a is earlier than b, negative if a is later than b, and 0 if they are
+   * equal.
+   */
+  static sort(a: TimeRange, b: TimeRange): number {
+    return TimeStamp.sort(a.start, b.start) || TimeStamp.sort(a.end, b.end);
   }
+}
 
+/** DataType is a string that represents a data type. */
+export class DataType
+  extends primitive.ValueExtension<string>
+  implements primitive.Stringer
+{
   constructor(value: CrudeDataType) {
     if (
       value instanceof DataType ||
       typeof value === "string" ||
       typeof value.valueOf() === "string"
-    ) {
-      this.value = value.valueOf() as string;
-      return;
-    }
-    const t = DataType.ARRAY_CONSTRUCTOR_DATA_TYPES.get(value.constructor.name);
-    if (t != null) {
-      this.value = t.valueOf();
-      return;
+    )
+      super(value.valueOf() as string);
+    else {
+      const t = DataType.ARRAY_CONSTRUCTOR_DATA_TYPES.get(value.constructor.name);
+      if (t == null)
+        throw new Error(`unable to find data type for ${value.toString()}`);
+      super(t.valueOf());
     }
-    this.value = DataType.UNKNOWN.valueOf();
-    throw new Error(`unable to find data type for ${value.toString()}`);
   }
 
   /**
@@ -1290,31 +1458,60 @@ export class DataType implements Stringer {
     return this.valueOf();
   }
 
+  /**
+   * @returns true if the DataType has a variable density.
+   * @example DataType.STRING.isVariable // true
+   * @example DataType.INT32.isVariable // false
+   */
   get isVariable(): boolean {
     return this.equals(DataType.JSON) || this.equals(DataType.STRING);
   }
 
+  /**
+   * @returns true if the DataType is numeric.
+   * @example DataType.INT32.isNumeric // true
+   * @example DataType.STRING.isNumeric // false
+   */
   get isNumeric(): boolean {
     return !this.isVariable && !this.equals(DataType.UUID);
   }
 
+  /**
+   * @returns true if the DataType is an integer.
+   * @example DataType.INT32.isInteger // true
+   * @example DataType.FLOAT32.isInteger // false
+   */
   get isInteger(): boolean {
     const str = this.toString();
     return str.startsWith("int") || str.startsWith("uint");
   }
 
+  /**
+   * @returns true if the DataType is a floating point number.
+   * @example DataType.FLOAT32.isFloat // true
+   * @example DataType.INT32.isFloat // false
+   */
   get isFloat(): boolean {
     return this.toString().startsWith("float");
   }
 
+  /**
+   * @returns the density of the DataType.
+   * @example DataType.INT16.density // Density.BIT32
+   * @example DataType.FLOAT32.density // Density.BIT32
+   */
   get density(): Density {
     const v = DataType.DENSITIES.get(this.toString());
     if (v == null) throw new Error(`unable to find density for ${this.valueOf()}`);
     return v;
   }
 
-  /** @returns ture if the data type is an unsigned numeric integer type */
-  get isUnsigned(): boolean {
+  /**
+   * @returns true if the DataType is an unsigned integer.
+   * @example DataType.UINT32.isUnsigned // true
+   * @example DataType.INT32.isUnsigned // false
+   */
+  get isUnsignedInteger(): boolean {
     return (
       this.equals(DataType.UINT8) ||
       this.equals(DataType.UINT16) ||
@@ -1323,8 +1520,12 @@ export class DataType implements Stringer {
     );
   }
 
-  /** @returns true if the data type is a signed numeric integer type */
-  get isSigned(): boolean {
+  /**
+   * @returns true if the DataType is a signed integer.
+   * @example DataType.INT32.isSigned // true
+   * @example DataType.UINT32.isSigned // false
+   */
+  get isSignedInteger(): boolean {
     return (
       this.equals(DataType.INT8) ||
       this.equals(DataType.INT16) ||
@@ -1338,7 +1539,7 @@ export class DataType implements Stringer {
     if (this.equals(other)) return true;
     if (!this.isNumeric || !other.isNumeric) return false;
     if (this.isVariable || other.isVariable) return false;
-    if (this.isUnsigned && other.isSigned) return false;
+    if (this.isUnsignedInteger && other.isSignedInteger) return false;
 
     if (this.isFloat)
       return other.isFloat && this.density.valueOf() <= other.density.valueOf();
@@ -1347,7 +1548,7 @@ export class DataType implements Stringer {
     if (this.isInteger && other.isInteger)
       return (
         this.density.valueOf() <= other.density.valueOf() &&
-        this.isUnsigned === other.isUnsigned
+        this.isUnsignedInteger === other.isUnsignedInteger
       );
 
     return false;
@@ -1359,10 +1560,17 @@ export class DataType implements Stringer {
     return this.equals(other);
   }
 
-  toJSON(): string {
-    return this.toString();
+  /**
+   * Checks whether the given TypedArray is of the same type as the DataType.
+   *
+   * @param array - The TypedArray to check.
+   * @returns True if the TypedArray is of the same type as the DataType.
+   */
+  checkArray(array: TypedArray): boolean {
+    return array.constructor === this.Array;
   }
 
+  /** @returns true if the data type uses bigints to store values. */
   get usesBigInt(): boolean {
     return DataType.BIG_INT_TYPES.some((t) => t.equals(this));
   }
@@ -1402,27 +1610,25 @@ export class DataType implements Stringer {
    * newline character. */
   static readonly JSON = new DataType("json");
 
-  static readonly ARRAY_CONSTRUCTORS: Map<string, TypedArrayConstructor> = new Map<
-    string,
-    TypedArrayConstructor
-  >([
-    [DataType.UINT8.toString(), Uint8Array],
-    [DataType.UINT16.toString(), Uint16Array],
-    [DataType.UINT32.toString(), Uint32Array],
-    [DataType.UINT64.toString(), BigUint64Array],
-    [DataType.FLOAT32.toString(), Float32Array],
-    [DataType.FLOAT64.toString(), Float64Array],
-    [DataType.INT8.toString(), Int8Array],
-    [DataType.INT16.toString(), Int16Array],
-    [DataType.INT32.toString(), Int32Array],
-    [DataType.INT64.toString(), BigInt64Array],
-    [DataType.TIMESTAMP.toString(), BigInt64Array],
-    [DataType.STRING.toString(), Uint8Array],
-    [DataType.JSON.toString(), Uint8Array],
-    [DataType.UUID.toString(), Uint8Array],
-  ]);
-
-  static readonly ARRAY_CONSTRUCTOR_DATA_TYPES: Map<string, DataType> = new Map<
+  private static readonly ARRAY_CONSTRUCTORS: Map<string, TypedArrayConstructor> =
+    new Map<string, TypedArrayConstructor>([
+      [DataType.UINT8.toString(), Uint8Array],
+      [DataType.UINT16.toString(), Uint16Array],
+      [DataType.UINT32.toString(), Uint32Array],
+      [DataType.UINT64.toString(), BigUint64Array],
+      [DataType.FLOAT32.toString(), Float32Array],
+      [DataType.FLOAT64.toString(), Float64Array],
+      [DataType.INT8.toString(), Int8Array],
+      [DataType.INT16.toString(), Int16Array],
+      [DataType.INT32.toString(), Int32Array],
+      [DataType.INT64.toString(), BigInt64Array],
+      [DataType.TIMESTAMP.toString(), BigInt64Array],
+      [DataType.STRING.toString(), Uint8Array],
+      [DataType.JSON.toString(), Uint8Array],
+      [DataType.UUID.toString(), Uint8Array],
+    ]);
+
+  private static readonly ARRAY_CONSTRUCTOR_DATA_TYPES: Map<string, DataType> = new Map<
     string,
     DataType
   >([
@@ -1438,7 +1644,7 @@ export class DataType implements Stringer {
     [BigInt64Array.name, DataType.INT64],
   ]);
 
-  static readonly DENSITIES = new Map<string, Density>([
+  private static readonly DENSITIES = new Map<string, Density>([
     [DataType.UINT8.toString(), Density.BIT8],
     [DataType.UINT16.toString(), Density.BIT16],
     [DataType.UINT32.toString(), Density.BIT32],
@@ -1484,9 +1690,12 @@ export class DataType implements Stringer {
 }
 
 /**
- * The Size of an elementy in bytes.
+ * The Size of an element in bytes.
  */
-export class Size extends Number implements Stringer {
+export class Size
+  extends primitive.ValueExtension<number>
+  implements primitive.Stringer
+{
   constructor(value: CrudeSize) {
     super(value.valueOf());
   }
@@ -1501,38 +1710,47 @@ export class Size extends Number implements Stringer {
     return this.valueOf() < other.valueOf();
   }
 
+  /** @returns a new Size representing the sum of the two Sizes. */
   add(other: CrudeSize): Size {
     return Size.bytes(this.valueOf() + other.valueOf());
   }
 
+  /** @returns a new Size representing the difference of the two Sizes. */
   sub(other: CrudeSize): Size {
     return Size.bytes(this.valueOf() - other.valueOf());
   }
 
+  /** @returns a new Size representing the truncated value of the Size. */
   truncate(span: CrudeSize): Size {
     return new Size(Math.trunc(this.valueOf() / span.valueOf()) * span.valueOf());
   }
 
+  /** @returns a new Size representing the remainder of the Size. */
   remainder(span: CrudeSize): Size {
     return Size.bytes(this.valueOf() % span.valueOf());
   }
 
+  /** @returns the number of gigabytes in the Size. */
   get gigabytes(): number {
     return this.valueOf() / Size.GIGABYTE.valueOf();
   }
 
+  /** @returns the number of megabytes in the Size. */
   get megabytes(): number {
     return this.valueOf() / Size.MEGABYTE.valueOf();
   }
 
+  /** @returns the number of kilobytes in the Size. */
   get kilobytes(): number {
     return this.valueOf() / Size.KILOBYTE.valueOf();
   }
 
+  /** @returns the number of terabytes in the Size. */
   get terabytes(): number {
     return this.valueOf() / Size.TERABYTE.valueOf();
   }
 
+  /** @returns a nicely formatted string representation of the Size. */
   toString(): string {
     const totalTB = this.truncate(Size.TERABYTE);
     const totalGB = this.truncate(Size.GIGABYTE);
@@ -1627,6 +1845,7 @@ export class Size extends Number implements Stringer {
     z.instanceof(Size),
   ]);
 
+  /** @returns true if the Size is zero. */
   get isZero(): boolean {
     return this.valueOf() === 0;
   }
@@ -1634,31 +1853,22 @@ export class Size extends Number implements Stringer {
 
 export type CrudeTimeStamp =
   | bigint
-  | BigInt
   | TimeStamp
   | TimeSpan
   | number
   | Date
   | string
-  | DateComponents
-  | Number;
+  | DateComponents;
 export type TimeStampT = number;
-export type CrudeTimeSpan =
-  | bigint
-  | BigInt
-  | TimeSpan
-  | TimeStamp
-  | number
-  | Number
-  | Rate;
+export type CrudeTimeSpan = bigint | TimeSpan | TimeStamp | number | Rate;
 export type TimeSpanT = number;
-export type CrudeRate = Rate | number | Number;
+export type CrudeRate = Rate | number;
 export type RateT = number;
-export type CrudeDensity = Density | number | Number;
+export type CrudeDensity = Density | number;
 export type DensityT = number;
 export type CrudeDataType = DataType | string | TypedArray;
 export type DataTypeT = string;
-export type CrudeSize = Size | number | Number;
+export type CrudeSize = Size | number;
 export type SizeT = number;
 export interface CrudeTimeRange {
   start: CrudeTimeStamp;
@@ -1727,11 +1937,11 @@ export const convertDataType = (
   target: DataType,
   value: math.Numeric,
   offset: math.Numeric = 0,
-): math.PrimitiveNumeric => {
+): math.Numeric => {
   if (source.usesBigInt && !target.usesBigInt) return Number(value) - Number(offset);
   if (!source.usesBigInt && target.usesBigInt)
     return BigInt(value.valueOf()) - BigInt(offset.valueOf());
-  return addSamples(value, -offset).valueOf();
+  return addSamples(value, -offset);
 };
 
 export const addSamples = (a: math.Numeric, b: math.Numeric): math.Numeric => {