@yume-chan/struct 0.0.19 → 0.0.20

package/src/basic/definition.ts

@@ -1,9 +1,6 @@
 import type { StructFieldValue } from "./field-value.js";
 import type { StructOptions } from "./options.js";
-import type {
-    StructAsyncDeserializeStream,
-    StructDeserializeStream,
-} from "./stream.js";
+import type { AsyncExactReadable, ExactReadable } from "./stream.js";
 import type { StructValue } from "./struct-value.js";
 
 /**
@@ -60,12 +57,12 @@ export abstract class StructFieldDefinition<
      */
     public abstract deserialize(
         options: Readonly<StructOptions>,
-        stream: StructDeserializeStream,
+        stream: ExactReadable,
         structValue: StructValue
     ): StructFieldValue<this>;
     public abstract deserialize(
         options: Readonly<StructOptions>,
-        stream: StructAsyncDeserializeStream,
+        stream: AsyncExactReadable,
         struct: StructValue
     ): Promise<StructFieldValue<this>>;
 }

package/src/basic/stream.ts

@@ -2,22 +2,33 @@ import type { ValueOrPromise } from "../utils.js";
 
 // TODO: allow over reading (returning a `Uint8Array`, an `offset` and a `length`) to avoid copying
 
-export interface StructDeserializeStream {
+export class ExactReadableEndedError extends Error {
+    public constructor() {
+        super("ExactReadable ended");
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+export interface ExactReadable {
+    readonly position: number;
+
     /**
      * 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.
+     * (due to end of file or other error condition), it must throw an {@link ExactReadableEndedError}.
      */
-    read(length: number): Uint8Array;
+    readExactly(length: number): Uint8Array;
 }
 
-export interface StructAsyncDeserializeStream {
+export interface AsyncExactReadable {
+    readonly position: number;
+
     /**
      * 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.
+     * (due to end of file or other error condition), it must throw an {@link ExactReadableEndedError}.
      */
-    read(length: number): ValueOrPromise<Uint8Array>;
+    readExactly(length: number): ValueOrPromise<Uint8Array>;
 }

package/src/index.ts

@@ -13,5 +13,6 @@ declare global {
 export * from "./basic/index.js";
 export * from "./struct.js";
 export { Struct as default } from "./struct.js";
+export * from "./sync-promise.js";
 export * from "./types/index.js";
 export * from "./utils.js";

package/src/struct.ts

@@ -1,11 +1,12 @@
 import type {
-    StructAsyncDeserializeStream,
-    StructDeserializeStream,
+    AsyncExactReadable,
+    ExactReadable,
     StructFieldDefinition,
     StructFieldValue,
     StructOptions,
 } from "./basic/index.js";
 import {
+    ExactReadableEndedError,
     STRUCT_VALUE_SYMBOL,
     StructDefaultOptions,
     StructValue,
@@ -30,9 +31,7 @@ import {
 import type { Evaluate, Identity, Overwrite, ValueOrPromise } from "./utils.js";
 
 export interface StructLike<TValue> {
-    deserialize(
-        stream: StructDeserializeStream | StructAsyncDeserializeStream
-    ): Promise<TValue>;
+    deserialize(stream: ExactReadable | AsyncExactReadable): Promise<TValue>;
 }
 
 /**
@@ -192,6 +191,27 @@ export type StructDeserializedResult<
     ? Overwrite<TExtra, TFields>
     : TPostDeserialized;
 
+export class StructDeserializeError extends Error {
+    public constructor(message: string) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+export class StructNotEnoughDataError extends StructDeserializeError {
+    public constructor() {
+        super(
+            "The underlying readable was ended before the struct was fully deserialized"
+        );
+    }
+}
+
+export class StructEmptyError extends StructDeserializeError {
+    public constructor() {
+        super("The underlying readable doesn't contain any more struct");
+    }
+}
+
 export class Struct<
     TFields extends object = Record<never, never>,
     TOmitInitKey extends PropertyKey = never,
@@ -218,22 +238,28 @@ export class Struct<
 
     public readonly options: Readonly<StructOptions>;
 
-    private _size = 0;
+    #size = 0;
     /**
      * Gets the static size (exclude fields that can change size at runtime)
      */
     public get size() {
-        return this._size;
+        return this.#size;
     }
 
-    private _fields: [
+    #fields: [
         name: PropertyKey,
         definition: StructFieldDefinition<any, any, any>
     ][] = [];
+    public get fields(): readonly [
+        name: PropertyKey,
+        definition: StructFieldDefinition<any, any, any>
+    ][] {
+        return this.#fields;
+    }
 
-    private _extra: Record<PropertyKey, unknown> = {};
+    #extra: Record<PropertyKey, unknown> = {};
 
-    private _postDeserialized?: StructPostDeserialized<any, any> | undefined;
+    #postDeserialized?: StructPostDeserialized<any, any> | undefined;
 
     public constructor(options?: Partial<Readonly<StructOptions>>) {
         this.options = { ...StructDefaultOptions, ...options };
@@ -256,20 +282,20 @@ export class Struct<
         TName,
         TDefinition
     > {
-        for (const field of this._fields) {
+        for (const field of this.#fields) {
             if (field[0] === name) {
+                // Convert Symbol to string
+                const nameString = String(name);
                 throw new Error(
-                    `This struct already have a field with name '${String(
-                        name
-                    )}'`
+                    `This struct already have a field with name '${nameString}'`
                 );
             }
         }
 
-        this._fields.push([name, definition]);
+        this.#fields.push([name, definition]);
 
         const size = definition.getSize();
-        this._size += size;
+        this.#size += size;
 
         // Force cast `this` to another type
         return this as any;
@@ -278,7 +304,7 @@ export class Struct<
     /**
      * Merges (flats) another `Struct`'s fields and extra fields into this one.
      */
-    public fields<TOther extends Struct<any, any, any, any>>(
+    public concat<TOther extends Struct<any, any, any, any>>(
         other: TOther
     ): Struct<
         TFields & TOther["TFields"],
@@ -286,13 +312,13 @@ export class Struct<
         TExtra & TOther["TExtra"],
         TPostDeserialized
     > {
-        for (const field of other._fields) {
-            this._fields.push(field);
+        for (const field of other.#fields) {
+            this.#fields.push(field);
         }
-        this._size += other._size;
+        this.#size += other.#size;
         Object.defineProperties(
-            this._extra,
-            Object.getOwnPropertyDescriptors(other._extra)
+            this.#extra,
+            Object.getOwnPropertyDescriptors(other.#extra)
         );
         return this as any;
     }
@@ -478,7 +504,7 @@ export class Struct<
         value: T & ThisType<Overwrite<Overwrite<TExtra, T>, TFields>>
     ): Struct<TFields, TOmitInitKey, Overwrite<TExtra, T>, TPostDeserialized> {
         Object.defineProperties(
-            this._extra,
+            this.#extra,
             Object.getOwnPropertyDescriptors(value)
         );
         return this as any;
@@ -512,7 +538,7 @@ export class Struct<
         callback?: StructPostDeserialized<TFields, TPostSerialize>
     ): Struct<TFields, TOmitInitKey, TExtra, TPostSerialize>;
     public postDeserialize(callback?: StructPostDeserialized<TFields, any>) {
-        this._postDeserialized = callback;
+        this.#postDeserialized = callback;
         return this as any;
     }
 
@@ -520,44 +546,51 @@ export class Struct<
      * Deserialize a struct value from `stream`.
      */
     public deserialize(
-        stream: StructDeserializeStream
+        stream: ExactReadable
     ): StructDeserializedResult<TFields, TExtra, TPostDeserialized>;
     public deserialize(
-        stream: StructAsyncDeserializeStream
+        stream: AsyncExactReadable
     ): Promise<StructDeserializedResult<TFields, TExtra, TPostDeserialized>>;
     public deserialize(
-        stream: StructDeserializeStream | StructAsyncDeserializeStream
+        stream: ExactReadable | AsyncExactReadable
     ): ValueOrPromise<
         StructDeserializedResult<TFields, TExtra, TPostDeserialized>
     > {
-        const structValue = new StructValue(this._extra);
+        const structValue = new StructValue(this.#extra);
 
         let promise = SyncPromise.resolve();
 
-        for (const [name, definition] of this._fields) {
+        const startPosition = stream.position;
+        for (const [name, definition] of this.#fields) {
             promise = promise
                 .then(() =>
-                    definition.deserialize(
-                        this.options,
-                        stream as any,
-                        structValue
-                    )
+                    definition.deserialize(this.options, stream, structValue)
                 )
-                .then((fieldValue) => {
-                    structValue.set(name, fieldValue);
-                });
+                .then(
+                    (fieldValue) => {
+                        structValue.set(name, fieldValue);
+                    },
+                    (e) => {
+                        if (!(e instanceof ExactReadableEndedError)) {
+                            throw e;
+                        }
+
+                        if (stream.position === startPosition) {
+                            throw new StructEmptyError();
+                        } else {
+                            throw new StructNotEnoughDataError();
+                        }
+                    }
+                );
         }
 
         return promise
             .then(() => {
-                const object = structValue.value;
+                const value = structValue.value;
 
                 // Run `postDeserialized`
-                if (this._postDeserialized) {
-                    const override = this._postDeserialized.call(
-                        object,
-                        object
-                    );
+                if (this.#postDeserialized) {
+                    const override = this.#postDeserialized.call(value, value);
                     // If it returns a new value, use that as result
                     // Otherwise it only inspects/mutates the object in place.
                     if (override !== undefined) {
@@ -565,7 +598,7 @@ export class Struct<
                     }
                 }
 
-                return object;
+                return value;
             })
             .valueOrPromise();
     }
@@ -590,7 +623,7 @@ export class Struct<
             }
         } else {
             structValue = new StructValue({});
-            for (const [name, definition] of this._fields) {
+            for (const [name, definition] of this.#fields) {
                 const fieldValue = definition.create(
                     this.options,
                     structValue,
@@ -603,7 +636,7 @@ export class Struct<
         let structSize = 0;
         const fieldsInfo: { fieldValue: StructFieldValue; size: number }[] = [];
 
-        for (const [name] of this._fields) {
+        for (const [name] of this.#fields) {
             const fieldValue = structValue.get(name);
             const size = fieldValue.getSize();
             fieldsInfo.push({ fieldValue, size });

package/src/sync-promise.ts

@@ -55,10 +55,10 @@ export const SyncPromise: SyncPromiseStatic = {
 };
 
 class PendingSyncPromise<T> implements SyncPromise<T> {
-    private promise: PromiseLike<T>;
+    #promise: PromiseLike<T>;
 
     public constructor(promise: PromiseLike<T>) {
-        this.promise = promise;
+        this.#promise = promise;
     }
 
     public then<TResult1 = T, TResult2 = never>(
@@ -72,20 +72,20 @@ class PendingSyncPromise<T> implements SyncPromise<T> {
             | undefined
     ) {
         return new PendingSyncPromise<TResult1 | TResult2>(
-            this.promise.then(onfulfilled, onrejected)
+            this.#promise.then(onfulfilled, onrejected)
         );
     }
 
     public valueOrPromise(): T | PromiseLike<T> {
-        return this.promise;
+        return this.#promise;
     }
 }
 
 class ResolvedSyncPromise<T> implements SyncPromise<T> {
-    private value: T;
+    #value: T;
 
     public constructor(value: T) {
-        this.value = value;
+        this.#value = value;
     }
 
     public then<TResult1 = T>(
@@ -97,19 +97,19 @@ class ResolvedSyncPromise<T> implements SyncPromise<T> {
         if (!onfulfilled) {
             return this as any;
         }
-        return SyncPromise.try(() => onfulfilled(this.value));
+        return SyncPromise.try(() => onfulfilled(this.#value));
     }
 
     public valueOrPromise(): T | PromiseLike<T> {
-        return this.value;
+        return this.#value;
     }
 }
 
 class RejectedSyncPromise<T> implements SyncPromise<T> {
-    private reason: any;
+    #reason: any;
 
     public constructor(reason: any) {
-        this.reason = reason;
+        this.#reason = reason;
     }
 
     public then<TResult1 = T, TResult2 = never>(
@@ -125,10 +125,10 @@ class RejectedSyncPromise<T> implements SyncPromise<T> {
         if (!onrejected) {
             return this as any;
         }
-        return SyncPromise.try(() => onrejected(this.reason));
+        return SyncPromise.try(() => onrejected(this.#reason));
     }
 
     public valueOrPromise(): T | PromiseLike<T> {
-        throw this.reason;
+        throw this.#reason;
     }
 }

package/src/types/bigint.ts

@@ -6,8 +6,8 @@ import {
 } from "@yume-chan/dataview-bigint-polyfill/esm/fallback.js";
 
 import type {
-    StructAsyncDeserializeStream,
-    StructDeserializeStream,
+    AsyncExactReadable,
+    ExactReadable,
     StructOptions,
     StructValue,
 } from "../basic/index.js";
@@ -86,21 +86,21 @@ export class BigIntFieldDefinition<
 
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructDeserializeStream,
+        stream: ExactReadable,
         struct: StructValue
     ): BigIntFieldValue<this>;
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructAsyncDeserializeStream,
+        stream: AsyncExactReadable,
         struct: StructValue
     ): Promise<BigIntFieldValue<this>>;
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructDeserializeStream | StructAsyncDeserializeStream,
+        stream: ExactReadable | AsyncExactReadable,
         struct: StructValue
     ): ValueOrPromise<BigIntFieldValue<this>> {
         return SyncPromise.try(() => {
-            return stream.read(this.getSize());
+            return stream.readExactly(this.getSize());
         })
             .then((array) => {
                 const view = new DataView(

package/src/types/buffer/base.ts

@@ -1,6 +1,6 @@
 import type {
-    StructAsyncDeserializeStream,
-    StructDeserializeStream,
+    AsyncExactReadable,
+    ExactReadable,
     StructOptions,
     StructValue,
 } from "../../basic/index.js";
@@ -127,17 +127,17 @@ export abstract class BufferLikeFieldDefinition<
 
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructDeserializeStream,
+        stream: ExactReadable,
         struct: StructValue
     ): BufferLikeFieldValue<this>;
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructAsyncDeserializeStream,
+        stream: AsyncExactReadable,
         struct: StructValue
     ): Promise<BufferLikeFieldValue<this>>;
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructDeserializeStream | StructAsyncDeserializeStream,
+        stream: ExactReadable | AsyncExactReadable,
         struct: StructValue
     ): ValueOrPromise<BufferLikeFieldValue<this>> {
         return SyncPromise.try(() => {
@@ -145,7 +145,7 @@ export abstract class BufferLikeFieldDefinition<
             if (size === 0) {
                 return EMPTY_UINT8_ARRAY;
             } else {
-                return stream.read(size);
+                return stream.readExactly(size);
             }
         })
             .then((array) => {

package/src/types/number.ts

@@ -1,6 +1,6 @@
 import type {
-    StructAsyncDeserializeStream,
-    StructDeserializeStream,
+    AsyncExactReadable,
+    ExactReadable,
     StructOptions,
     StructValue,
 } from "../basic/index.js";
@@ -49,15 +49,12 @@ export namespace NumberFieldType {
         signed: false,
         size: 2,
         deserialize(array, littleEndian) {
-            // PERF: Chrome's `DataView#getUint16` uses inefficient operations,
-            // including branching, bit extending and 32-bit bit swapping.
-            // The best way should use 16-bit bit rotation and conditional move,
-            // like LLVM does for code similar to the below one.
-            // This code is much faster on V8, but the actual generated assembly is unknown.
-            return (
-                (((array[1]! << 8) | array[0]!) * (littleEndian as any)) |
-                (((array[0]! << 8) | array[1]!) * (!littleEndian as any))
-            );
+            // PERF: Creating many `DataView`s over small buffers is 90% slower
+            // than this. Even if the `DataView` is cached, `DataView#getUint16`
+            // is still 1% slower than this.
+            const a = (array[1]! << 8) | array[0]!;
+            const b = (array[0]! << 8) | array[1]!;
+            return littleEndian ? a : b;
         },
         serialize(dataView, offset, value, littleEndian) {
             dataView.setUint16(offset, value, littleEndian);
@@ -92,18 +89,17 @@ export namespace NumberFieldType {
         signed: true,
         size: 4,
         deserialize(array, littleEndian) {
-            return (
-                (((array[3]! << 24) |
-                    (array[2]! << 16) |
-                    (array[1]! << 8) |
-                    array[0]!) *
-                    (littleEndian as any)) |
-                (((array[0]! << 24) |
-                    (array[1]! << 16) |
-                    (array[2]! << 8) |
-                    array[3]!) *
-                    (!littleEndian as any))
-            );
+            const a =
+                (array[3]! << 24) |
+                (array[2]! << 16) |
+                (array[1]! << 8) |
+                array[0]!;
+            const b =
+                (array[0]! << 24) |
+                (array[1]! << 16) |
+                (array[2]! << 8) |
+                array[3]!;
+            return littleEndian ? a : b;
         },
         serialize(dataView, offset, value, littleEndian) {
             dataView.setInt32(offset, value, littleEndian);
@@ -137,21 +133,21 @@ export class NumberFieldDefinition<
 
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructDeserializeStream,
+        stream: ExactReadable,
         struct: StructValue
     ): NumberFieldValue<this>;
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructAsyncDeserializeStream,
+        stream: AsyncExactReadable,
         struct: StructValue
     ): Promise<NumberFieldValue<this>>;
     public override deserialize(
         options: Readonly<StructOptions>,
-        stream: StructDeserializeStream | StructAsyncDeserializeStream,
+        stream: ExactReadable | AsyncExactReadable,
         struct: StructValue
     ): ValueOrPromise<NumberFieldValue<this>> {
         return SyncPromise.try(() => {
-            return stream.read(this.getSize());
+            return stream.readExactly(this.getSize());
         })
             .then((array) => {
                 const value = this.type.deserialize(