@2702rebels/wpidata 1.0.0

package/dist/formats/struct.d.cts

@@ -0,0 +1,134 @@
+import { DataChannel, DataTransformer, DataTypeImpl, StructuredTypeDescriptor } from "../abstractions.cjs";
+
+//#region src/formats/struct.d.ts
+type StructFieldType = "ref" | "bool" | "char" | "int8" | "int16" | "int32" | "int64" | "uint8" | "uint16" | "uint32" | "uint64" | "float" | "double";
+/** Describes individual field in {@link StructDescriptor}. */
+type StructFieldDescriptor = {
+  /** Field identifier */
+  identifier: string;
+  /** Field value type */
+  type: StructFieldType;
+  /** Reference for complex (nested) type */
+  typeRef?: StructDescriptor | string;
+  /** Offset to the packed field data in bytes */
+  offset: number;
+  /** Size of the packed field data in bytes */
+  size: number;
+  /** Fixed array size */
+  arraySize?: number;
+  /** Bit width of the field data (bit-field only) */
+  bitWidth?: number;
+  /** Bit shift for the field data (bit-field only) */
+  bitShift?: number;
+  /** Enum specification */
+  enum?: Map<number, string>;
+};
+/** Describes named struct type. */
+type StructDescriptor = {
+  /** Struct type name */
+  name: string;
+  /** Struct fields in packed order */
+  fields: ReadonlyArray<StructFieldDescriptor>;
+  /** Total packed size in bytes */
+  size: number;
+  /** Missing dependencies */
+  unresolved?: Set<string>;
+};
+type UnpackStructOptions = {
+  /**
+   * Indicates that integer numeric values with enum specification should be converted
+   * to the corresponding enum string value if possible.
+   */
+  useEnum?: boolean;
+};
+/**
+ * Unpacks serialized struct data into JSON object.
+ *
+ * Implementation of WPILiB packed struct serialization protocol
+ * https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/doc/struct.adoc
+ *
+ * @param name struct type name
+ * @param data serialized binary data
+ * @param repository repository of available descriptors
+ * @param options additional options
+ */
+declare function unpack(name: string, data: DataView<ArrayBufferLike> | Uint8Array<ArrayBufferLike>, repository: StructRepository, options?: UnpackStructOptions): Record<string, unknown>;
+/**
+ * Packs JSON object into serialized struct data.
+ *
+ * @param name struct type name
+ * @param value JSON object to pack
+ * @param repository repository of available descriptors
+ * @returns ArrayBuffer containing serialized data
+ */
+declare function pack(name: string, value: Record<string, unknown>, repository: StructRepository): Uint8Array<ArrayBuffer>;
+/** Repository of struct descriptors. */
+declare class StructRepository {
+  private readonly unresolved;
+  /** Descriptors in the repository. */
+  readonly descriptors: Map<string, StructDescriptor>;
+  /**
+   * Computes field bte offsets and returns total packed size in bytes.
+   *
+   * This method assumes that all fields have resolved external dependencies
+   * and will compute byte offsets and bit shifts for bit-field packed fields.
+   */
+  private static computeFieldOffsets;
+  /**
+   * Attempts to finalize any unresolved descriptors with the recently resolved one.
+   */
+  private resolve;
+  /**
+   * Determines whether type can be transformed, indicating that
+   * the parsed type descriptor is present.
+   *
+   * @param name struct type name
+   */
+  canTransform(name: string): boolean;
+  /**
+   * Gets the struct type serialized size in bytes.
+   *
+   * @param name struct type name
+   */
+  getSize(name: string): number;
+  /**
+   * Unpacks serialized struct data into JSON object.
+   *
+   * @param name struct type name
+   * @param data serialized binary data
+   * @param options additional options
+   */
+  unpack(name: string, data: DataView<ArrayBufferLike> | Uint8Array<ArrayBufferLike>, options?: UnpackStructOptions): Record<string, unknown>;
+  /**
+   * Packs JSON object into serialized struct data.
+   *
+   * @param name struct type  name
+   * @param value JSON object to pack
+   */
+  pack(name: string, value: Record<string, unknown>): Uint8Array<ArrayBuffer>;
+  /**
+   * Parses struct schema and adds the resulting descriptor to the repository.
+   *
+   * The descriptor may not be fully processed if it references other structs that
+   * we have not seen yet. Such pending descriptors will be processed automatically,
+   * once corresponding structs have been added. This code checks for circular
+   * dependencies and will fail when one is detected.
+   *
+   * @param name struct type name
+   * @param data struct schema in UTF-8 encoded binary representation
+   * @returns parsed descriptor or `null` if the operation failed
+   */
+  add(name: string, data: DataView<ArrayBufferLike> | Uint8Array<ArrayBufferLike>): StructDescriptor | null;
+}
+/** Implements {@link DataTransformer} interface for the `struct` serialization protocol. */
+declare class StructDataTransformer implements DataTransformer {
+  private readonly repo;
+  inspect(source: string, name: string, type: string, metadata?: string | Record<string, unknown>): DataChannel | string | undefined;
+  schema(typeName: string, value: unknown): void;
+  deserialize(value: unknown, type?: StructuredTypeDescriptor): DataTypeImpl | undefined;
+  serialize(value: unknown, type?: StructuredTypeDescriptor): Uint8Array;
+  canTransform(type: string): boolean;
+}
+//#endregion
+export { StructDataTransformer, StructDescriptor, StructFieldDescriptor, StructFieldType, StructRepository, UnpackStructOptions, pack, unpack };
+//# sourceMappingURL=struct.d.cts.map

