@yume-chan/struct 0.0.19 → 0.0.21

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>;
 }
 
 /**
@@ -51,7 +50,7 @@ type AddFieldDescriptor<
     TExtra extends object,
     TPostDeserialized,
     TFieldName extends PropertyKey,
-    TDefinition extends StructFieldDefinition<any, any, any>
+    TDefinition extends StructFieldDefinition<any, any, any>,
 > = Identity<
     Struct<
         // Merge two types
@@ -71,7 +70,7 @@ interface ArrayBufferLikeFieldCreator<
     TFields extends object,
     TOmitInitKey extends PropertyKey,
     TExtra extends object,
-    TPostDeserialized
+    TPostDeserialized,
 > {
     /**
      * Append a fixed-length array buffer like field to the `Struct`
@@ -85,12 +84,12 @@ interface ArrayBufferLikeFieldCreator<
     <
         TName extends PropertyKey,
         TType extends BufferFieldSubType<any, any>,
-        TTypeScriptType = TType["TTypeScriptType"]
+        TTypeScriptType = TType["TTypeScriptType"],
     >(
         name: TName,
         type: TType,
         options: FixedLengthBufferLikeFieldOptions,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ): AddFieldDescriptor<
         TFields,
         TOmitInitKey,
@@ -110,12 +109,12 @@ interface ArrayBufferLikeFieldCreator<
         TName extends PropertyKey,
         TType extends BufferFieldSubType<any, any>,
         TOptions extends VariableLengthBufferLikeFieldOptions<TFields>,
-        TTypeScriptType = TType["TTypeScriptType"]
+        TTypeScriptType = TType["TTypeScriptType"],
     >(
         name: TName,
         type: TType,
         options: TOptions,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ): AddFieldDescriptor<
         TFields,
         TOmitInitKey,
@@ -134,12 +133,12 @@ interface BoundArrayBufferLikeFieldDefinitionCreator<
     TOmitInitKey extends PropertyKey,
     TExtra extends object,
     TPostDeserialized,
-    TType extends BufferFieldSubType<any, any>
+    TType extends BufferFieldSubType<any, any>,
 > {
     <TName extends PropertyKey, TTypeScriptType = TType["TTypeScriptType"]>(
         name: TName,
         options: FixedLengthBufferLikeFieldOptions,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ): AddFieldDescriptor<
         TFields,
         TOmitInitKey,
@@ -160,11 +159,11 @@ interface BoundArrayBufferLikeFieldDefinitionCreator<
             TFields,
             TLengthField
         >,
-        TTypeScriptType = TType["TTypeScriptType"]
+        TTypeScriptType = TType["TTypeScriptType"],
     >(
         name: TName,
         options: TOptions,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ): AddFieldDescriptor<
         TFields,
         TOmitInitKey,
@@ -181,73 +180,100 @@ interface BoundArrayBufferLikeFieldDefinitionCreator<
 
 export type StructPostDeserialized<TFields, TPostDeserialized> = (
     this: TFields,
-    object: TFields
+    object: TFields,
 ) => TPostDeserialized;
 
 export type StructDeserializedResult<
     TFields extends object,
     TExtra extends object,
-    TPostDeserialized
+    TPostDeserialized,
 > = TPostDeserialized extends undefined
     ? Overwrite<TExtra, TFields>
     : TPostDeserialized;
 
+export class StructDeserializeError extends Error {
+    constructor(message: string) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+export class StructNotEnoughDataError extends StructDeserializeError {
+    constructor() {
+        super(
+            "The underlying readable was ended before the struct was fully deserialized",
+        );
+    }
+}
+
+export class StructEmptyError extends StructDeserializeError {
+    constructor() {
+        super("The underlying readable doesn't contain any more struct");
+    }
+}
+
 export class Struct<
     TFields extends object = Record<never, never>,
     TOmitInitKey extends PropertyKey = never,
     TExtra extends object = Record<never, never>,
-    TPostDeserialized = undefined
+    TPostDeserialized = undefined,
 > implements
         StructLike<
             StructDeserializedResult<TFields, TExtra, TPostDeserialized>
         >
 {
-    public readonly TFields!: TFields;
+    readonly TFields!: TFields;
 
-    public readonly TOmitInitKey!: TOmitInitKey;
+    readonly TOmitInitKey!: TOmitInitKey;
 
-    public readonly TExtra!: TExtra;
+    readonly TExtra!: TExtra;
 
-    public readonly TInit!: Evaluate<Omit<TFields, TOmitInitKey>>;
+    readonly TInit!: Evaluate<Omit<TFields, TOmitInitKey>>;
 
-    public readonly TDeserializeResult!: StructDeserializedResult<
+    readonly TDeserializeResult!: StructDeserializedResult<
         TFields,
         TExtra,
         TPostDeserialized
     >;
 
-    public readonly options: Readonly<StructOptions>;
+    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;
+    get size() {
+        return this.#size;
     }
 
-    private _fields: [
+    #fields: [
         name: PropertyKey,
-        definition: StructFieldDefinition<any, any, any>
+        definition: StructFieldDefinition<any, any, any>,
     ][] = [];
+    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>>) {
+    constructor(options?: Partial<Readonly<StructOptions>>) {
         this.options = { ...StructDefaultOptions, ...options };
     }
 
     /**
      * Appends a `StructFieldDefinition` to the `Struct
      */
