@yume-chan/struct 0.0.13 → 0.0.16

package/src/basic/definition.ts

@@ -1,70 +1,68 @@
-// cspell: ignore Syncbird
-
-import type { StructAsyncDeserializeStream, StructDeserializeStream } from "./stream.js";
-import type { StructFieldValue } from "./field-value.js";
-import type { StructValue } from "./struct-value.js";
-import type { StructOptions } from "./options.js";
-
-/**
- * A field definition defines how to deserialize a field.
- *
- * @template TOptions TypeScript type of this definition's `options`.
- * @template TValue TypeScript type of this field.
- * @template TOmitInitKey Optionally remove some fields from the init type. Should be a union of string literal types.
- */
-export abstract class StructFieldDefinition<
-    TOptions = void,
-    TValue = unknown,
-    TOmitInitKey extends PropertyKey = never,
-    > {
-    /**
-     * When `T` is a type initiated `StructFieldDefinition`,
-     * use `T['TValue']` to retrieve its `TValue` type parameter.
-     */
-    public readonly TValue!: TValue;
-
-    /**
-     * When `T` is a type initiated `StructFieldDefinition`,
-     * use `T['TOmitInitKey']` to retrieve its `TOmitInitKey` type parameter.
-     */
-    public readonly TOmitInitKey!: TOmitInitKey;
-
-    public readonly options: TOptions;
-
-    public constructor(options: TOptions) {
-        this.options = options;
-    }
-
-    /**
-     * When implemented in derived classes, returns the size (or minimal size if it's dynamic) of this field.
-     *
-     * Actual size can be retrieved from `StructFieldValue#getSize`
-     */
-    public abstract getSize(): number;
-
-    /**
-     * When implemented in derived classes, creates a `StructFieldValue` from a given `value`.
-     */
-    public abstract create(
-        options: Readonly<StructOptions>,
-        struct: StructValue,
-        value: TValue,
-    ): StructFieldValue<this>;
-
-    /**
-     * When implemented in derived classes,It must be synchronous (returns a value) or asynchronous (returns a `Promise`) depending
-     * on the type of `stream`. reads and creates a `StructFieldValue` from `stream`.
-     *
-     *  `Syncbird` can be used to make the implementation easier.
-     */
-    public abstract deserialize(
-        options: Readonly<StructOptions>,
-        stream: StructDeserializeStream,
-        struct: StructValue,
-    ): StructFieldValue<this>;
-    public abstract deserialize(
-        options: Readonly<StructOptions>,
-        stream: StructAsyncDeserializeStream,
-        struct: StructValue,
-    ): Promise<StructFieldValue<this>>;
-}
+import type { StructAsyncDeserializeStream, StructDeserializeStream } from "./stream.js";
+import type { StructFieldValue } from "./field-value.js";
+import type { StructValue } from "./struct-value.js";
+import type { StructOptions } from "./options.js";
+
+/**
+ * A field definition defines how to deserialize a field.
+ *
+ * @template TOptions TypeScript type of this definition's `options`.
+ * @template TValue TypeScript type of this field.
+ * @template TOmitInitKey Optionally remove some fields from the init type. Should be a union of string literal types.
+ */
+export abstract class StructFieldDefinition<
+    TOptions = void,
+    TValue = unknown,
+    TOmitInitKey extends PropertyKey = never,
+    > {
+    /**
+     * When `T` is a type initiated `StructFieldDefinition`,
+     * use `T['TValue']` to retrieve its `TValue` type parameter.
+     */
+    public readonly TValue!: TValue;
+
+    /**
+     * When `T` is a type initiated `StructFieldDefinition`,
+     * use `T['TOmitInitKey']` to retrieve its `TOmitInitKey` type parameter.
+     */
+    public readonly TOmitInitKey!: TOmitInitKey;
+
+    public readonly options: TOptions;
+
+    public constructor(options: TOptions) {
+        this.options = options;
+    }
+
+    /**
+     * When implemented in derived classes, returns the size (or minimal size if it's dynamic) of this field.
+     *
+     * Actual size can be retrieved from `StructFieldValue#getSize`
+     */
+    public abstract getSize(): number;
+
+    /**
+     * When implemented in derived classes, creates a `StructFieldValue` from a given `value`.
+     */
+    public abstract create(
+        options: Readonly<StructOptions>,
+        structValue: StructValue,
+        value: TValue,
+    ): StructFieldValue<this>;
+
+    /**
+     * When implemented in derived classes,It must be synchronous (returns a value) or asynchronous (returns a `Promise`) depending
+     * on the type of `stream`. reads and creates a `StructFieldValue` from `stream`.
+     *
+     *  `SyncPromise` can be used to simplify implementation.
+     */
+    public abstract deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructDeserializeStream,
+        structValue: StructValue,
+    ): StructFieldValue<this>;
+    public abstract deserialize(
+        options: Readonly<StructOptions>,
+        stream: StructAsyncDeserializeStream,
+        struct: StructValue,
+    ): Promise<StructFieldValue<this>>;
+}

