@yume-chan/struct 0.0.5 → 0.0.10

package/src/types/number.ts

@@ -1,101 +1,114 @@
-import { FieldDefinition, FieldRuntimeValue, StructDeserializationContext, StructOptions, StructSerializationContext } from '../basic';
-
-export type DataViewGetters =
-    { [TKey in keyof DataView]: TKey extends `get${string}` ? TKey : never }[keyof DataView];
-
-export type DataViewSetters =
-    { [TKey in keyof DataView]: TKey extends `set${string}` ? TKey : never }[keyof DataView];
-
-export class NumberFieldType<TTypeScriptType extends number | bigint = number | bigint> {
-    public static readonly Int8 = new NumberFieldType<number>(1, 'getInt8', 'setInt8');
-
-    public static readonly Uint8 = new NumberFieldType<number>(1, 'getUint8', 'setUint8');
-
-    public static readonly Int16 = new NumberFieldType<number>(2, 'getInt16', 'setInt16');
-
-    public static readonly Uint16 = new NumberFieldType<number>(2, 'getUint16', 'setUint16');
-
-    public static readonly Int32 = new NumberFieldType<number>(4, 'getInt32', 'setInt32');
-
-    public static readonly Uint32 = new NumberFieldType<number>(4, 'getUint32', 'setUint32');
-
-    public static readonly Int64 = new NumberFieldType<bigint>(8, 'getBigInt64', 'setBigInt64');
-
-    public static readonly Uint64 = new NumberFieldType<bigint>(8, 'getBigUint64', 'setBigUint64');
-
-    public readonly valueType!: TTypeScriptType;
-
-    public readonly size: number;
-
-    public readonly dataViewGetter: DataViewGetters;
-
-    public readonly dataViewSetter: DataViewSetters;
-
-    public constructor(
-        size: number,
-        dataViewGetter: DataViewGetters,
-        dataViewSetter: DataViewSetters
-    ) {
-        this.size = size;
-        this.dataViewGetter = dataViewGetter;
-        this.dataViewSetter = dataViewSetter;
-    }
-}
-
-export class NumberFieldDefinition<
-    TType extends NumberFieldType = NumberFieldType,
-    TTypeScriptType = TType['valueType'],
-    > extends FieldDefinition<
-    void,
-    TTypeScriptType
-    > {
-    public readonly type: TType;
-
-    public constructor(type: TType, _typescriptType?: TTypeScriptType) {
-        super();
-        this.type = type;
-    }
-
-    public getSize(): number {
-        return this.type.size;
-    }
-
-    public async deserialize(
-        options: Readonly<StructOptions>,
-        context: StructDeserializationContext,
-        object: any,
-    ): Promise<NumberFieldRuntimeValue<TType, TTypeScriptType>> {
-        const buffer = await context.read(this.getSize());
-        const view = new DataView(buffer);
-        const value = view[this.type.dataViewGetter](
-            0,
-            options.littleEndian
-        ) as any;
-        return this.createValue(options, context, object, value);
-    }
-
-    public createValue(
-        options: Readonly<StructOptions>,
-        context: StructSerializationContext,
-        object: any,
-        value: TTypeScriptType,
-    ): NumberFieldRuntimeValue<TType, TTypeScriptType> {
-        return new NumberFieldRuntimeValue(this, options, context, object, value);
-    }
-}
-
-export class NumberFieldRuntimeValue<
-    TType extends NumberFieldType = NumberFieldType,
-    TTypeScriptType = TType['valueType'],
-    > extends FieldRuntimeValue<NumberFieldDefinition<TType, TTypeScriptType>> {
-    public serialize(dataView: DataView, offset: number): void {
-        // `setBigInt64` requires a `bigint` while others require `number`
-        // So `dataView[DataViewSetters]` requires `bigint & number`
-        // and that is, `never`
-        (dataView[this.definition.type.dataViewSetter] as any)(
-            offset,
-            this.value!,
-            this.options.littleEndian
-        );
-    }
-}
+import { StructAsyncDeserializeStream, StructDeserializeStream, StructFieldDefinition, StructFieldValue, StructOptions, StructValue } from '../basic';
+import { Syncbird } from "../syncbird";
+import { ValueOrPromise } from "../utils";
+
+export type DataViewGetters =
+    { [TKey in keyof DataView]: TKey extends `get${string}` ? TKey : never }[keyof DataView];
+
+export type DataViewSetters =
+    { [TKey in keyof DataView]: TKey extends `set${string}` ? TKey : never }[keyof DataView];
+
+export class NumberFieldType<TTypeScriptType extends number | bigint = number | bigint> {
+    public readonly TTypeScriptType!: TTypeScriptType;
+
+    public readonly size: number;
+
+    public readonly dataViewGetter: DataViewGetters;
+
+    public readonly dataViewSetter: DataViewSetters;
+
+    public constructor(
+        size: number,
+        dataViewGetter: DataViewGetters,
+        dataViewSetter: DataViewSetters
+    ) {
+        this.size = size;
+        this.dataViewGetter = dataViewGetter;
+        this.dataViewSetter = dataViewSetter;
+    }
+
+    public static readonly Int8 = new NumberFieldType<number>(1, 'getInt8', 'setInt8');
+
+    public static readonly Uint8 = new NumberFieldType<number>(1, 'getUint8', 'setUint8');
+
+    public static readonly Int16 = new NumberFieldType<number>(2, 'getInt16', 'setInt16');
+
+    public static readonly Uint16 = new NumberFieldType<number>(2, 'getUint16', 'setUint16');
+
+    public static readonly Int32 = new NumberFieldType<number>(4, 'getInt32', 'setInt32');
+
+    public static readonly Uint32 = new NumberFieldType<number>(4, 'getUint32', 'setUint32');
+
+    public static readonly Int64 = new NumberFieldType<bigint>(8, 'getBigInt64', 'setBigInt64');
+
+    public static readonly Uint64 = new NumberFieldType<bigint>(8, 'getBigUint64', 'setBigUint64');
+}
+
+export class NumberFieldDefinition<
+    TType extends NumberFieldType = NumberFieldType,
+    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,
+    ): NumberFieldValue<this> {
+        return new NumberFieldValue(this, options, struct, value);
+    }
+
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructDeserializeStream,
+        struct: StructValue,
+    ): NumberFieldValue<this>;
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructAsyncDeserializeStream,
+        struct: StructValue,
+    ): Promise<NumberFieldValue<this>>;
+    public override deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructDeserializeStream | StructAsyncDeserializeStream,
+        struct: StructValue,
+    ): ValueOrPromise<NumberFieldValue<this>> {
+        return Syncbird.try(() => {
+            return stream.read(this.getSize());
+        }).then(buffer => {
+            const view = new DataView(buffer);
+            const value = view[this.type.dataViewGetter](
+                0,
+                options.littleEndian
+            ) as any;
+            return this.create(options, struct, value);
+        }).valueOrPromise();
+    }
+}
+
+export class NumberFieldValue<
+    TDefinition extends NumberFieldDefinition<NumberFieldType, any>,
+    > extends StructFieldValue<TDefinition> {
+    public serialize(dataView: DataView, offset: number): void {
+        // `setBigInt64` requires a `bigint` while others require `number`
+        // So `dataView[DataViewSetters]` requires `bigint & number`
+        // and that is, `never`
+        (dataView[this.definition.type.dataViewSetter] as any)(
+            offset,
+            this.value!,
+            this.options.littleEndian
+        );
+    }
+}

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

