@rotu/structview 0.8.2 → 0.10.0

package/esm/core.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Tools for declaring a binary struct as a class with properties
+ * @module
+ */
+import type { AnyStruct, MixinFromProps, StructConstructor, StructPropertyDescriptor, SubclassWithProperties } from "./types.js";
+export declare const dataViewSymbol: unique symbol;
+/**
+ * Get the underlying DataView of a struct
+ * @param struct
+ * @returns
+ */
+export declare function structDataView(struct: AnyStruct): DataView;
+/**
+ * Helper method to create a view of a contiguous subregion of a Struct's memory
+ * @param struct
+ * @param start byte offset to start
+ * @param end byte offset of the end of the subrange
+ * @returns region of the given struct.
+ */
+export declare function structBytes(struct: AnyStruct, start?: number, end?: number): Uint8Array;
+/**
+ * Define a descriptor based on a dataview of the struct
+ * @param fieldGetter function which, given a dataview, returns
+ * @returns
+ */
+export declare function fromDataView<Fn extends (dv: DataView) => unknown>(fieldGetter: Fn): StructPropertyDescriptor<ReturnType<Fn>>;
+/**
+ * Base class for a structured binary object
+ * Note there are no predeclared string-keyed properties - all property names are reserved for user-defined fields
+ */
+export declare class Struct {
+    [dataViewSymbol]: DataView;
+    get [Symbol.toStringTag](): string;
+    static toDataView(o: Struct): DataView;
+    /**
+     * Create a new Struct
+     * @param arg options for creating the struct.
+     *  If options has a `.buffer` property, we will use that as the backing memory (e.g. any TypedArray or DataView).
+     *  If options has no `.buffer` property but has a `.byteLength`, we will allocate a new buffer for the object.
+     */
+    constructor(arg: {
+        readonly buffer: ArrayBufferLike;
+        readonly byteOffset?: number;
+        readonly byteLength?: number;
+    } | {
+        readonly buffer?: undefined;
+        readonly byteOffset?: number;
+        readonly byteLength: number;
+    });
+}
+/**
+ * Subclass struct by adding the given property descriptors
+ * @param propertyDescriptors properties to add to subclass instances
+ * @returns A new class, inheriting from `Struct`, with the new property descriptors added
+ */
+export declare function defineStruct<const Props extends PropertyDescriptorMap>(propertyDescriptors: Props): SubclassWithProperties<typeof Struct, MixinFromProps<Props>>;
+/**
+ * Create a new struct subclass for an array of structs
+ * @param arrayOptions
+ * @returns A new class, inheriting from `Struct` whose elements are statically typed structs
+ */
+export declare function defineArray<Item extends object>(arrayOptions: {
+    /** Constructor for an object view of each item */
+    readonly struct: StructConstructor<Item>;
+    /** Number of bytes between the start of consecutive items */
+    readonly byteStride: number;
+    /** Total number of items in the array (not bytes). If omitted, the array length will depend on the size of its underlying buffer */
+    readonly length?: number;
+}): StructConstructor<{
+    readonly length: number;
+    element(i: number): Item;
+} & Iterable<Item>>;
+//# sourceMappingURL=core.d.ts.map

package/esm/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,SAAS,EAET,cAAc,EACd,iBAAiB,EACjB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AAEnB,eAAO,MAAM,cAAc,eAAgC,CAAA;AAE3D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAM1D;AACD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,EACjB,KAAK,CAAC,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,GACX,UAAU,CAOZ;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,EAC/D,WAAW,EAAE,EAAE,GACd,wBAAwB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAQ1C;AAED;;;GAGG;AACH,qBAAa,MAAM;IACjB,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAA;IAC1B,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IACD,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ;IAItC;;;;;OAKG;gBAED,GAAG,EACC;QACA,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;QAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAC7B,GACC;QACA,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAC5B;CAyBN;AAsBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,KAAK,SAAS,qBAAqB,EACpE,mBAAmB,EAAE,KAAK,GACzB,sBAAsB,CAAC,OAAO,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAC7C,YAAY,EAAE;IACZ,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAA;IACxC,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,oIAAoI;IACpI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB,GACA,iBAAiB,CAClB;IACE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB,GAAG,QAAQ,CAAC,IAAI,CAAC,CACnB,CA+CA"}

package/esm/core.js