package/dist/formats/struct.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"struct.d.cts","names":[],"sources":["../../src/formats/struct.ts"],"sourcesContent":[],"mappings":";;;KAQY,eAAA;;AAAA,KAgBA,qBAAA,GAhBe;EAgBf;EAIJ,UAAA,EAAA,MAAA;EAEI;EAYH,IAAA,EAdD,eAcC;EAAG;EAIA,OAAA,CAAA,EAhBA,gBAgBgB,GAAA,MAAA;EAIJ;EAAd,MAAA,EAAA,MAAA;EAIK;EAAG,IAAA,EAAA,MAAA;EAUN;EAmBI,SAAM,CAAA,EAAA,MAAA;EAEL;EAAT,QAAA,CAAA,EAAA,MAAA;EAAuC;EAAX,QAAA,CAAA,EAAA,MAAA;EACtB;EACF,IAAA,CAAA,EA7CH,GA6CG,CAAA,MAAA,EAAA,MAAA,CAAA;CAAmB;;AAyBf,KAlEJ,gBAAA,GAkEQ;EAAsB;EAAqC,IAAA,EAAA,MAAA;EAAgB;EAAA,MAAA,EA9DrF,aA8DqF,CA9DvE,qBA8DuE,CAAA;EAAA;EAkclF,IAAA,EAAA,MAAA;EAIgB;EAAA,UAAA,CAAA,EAhgBd,GAggBc,CAAA,MAAA,CAAA;CAyHV;AAAT,KA/mBE,mBAAA,GA+mBF;EAAuC;;;;EAYd,OAAA,CAAA,EAAA,OAAA;CAAuB;;;;;;;;AAsL1D;;;;AA0CuE,iBAx0BvD,MAAA,CAw0BuD,IAAA,EAAA,MAAA,EAAA,IAAA,EAt0B/D,QAs0B+D,CAt0BtD,eAs0BsD,CAAA,GAt0BnC,UAs0BmC,CAt0BxB,eAs0BwB,CAAA,EAAA,UAAA,EAr0BzD,gBAq0ByD,EAAA,OAAA,CAAA,EAp0B3D,mBAo0B2D,CAAA,EAp0BxC,MAo0BwC,CAAA,MAAA,EAAA,OAAA,CAAA;;;;;;;;;iBA3yBvD,IAAA,sBAA0B,qCAAqC,mBAAgB,WAAA;;cAkclF,gBAAA;;;wBAIgB,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAyHnB,SAAS,mBAAmB,WAAW,4BACnC,sBAAmB;;;;;;;4BAWE,0BAAuB,WAAA;;;;;;;;;;;;;0BAgBzB,SAAS,mBAAmB,WAAW,mBAAmB;;;cAsK9E,qBAAA,YAAiC;;0EAOtB,0BACnB;;qCAkCuC,2BAA2B;mCAkC7B,2BAA2B"}