package/src/basic/field-value.ts

@@ -1,67 +1,72 @@
-import type { StructFieldDefinition } from "./definition.js";
-import type { StructOptions } from "./options.js";
-import type { StructValue } from "./struct-value.js";
-
-/**
- * A field value defines how to serialize a field.
- *
- * It may contains extra metadata about the value which are essential or
- * helpful for the serialization process.
- */
-export abstract class StructFieldValue<
-    TDefinition extends StructFieldDefinition<any, any, any> = StructFieldDefinition<any, any, any>
-    > {
-    /** Gets the definition associated with this runtime value */
-    public readonly definition: TDefinition;
-
-    /** Gets the options of the associated `Struct` */
-    public readonly options: Readonly<StructOptions>;
-
-    /** Gets the associated `Struct` instance */
-    public readonly struct: StructValue;
-
-    protected value: TDefinition['TValue'];
-
-    public constructor(
-        definition: TDefinition,
-        options: Readonly<StructOptions>,
-        struct: StructValue,
-        value: TDefinition['TValue'],
-    ) {
-        this.definition = definition;
-        this.options = options;
-        this.struct = struct;
-        this.value = value;
-    }
-
-    /**
-     * Gets size of this field. By default, it returns its `definition`'s size.
-     *
-     * When overridden in derived classes, can have custom logic to calculate the actual size.
-     */
-    public getSize(): number {
-        return this.definition.getSize();
-    }
-
-    /**
-     * When implemented in derived classes, reads current field's value.
-     */
-    public get(): TDefinition['TValue'] {
-        return this.value;
-    }
-
-    /**
-     * When implemented in derived classes, updates current field's value.
-     */
-    public set(value: TDefinition['TValue']): void {
-        this.value = value;
-    }
-
-    /**
-     * When implemented in derived classes, serializes this field into `dataView` at `offset`
-     */
-    public abstract serialize(
-        dataView: DataView,
-        offset: number,
-    ): void;
-}
+import type { StructFieldDefinition } from "./definition.js";
+import type { StructOptions } from "./options.js";
+import type { StructValue } from "./struct-value.js";
+
+/**
+ * A field value defines how to serialize a field.
+ *
+ * It may contains extra metadata about the value which are essential or
+ * helpful for the serialization process.
+ */
+export abstract class StructFieldValue<
+    TDefinition extends StructFieldDefinition<any, any, any> = StructFieldDefinition<any, any, any>
+    > {
+    /** Gets the definition associated with this runtime value */
+    public readonly definition: TDefinition;
+
+    /** Gets the options of the associated `Struct` */
+    public readonly options: Readonly<StructOptions>;
+
+    /** Gets the associated `Struct` instance */
+    public readonly struct: StructValue;
+
+    public get hasCustomAccessors(): boolean {
+        return this.get !== StructFieldValue.prototype.get ||
+            this.set !== StructFieldValue.prototype.set;
+    }
+
+    protected value: TDefinition['TValue'];
+
+    public constructor(
+        definition: TDefinition,
+        options: Readonly<StructOptions>,
+        struct: StructValue,
+        value: TDefinition['TValue'],
+    ) {
+        this.definition = definition;
+        this.options = options;
+        this.struct = struct;
+        this.value = value;
+    }
+
+    /**
+     * Gets size of this field. By default, it returns its `definition`'s size.
+     *
+     * When overridden in derived classes, can have custom logic to calculate the actual size.
+     */
+    public getSize(): number {
+        return this.definition.getSize();
+    }
+
+    /**
+     * When implemented in derived classes, reads current field's value.
+     */
+    public get(): TDefinition['TValue'] {
+        return this.value;
+    }
+
+    /**
+     * When implemented in derived classes, updates current field's value.
+     */
+    public set(value: TDefinition['TValue']): void {
+        this.value = value;
+    }
+
+    /**
+     * When implemented in derived classes, serializes this field into `dataView` at `offset`
+     */
+    public abstract serialize(
+        dataView: DataView,
+        offset: number,
+    ): void;
+}

