@yume-chan/struct 0.0.9 → 0.0.13

package/src/syncbird.ts

@@ -0,0 +1,131 @@
+// cspell: ignore syncbird
+
+import Bluebird from 'bluebird';
+
+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>;
+
+    then<U>(onFulfill?: (value: R) => Resolvable<U>, onReject?: (error: any) => Resolvable<U>): Syncbird<U>; // For simpler signature help.
+    then<TResult1 = R, TResult2 = never>(
+        onfulfilled?: ((value: R) => Resolvable<TResult1>) | null,
+        onrejected?: ((reason: any) => Resolvable<TResult2>) | null
+    ): Syncbird<TResult1 | TResult2>;
+}
+
+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.
+     */
+    resolve(): Syncbird<void>;
+    resolve<R>(value: Resolvable<R>): Syncbird<R>;
+
+    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;
+
+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;
+        } else {
+            // 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 {
+        // Forward to Bluebird's `_then` method.
+        return _then.call(this, onfulfilled, onrejected, _, receiver, internalData);
+    }
+};
+
+(Syncbird.prototype as any).valueOrPromise = function <T>(this: Bluebird<T>): T | PromiseLike<T> {
+    if (this.isFulfilled()) {
+        return this.value();
+    } else {
+        return this as Promise<T>;
+    }
+};

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
+        );
+    }
+}

package/src/types/buffer/base.ts

@@ -0,0 +1,176 @@
+// cspell: ignore syncbird
+
+import { StructFieldDefinition, StructFieldValue, StructValue, type StructAsyncDeserializeStream, type StructDeserializeStream, type StructOptions } from '../../basic/index.js';
+import { Syncbird } from "../../syncbird.js";
+import { decodeUtf8, encodeUtf8, type ValueOrPromise } from "../../utils.js";
+
+/**
+ * Base class for all types that
+ * can be converted from an `Uint8Array` when deserialized,
+ * and need to be converted to an `Uint8Array` when serializing
+ *
+ * @template TValue The actual TypeScript type of this type
+ * @template TTypeScriptType Optional another type (should be compatible with `TType`)
+ * specified by user when creating field definitions.
+ */
+export abstract class BufferFieldSubType<TValue = unknown, TTypeScriptType = TValue> {
+    public readonly TTypeScriptType!: TTypeScriptType;
+
+    /**
+     * When implemented in derived classes, converts the type-specific `value` to an `Uint8Array`
+     *
+     * This function should be "pure", i.e.,
+     * same `value` should always be converted to `Uint8Array`s that have same content.
+     */
+    public abstract toBuffer(value: TValue): Uint8Array;
+
+    /** When implemented in derived classes, converts the `Uint8Array` to a type-specific value */
+    public abstract toValue(array: Uint8Array): TValue;
+
+    /**
+     * When implemented in derived classes, gets the size in byte of the type-specific `value`.
+     *
+     * If the size can't be calculated without first converting the `value` back to an `Uint8Array`,
+     * implementer can returns `-1`, so the caller will get its size by first converting it to
+     * an `Uint8Array` (and cache the result).
+     */
+    public abstract getSize(value: TValue): number;
+}
+
+/** An `BufferFieldSubType` that's actually an `Uint8Array` */
+export class Uint8ArrayBufferFieldSubType extends BufferFieldSubType<Uint8Array> {
+    public static readonly Instance = new Uint8ArrayBufferFieldSubType();
+
+    protected constructor() {
+        super();
+    }
+
+    public toBuffer(value: Uint8Array): Uint8Array {
+        return value;
+    }
+
+    public toValue(buffer: Uint8Array): Uint8Array {
+        return buffer;
+    }
+
+    public getSize(value: Uint8Array): number {
+        return value.byteLength;
+    }
+}
+
+/** An `BufferFieldSubType` that converts between `Uint8Array` and `string` */
+export class StringBufferFieldSubType<TTypeScriptType = string>
+    extends BufferFieldSubType<string, TTypeScriptType> {
+    public static readonly Instance = new StringBufferFieldSubType();
+
+    public toBuffer(value: string): Uint8Array {
+        return encodeUtf8(value);
+    }
+
+    public toValue(array: Uint8Array): string {
+        return decodeUtf8(array);
+    }
+
+    public getSize(): number {
+        // Return `-1`, so `BufferLikeFieldDefinition` will
+        // convert this `value` into an `Uint8Array` (and cache the result),
+        // Then get the size from that `Uint8Array`
+        return -1;
+    }
+}
+
+const EmptyBuffer = new Uint8Array(0);
+
+export abstract class BufferLikeFieldDefinition<
+    TType extends BufferFieldSubType<any, any> = BufferFieldSubType<unknown, unknown>,
+    TOptions = void,
+    TOmitInitKey extends PropertyKey = never,
+    > extends StructFieldDefinition<
+    TOptions,
+    TType['TTypeScriptType'],
+    TOmitInitKey
+    >{
+    public readonly type: TType;
+
+    public constructor(type: TType, options: TOptions) {
+        super(options);
+        this.type = type;
+    }
+
+    protected getDeserializeSize(struct: StructValue): number {
+        return this.getSize();
+    }
+
+    /**
+     * When implemented in derived classes, creates a `StructFieldValue` for the current field definition.
+     */
+    public create(
+        options: Readonly<StructOptions>,
+        struct: StructValue,
+        value: TType['TTypeScriptType'],
+        array?: Uint8Array,
+    ): BufferLikeFieldValue<this> {
+        return new BufferLikeFieldValue(this, options, struct, value, array);
+    }
+
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructDeserializeStream,
+        struct: StructValue,
+    ): BufferLikeFieldValue<this>;
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructAsyncDeserializeStream,
+        struct: StructValue,
+    ): Promise<BufferLikeFieldValue<this>>;
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructDeserializeStream | StructAsyncDeserializeStream,
+        struct: StructValue,
+    ): ValueOrPromise<BufferLikeFieldValue<this>> {
+        return Syncbird.try(() => {
+            const size = this.getDeserializeSize(struct);
+            if (size === 0) {
+                return EmptyBuffer;
+            } else {
+                return stream.read(size);
+            }
+        }).then(array => {
+            const value = this.type.toValue(array);
+            return this.create(options, struct, value, array);
+        }).valueOrPromise();
+    }
+}
+
+export class BufferLikeFieldValue<
+    TDefinition extends BufferLikeFieldDefinition<BufferFieldSubType<unknown, unknown>, any, any>,
+    > extends StructFieldValue<TDefinition> {
+    protected array: Uint8Array | undefined;
+
+    public constructor(
+        definition: TDefinition,
+        options: Readonly<StructOptions>,
+        struct: StructValue,
+        value: TDefinition['TValue'],
+        array?: Uint8Array,
+    ) {
+        super(definition, options, struct, value);
+        this.array = array;
+    }
+
+    public override set(value: TDefinition['TValue']): void {
+        super.set(value);
+        // When value changes, clear the cached `array`
+        // It will be lazily calculated in `serialize()`
+        this.array = undefined;
+    }
+
+    public serialize(dataView: DataView, offset: number): void {
+        if (!this.array) {
+            this.array = this.definition.type.toBuffer(this.value);
+        }
+
+        new Uint8Array(dataView.buffer, dataView.byteOffset, dataView.byteLength)
+            .set(this.array, offset);
+    }
+}

