@yume-chan/struct 0.0.10 → 0.0.14

package/src/struct.ts

@@ -1,8 +1,10 @@
-import type { StructAsyncDeserializeStream, StructDeserializeStream, StructFieldDefinition, StructFieldValue, StructOptions } from './basic';
-import { StructDefaultOptions, StructValue } from './basic';
-import { Syncbird } from "./syncbird";
-import { ArrayBufferFieldType, ArrayBufferLikeFieldType, FixedLengthArrayBufferLikeFieldDefinition, FixedLengthArrayBufferLikeFieldOptions, LengthField, NumberFieldDefinition, NumberFieldType, StringFieldType, Uint8ClampedArrayFieldType, VariableLengthArrayBufferLikeFieldDefinition, VariableLengthArrayBufferLikeFieldOptions } from './types';
-import { Evaluate, Identity, Overwrite, ValueOrPromise } from "./utils";
+// cspell: ignore Syncbird
+
+import type { StructAsyncDeserializeStream, StructDeserializeStream, StructFieldDefinition, StructFieldValue, StructOptions } from './basic/index.js';
+import { StructDefaultOptions, StructValue } from './basic/index.js';
+import { Syncbird } from "./syncbird.js";
+import { BigIntFieldDefinition, BigIntFieldType, BufferFieldSubType, FixedLengthBufferLikeFieldDefinition, NumberFieldDefinition, NumberFieldType, StringBufferFieldSubType, Uint8ArrayBufferFieldSubType, VariableLengthBufferLikeFieldDefinition, type FixedLengthBufferLikeFieldOptions, type LengthField, type VariableLengthBufferLikeFieldOptions } from './types/index.js';
+import type { Evaluate, Identity, Overwrite, ValueOrPromise } from "./utils.js";
 
 export interface StructLike<TValue> {
     deserialize(stream: StructDeserializeStream | StructAsyncDeserializeStream): Promise<TValue>;
@@ -55,12 +57,12 @@ interface ArrayBufferLikeFieldCreator<
      */
     <
         TName extends PropertyKey,
-        TType extends ArrayBufferLikeFieldType<any, any>,
+        TType extends BufferFieldSubType<any, any>,
         TTypeScriptType = TType['TTypeScriptType'],
         >(
         name: TName,
         type: TType,
-        options: FixedLengthArrayBufferLikeFieldOptions,
+        options: FixedLengthBufferLikeFieldOptions,
         typescriptType?: TTypeScriptType,
     ): AddFieldDescriptor<
         TFields,
@@ -68,9 +70,9 @@ interface ArrayBufferLikeFieldCreator<
         TExtra,
         TPostDeserialized,
         TName,
-        FixedLengthArrayBufferLikeFieldDefinition<
+        FixedLengthBufferLikeFieldDefinition<
             TType,
-            FixedLengthArrayBufferLikeFieldOptions
+            FixedLengthBufferLikeFieldOptions
         >
     >;
 
@@ -79,8 +81,8 @@ interface ArrayBufferLikeFieldCreator<
      */
     <
         TName extends PropertyKey,
-        TType extends ArrayBufferLikeFieldType<any, any>,
-        TOptions extends VariableLengthArrayBufferLikeFieldOptions<TFields>,
+        TType extends BufferFieldSubType<any, any>,
+        TOptions extends VariableLengthBufferLikeFieldOptions<TFields>,
         TTypeScriptType = TType['TTypeScriptType'],
         >(
         name: TName,
@@ -93,7 +95,7 @@ interface ArrayBufferLikeFieldCreator<
         TExtra,
         TPostDeserialized,
         TName,
-        VariableLengthArrayBufferLikeFieldDefinition<
+        VariableLengthBufferLikeFieldDefinition<
             TType,
             TOptions
         >
@@ -103,19 +105,19 @@ interface ArrayBufferLikeFieldCreator<
 /**
  * Similar to `ArrayBufferLikeFieldCreator`, but bind to `TType`
  */
-interface BindedArrayBufferLikeFieldDefinitionCreator<
+interface BoundArrayBufferLikeFieldDefinitionCreator<
     TFields extends object,
     TOmitInitKey extends PropertyKey,
     TExtra extends object,
     TPostDeserialized,
-    TType extends ArrayBufferLikeFieldType<any, any>
+    TType extends BufferFieldSubType<any, any>
     > {
     <
         TName extends PropertyKey,
         TTypeScriptType = TType['TTypeScriptType'],
         >(
         name: TName,
-        options: FixedLengthArrayBufferLikeFieldOptions,
+        options: FixedLengthBufferLikeFieldOptions,
         typescriptType?: TTypeScriptType,
     ): AddFieldDescriptor<
         TFields,
@@ -123,16 +125,16 @@ interface BindedArrayBufferLikeFieldDefinitionCreator<
         TExtra,
         TPostDeserialized,
         TName,
-        FixedLengthArrayBufferLikeFieldDefinition<
+        FixedLengthBufferLikeFieldDefinition<
             TType,
-            FixedLengthArrayBufferLikeFieldOptions
+            FixedLengthBufferLikeFieldOptions
         >
     >;
 
     <
         TName extends PropertyKey,
         TLengthField extends LengthField<TFields>,
-        TOptions extends VariableLengthArrayBufferLikeFieldOptions<TFields, TLengthField>,
+        TOptions extends VariableLengthBufferLikeFieldOptions<TFields, TLengthField>,
         TTypeScriptType = TType['TTypeScriptType'],
         >(
         name: TName,
@@ -144,7 +146,7 @@ interface BindedArrayBufferLikeFieldDefinitionCreator<
         TExtra,
         TPostDeserialized,
         TName,
-        VariableLengthArrayBufferLikeFieldDefinition<
+        VariableLengthBufferLikeFieldDefinition<
             TType,
             TOptions
         >
@@ -185,7 +187,7 @@ export class Struct<
 
     private _extra: PropertyDescriptorMap = {};
 
-    private _postDeserialized?: StructPostDeserialized<any, any>;
+    private _postDeserialized?: StructPostDeserialized<any, any> | undefined;
 
     public constructor(options?: Partial<Readonly<StructOptions>>) {
         this.options = { ...StructDefaultOptions, ...options };
@@ -210,7 +212,7 @@ export class Struct<
     > {
         for (const field of this._fields) {
             if (field[0] === name) {
-                throw new Error(`This struct already have a field with name '${name}'`);
+                throw new Error(`This struct already have a field with name '${String(name)}'`);
             }
         }
 
@@ -359,6 +361,21 @@ export class Struct<
         );
     }
 
+    private bigint<
+        TName extends PropertyKey,
+        TType extends BigIntFieldType = BigIntFieldType,
+        TTypeScriptType = TType['TTypeScriptType']
+    >(
+        name: TName,
+        type: TType,
+        _typescriptType?: TTypeScriptType,
+    ) {
+        return this.field(
+            name,
+            new BigIntFieldDefinition(type, _typescriptType),
+        );
+    }
+
     /**
      * Appends an `int64` field to the `Struct`
      *
@@ -366,14 +383,14 @@ export class Struct<
      */
     public int64<
         TName extends PropertyKey,
-        TTypeScriptType = (typeof NumberFieldType)['Int64']['TTypeScriptType']
+        TTypeScriptType = BigIntFieldType['TTypeScriptType']
     >(
         name: TName,
         _typescriptType?: TTypeScriptType,
     ) {
-        return this.number(
+        return this.bigint(
             name,
-            NumberFieldType.Int64,
+            BigIntFieldType.Int64,
             _typescriptType
         );
     }
@@ -385,14 +402,14 @@ export class Struct<
      */
     public uint64<
         TName extends PropertyKey,
-        TTypeScriptType = (typeof NumberFieldType)['Uint64']['TTypeScriptType']
+        TTypeScriptType = BigIntFieldType['TTypeScriptType']
     >(
         name: TName,
         _typescriptType?: TTypeScriptType,
     ) {
-        return this.number(
+        return this.bigint(
             name,
-            NumberFieldType.Uint64,
+            BigIntFieldType.Uint64,
             _typescriptType
         );
     }
@@ -404,59 +421,46 @@ export class Struct<
         TPostDeserialized
     > = (
         name: PropertyKey,
-        type: ArrayBufferLikeFieldType,
-        options: FixedLengthArrayBufferLikeFieldOptions | VariableLengthArrayBufferLikeFieldOptions
+        type: BufferFieldSubType,
+        options: FixedLengthBufferLikeFieldOptions | VariableLengthBufferLikeFieldOptions
     ): any => {
             if ('length' in options) {
                 return this.field(
                     name,
-                    new FixedLengthArrayBufferLikeFieldDefinition(type, options),
+                    new FixedLengthBufferLikeFieldDefinition(type, options),
                 );
             } else {
                 return this.field(
                     name,
-                    new VariableLengthArrayBufferLikeFieldDefinition(type, options),
+                    new VariableLengthBufferLikeFieldDefinition(type, options),
                 );
             }
         };
 
-    public arrayBuffer: BindedArrayBufferLikeFieldDefinitionCreator<
+    public uint8Array: BoundArrayBufferLikeFieldDefinitionCreator<
         TFields,
         TOmitInitKey,
         TExtra,
         TPostDeserialized,
-        ArrayBufferFieldType
+        Uint8ArrayBufferFieldSubType
     > = (
         name: PropertyKey,
         options: any
     ): any => {
-            return this.arrayBufferLike(name, ArrayBufferFieldType.instance, options);
+        return this.arrayBufferLike(name, Uint8ArrayBufferFieldSubType.Instance, options);
         };
 
-    public uint8ClampedArray: BindedArrayBufferLikeFieldDefinitionCreator<
+    public string: BoundArrayBufferLikeFieldDefinitionCreator<
         TFields,
         TOmitInitKey,
         TExtra,
         TPostDeserialized,
-        Uint8ClampedArrayFieldType
+        StringBufferFieldSubType
     > = (
         name: PropertyKey,
         options: any
     ): any => {
-            return this.arrayBufferLike(name, Uint8ClampedArrayFieldType.instance, options);
-        };
-
-    public string: BindedArrayBufferLikeFieldDefinitionCreator<
-        TFields,
-        TOmitInitKey,
-        TExtra,
-        TPostDeserialized,
-        StringFieldType
-    > = (
-        name: PropertyKey,
-        options: any
-    ): any => {
-            return this.arrayBufferLike(name, StringFieldType.instance, options);
+        return this.arrayBufferLike(name, StringBufferFieldSubType.Instance, options);
         };
 
     /**
@@ -522,6 +526,9 @@ export class Struct<
         return this as any;
     }
 
+    /**
+     * Deserialize a struct value from `stream`.
+     */
     public deserialize(
         stream: StructDeserializeStream,
     ): StructDeserializedResult<TFields, TExtra, TPostDeserialized>;
@@ -534,37 +541,35 @@ export class Struct<
         const value = new StructValue();
         Object.defineProperties(value.value, this._extra);
 
-        return Syncbird.try(() => {
-            const iterator = this._fields[Symbol.iterator]();
-            const iterate: () => StructValue | Syncbird<StructValue> = () => {
-                const result = iterator.next();
-                if (result.done) {
-                    return value;
-                }
-
-                const [name, definition] = result.value;
+        return Syncbird
+            .each(this._fields, ([name, definition]) => {
                 return Syncbird.resolve(
                     definition.deserialize(this.options, stream as any, value)
                 ).then(fieldValue => {
                     value.set(name, fieldValue);
-                    return iterate();
                 });
-            };
-            return iterate();
-        }).then(value => {
-            if (this._postDeserialized) {
-                const object = value.value as TFields;
-                const result = this._postDeserialized.call(object, object);
-                if (result) {
-                    return result;
+            })
+            .then(() => {
+                const object = value.value;
+
+                // Run `postDeserialized`
+                if (this._postDeserialized) {
+                    const override = this._postDeserialized.call(object, object);
+                    // If it returns a new value, use that as result
+                    // Otherwise it only inspects/mutates the object in place.
+                    if (override) {
+                        return override;
+                    }
                 }
-            }
 
-            return value.value;
-        }).valueOrPromise();
+                return object;
+            })
+            .valueOrPromise();
     }
 
-    public serialize(init: Evaluate<Omit<TFields, TOmitInitKey>>): ArrayBuffer {
+    public serialize(init: Evaluate<Omit<TFields, TOmitInitKey>>): Uint8Array;
+    public serialize(init: Evaluate<Omit<TFields, TOmitInitKey>>, output: Uint8Array): number;
+    public serialize(init: Evaluate<Omit<TFields, TOmitInitKey>>, output?: Uint8Array): Uint8Array | number {
         const value = new StructValue();
 
         for (const [name, definition] of this._fields) {
@@ -582,14 +587,23 @@ export class Struct<
             structSize += size;
         }
 
-        const buffer = new ArrayBuffer(structSize);
-        const dataView = new DataView(buffer);
+        let outputType = 'number';
+        if (!output) {
+            output = new Uint8Array(structSize);
+            outputType = 'Uint8Array';
+        }
+
+        const dataView = new DataView(output.buffer, output.byteOffset, output.byteLength);
         let offset = 0;
         for (const { fieldValue, size } of fieldsInfo) {
             fieldValue.serialize(dataView, offset);
             offset += size;
         }
 
-        return buffer;
+        if (outputType === 'number') {
+            return structSize;
+        } else {
+            return output;
+        }
     }
 }

package/src/syncbird.ts

@@ -1,6 +1,9 @@
+// cspell: ignore syncbird
+
 import Bluebird from 'bluebird';
 
-type Resolvable<R> = R | PromiseLike<R>;
+export type Resolvable<R> = R | PromiseLike<R>;
+export type IterateFunction<T, R> = (item: T, index: number, arrayLength: number) => Resolvable<R>;
 
 export interface Syncbird<R> extends Bluebird<R> {
     valueOrPromise(): R | PromiseLike<R>;
@@ -13,6 +16,39 @@ export interface Syncbird<R> extends Bluebird<R> {
 }
 
 interface SyncbirdStatic {
+    /**
+     * Iterate over an array, or a promise of an array,
+     * which contains promises (or a mix of promises and values) with the given iterator function with the signature `(item, index, value)`
+     * where item is the resolved value of a respective promise in the input array.
+     * Iteration happens serially. If any promise in the input array is rejected the returned promise is rejected as well.
+     *
+     * Resolves to the original array unmodified, this method is meant to be used for side effects.
+     * If the iterator function returns a promise or a thenable, the result for the promise is awaited for before continuing with next iteration.
+     */
+    each<R>(
+        values: Resolvable<Iterable<Resolvable<R>>>,
+        iterator: IterateFunction<R, any>
+    ): Syncbird<R[]>;
+
+    /**
+     * Reduce an array, or a promise of an array,
+     * which contains a promises (or a mix of promises and values) with the given `reducer` function with the signature `(total, current, index, arrayLength)`
+     * where `item` is the resolved value of a respective promise in the input array.
+     * If any promise in the input array is rejected the returned promise is rejected as well.
+     *
+     * If the reducer function returns a promise or a thenable, the result for the promise is awaited for before continuing with next iteration.
+     *
+     * *The original array is not modified. If no `initialValue` is given and the array doesn't contain at least 2 items,
+     * the callback will not be called and `undefined` is returned.
+     *
+     * If `initialValue` is given and the array doesn't have at least 1 item, `initialValue` is returned.*
+     */
+    reduce<R, U>(
+        values: Resolvable<Iterable<Resolvable<R>>>,
+        reducer: (total: U, current: R, index: number, arrayLength: number) => Resolvable<U>,
+        initialValue?: U
+    ): Syncbird<U>;
+
     /**
      * Create a promise that is resolved with the given `value`. If `value` is a thenable or promise, the returned promise will assume its state.
      */
@@ -22,25 +58,67 @@ interface SyncbirdStatic {
     try<R>(fn: () => Resolvable<R>): Syncbird<R>;
     attempt<R>(fn: () => Resolvable<R>): Syncbird<R>;
 
+    /**
+     * Configure long stack traces, warnings, monitoring and cancellation.
+     * Note that even though false is the default here, a development environment might be detected which automatically
+     *  enables long stack traces and warnings.
+     */
+    config(options: {
+        /** Enable warnings */
+        warnings?: boolean | {
+            /** Enables all warnings except forgotten return statements. */
+            wForgottenReturn: boolean;
+        } | undefined;
+        /** Enable long stack traces */
+        longStackTraces?: boolean | undefined;
+        /** Enable cancellation */
+        cancellation?: boolean | undefined;
+        /** Enable monitoring */
+        monitoring?: boolean | undefined;
+        /** Enable async hooks */
+        asyncHooks?: boolean | undefined;
+    }): void;
+
     new <R>(callback: (resolve: (thenableOrResult?: Resolvable<R>) => void, reject: (error?: any) => void, onCancel?: (callback: () => void) => void) => void): Syncbird<R>;
 }
 
 export const Syncbird: SyncbirdStatic = Bluebird.getNewLibraryCopy() as any;
 
-const _then = Bluebird.prototype.then;
-Syncbird.prototype.then = function <T, TResult1 = T, TResult2 = never>(
-    this: Bluebird<T>,
-    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
-    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null
-): Syncbird<TResult1 | TResult2> {
+Syncbird.config({
+    asyncHooks: false,
+    cancellation: false,
+    longStackTraces: false,
+    monitoring: false,
+    warnings: false,
+});
+
+// Bluebird uses `_then` internally.
+const _then = (Syncbird.prototype as any)._then;
+Syncbird.prototype._then = function <T, TResult1 = T, TResult2 = never>(
+    this: Syncbird<T>,
+    onfulfilled: ((value: T, internalData?: unknown) => unknown) | undefined | null,
+    onrejected: ((reason: any) => unknown) | undefined | null,
+    _: never,
+    receiver: unknown,
+    internalData: unknown,
+): Syncbird<unknown> {
     if (this.isFulfilled()) {
         if (!onfulfilled) {
-            return this as unknown as Syncbird<TResult1>;
+            return this;
         } else {
-            return Syncbird.resolve(onfulfilled(this.value())) as Syncbird<TResult1 | TResult2>;
+            // Synchronously call `onfulfilled`, and wrap the result in a new `Syncbird` object.
+            return Syncbird.resolve(
+                onfulfilled.call(
+                    receiver,
+                    this.value(),
+                    // Some Bluebird internal methods (for example `reduce`) need this `internalData`
+                    internalData
+                )
+            );
         }
     } else {
-        return _then.call(this, onfulfilled, onrejected) as Syncbird<TResult1 | TResult2>;
+        // Forward to Bluebird's `_then` method.
+        return _then.call(this, onfulfilled, onrejected, _, receiver, internalData);
     }
 };
 

package/src/types/bigint.ts

@@ -0,0 +1,102 @@
+// cspell: ignore syncbird
+
+import { getBigInt64, getBigUint64, setBigInt64, setBigUint64 } from '@yume-chan/dataview-bigint-polyfill/esm/fallback.js';
+import { StructFieldDefinition, StructFieldValue, StructValue, type StructAsyncDeserializeStream, type StructDeserializeStream, type StructOptions } from "../basic/index.js";
+import { Syncbird } from "../syncbird.js";
+import type { ValueOrPromise } from "../utils.js";
+
+type DataViewBigInt64Getter = (dataView: DataView, byteOffset: number, littleEndian: boolean | undefined) => bigint;
+
+type DataViewBigInt64Setter = (dataView: DataView, byteOffset: number, value: bigint, littleEndian: boolean | undefined) => void;
+
+export class BigIntFieldType {
+    public readonly TTypeScriptType!: bigint;
+
+    public readonly size: number;
+
+    public readonly getter: DataViewBigInt64Getter;
+
+    public readonly setter: DataViewBigInt64Setter;
+
+    public constructor(
+        size: number,
+        getter: DataViewBigInt64Getter,
+        setter: DataViewBigInt64Setter,
+    ) {
+        this.size = size;
+        this.getter = getter;
+        this.setter = setter;
+    }
+
+    public static readonly Int64 = new BigIntFieldType(8, getBigInt64, setBigInt64);
+
+    public static readonly Uint64 = new BigIntFieldType(8, getBigUint64, setBigUint64);
+}
+
+export class BigIntFieldDefinition<
+    TType extends BigIntFieldType = BigIntFieldType,
+    TTypeScriptType = TType["TTypeScriptType"],
+    > extends StructFieldDefinition<
+    void,
+    TTypeScriptType
+    > {
+    public readonly type: TType;
+
+    public constructor(type: TType, _typescriptType?: TTypeScriptType) {
+        super();
+        this.type = type;
+    }
+
+    public getSize(): number {
+        return this.type.size;
+    }
+
+    public create(
+        options: Readonly<StructOptions>,
+        struct: StructValue,
+        value: TTypeScriptType,
+    ): BigIntFieldValue<this> {
+        return new BigIntFieldValue(this, options, struct, value);
+    }
+
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructDeserializeStream,
+        struct: StructValue,
+    ): BigIntFieldValue<this>;
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructAsyncDeserializeStream,
+        struct: StructValue,
+    ): Promise<BigIntFieldValue<this>>;
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructDeserializeStream | StructAsyncDeserializeStream,
+        struct: StructValue,
+    ): ValueOrPromise<BigIntFieldValue<this>> {
+        return Syncbird.try(() => {
+            return stream.read(this.getSize());
+        }).then(array => {
+            const view = new DataView(array.buffer, array.byteOffset, array.byteLength);
+            const value = this.type.getter(
+                view,
+                0,
+                options.littleEndian
+            );
+            return this.create(options, struct, value as any);
+        }).valueOrPromise();
+    }
+}
+
+export class BigIntFieldValue<
+    TDefinition extends BigIntFieldDefinition<BigIntFieldType, any>,
+    > extends StructFieldValue<TDefinition> {
+    public serialize(dataView: DataView, offset: number): void {
+        this.definition.type.setter(
+            dataView,
+            offset,
+            this.value!,
+            this.options.littleEndian
+        );
+    }
+}