@rotu/structview 0.6.1

package/deno.lock

@@ -0,0 +1,23 @@
+{
+  "version": "5",
+  "specifiers": {
+    "jsr:@std/assert@1": "1.0.15",
+    "jsr:@std/internal@^1.0.12": "1.0.12"
+  },
+  "jsr": {
+    "@std/assert@1.0.15": {
+      "integrity": "d64018e951dbdfab9777335ecdb000c0b4e3df036984083be219ce5941e4703b",
+      "dependencies": [
+        "jsr:@std/internal"
+      ]
+    },
+    "@std/internal@1.0.12": {
+      "integrity": "972a634fd5bc34b242024402972cd5143eac68d8dffaca5eaa4dba30ce17b027"
+    }
+  },
+  "workspace": {
+    "dependencies": [
+      "jsr:@std/assert@1"
+    ]
+  }
+}

package/mod.js

@@ -0,0 +1,336 @@
+/**
+ * Strongly typed classes for accessing binary data in a structured way
+ * @module
+ */ var _computedKey;
+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.
+ */ 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);
+    }
+  };
+}
+/**
+ * Field for a 8-bit unsigned integer
+ */ export function u8(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getUint8(fieldOffset);
+    },
+    set (value) {
+      structDataView(this).setUint8(fieldOffset, value);
+    }
+  };
+}
+/**
+ * Field for a little-endian 16-bit unsigned integer
+ */ export function u16(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getUint16(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setUint16(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a little-endian 32-bit unsigned integer
+ */ export function u32(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getUint32(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setUint32(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a little-endian 64-bit unsigned integer
+ */ export function u64(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getBigUint64(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setBigUint64(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a little-endian 8-bit signed integer
+ */ export function i8(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getInt8(fieldOffset);
+    },
+    set (value) {
+      structDataView(this).setInt8(fieldOffset, value);
+    }
+  };
+}
+/**
+ * Field for a little-endian 16-bit signed integer
+ */ export function i16(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getInt16(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setInt16(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a little-endian 32-bit signed integer
+ */ export function i32(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getInt32(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setInt32(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a little-endian 64-bit signed integer
+ */ export function i64(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getBigInt64(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setBigInt64(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a little-endian 16-bit binary float (float16_t)
+ */ export function f16(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getFloat16(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setFloat16(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a little-endian 32-bit binary float (float32_t)
+ */ export function f32(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getFloat32(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setFloat32(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a little-endian 64-bit binary float (float64_t)
+ */ export function f64(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return structDataView(this).getFloat64(fieldOffset, true);
+    },
+    set (value) {
+      structDataView(this).setFloat64(fieldOffset, value, true);
+    }
+  };
+}
+/**
+ * Field for a UTF-8 fixed-length string
+ */ export function string(fieldOffset, byteLength) {
+  const TEXT_DECODER = new TextDecoder();
+  const TEXT_ENCODER = new TextEncoder();
+  return {
+    enumerable: true,
+    get () {
+      const str = TEXT_DECODER.decode(structBytes(this, fieldOffset, fieldOffset + byteLength));
+      // trim all trailing null characters
+      return str.replace(/\0+$/, "");
+    },
+    set (value) {
+      const bytes = structBytes(this, fieldOffset, fieldOffset + byteLength);
+      bytes.fill(0);
+      TEXT_ENCODER.encodeInto(value, bytes);
+    }
+  };
+}
+/**
+ * Field for a boolean stored in a byte (0 = false, nonzero = true)
+ * True will be stored as 1
+ */ export function bool(fieldOffset) {
+  return {
+    enumerable: true,
+    get () {
+      return Boolean(structDataView(this).getUint8(fieldOffset));
+    },
+    set (value) {
+      structDataView(this).setUint8(fieldOffset, value ? 1 : 0);
+    }
+  };
+}
+/**
+ * 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 function substruct(ctor, byteOffset, bytelength) {
+  return fromDataView(function(dv) {
+    const offset2 = dv.byteOffset + (byteOffset ?? 0);
+    const bytelength2 = bytelength ?? dv.byteLength - (byteOffset ?? 0);
+    return Reflect.construct(ctor, [
+      {
+        buffer: dv.buffer,
+        byteOffset: offset2,
+        byteLength: bytelength2
+      }
+    ]);
+  });
+}
+_computedKey = Symbol.toStringTag;
+/**
+ * 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 {
+  [dataViewSymbol];
+  get [_computedKey]() {
+    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){
+    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) {
+  return class extends ctor {
+    static{
+      Object.defineProperties(this.prototype, propertyDescriptors);
+    }
+  };
+}
+/**
+ * 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 _computedKey;
+  const { struct, byteStride, length } = arrayOptions;
+  // Define a subclass of Struct which translates array-like index access into element access
+  // x[2] -> x.element(2)
+  const ProxiedStruct = function(...args) {
+    return Reflect.construct(Struct, args, new.target);
+  };
+  ProxiedStruct.prototype = new Proxy(Struct.prototype, {
+    get (target, p, receiver) {
+      if (typeof p === "string") {
+        const i = parseInt(p);
+        if (p === String(i)) {
+          return receiver.element(i);
+        }
+      }
+      return Reflect.get(target, p, receiver);
+    }
+  });
+  _computedKey = Symbol.iterator;
+  class StructArray extends ProxiedStruct {
+    #struct = struct;
+    #length = length;
+    #byteStride = byteStride;
+    get length() {
+      if (typeof this.#length === "number") {
+        return this.#length;
+      }
+      return structDataView(this).byteLength / this.#byteStride;
+    }
+    element(i) {
+      const ctor = this.#struct;
+      return new ctor(structBytes(this, this.#byteStride * i, this.#byteStride * (i + 1)));
+    }
+    *[_computedKey]() {
+      for(let i = 0; i < this.length; ++i){
+        yield this.element(i);
+      }
+    }
+  }
+  // deno-lint-ignore no-explicit-any
+  return StructArray;
+}
+//# sourceMappingURL=mod.js.map

package/mod.js.map

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