package/src/types/buffer/fixed-length.ts

@@ -0,0 +1,17 @@
+import { BufferLikeFieldDefinition, type BufferFieldSubType } from "./base.js";
+
+export interface FixedLengthBufferLikeFieldOptions {
+    length: number;
+}
+
+export class FixedLengthBufferLikeFieldDefinition<
+    TType extends BufferFieldSubType = BufferFieldSubType,
+    TOptions extends FixedLengthBufferLikeFieldOptions = FixedLengthBufferLikeFieldOptions,
+    > extends BufferLikeFieldDefinition<
+    TType,
+    TOptions
+    > {
+    public getSize(): number {
+        return this.options.length;
+    }
+};

package/src/types/buffer/index.ts

@@ -0,0 +1,3 @@
+export * from "./base.js";
+export * from "./fixed-length.js";
+export * from "./variable-length.js";

package/src/types/buffer/variable-length.ts

@@ -0,0 +1,156 @@
+import { StructFieldValue, type StructFieldDefinition, type StructOptions, type StructValue } from '../../basic/index.js';
+import type { KeysOfType } from '../../utils.js';
+import { BufferLikeFieldDefinition, BufferLikeFieldValue, type BufferFieldSubType } from './base.js';
+
+export type LengthField<TFields> = KeysOfType<TFields, number | string>;
+
+export interface VariableLengthBufferLikeFieldOptions<
+    TFields = object,
+    TLengthField extends LengthField<TFields> = any,
+    > {
+    /**
+     * The name of the field that contains the length of the buffer.
+     *
+     * This field must be a `number` or `string` (can't be `bigint`) field.
+     */
+    lengthField: TLengthField;
+
+    /**
+     * If the `lengthField` refers to a string field,
+     * what radix to use when converting the string to a number.
+     *
+     * @default 10
+     */
+    lengthFieldRadix?: number;
+}
+
+export class VariableLengthBufferLikeFieldDefinition<
+    TType extends BufferFieldSubType = BufferFieldSubType,
+    TOptions extends VariableLengthBufferLikeFieldOptions = VariableLengthBufferLikeFieldOptions
+    > extends BufferLikeFieldDefinition<
+    TType,
+    TOptions,
+    TOptions['lengthField']
+    > {
+    public getSize(): number {
+        return 0;
+    }
+
+    protected override getDeserializeSize(struct: StructValue) {
+        let value = struct.value[this.options.lengthField] as number | string;
+        if (typeof value === 'string') {
+            value = Number.parseInt(value, this.options.lengthFieldRadix ?? 10);
+        }
+        return value;
+    }
+
+    public override create(
+        options: Readonly<StructOptions>,
+        struct: StructValue,
+        value: TType['TTypeScriptType'],
+        array?: Uint8Array
+    ): VariableLengthBufferLikeStructFieldValue<this> {
+        return new VariableLengthBufferLikeStructFieldValue(
+            this,
+            options,
+            struct,
+            value,
+            array,
+        );
+    }
+}
+
+export class VariableLengthBufferLikeStructFieldValue<
+    TDefinition extends VariableLengthBufferLikeFieldDefinition = VariableLengthBufferLikeFieldDefinition,
+    > extends BufferLikeFieldValue<TDefinition> {
+    protected length: number | undefined;
+
+    protected lengthFieldValue: VariableLengthBufferLikeFieldLengthValue;
+
+    public constructor(
+        definition: TDefinition,
+        options: Readonly<StructOptions>,
+        struct: StructValue,
+        value: TDefinition['TValue'],
+        array?: Uint8Array,
+    ) {
+        super(definition, options, struct, value, array);
+
+        if (array) {
+            this.length = array.byteLength;
+        }
+
+        // Patch the associated length field.
+        const lengthField = this.definition.options.lengthField;
+
+        const originalValue = struct.get(lengthField);
+        this.lengthFieldValue = new VariableLengthBufferLikeFieldLengthValue(
+            originalValue,
+            this,
+        );
+        struct.set(lengthField, this.lengthFieldValue);
+    }
+
+    public override getSize() {
+        if (this.length === undefined) {
+            this.length = this.definition.type.getSize(this.value);
+            if (this.length === -1) {
+                this.array = this.definition.type.toBuffer(this.value);
+                this.length = this.array.byteLength;
+            }
+        }
+
+        return this.length;
+    }
+
+    public override set(value: unknown) {
+        super.set(value);
+        this.array = undefined;
+        this.length = undefined;
+    }
+}
+
+// Not using `VariableLengthBufferLikeStructFieldValue` directly makes writing tests much easier...
+type VariableLengthBufferLikeFieldValueLike =
+    StructFieldValue<StructFieldDefinition<VariableLengthBufferLikeFieldOptions, any, any>>;
+
+export class VariableLengthBufferLikeFieldLengthValue
+    extends StructFieldValue {
+    protected originalField: StructFieldValue;
+
+    protected bufferField: VariableLengthBufferLikeFieldValueLike;
+
+    public constructor(
+        originalField: StructFieldValue,
+        arrayBufferField: VariableLengthBufferLikeFieldValueLike,
+    ) {
+        super(originalField.definition, originalField.options, originalField.struct, 0);
+        this.originalField = originalField;
+        this.bufferField = arrayBufferField;
+    }
+
+    public override getSize() {
+        return this.originalField.getSize();
+    }
+
+    public override get() {
+        let value: string | number = this.bufferField.getSize();
+
+        const originalValue = this.originalField.get();
+        if (typeof originalValue === 'string') {
+            value = value.toString(this.bufferField.definition.options.lengthFieldRadix ?? 10);
+        }
+
+        return value;
+    }
+
+    public override set() {
+        // Ignore setting
+        // It will always be in sync with the buffer size
+    }
+
+    serialize(dataView: DataView, offset: number) {
+        this.originalField.set(this.get());
+        this.originalField.serialize(dataView, offset);
+    }
+}

package/src/types/index.ts

@@ -1,4 +1,3 @@
-export * from './array-buffer';
-export * from './fixed-length-array-buffer';
-export * from './number';
-export * from './variable-length-array-buffer';
+export * from "./bigint.js";
+export * from "./buffer/index.js";
+export * from "./number.js";