package/src/basic/index.ts

@@ -1,5 +1,5 @@
-export * from './definition.js';
-export * from './field-value.js';
-export * from './options.js';
-export * from './stream.js';
-export * from './struct-value.js';
+export * from './definition.js';
+export * from './field-value.js';
+export * from './options.js';
+export * from './stream.js';
+export * from './struct-value.js';

package/src/basic/options.ts

@@ -1,19 +1,19 @@
-export interface StructOptions {
-    /**
-     * Whether all multi-byte fields in this struct are little-endian encoded.
-     *
-     * @default false
-     */
-    littleEndian: boolean;
-
-    // TODO: StructOptions: investigate whether this is necessary
-    // I can't think about any other options which need to be struct wide.
-    // Even endianness can be set on a per-field basis (because it's not meaningful
-    // for some field types like `Uint8Array`, and very rarely, a struct may contain
-    // mixed endianness).
-    // It's just more common and a little more convenient to have it here.
-}
-
-export const StructDefaultOptions: Readonly<StructOptions> = {
-    littleEndian: false,
-};
+export interface StructOptions {
+    /**
+     * Whether all multi-byte fields in this struct are little-endian encoded.
+     *
+     * @default false
+     */
+    littleEndian: boolean;
+
+    // TODO: StructOptions: investigate whether this is necessary
+    // I can't think about any other options which need to be struct wide.
+    // Even endianness can be set on a per-field basis (because it's not meaningful
+    // for some field types like `Uint8Array`, and very rarely, a struct may contain
+    // mixed endianness).
+    // It's just more common and a little more convenient to have it here.
+}
+
+export const StructDefaultOptions: Readonly<StructOptions> = {
+    littleEndian: false,
+};

package/src/basic/stream.ts

@@ -1,19 +1,21 @@
-export interface StructDeserializeStream {
-    /**
-     * 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.
-     */
-    read(length: number): Uint8Array;
-}
-
-export interface StructAsyncDeserializeStream {
-    /**
-     * 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.
-     */
-    read(length: number): Promise<Uint8Array>;
-}
+import type { ValueOrPromise } from "../utils.js";
+
+export interface StructDeserializeStream {
+    /**
+     * 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.
+     */
+    read(length: number): Uint8Array;
+}
+
+export interface StructAsyncDeserializeStream {
+    /**
+     * 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.
+     */
+    read(length: number): ValueOrPromise<Uint8Array>;
+}

package/src/basic/struct-value.ts