package/dist/formats/struct.d.mts

@@ -0,0 +1,134 @@
+import { DataChannel, DataTransformer, DataTypeImpl, StructuredTypeDescriptor } from "../abstractions.mjs";
+
+//#region src/formats/struct.d.ts
+type StructFieldType = "ref" | "bool" | "char" | "int8" | "int16" | "int32" | "int64" | "uint8" | "uint16" | "uint32" | "uint64" | "float" | "double";
+/** Describes individual field in {@link StructDescriptor}. */
+type StructFieldDescriptor = {
+  /** Field identifier */
+  identifier: string;
+  /** Field value type */
+  type: StructFieldType;
+  /** Reference for complex (nested) type */
+  typeRef?: StructDescriptor | string;
+  /** Offset to the packed field data in bytes */
+  offset: number;
+  /** Size of the packed field data in bytes */
+  size: number;
+  /** Fixed array size */
+  arraySize?: number;
+  /** Bit width of the field data (bit-field only) */
+  bitWidth?: number;
+  /** Bit shift for the field data (bit-field only) */
+  bitShift?: number;
+  /** Enum specification */
+  enum?: Map<number, string>;
+};
+/** Describes named struct type. */
+type StructDescriptor = {
+  /** Struct type name */
+  name: string;
+  /** Struct fields in packed order */
+  fields: ReadonlyArray<StructFieldDescriptor>;
+  /** Total packed size in bytes */
+  size: number;
+  /** Missing dependencies */
+  unresolved?: Set<string>;
+};
+type UnpackStructOptions = {
+  /**
+   * Indicates that integer numeric values with enum specification should be converted
+   * to the corresponding enum string value if possible.
+   */
+  useEnum?: boolean;
+};
+/**
+ * Unpacks serialized struct data into JSON object.
+ *
+ * Implementation of WPILiB packed struct serialization protocol
+ * https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/doc/struct.adoc
+ *
+ * @param name struct type name
+ * @param data serialized binary data
+ * @param repository repository of available descriptors
+ * @param options additional options
+ */
+declare function unpack(name: string, data: DataView<ArrayBufferLike> | Uint8Array<ArrayBufferLike>, repository: StructRepository, options?: UnpackStructOptions): Record<string, unknown>;
+/**
+ * Packs JSON object into serialized struct data.
+ *
+ * @param name struct type name
+ * @param value JSON object to pack
+ * @param repository repository of available descriptors
+ * @returns ArrayBuffer containing serialized data
+ */
+declare function pack(name: string, value: Record<string, unknown>, repository: StructRepository): Uint8Array<ArrayBuffer>;
+/** Repository of struct descriptors. */
+declare class StructRepository {
+  private readonly unresolved;
+  /** Descriptors in the repository. */
+  readonly descriptors: Map<string, StructDescriptor>;
+  /**
+   * Computes field bte offsets and returns total packed size in bytes.
+   *
+   * This method assumes that all fields have resolved external dependencies
+   * and will compute byte offsets and bit shifts for bit-field packed fields.
+   */
+  private static computeFieldOffsets;
+  /**
+   * Attempts to finalize any unresolved descriptors with the recently resolved one.
+   */
+  private resolve;
+  /**
+   * Determines whether type can be transformed, indicating that
+   * the parsed type descriptor is present.
+   *
+   * @param name struct type name
+   */
+  canTransform(name: string): boolean;
+  /**
+   * Gets the struct type serialized size in bytes.
+   *
+   * @param name struct type name
+   */
+  getSize(name: string): number;
+  /**
+   * Unpacks serialized struct data into JSON object.
+   *
+   * @param name struct type name
+   * @param data serialized binary data
+   * @param options additional options
+   */
+  unpack(name: string, data: DataView<ArrayBufferLike> | Uint8Array<ArrayBufferLike>, options?: UnpackStructOptions): Record<string, unknown>;
+  /**
+   * Packs JSON object into serialized struct data.
+   *
+   * @param name struct type  name
+   * @param value JSON object to pack
+   */
+  pack(name: string, value: Record<string, unknown>): Uint8Array<ArrayBuffer>;
+  /**
+   * Parses struct schema and adds the resulting descriptor to the repository.
+   *
+   * The descriptor may not be fully processed if it references other structs that
+   * we have not seen yet. Such pending descriptors will be processed automatically,
+   * once corresponding structs have been added. This code checks for circular
+   * dependencies and will fail when one is detected.
+   *
+   * @param name struct type name
+   * @param data struct schema in UTF-8 encoded binary representation
+   * @returns parsed descriptor or `null` if the operation failed
+   */
+  add(name: string, data: DataView<ArrayBufferLike> | Uint8Array<ArrayBufferLike>): StructDescriptor | null;
+}
+/** Implements {@link DataTransformer} interface for the `struct` serialization protocol. */
+declare class StructDataTransformer implements DataTransformer {
+  private readonly repo;
+  inspect(source: string, name: string, type: string, metadata?: string | Record<string, unknown>): DataChannel | string | undefined;
+  schema(typeName: string, value: unknown): void;
+  deserialize(value: unknown, type?: StructuredTypeDescriptor): DataTypeImpl | undefined;
+  serialize(value: unknown, type?: StructuredTypeDescriptor): Uint8Array;
+  canTransform(type: string): boolean;
+}
+//#endregion
+export { StructDataTransformer, StructDescriptor, StructFieldDescriptor, StructFieldType, StructRepository, UnpackStructOptions, pack, unpack };
+//# sourceMappingURL=struct.d.mts.map