-    public field<
+    field<
         TName extends PropertyKey,
-        TDefinition extends StructFieldDefinition<any, any, any>
+        TDefinition extends StructFieldDefinition<any, any, any>,
     >(
         name: TName,
-        definition: TDefinition
+        definition: TDefinition,
     ): AddFieldDescriptor<
         TFields,
         TOmitInitKey,
@@ -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,104 +304,104 @@ export class Struct<
     /**
      * Merges (flats) another `Struct`'s fields and extra fields into this one.
      */
-    public fields<TOther extends Struct<any, any, any, any>>(
-        other: TOther
+    concat<TOther extends Struct<any, any, any, any>>(
+        other: TOther,
     ): Struct<
         TFields & TOther["TFields"],
         TOmitInitKey | TOther["TOmitInitKey"],
         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;
     }
 
-    private number<
+    #number<
         TName extends PropertyKey,
         TType extends NumberFieldType = NumberFieldType,
-        TTypeScriptType = number
+        TTypeScriptType = number,
     >(name: TName, type: TType, typeScriptType?: TTypeScriptType) {
         return this.field(
             name,
-            new NumberFieldDefinition(type, typeScriptType)
+            new NumberFieldDefinition(type, typeScriptType),
         );
     }
 
     /**
      * Appends an `int8` field to the `Struct`
      */