@@ -1,121 +1,142 @@
-import { FieldRuntimeValue, getRuntimeValue, setRuntimeValue, StructOptions, StructSerializationContext } from '../basic';
-import { ArrayBufferLikeFieldDefinition, ArrayBufferLikeFieldRuntimeValue, ArrayBufferLikeFieldType } from './array-buffer';
-import { KeysOfType } from './utils';
-
-export interface VariableLengthArrayBufferLikeFieldOptions<
-    TFields = object,
-    TLengthField extends KeysOfType<TFields, number | string> = any,
-    > {
-    lengthField: TLengthField;
-}
-
-export class VariableLengthArrayBufferLikeFieldDefinition<
-    TType extends ArrayBufferLikeFieldType = ArrayBufferLikeFieldType,
-    TOptions extends VariableLengthArrayBufferLikeFieldOptions = VariableLengthArrayBufferLikeFieldOptions
-    > extends ArrayBufferLikeFieldDefinition<
-    TType,
-    TOptions,
-    TOptions['lengthField']
-    > {
-    public getSize(): number {
-        return 0;
-    }
-
-    protected getDeserializeSize(object: any) {
-        let value = object[this.options.lengthField] as number | string;
-        if (typeof value === 'string') {
-            value = Number.parseInt(value, 10);
-        }
-        return value;
-    }
-
-    public createValue(
-        options: Readonly<StructOptions>,
-        context: StructSerializationContext,
-        object: any,
-        value: TType['valueType'],
-    ): VariableLengthArrayBufferLikeFieldRuntimeValue<TType, TOptions> {
-        return new VariableLengthArrayBufferLikeFieldRuntimeValue(this, options, context, object, value);
-    }
-}
-
-class VariableLengthArrayBufferLikeLengthFieldRuntimeValue extends FieldRuntimeValue {
-    protected originalValue: FieldRuntimeValue;
-
-    protected arrayBufferValue: VariableLengthArrayBufferLikeFieldRuntimeValue;
-
-    public constructor(
-        originalValue: FieldRuntimeValue,
-        arrayBufferValue: VariableLengthArrayBufferLikeFieldRuntimeValue,
-    ) {
-        super(originalValue.definition, originalValue.options, originalValue.context, originalValue.object, 0);
-        this.originalValue = originalValue;
-        this.arrayBufferValue = arrayBufferValue;
-    }
-
-    public getSize() {
-        return this.originalValue.getSize();
-    }
-
-    get() {
-        // TODO: originalValue might be a `string` type, now it always returns `number`.
-        return this.arrayBufferValue.getSize();
-    }
-
-    set() { }
-
-    serialize(dataView: DataView, offset: number, context: StructSerializationContext) {
-        this.originalValue.set(this.get());
-        this.originalValue.serialize(dataView, offset, context);
-    }
-}
-
-class VariableLengthArrayBufferLikeFieldRuntimeValue<
-    TType extends ArrayBufferLikeFieldType = ArrayBufferLikeFieldType,
-    TOptions extends VariableLengthArrayBufferLikeFieldOptions = VariableLengthArrayBufferLikeFieldOptions
-    > extends ArrayBufferLikeFieldRuntimeValue<VariableLengthArrayBufferLikeFieldDefinition<TType, TOptions>> {
-    public static getSize() {
-        return 0;
-    }
-
-    protected length: number | undefined;
-
-    protected lengthFieldValue: VariableLengthArrayBufferLikeLengthFieldRuntimeValue;
-
-    public constructor(
-        definition: VariableLengthArrayBufferLikeFieldDefinition<TType, TOptions>,
-        options: Readonly<StructOptions>,
-        context: StructSerializationContext,
-        object: any,
-        value: TType['valueType'],
-    ) {
-        super(definition, options, context, object, value);
-
-        // Patch the associated length field.
-        const lengthField = this.definition.options.lengthField;
-        const originalValue = getRuntimeValue(object, lengthField);
-        this.lengthFieldValue = new VariableLengthArrayBufferLikeLengthFieldRuntimeValue(originalValue, this);
-        setRuntimeValue(object, lengthField, this.lengthFieldValue);
-    }
-
-    public getSize() {
-        if (this.length === undefined) {
-            if (this.arrayBuffer !== undefined) {
-                this.length = this.arrayBuffer.byteLength;
-            } else {
-                this.length = this.definition.type.getSize(this.value);
-                if (this.length === -1) {
-                    this.arrayBuffer = this.definition.type.toArrayBuffer(this.value, this.context);
-                    this.length = this.arrayBuffer.byteLength;
-                }
-            }
-        }
-
-        return this.length;
-    }
-
-    public set(value: unknown) {
-        super.set(value);
-        this.length = undefined;
-    }
-}
+import { StructFieldDefinition, StructFieldValue, StructOptions, StructValue } from '../basic';
+import type { KeysOfType } from '../utils';
+import { ArrayBufferLikeFieldDefinition, ArrayBufferLikeFieldType, ArrayBufferLikeFieldValue } from './array-buffer';
+
+export type LengthField<TFields> = KeysOfType<TFields, number | string>;
+
+export interface VariableLengthArrayBufferLikeFieldOptions<
+    TFields = object,
+    TLengthField extends LengthField<TFields> = any,
+    > {
+    lengthField: TLengthField;
+
+    lengthFieldBase?: number;
+}
+
+export class VariableLengthArrayBufferLikeFieldDefinition<
+    TType extends ArrayBufferLikeFieldType = ArrayBufferLikeFieldType,
+    TOptions extends VariableLengthArrayBufferLikeFieldOptions = VariableLengthArrayBufferLikeFieldOptions
+    > extends ArrayBufferLikeFieldDefinition<
+    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.lengthFieldBase ?? 10);
+        }
+        return value;
+    }
+
+    public override create(
+        options: Readonly<StructOptions>,
+        struct: StructValue,
+        value: TType['TTypeScriptType'],
+        arrayBuffer?: ArrayBuffer
+    ): VariableLengthArrayBufferLikeStructFieldValue<this> {
+        return new VariableLengthArrayBufferLikeStructFieldValue(
+            this,
+            options,
+            struct,
+            value,
+            arrayBuffer,
+        );
+    }
+}
+
+export class VariableLengthArrayBufferLikeStructFieldValue<
+    TDefinition extends VariableLengthArrayBufferLikeFieldDefinition = VariableLengthArrayBufferLikeFieldDefinition,
+    > extends ArrayBufferLikeFieldValue<TDefinition> {
+    protected length: number | undefined;
+
+    protected lengthFieldValue: VariableLengthArrayBufferLikeFieldLengthValue;
+
+    public constructor(
+        definition: TDefinition,
+        options: Readonly<StructOptions>,
+        struct: StructValue,
+        value: TDefinition['TValue'],
+        arrayBuffer?: ArrayBuffer,
+    ) {
+        super(definition, options, struct, value, arrayBuffer);
+
+        if (arrayBuffer) {
+            this.length = arrayBuffer.byteLength;
+        }
+
+        // Patch the associated length field.
+        const lengthField = this.definition.options.lengthField;
+
+        const originalValue = struct.get(lengthField);
+        this.lengthFieldValue = new VariableLengthArrayBufferLikeFieldLengthValue(
+            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.arrayBuffer = this.definition.type.toArrayBuffer(this.value);
+                this.length = this.arrayBuffer.byteLength;
+            }
+        }
+
+        return this.length;
+    }
+
+    public override set(value: unknown) {
+        super.set(value);
+        this.arrayBuffer = undefined;
+        this.length = undefined;
+    }
+}
+
+// Not using `VariableLengthArrayBufferLikeStructFieldValue` directly makes writing tests much easier...
+type VariableLengthArrayBufferLikeFieldValueLike =
+    StructFieldValue<StructFieldDefinition<VariableLengthArrayBufferLikeFieldOptions, any, any>>;
+
+export class VariableLengthArrayBufferLikeFieldLengthValue
+    extends StructFieldValue {
+    protected originalField: StructFieldValue;
+
+    protected arrayBufferField: VariableLengthArrayBufferLikeFieldValueLike;
+
+    public constructor(
+        originalField: StructFieldValue,
+        arrayBufferField: VariableLengthArrayBufferLikeFieldValueLike,
+    ) {
+        super(originalField.definition, originalField.options, originalField.struct, 0);
+        this.originalField = originalField;
+        this.arrayBufferField = arrayBufferField;
+    }
+
+    public override getSize() {
+        return this.originalField.getSize();
+    }
+
+    public override get() {
+        let value: string | number = this.arrayBufferField.getSize();
+
+        const originalValue = this.originalField.get();
+        if (typeof originalValue === 'string') {
+            value = value.toString(this.arrayBufferField.definition.options.lengthFieldBase ?? 10);
+        }
+
+        return value;
+    }
+
+    public override set() { }
+
+    serialize(dataView: DataView, offset: number) {
+        this.originalField.set(this.get());
+        this.originalField.serialize(dataView, offset);
+    }
+}