package/dist/formats/struct.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"struct.d.mts","names":[],"sources":["../../src/formats/struct.ts"],"sourcesContent":[],"mappings":";;;KAQY,eAAA;;AAAA,KAgBA,qBAAA,GAhBe;EAgBf;EAIJ,UAAA,EAAA,MAAA;EAEI;EAYH,IAAA,EAdD,eAcC;EAAG;EAIA,OAAA,CAAA,EAhBA,gBAgBgB,GAAA,MAAA;EAIJ;EAAd,MAAA,EAAA,MAAA;EAIK;EAAG,IAAA,EAAA,MAAA;EAUN;EAmBI,SAAM,CAAA,EAAA,MAAA;EAEL;EAAT,QAAA,CAAA,EAAA,MAAA;EAAuC;EAAX,QAAA,CAAA,EAAA,MAAA;EACtB;EACF,IAAA,CAAA,EA7CH,GA6CG,CAAA,MAAA,EAAA,MAAA,CAAA;CAAmB;;AAyBf,KAlEJ,gBAAA,GAkEQ;EAAsB;EAAqC,IAAA,EAAA,MAAA;EAAgB;EAAA,MAAA,EA9DrF,aA8DqF,CA9DvE,qBA8DuE,CAAA;EAAA;EAkclF,IAAA,EAAA,MAAA;EAIgB;EAAA,UAAA,CAAA,EAhgBd,GAggBc,CAAA,MAAA,CAAA;CAyHV;AAAT,KA/mBE,mBAAA,GA+mBF;EAAuC;;;;EAYd,OAAA,CAAA,EAAA,OAAA;CAAuB;;;;;;;;AAsL1D;;;;AA0CuE,iBAx0BvD,MAAA,CAw0BuD,IAAA,EAAA,MAAA,EAAA,IAAA,EAt0B/D,QAs0B+D,CAt0BtD,eAs0BsD,CAAA,GAt0BnC,UAs0BmC,CAt0BxB,eAs0BwB,CAAA,EAAA,UAAA,EAr0BzD,gBAq0ByD,EAAA,OAAA,CAAA,EAp0B3D,mBAo0B2D,CAAA,EAp0BxC,MAo0BwC,CAAA,MAAA,EAAA,OAAA,CAAA;;;;;;;;;iBA3yBvD,IAAA,sBAA0B,qCAAqC,mBAAgB,WAAA;;cAkclF,gBAAA;;;wBAIgB,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAyHnB,SAAS,mBAAmB,WAAW,4BACnC,sBAAmB;;;;;;;4BAWE,0BAAuB,WAAA;;;;;;;;;;;;;0BAgBzB,SAAS,mBAAmB,WAAW,mBAAmB;;;cAsK9E,qBAAA,YAAiC;;0EAOtB,0BACnB;;qCAkCuC,2BAA2B;mCAkC7B,2BAA2B"}