@@ -0,0 +1,166 @@
+/**
+ * Tools for declaring a binary struct as a class with properties
+ * @module
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _a;
+export const dataViewSymbol = Symbol.for("Struct.dataview");
+/**
+ * Get the underlying DataView of a struct
+ * @param struct
+ * @returns
+ */
+export function structDataView(struct) {
+    const result = struct[dataViewSymbol];
+    if (!(result instanceof DataView)) {
+        throw new TypeError("not a struct");
+    }
+    return struct[dataViewSymbol];
+}
+/**
+ * Helper method to create a view of a contiguous subregion of a Struct's memory
+ * @param struct
+ * @param start byte offset to start
+ * @param end byte offset of the end of the subrange
+ * @returns region of the given struct.
+ */
+export function structBytes(struct, start, end) {
+    const dv = structDataView(struct);
+    start ??= 0;
+    end ??= dv.byteLength;
+    console.assert(start <= end);
+    console.assert(end <= dv.byteLength);
+    return new Uint8Array(dv.buffer, dv.byteOffset + start, end - start);
+}
+/**
+ * Define a descriptor based on a dataview of the struct
+ * @param fieldGetter function which, given a dataview, returns
+ * @returns
+ */
+export function fromDataView(fieldGetter) {
+    return {
+        enumerable: true,
+        get() {
+            const dv = this[dataViewSymbol];
+            return fieldGetter(dv);
+        },
+    };
+}
+/**
+ * Base class for a structured binary object
+ * Note there are no predeclared string-keyed properties - all property names are reserved for user-defined fields
+ */
+export class Struct {
+    get [(_a = dataViewSymbol, Symbol.toStringTag)]() {
+        return Struct.name;
+    }
+    static toDataView(o) {
+        return o[dataViewSymbol];
+    }
+    /**
+     * Create a new Struct
+     * @param arg options for creating the struct.
+     *  If options has a `.buffer` property, we will use that as the backing memory (e.g. any TypedArray or DataView).
+     *  If options has no `.buffer` property but has a `.byteLength`, we will allocate a new buffer for the object.
+     */
+    constructor(arg) {
+        Object.defineProperty(this, _a, {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (typeof arg !== "object" || arg === null) {
+            throw new TypeError("Expected argument to be an object");
+        }
+        Object.preventExtensions(this);
+        if (arg.buffer) {
+            this[dataViewSymbol] = new DataView(arg.buffer, arg.byteOffset, arg.byteLength);
+        }
+        else if (typeof arg.byteLength === "number") {
+            this[dataViewSymbol] = new DataView(new ArrayBuffer(arg.byteLength + (arg.byteOffset ?? 0)), arg.byteOffset, arg.byteLength);
+        }
+        else {
+            throw new TypeError("Must provide either {buffer} or {byteLength}");
+        }
+    }
+}
+/**
+ * Subclass a type by adding the given property descriptors
+ * @param ctor constructor for the base class
+ * @param propertyDescriptors properties to add to subclass instances
+ * @returns A new class, inheriting from the base class, with the new property descriptors added
+ */
+function subclassWithProperties(ctor, propertyDescriptors) {
+    var _b;
+    return (_b = class extends ctor {
+        },
+        (() => {
+            Object.defineProperties(_b.prototype, propertyDescriptors);
+        })(),
+        _b);
+}
+/**
+ * Subclass struct by adding the given property descriptors
+ * @param propertyDescriptors properties to add to subclass instances
+ * @returns A new class, inheriting from `Struct`, with the new property descriptors added
+ */
+export function defineStruct(propertyDescriptors) {
+    return subclassWithProperties(Struct, propertyDescriptors);
+}
+/**
+ * Create a new struct subclass for an array of structs
+ * @param arrayOptions
+ * @returns A new class, inheriting from `Struct` whose elements are statically typed structs
+ */
+export function defineArray(arrayOptions) {
+    var _StructArray_struct, _StructArray_length, _StructArray_byteStride;
+    const { struct, byteStride, length } = arrayOptions;
+    class StructArray extends Struct {
+        constructor() {
+            super(...arguments);
+            _StructArray_struct.set(this, struct);
+            _StructArray_length.set(this, length);
+            _StructArray_byteStride.set(this, byteStride
+            /**
+             * Number of items in the array
+             */
+            );
+        }
+        /**
+         * Number of items in the array
+         */
+        get length() {
+            if (typeof __classPrivateFieldGet(this, _StructArray_length, "f") === "number") {
+                return __classPrivateFieldGet(this, _StructArray_length, "f");
+            }
+            return structDataView(this).byteLength / __classPrivateFieldGet(this, _StructArray_byteStride, "f");
+        }
+        /**
+         * A view of the item at the given index
+         * @param index
+         * @returns a new struct instance viewing the item at the given index
+         */
+        item(index) {
+            const ctor = __classPrivateFieldGet(this, _StructArray_struct, "f");
+            return new ctor(structBytes(this, __classPrivateFieldGet(this, _StructArray_byteStride, "f") * index, __classPrivateFieldGet(this, _StructArray_byteStride, "f") * (index + 1)));
+        }
+        /** @deprecated use item() instead */
+        element(index) {
+            return this.item(index);
+        }
+        /**
+         * Iterate over the items in the array
+         */
+        *[(_StructArray_struct = new WeakMap(), _StructArray_length = new WeakMap(), _StructArray_byteStride = new WeakMap(), Symbol.iterator)]() {
+            for (let i = 0; i < this.length; ++i) {
+                yield this.item(i);
+            }
+        }
+    }
+    return StructArray;
+}

package/esm/fields.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Factories for property descriptors representing fields in a binary struct
+ * @module
+ */
+import type { StructConstructor, StructPropertyDescriptor, TypedArraySpecies } from "./types.js";
+/**
+ * Field for a 8-bit unsigned integer
+ */
+export declare function u8(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a little-endian 16-bit unsigned integer
+ */
+export declare function u16(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a little-endian 32-bit unsigned integer
+ */
+export declare function u32(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a little-endian 64-bit unsigned integer
+ */
+export declare function u64(fieldOffset: number): StructPropertyDescriptor<bigint>;
+/**
+ * Field for a little-endian 8-bit signed integer
+ */
+export declare function i8(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a little-endian 16-bit signed integer
+ */
+export declare function i16(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a little-endian 32-bit signed integer
+ */
+export declare function i32(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a little-endian 64-bit signed integer
+ */
+export declare function i64(fieldOffset: number): StructPropertyDescriptor<bigint>;
+/**
+ * Field for a little-endian unsigned integer of arbitrary byte length
+ */
+export declare function biguintle(fieldOffset: number, { byteLength }: {
+    byteLength: number;
+}): StructPropertyDescriptor<bigint>;
+/**
+ * Field for a little-endian signed integer of arbitrary byte length
+ */
+export declare function bigintle(offset: number, options: {
+    byteLength: number;
+}): StructPropertyDescriptor<bigint>;
+/**
+ * Field for a little-endian 16-bit binary float (float16_t)
+ */
+export declare function f16(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a little-endian 32-bit binary float (float32_t)
+ */
+export declare function f32(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a little-endian 64-bit binary float (float64_t)
+ */
+export declare function f64(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a UTF-8 fixed-length string
+ */
+export declare function string(fieldOffset: number, byteLength: number): StructPropertyDescriptor<string>;
+/**
+ * Field for a boolean stored in a byte (0 = false, nonzero = true)
+ * True will be stored as 1
+ */
+export declare function bool(fieldOffset: number): StructPropertyDescriptor<boolean>;
+/**
+ * Field for an embedded struct
+ * @param ctor constructor for the inner struct
+ * @param byteOffset where the inner struct starts relative to the outer struct
+ * @param bytelength the length in bytes of the inner struct
+ * @returns property descriptor for a struct
+ */
+export declare function substruct<T extends object>(ctor: StructConstructor<T>, byteOffset?: number, bytelength?: number): StructPropertyDescriptor<T>;
+/**
+ * Field for a typed array
+ *
+ * @remarks
+ *
+ * I'm not totally happy with this.
+ * - TypedArray does not support endianness.
+ * - Changing the length property of the parent struct will not change the length of the returned value. `a=x.ar; x.arlength=2;` will not change a's length (though a will still be a live view of the underlying buffer).
+ *
+ * @param fieldOffset  where the array starts relative to the parent struct
+ */
+export declare function typedArray<T>(fieldOffset: number, kwargs: {
+    /** length or property name for the length of the array */
+    readonly length: number | string | undefined;
+    /** TypedArray constructor */
+    readonly species: TypedArraySpecies<T>;
+}): StructPropertyDescriptor<T>;
+/**
+ * Field for a big-endian 16-bit unsigned integer
+ */
+export declare function u16be(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a big-endian 32-bit unsigned integer
+ */
+export declare function u32be(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a big-endian 64-bit unsigned integer
+ */
+export declare function u64be(fieldOffset: number): StructPropertyDescriptor<bigint>;
+/**
+ * Field for a big-endian 16-bit signed integer
+ */
+export declare function i16be(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a big-endian 32-bit signed integer
+ */
+export declare function i32be(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a big-endian 64-bit signed integer
+ */
+export declare function i64be(fieldOffset: number): StructPropertyDescriptor<bigint>;
+/**
+ * Field for a big-endian 16-bit binary float (float16_t)
+ */
+export declare function f16be(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a big-endian 32-bit binary float (float32_t)
+ */
+export declare function f32be(fieldOffset: number): StructPropertyDescriptor<number>;
+/**
+ * Field for a big-endian 64-bit binary float (float64_t)
+ */
+export declare function f64be(fieldOffset: number): StructPropertyDescriptor<number>;
+//# sourceMappingURL=fields.d.ts.map

package/esm/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"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"}