-    public int8<TName extends PropertyKey, TTypeScriptType = number>(
+    int8<TName extends PropertyKey, TTypeScriptType = number>(
         name: TName,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ) {
-        return this.number(name, NumberFieldType.Int8, typeScriptType);
+        return this.#number(name, NumberFieldType.Int8, typeScriptType);
     }
 
     /**
      * Appends an `uint8` field to the `Struct`
      */
-    public uint8<TName extends PropertyKey, TTypeScriptType = number>(
+    uint8<TName extends PropertyKey, TTypeScriptType = number>(
         name: TName,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ) {
-        return this.number(name, NumberFieldType.Uint8, typeScriptType);
+        return this.#number(name, NumberFieldType.Uint8, typeScriptType);
     }
 
     /**
      * Appends an `int16` field to the `Struct`
      */
-    public int16<TName extends PropertyKey, TTypeScriptType = number>(
+    int16<TName extends PropertyKey, TTypeScriptType = number>(
         name: TName,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ) {
-        return this.number(name, NumberFieldType.Int16, typeScriptType);
+        return this.#number(name, NumberFieldType.Int16, typeScriptType);
     }
 
     /**
      * Appends an `uint16` field to the `Struct`
      */
-    public uint16<TName extends PropertyKey, TTypeScriptType = number>(
+    uint16<TName extends PropertyKey, TTypeScriptType = number>(
         name: TName,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ) {
-        return this.number(name, NumberFieldType.Uint16, typeScriptType);
+        return this.#number(name, NumberFieldType.Uint16, typeScriptType);
     }
 
     /**
      * Appends an `int32` field to the `Struct`
      */
-    public int32<TName extends PropertyKey, TTypeScriptType = number>(
+    int32<TName extends PropertyKey, TTypeScriptType = number>(
         name: TName,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ) {
-        return this.number(name, NumberFieldType.Int32, typeScriptType);
+        return this.#number(name, NumberFieldType.Int32, typeScriptType);
     }
 
     /**
      * Appends an `uint32` field to the `Struct`
      */
-    public uint32<TName extends PropertyKey, TTypeScriptType = number>(
+    uint32<TName extends PropertyKey, TTypeScriptType = number>(
         name: TName,
-        typeScriptType?: TTypeScriptType
+        typeScriptType?: TTypeScriptType,
     ) {
-        return this.number(name, NumberFieldType.Uint32, typeScriptType);
+        return this.#number(name, NumberFieldType.Uint32, typeScriptType);
     }
 
-    private bigint<
+    #bigint<
         TName extends PropertyKey,
         TType extends BigIntFieldType = BigIntFieldType,
-        TTypeScriptType = TType["TTypeScriptType"]
+        TTypeScriptType = TType["TTypeScriptType"],
     >(name: TName, type: TType, typeScriptType?: TTypeScriptType) {
         return this.field(
             name,
-            new BigIntFieldDefinition(type, typeScriptType)
+            new BigIntFieldDefinition(type, typeScriptType),
         );
     }
 
@@ -384,11 +410,11 @@ export class Struct<
      *
      * Requires native `BigInt` support
      */
-    public int64<
+    int64<
         TName extends PropertyKey,
-        TTypeScriptType = BigIntFieldType["TTypeScriptType"]
+        TTypeScriptType = BigIntFieldType["TTypeScriptType"],
     >(name: TName, typeScriptType?: TTypeScriptType) {
-        return this.bigint(name, BigIntFieldType.Int64, typeScriptType);
+        return this.#bigint(name, BigIntFieldType.Int64, typeScriptType);
     }
 
     /**
@@ -396,14 +422,14 @@ export class Struct<
      *
      * Requires native `BigInt` support
      */
-    public uint64<
+    uint64<
         TName extends PropertyKey,
-        TTypeScriptType = BigIntFieldType["TTypeScriptType"]
+        TTypeScriptType = BigIntFieldType["TTypeScriptType"],
     >(name: TName, typeScriptType?: TTypeScriptType) {
-        return this.bigint(name, BigIntFieldType.Uint64, typeScriptType);
+        return this.#bigint(name, BigIntFieldType.Uint64, typeScriptType);
     }
 
-    private arrayBufferLike: ArrayBufferLikeFieldCreator<
+    #arrayBufferLike: ArrayBufferLikeFieldCreator<
         TFields,
         TOmitInitKey,
         TExtra,
@@ -413,48 +439,48 @@ export class Struct<
         type: BufferFieldSubType,
         options:
             | FixedLengthBufferLikeFieldOptions
-            | VariableLengthBufferLikeFieldOptions
+            | VariableLengthBufferLikeFieldOptions,
     ): any => {
         if ("length" in options) {
             return this.field(
                 name,
-                new FixedLengthBufferLikeFieldDefinition(type, options)
+                new FixedLengthBufferLikeFieldDefinition(type, options),
             );
         } else {
             return this.field(
                 name,
-                new VariableLengthBufferLikeFieldDefinition(type, options)
+                new VariableLengthBufferLikeFieldDefinition(type, options),
             );
         }
     };
 
-    public uint8Array: BoundArrayBufferLikeFieldDefinitionCreator<
+    uint8Array: BoundArrayBufferLikeFieldDefinitionCreator<
         TFields,
         TOmitInitKey,
         TExtra,
         TPostDeserialized,
         Uint8ArrayBufferFieldSubType
     > = (name: PropertyKey, options: any, typeScriptType: any): any => {
-        return this.arrayBufferLike(
+        return this.#arrayBufferLike(
             name,
             Uint8ArrayBufferFieldSubType.Instance,
             options,
-            typeScriptType
+            typeScriptType,
         );
     };
 
-    public string: BoundArrayBufferLikeFieldDefinitionCreator<
+    string: BoundArrayBufferLikeFieldDefinitionCreator<
         TFields,
         TOmitInitKey,
         TExtra,
         TPostDeserialized,
         StringBufferFieldSubType
     > = (name: PropertyKey, options: any, typeScriptType: any): any => {
-        return this.arrayBufferLike(
+        return this.#arrayBufferLike(
             name,
             StringBufferFieldSubType.Instance,
             options,
-            typeScriptType
+            typeScriptType,
         );
     };
 
@@ -468,18 +494,18 @@ export class Struct<
      * @param value
      * An object containing properties to be added to the result value. Accessors and methods are also allowed.
      */
-    public extra<
+    extra<
         T extends Record<
             // This trick disallows any keys that are already in `TValue`
             Exclude<keyof T, Exclude<keyof T, keyof TFields>>,
             never
-        >
+        >,
     >(
-        value: T & ThisType<Overwrite<Overwrite<TExtra, T>, TFields>>
+        value: T & ThisType<Overwrite<Overwrite<TExtra, T>, TFields>>,
     ): Struct<TFields, TOmitInitKey, Overwrite<TExtra, T>, TPostDeserialized> {
         Object.defineProperties(
-            this._extra,
-            Object.getOwnPropertyDescriptors(value)
+            this.#extra,
+            Object.getOwnPropertyDescriptors(value),
         );
         return this as any;
     }
@@ -490,8 +516,8 @@ export class Struct<
      * A callback returning `never` (always throw an error)
      * will also change the return type of `deserialize` to `never`.
      */
-    public postDeserialize(
-        callback: StructPostDeserialized<TFields, never>
+    postDeserialize(
+        callback: StructPostDeserialized<TFields, never>,
     ): Struct<TFields, TOmitInitKey, TExtra, never>;
     /**
      * Registers (or replaces) a custom callback to be run after deserialized.
@@ -499,8 +525,8 @@ export class Struct<
      * A callback returning `void` means it modify the result object in-place
      * (or doesn't modify it at all), so `deserialize` will still return the result object.
      */
-    public postDeserialize(
-        callback?: StructPostDeserialized<TFields, void>
+    postDeserialize(
+        callback?: StructPostDeserialized<TFields, void>,
     ): Struct<TFields, TOmitInitKey, TExtra, undefined>;
     /**
      * Registers (or replaces) a custom callback to be run after deserialized.
@@ -508,56 +534,63 @@ export class Struct<
      * A callback returning anything other than `undefined`
      * will `deserialize` to return that object instead.
      */
-    public postDeserialize<TPostSerialize>(
-        callback?: StructPostDeserialized<TFields, TPostSerialize>
+    postDeserialize<TPostSerialize>(
+        callback?: StructPostDeserialized<TFields, TPostSerialize>,
     ): Struct<TFields, TOmitInitKey, TExtra, TPostSerialize>;
-    public postDeserialize(callback?: StructPostDeserialized<TFields, any>) {
-        this._postDeserialized = callback;
+    postDeserialize(callback?: StructPostDeserialized<TFields, any>) {
+        this.#postDeserialized = callback;
         return this as any;
     }
 
     /**
      * Deserialize a struct value from `stream`.
      */
-    public deserialize(
-        stream: StructDeserializeStream
+    deserialize(
+        stream: ExactReadable,
     ): StructDeserializedResult<TFields, TExtra, TPostDeserialized>;
-    public deserialize(
-        stream: StructAsyncDeserializeStream
+    deserialize(
+        stream: AsyncExactReadable,
     ): Promise<StructDeserializedResult<TFields, TExtra, TPostDeserialized>>;
-    public deserialize(
-        stream: StructDeserializeStream | StructAsyncDeserializeStream
+    deserialize(
+        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,19 +598,19 @@ export class Struct<
                     }
                 }
 
-                return object;
+                return value;
             })
             .valueOrPromise();
     }
 
-    public serialize(init: Evaluate<Omit<TFields, TOmitInitKey>>): Uint8Array;
-    public serialize(
+    serialize(init: Evaluate<Omit<TFields, TOmitInitKey>>): Uint8Array;
+    serialize(
         init: Evaluate<Omit<TFields, TOmitInitKey>>,
-        output: Uint8Array
+        output: Uint8Array,
     ): number;
-    public serialize(
+    serialize(
         init: Evaluate<Omit<TFields, TOmitInitKey>>,
-        output?: Uint8Array
+        output?: Uint8Array,
     ): Uint8Array | number {
         let structValue: StructValue;
         if (STRUCT_VALUE_SYMBOL in init) {
@@ -590,11 +623,11 @@ 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,
-                    (init as any)[name]
+                    (init as any)[name],
                 );
                 structValue.set(name, fieldValue);
             }
@@ -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 });
@@ -619,7 +652,7 @@ export class Struct<
         const dataView = new DataView(
             output.buffer,
             output.byteOffset,
-            output.byteLength
+            output.byteLength,
         );
         let offset = 0;
         for (const { fieldValue, size } of fieldsInfo) {