@yume-chan/struct 0.0.10 → 0.0.14

package/CHANGELOG.json

@@ -1,6 +1,54 @@
 {
   "name": "@yume-chan/struct",
   "entries": [
+    {
+      "version": "0.0.14",
+      "tag": "@yume-chan/struct_v0.0.14",
+      "date": "Sat, 30 Apr 2022 14:05:48 GMT",
+      "comments": {}
+    },
+    {
+      "version": "0.0.13",
+      "tag": "@yume-chan/struct_v0.0.13",
+      "date": "Thu, 28 Apr 2022 01:23:53 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Fix an issue that `uint64` still deserialize to negative numbers"
+          },
+          {
+            "comment": "Fix an issue where `Syncbird` can't synchronously invoke `then` on some Bluebird internal methods (for example `reduce`)"
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.0.12",
+      "tag": "@yume-chan/struct_v0.0.12",
+      "date": "Sun, 03 Apr 2022 11:18:47 GMT",
+      "comments": {}
+    },
+    {
+      "version": "0.0.11",
+      "tag": "@yume-chan/struct_v0.0.11",
+      "date": "Sun, 03 Apr 2022 11:18:11 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Update to use Web Streams API"
+          },
+          {
+            "comment": "Improve compatibility with Node.js 12 ESM format"
+          },
+          {
+            "comment": "Update compatibility matrix"
+          },
+          {
+            "comment": "Update license year"
+          }
+        ]
+      }
+    },
     {
       "version": "0.0.10",
       "tag": "@yume-chan/struct_v0.0.10",

package/CHANGELOG.md

@@ -1,6 +1,34 @@
 # Change Log - @yume-chan/struct
 
-This log was last generated on Sun, 09 Jan 2022 15:52:20 GMT and should not be manually modified.
+This log was last generated on Sat, 30 Apr 2022 14:05:48 GMT and should not be manually modified.
+
+## 0.0.14
+Sat, 30 Apr 2022 14:05:48 GMT
+
+_Version update only_
+
+## 0.0.13
+Thu, 28 Apr 2022 01:23:53 GMT
+
+### Updates
+
+- Fix an issue that `uint64` still deserialize to negative numbers
+- Fix an issue where `Syncbird` can't synchronously invoke `then` on some Bluebird internal methods (for example `reduce`)
+
+## 0.0.12
+Sun, 03 Apr 2022 11:18:47 GMT
+
+_Version update only_
+
+## 0.0.11
+Sun, 03 Apr 2022 11:18:11 GMT
+
+### Updates
+
+- Update to use Web Streams API
+- Improve compatibility with Node.js 12 ESM format
+- Update compatibility matrix
+- Update license year
 
 ## 0.0.10
 Sun, 09 Jan 2022 15:52:20 GMT

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Simon Chan
+Copyright (c) 2020-2022 Simon Chan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,10 @@
 # @yume-chan/struct
 
+<!--
+cspell: ignore Codecov
+cspell: ignore uint8arraystring
+-->
+
 ![license](https://img.shields.io/npm/l/@yume-chan/struct)
 ![npm type definitions](https://img.shields.io/npm/types/@yume-chan/struct)
 [![npm version](https://img.shields.io/npm/v/@yume-chan/struct)](https://www.npmjs.com/package/@yume-chan/struct)
@@ -37,20 +42,25 @@ value.baz // string
 const buffer = MyStruct.serialize({
     foo: 42,
     bar: 42n,
-    // `bazLength` automatically set to `baz.length`
+    // `bazLength` automatically set to `baz`'s byte length
     baz: 'Hello, World!',
 });
 ```
 
+<!-- cspell: disable -->
+
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Compatibility](#compatibility)
+  - [Basic usage](#basic-usage)
+  - [`int64`/`uint64`](#int64uint64)
+  - [`string`](#string)
 - [API](#api)
   - [`placeholder`](#placeholder)
   - [`Struct`](#struct)
     - [`int8`/`uint8`/`int16`/`uint16`/`int32`/`uint32`](#int8uint8int16uint16int32uint32)
-    - [`int64`/`uint64`](#int64uint64)
-    - [`arraybuffer`/`uint8ClampedArray`/`string`](#arraybufferuint8clampedarraystring)
+    - [`int64`/`uint64`](#int64uint64-1)
+    - [`uint8Array`/`string`](#uint8arraystring)
     - [`fields`](#fields)
     - [`extra`](#extra)
     - [`postDeserialize`](#postdeserialize)
@@ -58,6 +68,7 @@ const buffer = MyStruct.serialize({
     - [`serialize`](#serialize)
 - [Custom field type](#custom-field-type)
   - [`Struct#field`](#structfield)
+  - [Relationship between types](#relationship-between-types)
   - [`StructFieldDefinition`](#structfielddefinition)
     - [`TValue`/`TOmitInitKey`](#tvaluetomitinitkey)
     - [`getSize`](#getsize)
@@ -68,31 +79,47 @@ const buffer = MyStruct.serialize({
     - [`get`/`set`](#getset)
     - [`serialize`](#serialize-1)
 
+<!-- cspell: enable -->
+
 ## Compatibility
 
-|                                                      | Chrome | Edge | Firefox | Internet Explorer | Safari         | Node.js |
-| ---------------------------------------------------- | ------ | ---- | ------- | ----------------- | -------------- | ------- |
-| [`Promise`][MDN_Promise]                             | 32     | 12   | 29      | No<sup>1</sup>    | 8              | 0.12    |
-| [`ArrayBuffer`][MDN_ArrayBuffer]                     | 7      | 12   | 4       | 10                | 5.1            | 0.10    |
-| [`Uint8Array`][MDN_Uint8Array]                       | 7      | 12   | 4       | 10                | 5.1            | 0.10    |
-| [`DataView`][MDN_DataView]                           | 9      | 12   | 15      | 10                | 5.1            | 0.10    |
-| **Basic usage**                                      | 32     | 12   | 29      | 10<sup>1</sup>    | 8              | 0.12    |
-| [`BigInt`][MDN_BigInt]                               | 67     | 79   | 68      | No                | 14             | 10.4    |
-| [`DataView#getBigUint64`][MDN_DataView_getBigUint64] | 67     | 79   | 68      | No                | No<sup>2</sup> | 10.4    |
-| [`DataView#setBigUint64`][MDN_DataView_setBigUint64] | 67     | 79   | 68      | No                | No<sup>2</sup> | 10.4    |
-| **Use [`int64/uint64`](#int64uint64) API**           | 67     | 79   | 68      | No                | 14<sup>2</sup> | 10.4    |
+Here is a list of features, their used APIs, and their compatibilities. If an optional feature is not actually used, its requirements can be ignored.
+
+Some features can be polyfilled to support older runtimes, but this library doesn't ship with any polyfills.
+
+### Basic usage
+
+| API                              | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
+| -------------------------------- | ------ | ---- | ------- | ----------------- | ------ | ------- |
+| [`Promise`][MDN_Promise]         | 32     | 12   | 29      | No                | 8      | 0.12    |
+| [`ArrayBuffer`][MDN_ArrayBuffer] | 7      | 12   | 4       | 10                | 5.1    | 0.10    |
+| [`Uint8Array`][MDN_Uint8Array]   | 7      | 12   | 4       | 10                | 5.1    | 0.10    |
+| [`DataView`][MDN_DataView]       | 9      | 12   | 15      | 10                | 5.1    | 0.10    |
+| *Overall*                        | 32     | 12   | 29      | No                | 8      | 0.12    |
+
+### [`int64`/`uint64`](#int64uint64-1)
 
-<sup>1</sup> Requires a polyfill for Promise (e.g. [promise-polyfill](https://www.npmjs.com/package/promise-polyfill))
+| API                                | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
+| ---------------------------------- | ------ | ---- | ------- | ----------------- | ------ | ------- |
+| [`BigInt`][MDN_BigInt]<sup>1</sup> | 67     | 79   | 68      | No                | 14     | 10.4    |
 
-<sup>2</sup> Requires a polyfill for `DataView#getBigUint64` and `DataView#setBigUint64`
+<sup>1</sup> Can't be polyfilled
+
+### [`string`](#uint8arraystring)
+
+| API                              | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js             |
+| -------------------------------- | ------ | ---- | ------- | ----------------- | ------ | ------------------- |
+| [`TextEncoder`][MDN_TextEncoder] | 38     | 79   | 19      | No                | 10.1   | 8.3<sup>1</sup>, 11 |
+
+<sup>1</sup> `TextEncoder` and `TextDecoder` are only available in `util` module. Need to be assigned to `globalThis`.
 
 [MDN_Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
 [MDN_ArrayBuffer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
 [MDN_Uint8Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
 [MDN_DataView]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
 [MDN_BigInt]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
-[MDN_DataView_getBigUint64]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigUint64
-[MDN_DataView_setBigUint64]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigUint64
+[MDN_DataView]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
+[MDN_TextEncoder]: https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder
 
 ## API
 
@@ -148,7 +175,7 @@ class Struct<
 }
 ```
 
-Creates a new structure declaration.
+Creates a new structure definition.
 
 <details>
 <summary>Generic parameters (click to expand)</summary>
@@ -156,7 +183,7 @@ Creates a new structure declaration.
 This information was added to help you understand how does it work. These are considered as "internal state" so don't specify them manually.
 
 1. `TFields`: Type of the Struct value. Modified when new fields are added.
-2. `TOmitInitKey`: When serializing a structure containing variable length arrays, the length field can be calculate from the array field, so they doesn't need to be provided explicitly.
+2. `TOmitInitKey`: When serializing a structure containing variable length buffers, the length field can be calculate from the buffer field, so they doesn't need to be provided explicitly.
 3. `TExtra`: Type of extra fields. Modified when `extra` is called.
 4. `TPostDeserialized`: State of the `postDeserialize` function. Modified when `postDeserialize` is called. Affects return type of `deserialize`
 </details>
@@ -196,7 +223,7 @@ Appends an `int8`/`uint8`/`int16`/`uint16`/`int32`/`uint32` field to the `Struct
 
 **Parameters**
 
-1. `name`: (Required) Field name. Must have a [literal type](https://www.typescriptlang.org/docs/handbook/literal-types.html).
+1. `name`: (Required) Field name. Must be a string literal.
 2. `_typescriptType`: Set field's type. See examples below.
 
 **Note**
@@ -259,19 +286,19 @@ int64<
 >;
 ```
 
-Appends an `int64`/`uint64` field to the `Struct`.
+Appends an `int64`/`uint64` field to the `Struct`. The usage is same as `uint32`/`uint32`.
 
 Requires native support for `BigInt`. Check [compatibility table](#compatibility) for more information.
 
-#### `arraybuffer`/`uint8ClampedArray`/`string`
+#### `uint8Array`/`string`
 
 ```ts
-arraybuffer<
+uint8Array<
     TName extends string | number | symbol,
     TTypeScriptType = ArrayBuffer
 >(
     name: TName,
-    options: FixedLengthArrayBufferLikeFieldOptions,
+    options: FixedLengthBufferLikeFieldOptions,
     _typescriptType?: TTypeScriptType,
 ): Struct<
     TFields & Record<TName, TTypeScriptType>,
@@ -280,9 +307,10 @@ arraybuffer<
     TPostDeserialized
 >;
 
-arraybuffer<
+uint8Array<
     TName extends string | number | symbol,
-    TOptions extends VariableLengthArrayBufferLikeFieldOptions<TFields>,
+    TLengthField extends LengthField<TFields>,
+    TOptions extends VariableLengthBufferLikeFieldOptions<TFields, TLengthField>,
     TTypeScriptType = ArrayBuffer,
 >(
     name: TName,
@@ -290,20 +318,18 @@ arraybuffer<
     _typescriptType?: TTypeScriptType,
 ): Struct<
     TFields & Record<TName, TTypeScriptType>,
-    TOmitInitKey | TOptions['lengthField'],
+    TOmitInitKey | TLengthField,
     TExtra,
     TPostDeserialized
 >;
 ```
 
-Appends an `ArrayBuffer`/`Uint8ClampedArray`/`string` field to the `Struct`.
+Appends an `uint8Array`/`string` field to the `Struct`.
 
 The `options` parameter defines its length, it can be in two formats:
 
 * `{ length: number }`: Presence of the `length` option indicates that it's a fixed length array.
-* `{ lengthField: string }`: Presence of the `lengthField` option indicates it's a variable length array. The `lengthField` options must refers to a `number` or `string` typed field that's already defined in this `Struct`. When deserializing, it will use that field's value as its length. And when serializing, it will write its length to that field.
-
-All these three are actually deserialized to `ArrayBuffer`, then converted to `Uint8ClampedArray` or `string` for ease of use.
+* `{ lengthField: string; lengthFieldRadix?: number }`: Presence of the `lengthField` option indicates it's a variable length array. The `lengthField` options must refers to a `number` or `string` (can't be `bigint`) typed field that's already defined in this `Struct`. If the length field is a `string`, the optional `lengthFieldRadix` option (defaults to `10`) defines the radix when converting the string to a number. When deserializing, it will use that field's value as its length. When serializing, it will write its length to that field.
 
 #### `fields`
 
@@ -443,7 +469,7 @@ Multiple calls merge all extra fields together.
 postDeserialize(): Struct<TFields, TOmitInitKey, TExtra, undefined>;
 ```
 
-Remove any registered post deserialization callback.
+Remove any registered post-deserialization callback.
 
 ```ts
 postDeserialize(
@@ -526,10 +552,20 @@ interface StructDeserializeStream {
     /**
      * Read data from the underlying data source.
      *
-     * Stream must return exactly `length` bytes or data. If that's not possible
+     * The stream must return exactly `length` bytes or data. If that's not possible
      * (due to end of file or other error condition), it must throw an error.
      */
-    read(length: number): ArrayBuffer;
+    read(length: number): Uint8Array;
+}
+
+interface StructAsyncDeserializeStream {
+    /**
+     * Read data from the underlying data source.
+     *
+     * The stream must return exactly `length` bytes or data. If that's not possible
+     * (due to end of file or other error condition), it must throw an error.
+     */
+    read(length: number): Promise<Uint8Array>;
 }
 
 deserialize(
@@ -548,7 +584,9 @@ deserialize(
 >;
 ```
 
-Deserialize a Struct value from `stream`.
+Deserialize a struct value from `stream`.
+
+It will be synchronous (returns a value) or asynchronous (returns a `Promise`) depending on the type of `stream`.
 
 As the signature shows, if the `postDeserialize` callback returns any value, `deserialize` will return that value instead.
 
@@ -557,16 +595,17 @@ The `read` method of `stream`, when being called, should returns exactly `length
 #### `serialize`
 
 ```ts
-serialize(
-    init: Omit<TFields, TOmitInitKey>
-): ArrayBuffer;
+serialize(init: Evaluate<Omit<TFields, TOmitInitKey>>): Uint8Array;
+serialize(init: Evaluate<Omit<TFields, TOmitInitKey>>, output: Uint8Array): number;
 ```
 
-Serialize a Struct value into an `ArrayBuffer`.
+Serialize a struct value into an `Uint8Array`.
+
+If an `output` is given, it will serialize the struct into it, and returns the number of bytes written.
 
 ## Custom field type
 
-This library supports adding fields of user defined types.
+It's also possible to create your own field types.
 
 ### `Struct#field`
 
@@ -587,7 +626,7 @@ field<
 
 Appends a `StructFieldDefinition` to the `Struct`.
 
-Actually, all built-in field type methods are aliases of `field`. For example, calling
+All built-in field type methods are actually aliases to it. For example, calling
 
 ```ts
 struct.int8('foo')
@@ -604,6 +643,15 @@ struct.field(
 )
 ```
 
+### Relationship between types
+
+A `Struct` is a map between keys and `StructFieldDefinition`s.
+
+A `StructValue` is a map between keys and `StructFieldValue`s.
+
+A `Struct` can create (deserialize) multiple `StructValue`s with same field definitions.
+
+Each time a `Struct` deserialize, each `StructFieldDefinition` in it creates exactly one `StructFieldValue` to be put into the `StructValue`.
 
 ### `StructFieldDefinition`
 
@@ -619,13 +667,13 @@ abstract class StructFieldDefinition<
 }
 ```
 
-A `StructFieldDefinition` describes type, size and runtime semantics of a field.
+A field definition defines how to deserialize a field.
 
-It's an `abstract` class, means it lacks some method implementations, so it shouldn't be constructed.
+It's an `abstract` class, means it can't be constructed (`new`ed) directly. It's only used as a base class for other field types.
 
 #### `TValue`/`TOmitInitKey`
 
-These two fields are used to provide type information to TypeScript. Their values will always be `undefined`, but having correct types is enough. You don't need to care about them.
+These two fields provide type information to TypeScript compiler. Their values will always be `undefined`, but having correct types is enough. You don't need to touch them.
 
 #### `getSize`
 
@@ -666,14 +714,17 @@ abstract deserialize(
 ): Promise<StructFieldValue<this>>;
 ```
 
-Derived classes must implement this method to define how to deserialize a value from `stream`. Can also return a `Promise`.
+Derived classes must implement this method to define how to deserialize a value from `stream`.
+
+It must be synchronous (returns a value) or asynchronous (returns a `Promise`) depending on the type of `stream`.
 
 Usually implementations should be:
 
-1. Somehow parse the value from `stream`
-2. Pass the value into its `create` method
+1. Read required bytes from `stream`
+2. Parse it to your type
+3. Pass the value into your own `create` method
 
-Sometimes, some metadata is present when deserializing, but need to be calculated when serializing, for example a UTF-8 encoded string may have different length between itself (character count) and serialized form (byte length). So `deserialize` can save those metadata on the `StructFieldValue` instance for later use.
+Sometimes, extra metadata is present when deserializing, but need to be calculated when serializing, for example a UTF-8 encoded string may have different length between itself (character count) and serialized form (byte length). So `deserialize` can save those metadata on the `StructFieldValue` instance for later use.
 
 ### `StructFieldValue`
 
@@ -683,9 +734,7 @@ abstract class StructFieldValue<
 >
 ```
 
-To define a custom type, one must create their own `StructFieldValue` type to define the runtime semantics.
-
-Each `StructFieldValue` is linked to a `StructFieldDefinition`.
+A field value defines how to serialize a field.
 
 #### `getSize`
 
@@ -704,7 +753,7 @@ get(): TDefinition['TValue'];
 set(value: TDefinition['TValue']): void;
 ```
 
-Defines how to get or set this field's value. By default, it store its value in `value` field.
+Defines how to get or set this field's value. By default, it reads/writes its `value` field.
 
 If one needs to manipulate other states when getting/setting values, they can override these methods.
 

package/{dts → esm}/basic/definition.d.ts

@@ -1,16 +1,9 @@
-import type { StructAsyncDeserializeStream, StructDeserializeStream, StructOptions } from './context';
-import type { StructFieldValue } from './field-value';
-import type { StructValue } from './struct-value';
+import type { StructAsyncDeserializeStream, StructDeserializeStream } from "./stream.js";
+import type { StructFieldValue } from "./field-value.js";
+import type { StructValue } from "./struct-value.js";
+import type { StructOptions } from "./options.js";
 /**
- * A field definition is a bridge between its type and its runtime value.
- *
- * `Struct` record fields in a list of `StructFieldDefinition`s.
- *
- * When `Struct#create` or `Struct#deserialize` are called, each field's definition
- * crates its own type of `StructFieldValue` to manage the field value in that `Struct` instance.
- *
- * One `StructFieldDefinition` can represents multiple similar types, just returns the corresponding
- * `StructFieldValue` when `createValue` was called.
+ * A field definition defines how to deserialize a field.
  *
  * @template TOptions TypeScript type of this definition's `options`.
  * @template TValue TypeScript type of this field.
@@ -40,7 +33,10 @@ export declare abstract class StructFieldDefinition<TOptions = void, TValue = un
      */
     abstract create(options: Readonly<StructOptions>, struct: StructValue, value: TValue): StructFieldValue<this>;
     /**
-     * When implemented in derived classes, creates a `StructFieldValue` by parsing `context`.
+     * When implemented in derived classes,It must be synchronous (returns a value) or asynchronous (returns a `Promise`) depending
+     * on the type of `stream`. reads and creates a `StructFieldValue` from `stream`.
+     *
+     *  `Syncbird` can be used to make the implementation easier.
      */
     abstract deserialize(options: Readonly<StructOptions>, stream: StructDeserializeStream, struct: StructValue): StructFieldValue<this>;
     abstract deserialize(options: Readonly<StructOptions>, stream: StructAsyncDeserializeStream, struct: StructValue): Promise<StructFieldValue<this>>;

package/esm/basic/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/basic/definition.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;GAMG;AACH,8BAAsB,qBAAqB,CACvC,QAAQ,GAAG,IAAI,EACf,MAAM,GAAG,OAAO,EAChB,YAAY,SAAS,WAAW,GAAG,KAAK;IAExC;;;OAGG;IACH,SAAgB,MAAM,EAAG,MAAM,CAAC;IAEhC;;;OAGG;IACH,SAAgB,YAAY,EAAG,YAAY,CAAC;IAE5C,SAAgB,OAAO,EAAE,QAAQ,CAAC;gBAEf,OAAO,EAAE,QAAQ;IAIpC;;;;OAIG;aACa,OAAO,IAAI,MAAM;IAEjC;;OAEG;aACa,MAAM,CAClB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,EAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,GACd,gBAAgB,CAAC,IAAI,CAAC;IAEzB;;;;;OAKG;aACa,WAAW,CACvB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,EAChC,MAAM,EAAE,uBAAuB,EAC/B,MAAM,EAAE,WAAW,GACpB,gBAAgB,CAAC,IAAI,CAAC;aACT,WAAW,CACvB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,EAChC,MAAM,EAAE,4BAA4B,EACpC,MAAM,EAAE,WAAW,GACpB,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;CACrC"}

package/esm/basic/definition.js

@@ -1,19 +1,23 @@
+// cspell: ignore Syncbird
 /**
- * A field definition is a bridge between its type and its runtime value.
- *
- * `Struct` record fields in a list of `StructFieldDefinition`s.
- *
- * When `Struct#create` or `Struct#deserialize` are called, each field's definition
- * crates its own type of `StructFieldValue` to manage the field value in that `Struct` instance.
- *
- * One `StructFieldDefinition` can represents multiple similar types, just returns the corresponding
- * `StructFieldValue` when `createValue` was called.
+ * A field definition defines how to deserialize a field.
  *
  * @template TOptions TypeScript type of this definition's `options`.
  * @template TValue TypeScript type of this field.
  * @template TOmitInitKey Optionally remove some fields from the init type. Should be a union of string literal types.
  */
 export class StructFieldDefinition {
+    /**
+     * When `T` is a type initiated `StructFieldDefinition`,
+     * use `T['TValue']` to retrieve its `TValue` type parameter.
+     */
+    TValue;
+    /**
+     * When `T` is a type initiated `StructFieldDefinition`,
+     * use `T['TOmitInitKey']` to retrieve its `TOmitInitKey` type parameter.
+     */
+    TOmitInitKey;
+    options;
     constructor(options) {
         this.options = options;
     }

package/esm/basic/definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/basic/definition.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAgB,qBAAqB;IAmBvC,YAAmB,OAAiB;QAChC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CA+BJ"}
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/basic/definition.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAO1B;;;;;;GAMG;AACH,MAAM,OAAgB,qBAAqB;IAKvC;;;OAGG;IACa,MAAM,CAAU;IAEhC;;;OAGG;IACa,YAAY,CAAgB;IAE5B,OAAO,CAAW;IAElC,YAAmB,OAAiB;QAChC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CAkCJ"}

package/{dts → esm}/basic/field-value.d.ts

@@ -1,11 +1,11 @@
-import type { StructOptions } from './context';
-import type { StructFieldDefinition } from './definition';
-import type { StructValue } from './struct-value';
+import type { StructFieldDefinition } from "./definition.js";
+import type { StructOptions } from "./options.js";
+import type { StructValue } from "./struct-value.js";
 /**
- * Field runtime value manages one field of one `Struct` instance.
+ * A field value defines how to serialize a field.
  *
- * If one `StructFieldDefinition` needs to change other field's semantics
- * It can override other fields' `StructFieldValue` in its own `StructFieldValue`'s constructor
+ * It may contains extra metadata about the value which are essential or
+ * helpful for the serialization process.
  */
 export declare abstract class StructFieldValue<TDefinition extends StructFieldDefinition<any, any, any> = StructFieldDefinition<any, any, any>> {
     /** Gets the definition associated with this runtime value */
@@ -23,11 +23,11 @@ export declare abstract class StructFieldValue<TDefinition extends StructFieldDe
      */
     getSize(): number;
     /**
-     * When implemented in derived classes, returns the current value of this field
+     * When implemented in derived classes, reads current field's value.
      */
     get(): TDefinition['TValue'];
     /**
-     * When implemented in derived classes, update the current value of this field
+     * When implemented in derived classes, updates current field's value.
      */
     set(value: TDefinition['TValue']): void;
     /**

package/esm/basic/field-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-value.d.ts","sourceRoot":"","sources":["../../src/basic/field-value.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;GAKG;AACH,8BAAsB,gBAAgB,CAClC,WAAW,SAAS,qBAAqB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,qBAAqB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IAE/F,6DAA6D;IAC7D,SAAgB,UAAU,EAAE,WAAW,CAAC;IAExC,kDAAkD;IAClD,SAAgB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAEjD,4CAA4C;IAC5C,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,SAAS,CAAC,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;gBAGnC,UAAU,EAAE,WAAW,EACvB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,EAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC;IAQhC;;;;OAIG;IACI,OAAO,IAAI,MAAM;IAIxB;;OAEG;IACI,GAAG,IAAI,WAAW,CAAC,QAAQ,CAAC;IAInC;;OAEG;IACI,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI;IAI9C;;OAEG;aACa,SAAS,CACrB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,GACf,IAAI;CACV"}

package/esm/basic/field-value.js

@@ -1,10 +1,17 @@
 /**
- * Field runtime value manages one field of one `Struct` instance.
+ * A field value defines how to serialize a field.
  *
- * If one `StructFieldDefinition` needs to change other field's semantics
- * It can override other fields' `StructFieldValue` in its own `StructFieldValue`'s constructor
+ * It may contains extra metadata about the value which are essential or
+ * helpful for the serialization process.
  */
 export class StructFieldValue {
+    /** Gets the definition associated with this runtime value */
+    definition;
+    /** Gets the options of the associated `Struct` */
+    options;
+    /** Gets the associated `Struct` instance */
+    struct;
+    value;
     constructor(definition, options, struct, value) {
         this.definition = definition;
         this.options = options;
@@ -20,13 +27,13 @@ export class StructFieldValue {
         return this.definition.getSize();
     }
     /**
-     * When implemented in derived classes, returns the current value of this field
+     * When implemented in derived classes, reads current field's value.
      */
     get() {
         return this.value;
     }
     /**
-     * When implemented in derived classes, update the current value of this field
+     * When implemented in derived classes, updates current field's value.
      */
     set(value) {
         this.value = value;

package/esm/basic/field-value.js.map

@@ -1 +1 @@
-{"version":3,"file":"field-value.js","sourceRoot":"","sources":["../../src/basic/field-value.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,OAAgB,gBAAgB;IAclC,YACI,UAAuB,EACvB,OAAgC,EAChC,MAAmB,EACnB,KAA4B;QAE5B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACI,OAAO;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC;IAED;;OAEG;IACI,GAAG;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,KAA4B;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CASJ"}
+{"version":3,"file":"field-value.js","sourceRoot":"","sources":["../../src/basic/field-value.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,OAAgB,gBAAgB;IAGlC,6DAA6D;IAC7C,UAAU,CAAc;IAExC,kDAAkD;IAClC,OAAO,CAA0B;IAEjD,4CAA4C;IAC5B,MAAM,CAAc;IAE1B,KAAK,CAAwB;IAEvC,YACI,UAAuB,EACvB,OAAgC,EAChC,MAAmB,EACnB,KAA4B;QAE5B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACI,OAAO;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC;IAED;;OAEG;IACI,GAAG;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,KAA4B;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CASJ"}

package/esm/basic/index.d.ts

@@ -0,0 +1,6 @@
+export * from './definition.js';
+export * from './field-value.js';
+export * from './options.js';
+export * from './stream.js';
+export * from './struct-value.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/basic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/basic/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/esm/basic/index.js

@@ -1,5 +1,6 @@
-export * from './context';
-export * from './definition';
-export * from './field-value';
-export * from './struct-value';
+export * from './definition.js';
+export * from './field-value.js';
+export * from './options.js';
+export * from './stream.js';
+export * from './struct-value.js';
 //# sourceMappingURL=index.js.map

package/esm/basic/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/basic/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/basic/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/esm/basic/options.d.ts

@@ -0,0 +1,10 @@
+export interface StructOptions {
+    /**
+     * Whether all multi-byte fields in this struct are little-endian encoded.
+     *
+     * @default false
+     */
+    littleEndian: boolean;
+}
+export declare const StructDefaultOptions: Readonly<StructOptions>;
+//# sourceMappingURL=options.d.ts.map