@2702rebels/wpidata 1.0.0

package/dist/formats/struct.cjs

@@ -0,0 +1,593 @@
+const require_utils = require('../utils.cjs');
+
+//#region src/formats/struct.ts
+const error = (message) => {
+	return new Error(message);
+};
+const utf8decoder = new TextDecoder("utf-8", { fatal: true });
+const utf8encoder = new TextEncoder();
+/**
+* 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
+*/
+function unpack(name, data, repository, options) {
+	const descriptor = repository.descriptors.get(name);
+	if (descriptor == null) throw error(`Failed to unpack struct data: missing '${name}' type definition`);
+	if (descriptor.size === 0) throw error(`Failed to unpack struct data: '${name}' type definition has unresolved dependencies`);
+	const result = {};
+	unpackStruct(result, descriptor, require_utils.toDataView(data), 0, options?.useEnum ? transformEnums : (_, v) => v);
+	return result;
+}
+/**
+* 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
+*/
+function pack(name, value, repository) {
+	const descriptor = repository.descriptors.get(name);
+	if (descriptor == null) throw error(`Failed to pack struct data: missing '${name}' type definition`);
+	if (descriptor.size === 0) throw error(`Failed to pack struct data: '${name}' type definition has unresolved dependencies`);
+	const buffer = new ArrayBuffer(descriptor.size);
+	packStruct(value, descriptor, new DataView(buffer), 0, transformValue);
+	return new Uint8Array(buffer);
+}
+/**
+* Transforms field values according to the field descriptor.
+*
+* Handles conversion of enum strings into their numeric representation.
+*/
+function transformValue(field, value) {
+	if (field.enum != null && typeof value === "string") {
+		for (const [key, v] of field.enum) if (v === value) return key;
+	}
+	return value;
+}
+/** Transforms numeric values to enum names for fields that support enums. */
+function transformEnums(field, value) {
+	if (field.enum != null && typeof value === "number") {
+		const enumName = field.enum.get(value);
+		if (enumName != null) return enumName;
+	}
+	return value;
+}
+/**
+* Unpacks data per descriptor specification and populates `sink` placeholder instance.
+*
+* @param sink target object to populate with parsed data
+* @param descriptor struct type descriptor
+* @param view source buffer view
+* @param byteOffset offset in bytes within `view`
+* @param transformer primitive field value transformer
+*/
+function unpackStruct(sink, descriptor, view, byteOffset, transformer) {
+	for (const field of descriptor.fields) if (field.type === "ref") {
+		if (field.typeRef == null || typeof field.typeRef !== "object") throw error(`Failed to unpack struct data: field '${field.identifier}' references unresolved type`);
+		const result = {};
+		unpackStruct(result, field.typeRef, view, byteOffset + field.offset, transformer);
+		sink[field.identifier] = result;
+	} else if (field.arraySize != null) if (field.type === "char") sink[field.identifier] = transformer(field, decodeStringValue(view, byteOffset + field.offset, field.arraySize));
+	else {
+		const result = [];
+		for (let i = 0; i < field.arraySize; ++i) result.push(transformer(field, decodePrimitiveValue(field, view, byteOffset + field.offset + i * field.size)));
+	}
+	else if (field.bitWidth != null) sink[field.identifier] = transformer(field, decodeBitFieldValue(field, view, byteOffset + field.offset));
+	else sink[field.identifier] = transformer(field, decodePrimitiveValue(field, view, byteOffset + field.offset));
+}
+/**
+* Packs data per descriptor specification.
+*
+* @param source source object to pack
+* @param descriptor struct type descriptor
+* @param view target buffer view
+* @param byteOffset offset in bytes within `view`
+* @param transformer primitive field value transformer
+*/
+function packStruct(source, descriptor, view, byteOffset, transformer) {
+	for (const field of descriptor.fields) {
+		const value = source[field.identifier];
+		if (field.type === "ref") {
+			if (field.typeRef == null || typeof field.typeRef !== "object") throw error(`Failed to pack struct data: field '${field.identifier}' references unresolved type`);
+			packStruct(value ?? {}, field.typeRef, view, byteOffset + field.offset, transformer);
+		} else if (field.arraySize != null) if (field.type === "char") encodeStringValue(view, byteOffset + field.offset, field.arraySize, transformer(field, value) ?? "");
+		else for (let i = 0; i < field.arraySize; ++i) encodePrimitiveValue(field, view, byteOffset + field.offset + i * field.size, transformer(field, value));
+		else if (field.bitWidth != null) encodeBitFieldValue(field, view, byteOffset + field.offset, transformer(field, value));
+		else encodePrimitiveValue(field, view, byteOffset + field.offset, transformer(field, value));
+	}
+}
+/**
+* Decodes a string field value.
+*
+* Assumes UTF-8 encoding, handles zero-termination, continuation bytes.
+*/
+function decodeStringValue(view, byteOffset, byteLength) {
+	let length = byteLength;
+	for (; length > 0; --length) if (view.getUint8(byteOffset + length - 1) !== 0) break;
+	if (length === 0) return "";
+	if ((view.getUint8(byteOffset + length - 1) & 128) !== 0) {
+		let start = length;
+		for (; start > 0; --start) if ((view.getUint8(byteOffset + start - 1) & 64) != 0) break;
+		if (start == 0) return "";
+		start--;
+		const b = view.getUint8(byteOffset + start);
+		if ((b & 224) === 192) {
+			if (start !== length - 2) length = start;
+		} else if ((b & 240) === 224) {
+			if (start !== length - 3) length = start;
+		} else if ((b & 248) === 240) {
+			if (start !== length - 4) length = start;
+		}
+	}
+	return utf8decoder.decode(new DataView(view.buffer, view.byteOffset + byteOffset, length));
+}
+/**
+* Encodes a string field value.
+*
+* The implementation relies on the behavior of `Uint8Array` that is initialized to all zeros
+* and automatically clamps the size of the encoded data to the length of the array.
+*/
+function encodeStringValue(view, byteOffset, byteLength, value) {
+	utf8encoder.encodeInto(value, new Uint8Array(view.buffer, view.byteOffset + byteOffset, byteLength));
+}
+/**
+* Decodes a primitive field value.
+*
+* † Javascript limits integer types to 53-bit representation.
+* Decoding 64-bit integers may result in loss of precision as values
+* that do not fit within the safe integer limit will be represented by
+* floating-point numbers with double precision.
+*
+* ‡ Decoding a character value only makes sense for reading fields that
+* consist of exactly one character, where UTF-8 is essentially ASCII.
+* In practice UTF-8 encoded strings use multiple bytes to represent
+* non-ASCII characters and must be handled in a special way when array
+* of chars is decoded. @see {decodeStringValue}.
+*/
+function decodePrimitiveValue(field, view, byteOffset) {
+	switch (field.type) {
+		case "bool": return view.getUint8(byteOffset) !== 0;
+		case "char": return String.fromCharCode(view.getUint8(byteOffset));
+		case "int8": return view.getInt8(byteOffset);
+		case "int16": return view.getInt16(byteOffset, true);
+		case "int32": return view.getInt32(byteOffset, true);
+		case "int64": return Number(view.getBigInt64(byteOffset, true));
+		case "uint8": return view.getUint8(byteOffset);
+		case "uint16": return view.getUint16(byteOffset, true);
+		case "uint32": return view.getUint32(byteOffset, true);
+		case "uint64": return Number(view.getBigUint64(byteOffset, true));
+		case "float": return view.getFloat32(byteOffset, true);
+		case "double": return view.getFloat64(byteOffset, true);
+	}
+}
+/**
+* Encodes a primitive field value.
+*/
+function encodePrimitiveValue(field, view, byteOffset, value) {
+	const v = value == null ? 0 : typeof value === "string" ? value.length === 0 ? 0 : value.charCodeAt(0) : Number(value);
+	switch (field.type) {
+		case "bool":
+			view.setUint8(byteOffset, v);
+			break;
+		case "char":
+			view.setUint8(byteOffset, v);
+			break;
+		case "int8":
+			view.setInt8(byteOffset, v);
+			break;
+		case "int16":
+			view.setInt16(byteOffset, v, true);
+			break;
+		case "int32":
+			view.setInt32(byteOffset, v, true);
+			break;
+		case "int64":
+			view.setBigInt64(byteOffset, BigInt(v), true);
+			break;
+		case "uint8":
+			view.setUint8(byteOffset, v);
+			break;
+		case "uint16":
+			view.setUint16(byteOffset, v, true);
+			break;
+		case "uint32":
+			view.setUint32(byteOffset, v, true);
+			break;
+		case "uint64":
+			view.setBigUint64(byteOffset, BigInt(v), true);
+			break;
+		case "float":
+			view.setFloat32(byteOffset, v, true);
+			break;
+		case "double":
+			view.setFloat64(byteOffset, v, true);
+			break;
+	}
+}
+/**
+* Decodes a bit-field integer value.
+*/
+function decodeBitFieldValue(field, view, byteOffset) {
+	const width = field.bitWidth;
+	const shift = field.bitShift;
+	if (field.size === 8) if (width <= 32) {
+		const h32 = view.getUint32(byteOffset + 4, true);
+		const l32 = view.getUint32(byteOffset, true);
+		const v = (shift >= 32 ? h32 >>> shift - 32 : l32 >>> shift | h32 << 32 - shift) & bitmask(width);
+		return field.type === "int64" ? v << 32 - width >> 32 - width : v;
+	} else {
+		const data = view.getBigUint64(byteOffset, true);
+		return Number(data >> BigInt(shift) & 2n ** BigInt(width) - 1n);
+	}
+	else {
+		const data = field.size === 4 ? view.getUint32(byteOffset, true) : field.size === 2 ? view.getUint16(byteOffset, true) : view.getUint8(byteOffset);
+		switch (field.type) {
+			case "bool":
+			case "uint8":
+			case "uint16":
+			case "uint32": {
+				const v = data >>> shift & bitmask(width);
+				return field.type === "bool" ? v !== 0 : v;
+			}
+		}
+		return data << 32 - shift - width >> 32 - width;
+	}
+}
+/**
+* Encodes a bit-field integer value.
+*/
+function encodeBitFieldValue(field, view, byteOffset, value) {
+	const width = field.bitWidth;
+	const shift = field.bitShift;
+	const n = value == null ? 0 : Number(value);
+	const overlay = (n$1, v, mask, shift$1) => v & ~(mask << shift$1) | (n$1 & mask) << shift$1;
+	if (field.size === 8) if (width <= 32) {
+		const mask = bitmask(width);
+		if (shift >= 32) view.setUint32(byteOffset + 4, overlay(n, view.getUint32(byteOffset + 4, true), mask, shift - 32), true);
+		else if (shift + width <= 32) view.setUint32(byteOffset, overlay(n, view.getUint32(byteOffset, true), mask, shift), true);
+		else {
+			const h32 = view.getUint32(byteOffset + 4, true);
+			const l32 = view.getUint32(byteOffset, true);
+			const nm = n & mask;
+			view.setUint32(byteOffset + 4, h32 & ~bitmask(shift + width - 32) | nm >>> 32 - shift, true);
+			view.setUint32(byteOffset, overlay(nm, l32, bitmask(32 - shift), shift), true);
+		}
+	} else {
+		const data = view.getBigUint64(byteOffset, true);
+		const mask = 2n ** BigInt(width) - 1n;
+		view.setBigUint64(byteOffset, data & ~(mask << BigInt(shift)) | (BigInt(n) & mask) << BigInt(shift), true);
+	}
+	else {
+		const mask = bitmask(width);
+		switch (field.size) {
+			case 4:
+				view.setUint32(byteOffset, overlay(n, view.getUint32(byteOffset, true), mask, shift), true);
+				break;
+			case 2:
+				view.setUint16(byteOffset, overlay(n, view.getUint16(byteOffset, true), mask, shift), true);
+				break;
+			case 1:
+				view.setUint8(byteOffset, overlay(n, view.getUint8(byteOffset), mask, shift));
+				break;
+		}
+	}
+}
+/** Constructs bitmask of the specified `width` (max 32 bits). */
+const bitmask = (width) => -1 >>> 32 - width;
+/** Bytes size of the value type. */
+const fieldTypeByteSize = {
+	bool: 1,
+	char: 1,
+	int8: 1,
+	int16: 2,
+	int32: 4,
+	int64: 8,
+	uint8: 1,
+	uint16: 2,
+	uint32: 4,
+	uint64: 8,
+	float: 4,
+	double: 8
+};
+const getFieldType = (type) => {
+	switch (type) {
+		case "bool":
+		case "char":
+		case "int8":
+		case "int16":
+		case "int32":
+		case "int64":
+		case "uint8":
+		case "uint16":
+		case "uint32":
+		case "uint64":
+		case "float":
+		case "double": return type;
+		case "float32": return "float";
+		case "float64": return "double";
+		default: return "ref";
+	}
+};
+/** Repository of struct descriptors. */
+var StructRepository = class StructRepository {
+	unresolved = [];
+	/** Descriptors in the repository. */
+	descriptors = /* @__PURE__ */ new Map();
+	/**
+	* 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.
+	*/
+	static computeFieldOffsets(fields) {
+		let offset = 0;
+		let bitBlock = 0;
+		let bitAvail = 0;
+		for (const field of fields) if (field.bitWidth != null) {
+			if (bitBlock !== field.size && field.type !== "bool" || field.bitWidth > bitAvail) {
+				if (bitBlock > 0) offset += bitBlock;
+				bitBlock = field.size;
+				bitAvail = bitBlock << 3;
+			}
+			if (field.type === "bool") field.size = bitBlock;
+			field.offset = offset;
+			field.bitShift = (bitBlock << 3) - bitAvail;
+			bitAvail -= field.bitWidth;
+		} else {
+			if (bitBlock > 0) {
+				offset += bitBlock;
+				bitBlock = 0;
+				bitAvail = 0;
+			}
+			field.offset = offset;
+			offset += field.size * (field.arraySize ?? 1);
+		}
+		return offset + bitBlock;
+	}
+	/**
+	* Attempts to finalize any unresolved descriptors with the recently resolved one.
+	*/
+	resolve(descriptor) {
+		const resolved = [];
+		for (let i = this.unresolved.length - 1; i >= 0; --i) {
+			const d = this.unresolved[i];
+			if (d.unresolved?.has(descriptor.name)) {
+				d.unresolved?.delete(descriptor.name);
+				d.fields.forEach((_) => {
+					if (_.typeRef === descriptor.name) {
+						_.typeRef = descriptor;
+						_.size = descriptor.size;
+					}
+				});
+				if (d.unresolved.size === 0) {
+					d.unresolved = void 0;
+					d.size = StructRepository.computeFieldOffsets(d.fields);
+					this.unresolved.splice(i, 1);
+					resolved.push(d);
+				}
+			}
+		}
+		for (const d of resolved) this.resolve(d);
+	}
+	/**
+	* Determines whether type can be transformed, indicating that
+	* the parsed type descriptor is present.
+	*
+	* @param name struct type name
+	*/
+	canTransform(name) {
+		const d = this.descriptors.get(name);
+		return d != null && d.size > 0;
+	}
+	/**
+	* Gets the struct type serialized size in bytes.
+	*
+	* @param name struct type name
+	*/
+	getSize(name) {
+		const size = this.descriptors.get(name)?.size;
+		if (size == null || size == 0) throw new Error(`Descriptor for type '${name}' does not exist or is not fully defined`);
+		return size;
+	}
+	/**
+	* Unpacks serialized struct data into JSON object.
+	*
+	* @param name struct type name
+	* @param data serialized binary data
+	* @param options additional options
+	*/
+	unpack(name, data, options) {
+		return unpack(name, data, this, options);
+	}
+	/**
+	* Packs JSON object into serialized struct data.
+	*
+	* @param name struct type  name
+	* @param value JSON object to pack
+	*/
+	pack(name, value) {
+		return pack(name, value, this);
+	}
+	/**
+	* 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, data) {
+		let decoded;
+		try {
+			decoded = utf8decoder.decode(data);
+		} catch (exception) {
+			throw error(exception instanceof TypeError ? `Failed to parse schema: ${exception.message}` : `Failed to parse schema: unknown error`);
+		}
+		const fields = [];
+		const tokens = decoded.split(";").map((_) => _.trim()).filter((_) => _.length > 0);
+		const unresolved = /* @__PURE__ */ new Set();
+		for (const token of tokens) {
+			const m = /^(?:(?:enum)?\s*(?:{\s*}|{(?<enum>(?:\s*\w\s*=\s*-?\d+\s*)(?:,\s*\w\s*=\s*-?\d+\s*)*),?\s*}))?\s*(?<type>\w+)\s+(?<id>\w+)\s*(?:(?:\[\s*(?<array>\d+)\s*\])|:\s*(?<bits>[1-9]\d?))?$/i.exec(token);
+			if (m == null || m.groups == null) throw error(`Failed to parse schema: invalid declaration '${token}'`);
+			const id = m.groups["id"];
+			const typeRaw = m.groups["type"];
+			if (fields.some((_) => _.identifier === id)) throw error(`Failed to parse schema: duplicate '${id}' field declaration`);
+			const field = {
+				identifier: id,
+				type: getFieldType(typeRaw),
+				offset: -1,
+				size: 0
+			};
+			if (field.type === "ref") {
+				field.typeRef = this.descriptors.get(typeRaw);
+				if (field.typeRef == null) {
+					field.typeRef = typeRaw;
+					unresolved.add(typeRaw);
+				} else if (field.typeRef.size === 0) throw error(`Failed to parse schema: circular dependency detected between '${name}' and '${field.typeRef.name}'`);
+				else field.size = field.typeRef.size;
+			} else field.size = fieldTypeByteSize[field.type];
+			const bitWidthRaw = m.groups["bits"];
+			if (bitWidthRaw != null) {
+				field.bitWidth = parseInt(bitWidthRaw, 10);
+				if (Number.isNaN(field.bitWidth)) throw error(`Failed to parse schema: non-numeric bit-field width in '${id}' field declaration`);
+				switch (field.type) {
+					case "bool":
+						if (field.bitWidth !== 1) throw error(`Failed to parse schema: invalid boolean bit-field width '${id}' field declaration`);
+						break;
+					case "int8":
+					case "int16":
+					case "int32":
+					case "int64":
+					case "uint8":
+					case "uint16":
+					case "uint32":
+					case "uint64":
+						if (field.bitWidth < 1 || field.bitWidth > fieldTypeByteSize[field.type] << 3) throw error(`Failed to parse schema: invalid integer bit-field width '${id}' field declaration`);
+						break;
+					default: throw error(`Failed to parse schema: bit-field in non-integer/boolean '${id}' field declaration`);
+				}
+			}
+			const arraySizeRaw = m.groups["array"];
+			if (arraySizeRaw != null) {
+				field.arraySize = parseInt(arraySizeRaw, 10);
+				if (Number.isNaN(field.arraySize) || field.arraySize <= 0) throw error(`Failed to parse schema: invalid array size in '${id}' field declaration`);
+			}
+			const enumBodyRaw = m.groups["enum"];
+			if (enumBodyRaw) {
+				switch (field.type) {
+					case "int8":
+					case "int16":
+					case "int32":
+					case "int64":
+					case "uint8":
+					case "uint16":
+					case "uint32":
+					case "uint64": break;
+					default: throw error(`Failed to parse schema: enum declaration in non-integer '${id}' field declaration`);
+				}
+				field.enum = /* @__PURE__ */ new Map();
+				for (const tuple of enumBodyRaw.split(",")) {
+					const [enumName, valueRaw] = tuple.trim().split("=", 2);
+					const enumValue = parseInt(valueRaw.trim(), 10);
+					if (Number.isNaN(enumValue)) throw error(`Failed to parse schema: enum declaration contains non-integer value '${valueRaw}' in '${id}' field declaration`);
+					field.enum.set(enumValue, enumName);
+				}
+			}
+			fields.push(field);
+		}
+		const descriptor = {
+			name,
+			fields,
+			size: unresolved.size > 0 ? 0 : StructRepository.computeFieldOffsets(fields),
+			unresolved: unresolved.size > 0 ? unresolved : void 0
+		};
+		this.descriptors.set(name, descriptor);
+		if (descriptor.size > 0) this.resolve(descriptor);
+		else this.unresolved.push(descriptor);
+		return descriptor;
+	}
+};
+/** Implements {@link DataTransformer} interface for the `struct` serialization protocol. */
+var StructDataTransformer = class {
+	repo = new StructRepository();
+	inspect(source, name, type, metadata) {
+		if (name.startsWith("/.schema/struct:")) {
+			if (type !== "structschema") throw new Error(`Unexpected type '${type}' for struct schema entry`);
+			return name.substring(16);
+		}
+		if (type.startsWith("struct:")) {
+			const isArrayType = type.endsWith("[]");
+			return {
+				source,
+				id: name,
+				dataType: "json",
+				publishedDataType: type,
+				transformer: this,
+				structuredType: {
+					name: isArrayType ? type.slice(7, -2) : type.slice(7),
+					format: "struct",
+					isArray: isArrayType
+				},
+				metadata
+			};
+		}
+	}
+	schema(typeName, value) {
+		this.repo.add(typeName, require_utils.toUint8Array(value));
+	}
+	deserialize(value, type) {
+		if (type == null) throw new Error(`Transformation requires type to be specified. This situation should not be possible if the transformer is wired correctly.`);
+		if (this.repo.canTransform(type.name)) {
+			const buffer = require_utils.toUint8Array(value);
+			if (type.isArray) {
+				const result = [];
+				const itemSize = this.repo.getSize(type.name);
+				let byteOffset = 0;
+				while (byteOffset + itemSize <= buffer.byteLength) {
+					result.push(this.repo.unpack(type.name, new DataView(buffer.buffer, buffer.byteOffset + byteOffset, itemSize), { useEnum: true }));
+					byteOffset += itemSize;
+				}
+				return result;
+			}
+			return this.repo.unpack(type.name, buffer, { useEnum: true });
+		}
+	}
+	serialize(value, type) {
+		if (type == null) throw new Error(`Transformation requires type to be specified. This situation should not be possible if the transformer is wired correctly.`);
+		if (value == null || typeof value !== "object") throw new Error("Only JSON objects can be serialized");
+		if (this.repo.canTransform(type.name)) {
+			if (Array.isArray(value)) {
+				const itemSize = this.repo.getSize(type.name);
+				const result = new Uint8Array(itemSize * value.length);
+				for (let i = 0; i < value.length; ++i) {
+					const part = this.repo.pack(type.name, value[i]);
+					result.set(part, i * itemSize);
+				}
+				return result;
+			}
+			return this.repo.pack(type.name, value);
+		}
+		throw new Error(`Struct serialization is not supported for '${type.name}'`);
+	}
+	canTransform(type) {
+		return this.repo.canTransform(type);
+	}
+};
+
+//#endregion
+exports.StructDataTransformer = StructDataTransformer;
+exports.StructRepository = StructRepository;
+exports.pack = pack;
+exports.unpack = unpack;