package/src/{types/utils.ts → utils.ts}

@@ -1,47 +1,62 @@
-/**
- * When evaluating a very complex generic type alias,
- * tell TypeScript to use `T`, instead of current type alias' name, as the result type name
- *
- * Example:
- *
- * ```ts
- * type WithIdentity<T> = Identity<SomeType<T>>;
- * type WithoutIdentity<T> = SomeType<T>;
- *
- * type WithIdentityResult = WithIdentity<number>;
- * // Hover on this one shows `SomeType<number>`
- *
- * type WithoutIdentityResult = WithoutIdentity<number>;
- * // Hover on this one shows `WithoutIdentity<number>`
- * ```
- */
-export type Identity<T> = T;
-
-/**
- * Collapse an intersection type (`{ foo: string } & { bar: number }`) to a simple type (`{ foo: string, bar: number }`)
- */
-export type Evaluate<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
-
-/**
- * Overwrite fields in `TBase` with fields in `TNew`
- */
-export type Overwrite<TBase extends object, TNew extends object> =
-    Evaluate<Omit<TBase, keyof TNew> & TNew>;
-
-/**
- * Remove fields with `never` type
- */
-export type OmitNever<T> = Pick<T, { [K in keyof T]: [T[K]] extends [never] ? never : K }[keyof T]>;
-
-/**
- * Extract keys of fields in `T` that has type `TValue`
- */
-export type KeysOfType<T, TValue> =
-    { [TKey in keyof T]: T[TKey] extends TValue ? TKey : never }[keyof T];
-
-/**
- * Returns a (fake) value of the given type.
- */
-export function placeholder<T>(): T {
-    return undefined as unknown as T;
-}
+/**
+ * When evaluating a very complex generic type alias,
+ * tell TypeScript to use `T`, instead of current type alias' name, as the result type name
+ *
+ * Example:
+ *
+ * ```ts
+ * type WithIdentity<T> = Identity<SomeType<T>>;
+ * type WithoutIdentity<T> = SomeType<T>;
+ *
+ * type WithIdentityResult = WithIdentity<number>;
+ * // Hover on this one shows `SomeType<number>`
+ *
+ * type WithoutIdentityResult = WithoutIdentity<number>;
+ * // Hover on this one shows `WithoutIdentity<number>`
+ * ```
+ */
+export type Identity<T> = T;
+
+/**
+ * Collapse an intersection type (`{ foo: string } & { bar: number }`) to a simple type (`{ foo: string, bar: number }`)
+ */
+export type Evaluate<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
+
+/**
+ * Overwrite fields in `TBase` with fields in `TNew`
+ */
+export type Overwrite<TBase extends object, TNew extends object> =
+    Evaluate<Omit<TBase, keyof TNew> & TNew>;
+
+/**
+ * Remove fields with `never` type
+ */
+export type OmitNever<T> = Pick<T, { [K in keyof T]: [T[K]] extends [never] ? never : K }[keyof T]>;
+
+/**
+ * Extract keys of fields in `T` that has type `TValue`
+ */
+export type KeysOfType<T, TValue> =
+    { [TKey in keyof T]: T[TKey] extends TValue ? TKey : never }[keyof T];
+
+export type ValueOrPromise<T> = T | PromiseLike<T>;
+
+/**
+ * Returns a (fake) value of the given type.
+ */
+export function placeholder<T>(): T {
+    return undefined as unknown as T;
+}
+
+// @ts-expect-error @types/node missing `TextEncoder`
+const Utf8Encoder = new TextEncoder();
+// @ts-expect-error @types/node missing `TextDecoder`
+const Utf8Decoder = new TextDecoder();
+
+export function encodeUtf8(input: string): ArrayBuffer {
+    return Utf8Encoder.encode(input).buffer;
+}
+
+export function decodeUtf8(buffer: ArrayBuffer): string {
+    return Utf8Decoder.decode(buffer);
+}

