@2702rebels/wpidata 1.0.0

package/src/types/struct.ts

@@ -0,0 +1,333 @@
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/struct/VectorStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/struct/VectorStruct.h
+ */
+export interface VectorStruct {
+  readonly data: ReadonlyArray<number>;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/struct/MatrixStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/struct/MatrixStruct.h
+ */
+export interface MatrixStruct {
+  readonly data: ReadonlyArray<number>;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Translation2dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Translation2dStruct.h
+ */
+export interface Translation2dStruct {
+  readonly x: number;
+  readonly y: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Translation3dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Translation3dStruct.h
+ */
+export interface Translation3dStruct {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Twist2dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Twist2dStruct.h
+ */
+export interface Twist2dStruct {
+  readonly dx: number;
+  readonly dy: number;
+  readonly dtheta: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Twist3dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Twist3dStruct.h
+ */
+export interface Twist3dStruct {
+  readonly dx: number;
+  readonly dy: number;
+  readonly dz: number;
+  readonly rx: number;
+  readonly ry: number;
+  readonly rz: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/QauternionStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/QuaternionStruct.h
+ */
+export interface QuaternionStruct {
+  readonly w: number;
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Rotation2dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Rotation2dStruct.h
+ */
+export interface Rotation2dStruct {
+  readonly value: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Rotation3dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Rotation3dStruct.h
+ */
+export interface Rotation3dStruct {
+  readonly q: QuaternionStruct;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Transform2dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Transform2dStruct.h
+ */
+export interface Transform2dStruct {
+  readonly translation: Translation2dStruct;
+  readonly rotation: Rotation2dStruct;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Transform3dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Transform3dStruct.h
+ */
+export interface Transform3dStruct {
+  readonly translation: Translation3dStruct;
+  readonly rotation: Rotation3dStruct;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Pose2dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Pose2dStruct.h
+ */
+export interface Pose2dStruct {
+  readonly translation: Translation2dStruct;
+  readonly rotation: Rotation2dStruct;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Pose3dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Pose3dStruct.h
+ */
+export interface Pose3dStruct {
+  readonly translation: Translation3dStruct;
+  readonly rotation: Rotation3dStruct;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Ellipse2dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Ellipse2dStruct.h
+ */
+export interface Ellipse2dStruct {
+  readonly center: Pose2dStruct;
+  readonly xSemiAxis: number;
+  readonly ySemiAxis: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/geometry/struct/Rectangle2dStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/geometry/struct/Rectangle2dStruct.h
+ */
+export interface Rectangle2dStruct {
+  readonly center: Pose2dStruct;
+  readonly xWidth: number;
+  readonly yWidth: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/controller/struct/ArmFeedforwardStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/controller/struct/ArmFeedforwardStruct.h
+ */
+export interface ArmFeedforwardStruct {
+  readonly ks: number;
+  readonly kg: number;
+  readonly kv: number;
+  readonly ka: number;
+  readonly dt: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/controller/struct/DifferentialDriveFeedforwardStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/controller/struct/DifferentialDriveFeedforwardStruct.h
+ */
+export interface DifferentialDriveFeedforwardStruct {
+  readonly kVLinear: number;
+  readonly kALinear: number;
+  readonly kVAngular: number;
+  readonly kAAngular: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/controller/struct/DifferentialDriveWheelVoltagesStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/controller/struct/DifferentialDriveWheelVoltagesStruct.h
+ */
+export interface DifferentialDriveWheelVoltagesStruct {
+  readonly left: number;
+  readonly right: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/controller/struct/ElevatorFeedforwardStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/controller/struct/ElevatorFeedforwardStruct.h
+ */
+export interface ElevatorFeedforwardStruct {
+  readonly ks: number;
+  readonly kg: number;
+  readonly kv: number;
+  readonly ka: number;
+  readonly dt: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/controller/struct/SimpleMotorFeedforwardStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/controller/struct/SimpleMotorFeedforwardStruct.h
+ */
+export interface SimpleMotorFeedforwardStruct {
+  readonly ks: number;
+  readonly kv: number;
+  readonly ka: number;
+  readonly dt: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/ChassisSpeedsStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/ChassisSpeedsStruct.h
+ */
+export interface ChassisSpeedsStruct {
+  readonly vx: number;
+  readonly vy: number;
+  readonly omega: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/DifferentialDriveKinematicsStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/DifferentialDriveKinematicsStruct.h
+ */
+export interface DifferentialDriveKinematicsStruct {
+  readonly track_width: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/DifferentialDriveWheelPositionsStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/DifferentialDriveWheelPositionsStruct.h
+ */
+export interface DifferentialDriveWheelPositionsStruct {
+  readonly left: number;
+  readonly right: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/DifferentialDriveWheelSpeedsStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/DifferentialDriveWheelSpeedsStruct.h
+ */
+export interface DifferentialDriveWheelSpeedsStruct {
+  readonly left: number;
+  readonly right: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/MecanumDriveKinematicsStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/MecanumDriveKinematicsStruct.h
+ */
+export interface MecanumDriveKinematicsStruct {
+  readonly front_left: Translation2dStruct;
+  readonly front_right: Translation2dStruct;
+  readonly rear_left: Translation2dStruct;
+  readonly rear_right: Translation2dStruct;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/MecanumDriveMotorVoltagesStruct.java
+ */
+export interface MecanumDriveMotorVoltagesStruct {
+  readonly front_left: number;
+  readonly front_right: number;
+  readonly rear_left: number;
+  readonly rear_right: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/MecanumDriveWheelPositionsStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/MecanumDriveWheelPositionsStruct.h
+ */
+export interface MecanumDriveWheelPositionsStruct {
+  readonly front_left: number;
+  readonly front_right: number;
+  readonly rear_left: number;
+  readonly rear_right: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/MecanumDriveWheelSpeedsStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/MecanumDriveWheelSpeedsStruct.h
+ */
+export interface MecanumDriveWheelSpeedsStruct {
+  readonly front_left: number;
+  readonly front_right: number;
+  readonly rear_left: number;
+  readonly rear_right: number;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/SwerveDriveKinematicsStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/SwerveDriveKinematicsStruct.h
+ */
+export interface SwerveDriveKinematicsStruct {
+  readonly modules: ReadonlyArray<Translation2dStruct>;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/SwerveModulePositionStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/SwerveModulePositionStruct.h
+ */
+export interface SwerveModulePositionStruct {
+  readonly distance: number;
+  readonly angle: Rotation2dStruct;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/kinematics/struct/SwerveModuleStateStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/kinematics/struct/SwerveModuleStateStruct.h
+ */
+export interface SwerveModuleStateStruct {
+  readonly speed: number;
+  readonly angle: Rotation2dStruct;
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/spline/struct/CubicHermiteSplineStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/spline/struct/CubicHermiteSplineStruct.h
+ */
+export interface CubicHermiteSplineStruct {
+  readonly xInitial: readonly [number, number];
+  readonly xFinal: readonly [number, number];
+  readonly yInitial: readonly [number, number];
+  readonly yFinal: readonly [number, number];
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/spline/struct/QuinticHermiteSplineStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/spline/struct/QuinticHermiteSplineStruct.h
+ */
+export interface QuinticHermiteSplineStruct {
+  readonly xInitial: readonly [number, number, number];
+  readonly xFinal: readonly [number, number, number];
+  readonly yInitial: readonly [number, number, number];
+  readonly yFinal: readonly [number, number, number];
+}
+
+/**
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/java/edu/wpi/first/math/system/struct/LinearSystemStruct.java
+ * @see https://github.com/wpilibsuite/allwpilib/blob/main/wpimath/src/main/native/include/frc/system/struct/LinearSystemStruct.h
+ */
+export interface LinearSystemStruct {
+  readonly a: MatrixStruct;
+  readonly b: MatrixStruct;
+  readonly c: MatrixStruct;
+  readonly d: MatrixStruct;
+}

package/src/utils.ts

@@ -0,0 +1,241 @@
+import type { DataChannelRecord, DataTypeImpl } from "./abstractions";
+
+/** Constructs the {@link DataView} from the buffer source. */
+export function toDataView(source: unknown) {
+  if (source instanceof DataView) {
+    return source;
+  }
+
+  if (source instanceof ArrayBuffer) {
+    return new DataView(source);
+  }
+
+  if (ArrayBuffer.isView(source)) {
+    return new DataView(source.buffer, source.byteOffset, source.byteLength);
+  }
+
+  throw new Error(`Parameter of type '${typeof source}' cannot be wrapped into DataView`);
+}
+
+/** Returns the specified buffer source as {@link Uint8Array} view. */
+export function toUint8Array(source: unknown) {
+  if (source instanceof ArrayBuffer) {
+    return new Uint8Array(source);
+  }
+
+  if (ArrayBuffer.isView(source)) {
+    return source instanceof Uint8Array ? source : new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+  }
+
+  throw new Error(`Parameter of type '${typeof source}' cannot be represented as Uint8Array`);
+}
+
+/**
+ * Adds timestamped record to an array of records.
+ *
+ * The `records` array is assumed to be sorted by the timestamp in ascending order,
+ * earlier records have smaller indices.
+ *
+ * @returns the index at which the record has been inserted or updated
+ */
+export function addTimestampedRecord<T extends DataTypeImpl>(
+  records: Array<DataChannelRecord<T>>,
+  timestamp: number,
+  value: T
+): number {
+  if (records.length === 0) {
+    records.push({
+      timestamp,
+      value,
+    });
+
+    return 0;
+  }
+
+  // records must be sorted by the timestamp in ascending order
+  // timestamps of 0 and 1 are special, representing "weak" (set default)
+  // and "strong" (set while disconnected) timestamps; otherwise we
+  // expect timestamps to be generally newer than existing data
+
+  const tail = records[0]!;
+  let index = 0;
+
+  if (timestamp === 0) {
+    // replace value at timestamp zero
+    if (tail.timestamp === 0) {
+      tail.value = value;
+    } else {
+      records.unshift({
+        timestamp,
+        value,
+      });
+    }
+  } else if (timestamp === 1) {
+    if (tail.timestamp === 1) {
+      tail.value = value;
+    } else if (tail.timestamp === 0) {
+      index = 1;
+      if (records.length === 1) {
+        records.push({
+          timestamp,
+          value,
+        });
+      } else if (records[1]!.timestamp === 1) {
+        records[1]!.value = value;
+      } else {
+        records.splice(1, 0, {
+          timestamp,
+          value,
+        });
+      }
+    } else {
+      records.unshift({
+        timestamp,
+        value,
+      });
+    }
+  } else {
+    for (let i = records.length - 1; i >= 0; --i) {
+      const record = records[i]!;
+      if (record.timestamp === timestamp) {
+        index = i;
+        record.value = value;
+        return index;
+      }
+      if (record.timestamp < timestamp) {
+        index = i + 1;
+        records.splice(i + 1, 0, {
+          timestamp,
+          value,
+        });
+        return index;
+      }
+    }
+
+    records.unshift({
+      timestamp,
+      value,
+    });
+  }
+
+  return index;
+}
+
+/**
+ * Gets nearest (latest) timestamped record and its index.
+ *
+ * The `records` array is assumed to be sorted by the timestamp in ascending order,
+ * earlier records have smaller indices.
+ */
+export function getTimestampedRecord<T extends DataTypeImpl>(
+  records: Array<DataChannelRecord<T>>,
+  timestamp: number
+): [DataChannelRecord<T>, number] | [undefined, -1] {
+  if (records.length === 0) {
+    return [undefined, -1];
+  }
+
+  // timestamps of 0 and 1 are special
+  if (timestamp === 0) {
+    return records[0]!.timestamp === 0 ? [records[0]!, 0] : [undefined, -1];
+  }
+
+  if (timestamp === 1) {
+    if (records[0]!.timestamp === 1) {
+      return [records[0]!, 0];
+    }
+
+    if (records.length > 1 && records[1]!.timestamp === 1) {
+      return [records[1]!, 1];
+    }
+
+    return [undefined, -1];
+  }
+
+  for (let i = records.length - 1; i >= 0; --i) {
+    const record = records[i]!;
+    if (record.timestamp <= timestamp) {
+      return [record, i];
+    }
+  }
+
+  return [undefined, -1];
+}
+
+/**
+ * Reduces timestamps records array by pruning records with older timestamps
+ * per `maxSize` and `cutoff` window retention settings.
+ *
+ * Always retains special records with timestamps 0 and 1, these do not count
+ * towards maximum size limit.
+ *
+ * @param records array of records sorted by the timestamp in ascending order
+ * @param maxSize maximum number of entries to retain
+ * @param cutoff cutoff timestamp
+ */
+export function pruneTimestampedRecords(
+  records: Array<DataChannelRecord<DataTypeImpl>>,
+  maxSize?: number,
+  cutoff?: number
+) {
+  // shortcuts
+  if (cutoff == null && (maxSize == null || records.length <= maxSize)) {
+    return records;
+  }
+
+  // skip special records and find the oldest timestamp
+  const tailIndex = records.findIndex((_) => _.timestamp > 1);
+  if (tailIndex < 0) {
+    return records;
+  }
+
+  // apply maximum size policy first
+  if (maxSize != null && records.length - tailIndex - maxSize > 0) {
+    records.splice(tailIndex, records.length - tailIndex - maxSize);
+  }
+
+  // apply time window policy
+  if (cutoff != null) {
+    const oldest = records[tailIndex]!;
+    if (oldest.timestamp >= cutoff) {
+      return records;
+    }
+
+    let cutoffIndex = tailIndex;
+    // do not delete last record even if it is outside of the window
+    for (; cutoffIndex < records.length - 1; ++cutoffIndex) {
+      if (records[cutoffIndex]!.timestamp >= cutoff) {
+        break;
+      }
+    }
+
+    if (cutoffIndex > tailIndex) {
+      records.splice(tailIndex, cutoffIndex - tailIndex);
+    }
+  }
+
+  return records;
+}
+
+/** Sets deeply nested object value. */
+export function setValueByPath(
+  object: Record<string, unknown>,
+  path: Array<string>,
+  value: unknown,
+  insertOnly = false
+) {
+  path.reduce((o, key, i) => {
+    if (i === path.length - 1) {
+      if (!insertOnly || o[key] === undefined) {
+        o[key] = value;
+      }
+    } else if (o[key] === undefined) {
+      o[key] = {};
+    }
+
+    return o[key];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  }, object as any);
+
+  return object;
+}