@@ -1,39 +1,61 @@
-import type { StructFieldValue } from "./field-value.js";
-
-/**
- * A struct value is a map between keys in a struct and their field values.
- */
-export class StructValue {
-    /** @internal */ readonly fieldValues: Record<PropertyKey, StructFieldValue> = {};
-
-    /**
-     * Gets the result struct value object
-     */
-    public readonly value: Record<PropertyKey, unknown> = {};
-
-    /**
-     * Sets a `StructFieldValue` for `key`
-     *
-     * @param key The field name
-     * @param value The associated `StructFieldValue`
-     */
-    public set(key: PropertyKey, value: StructFieldValue): void {
-        this.fieldValues[key] = value;
-
-        Object.defineProperty(this.value, key, {
-            configurable: true,
-            enumerable: true,
-            get() { return value.get(); },
-            set(v) { value.set(v); },
-        });
-    }
-
-    /**
-     * Gets the `StructFieldValue` for `key`
-     *
-     * @param key The field name
-     */
-    public get(key: PropertyKey): StructFieldValue {
-        return this.fieldValues[key]!;
-    }
-}
+import type { StructFieldValue } from "./field-value.js";
+
+export const STRUCT_VALUE_SYMBOL = Symbol("struct-value");
+
+/**
+ * A struct value is a map between keys in a struct and their field values.
+ */
+export class StructValue {
+    /** @internal */ readonly fieldValues: Record<PropertyKey, StructFieldValue> = {};
+
+    /**
+     * Gets the result struct value object
+     */
+    public readonly value: Record<PropertyKey, unknown>;
+
+    public constructor(prototype: any) {
+        // PERF: `Object.create(extra)` is 50% faster
+        // than `Object.defineProperties(this.value, extra)`
+        this.value = Object.create(prototype);
+
+        // PERF: `Object.defineProperty` is slow
+        // but we need it to be non-enumerable
+        Object.defineProperty(
+            this.value,
+            STRUCT_VALUE_SYMBOL,
+            { enumerable: false, value: this }
+        );
+    }
+
+    /**
+     * Sets a `StructFieldValue` for `key`
+     *
+     * @param name The field name
+     * @param fieldValue The associated `StructFieldValue`
+     */
+    public set(name: PropertyKey, fieldValue: StructFieldValue): void {
+        this.fieldValues[name] = fieldValue;
+
+        // PERF: `Object.defineProperty` is slow
+        // use normal property when possible
+        if (fieldValue.hasCustomAccessors) {
+            Object.defineProperty(this.value, name, {
+                configurable: true,
+                enumerable: true,
+                get() { return fieldValue.get(); },
+                set(v) { fieldValue.set(v); },
+            });
+        } else {
+            this.value[name] = fieldValue.get();
+        }
+    }
+
+    /**
+     * Gets the `StructFieldValue` for `key`
+     *
+     * @param name The field name
+     */
+    public get(name: PropertyKey): StructFieldValue {
+        return this.fieldValues[name]!;
+    }
+}

package/src/index.ts

@@ -1,17 +1,17 @@
-declare global {
-    interface ArrayBuffer {
-        // Disallow assigning `Uint8Array` to `Arraybuffer`
-        __brand: never;
-    }
-
-    interface SharedArrayBuffer {
-        // Allow `SharedArrayBuffer` to be assigned to `ArrayBuffer`
-        __brand: never;
-    }
-}
-
-export * from './basic/index.js';
-export * from './struct.js';
-export { Struct as default } from './struct.js';
-export * from './types/index.js';
-export * from './utils.js';
+declare global {
+    interface ArrayBuffer {
+        // Disallow assigning `Uint8Array` to `Arraybuffer`
+        __brand: never;
+    }
+
+    interface SharedArrayBuffer {
+        // Allow `SharedArrayBuffer` to be assigned to `ArrayBuffer`
+        __brand: never;
+    }
+}
+
+export * from './basic/index.js';
+export * from './struct.js';
+export { Struct as default } from './struct.js';
+export * from './types/index.js';
+export * from './utils.js';