@rotu/structview 0.10.1 → 0.10.3

package/README.md

@@ -85,3 +85,21 @@ for (const dish of myMenu) {
   console.log(`${dish.name} costs \$${dish.price}`)
 }
 ```
+
+# Gotchas and rough edges
+
+1. Resizable structs are not yet implemented. Resizable `Arraybuffer`s only
+   allow you to add or remove bytes at the end which is not the best experience.
+   You can still create a `Struct` on top of a resizable `ArrayBuffer` at your
+   own risk.
+2. Struct fields have a byte offset specified in bytes from the beginning of the
+   declaring struct. This is a bit verbose but is a deliberate choice.
+   - It prevents changes to the struct from accidentally changing other fields
+   - It implicitly allows C-style `union`s for free.
+   - Different languages and compilers have different expectations for alignment
+     and spacing of fields.
+3. Be careful using `TypedArray`s. They have an alignment requirement relative
+   to their underlying `ArrayBuffer`.
+4. `Struct` classes define properties on the prototype, _not_ on the instance.
+   That means spread syntax (`x = {...s}`) and `JSON.stringify(s)` will _not_
+   reflect inherited fields.

package/esm/bigendian.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Property descriptor factories for big-endian numbers
+ * @module
+ */
+/** @deprecated Import from `fields.ts` instead */
+export { f16be, f32be, f64be, i16be, i32be, i64be, u16be, u32be, u64be, } from "./fields.js";
+//# sourceMappingURL=bigendian.d.ts.map

package/esm/bigendian.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigendian.d.ts","sourceRoot":"","sources":["../src/bigendian.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kDAAkD;AAClD,OAAO,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,GACN,MAAM,aAAa,CAAA"}

package/esm/bigendian.js

@@ -0,0 +1,6 @@
+/**
+ * Property descriptor factories for big-endian numbers
+ * @module
+ */
+/** @deprecated Import from `fields.ts` instead */
+export { f16be, f32be, f64be, i16be, i32be, i64be, u16be, u32be, u64be, } from "./fields.js";

package/esm/core.d.ts

@@ -31,6 +31,9 @@ export declare class 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.
+     * @remarks
+     * The reason we don't use a positional argument for `byteLength` is because it's confusing - TypedArray constructors take a `length` argument that is in elements, not bytes.
+     * Another reason is because this allows you to pass in a `DataView` or a `TypedArray` directly to reinterpret its memory as a struct.
      */
     constructor(arg: {
         readonly buffer: ArrayBufferLike;

package/esm/core.d.ts.map

@@ -1 +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,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;;;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"}
+{"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,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;;;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;;;;;;;;OAQG;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,CAqDA"}

package/esm/core.js

@@ -52,6 +52,9 @@ export class 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.
+     * @remarks
+     * The reason we don't use a positional argument for `byteLength` is because it's confusing - TypedArray constructors take a `length` argument that is in elements, not bytes.
+     * Another reason is because this allows you to pass in a `DataView` or a `TypedArray` directly to reinterpret its memory as a struct.
      */
     constructor(arg) {
         Object.defineProperty(this, _a, {
@@ -106,6 +109,9 @@ export function defineStruct(propertyDescriptors) {
 export function defineArray(arrayOptions) {
     var _StructArray_struct, _StructArray_length, _StructArray_byteStride;
     const { struct, byteStride, length } = arrayOptions;
+    /**
+     * Class representing an array of structs.
+     */
     class StructArray extends Struct {
         constructor() {
             super(...arguments);
@@ -130,6 +136,8 @@ export function defineArray(arrayOptions) {
          * A view of the item at the given index
          * @param index
          * @returns a new struct instance viewing the item at the given index
+         * @remarks
+         * Items are gettable but not settable. It is assumed that you will mutate the struct in place.
          */
         item(index) {
             const ctor = __classPrivateFieldGet(this, _StructArray_struct, "f");

package/esm/mod.d.ts

@@ -5,4 +5,5 @@
 export type * from "./types.js";
 export * from "./core.js";
 export * from "./fields.js";
+export * as bigendian from "./bigendian.js";
 //# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mBAAmB,YAAY,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mBAAmB,YAAY,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAE3B,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA"}

package/esm/mod.js

@@ -4,3 +4,4 @@
  */
 export * from "./core.js";
 export * from "./fields.js";
+export * as bigendian from "./bigendian.js";

package/esm/types.d.ts

@@ -24,6 +24,9 @@ export type TPropertyDescriptor<T> = {
     value?: T;
     writable?: boolean;
 };
+/**
+ * Object type that would result from Object.defineProperties(p:Props)
+ */
 export type MixinFromProps<Props extends object> = {
     -readonly [K in keyof Props]: Props[K] extends TPropertyDescriptor<infer V> ? V : unknown;
 };
@@ -38,6 +41,9 @@ export type StructConstructor<T extends object> = {
         readonly byteLength: number;
     }): T;
 };
+/**
+ * Type of a TypedArray subclass constructor
+ */
 export type TypedArraySpecies<T> = {
     new (buffer: ArrayBufferLike, byteOffset?: number, length?: number): T;
     readonly BYTES_PER_ELEMENT: number;

package/esm/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE/C,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;CAAE,CAAA;AAExD,MAAM,MAAM,sBAAsB,CAChC,IAAI,SAAS,WAAW,CAAC,MAAM,CAAC,EAChC,KAAK,IAEH;KAAG,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;CAAE,GAC9B;IACA,KACE,GAAG,IAAI,EAAE,qBAAqB,CAAC,IAAI,CAAC,GACnC,YAAY,CAAC,IAAI,CAAC,GAAG;SAAG,CAAC,IAAI,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;KAAE,CAAA;CACzD,CAAA;AAEH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IACnC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,GAAG,CAAC,IAAI,CAAC,CAAA;IACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAA;IACrB,KAAK,CAAC,EAAE,CAAC,CAAA;IACT,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,MAAM,IAAI;IACjD,CAAC,UAAU,CAAC,IAAI,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,mBAAmB,CAAC,MAAM,CAAC,CAAC,GACvE,CAAC,GACD,OAAO;CACZ,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAClC,QAAQ,CAAC,SAAS,CAAC,GACnB,mBAAmB,CAAC,CAAC,CAAC,CAAA;AAE1B,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI;IAChD,KAAK,GAAG,EAAE;QACR,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;QAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;QAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAC5B,GAAG,CAAC,CAAA;CACN,CAAA;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IACjC,KACE,MAAM,EAAE,eAAe,EACvB,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,CAAC,CAAA;IACJ,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CACnC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE/C,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;CAAE,CAAA;AAExD,MAAM,MAAM,sBAAsB,CAChC,IAAI,SAAS,WAAW,CAAC,MAAM,CAAC,EAChC,KAAK,IAEH;KAAG,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;CAAE,GAC9B;IACA,KACE,GAAG,IAAI,EAAE,qBAAqB,CAAC,IAAI,CAAC,GACnC,YAAY,CAAC,IAAI,CAAC,GAAG;SAAG,CAAC,IAAI,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;KAAE,CAAA;CACzD,CAAA;AAEH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IACnC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,GAAG,CAAC,IAAI,CAAC,CAAA;IACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAA;IACrB,KAAK,CAAC,EAAE,CAAC,CAAA;IACT,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,MAAM,IAAI;IACjD,CAAC,UAAU,CAAC,IAAI,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,mBAAmB,CAAC,MAAM,CAAC,CAAC,GACvE,CAAC,GACD,OAAO;CACZ,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAClC,QAAQ,CAAC,SAAS,CAAC,GACnB,mBAAmB,CAAC,CAAC,CAAC,CAAA;AAC1B,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI;IAChD,KAAK,GAAG,EAAE;QACR,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;QAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;QAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAC5B,GAAG,CAAC,CAAA;CACN,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IACjC,KACE,MAAM,EAAE,eAAe,EACvB,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,CAAC,CAAA;IACJ,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CACnC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rotu/structview",
-  "version": "0.10.1+dnt",
+  "version": "0.10.3+dnt",
   "description": "Read and write structured binary data with typesafe views",
   "repository": {
     "type": "git",
@@ -11,6 +11,9 @@
   "exports": {
     ".": {
       "import": "./esm/mod.js"
+    },
+    "./bigendian": {
+      "import": "./esm/bigendian.js"
     }
   },
   "scripts": {