package/cjs/basic/context.js

@@ -1,7 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.StructDefaultOptions = void 0;
-exports.StructDefaultOptions = {
-    littleEndian: false,
-};
-//# sourceMappingURL=context.js.map

package/cjs/basic/context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/basic/context.ts"],"names":[],"mappings":";;;AAqCa,QAAA,oBAAoB,GAA4B;IACzD,YAAY,EAAE,KAAK;CACtB,CAAC"}

package/cjs/basic/definition.js

@@ -1,26 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FieldDefinition = void 0;
-/**
- * A field definition is a bridge between its type and its runtime value.
- *
- * `Struct` record fields in a list of `FieldDefinition`s.
- *
- * When `Struct#create` or `Struct#deserialize` are called, each field's definition
- * crates its own type of `FieldRuntimeValue` to manage the field value in that `Struct` instance.
- *
- * One `FieldDefinition` can represents multiple similar types, just returns the corresponding
- * `FieldRuntimeValue` when `createValue` was called.
- *
- * @template TOptions TypeScript type of this definition's `options`.
- * @template TValueType TypeScript type of this field.
- * @template TOmitInit Optionally remove some fields from the init type. Should be a union of string literal types.
- */
-var FieldDefinition = /** @class */ (function () {
-    function FieldDefinition(options) {
-        this.options = options;
-    }
-    return FieldDefinition;
-}());
-exports.FieldDefinition = FieldDefinition;
-//# sourceMappingURL=definition.js.map

package/cjs/basic/definition.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/basic/definition.ts"],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;;GAcG;AACH;IAmBI,yBAAmB,OAAiB;QAChC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IA2BL,sBAAC;AAAD,CAAC,AAhDD,IAgDC;AAhDqB,0CAAe"}

package/cjs/basic/index.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-var tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./context"), exports);
-tslib_1.__exportStar(require("./definition"), exports);
-tslib_1.__exportStar(require("./runtime-value"), exports);
-tslib_1.__exportStar(require("./runtime-object"), exports);
-//# sourceMappingURL=index.js.map

package/cjs/basic/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/basic/index.ts"],"names":[],"mappings":";;;AAAA,oDAA0B;AAC1B,uDAA6B;AAC7B,0DAAgC;AAChC,2DAAiC"}