@yume-chan/struct 0.0.9 → 0.0.13

package/src/basic/definition.ts

@@ -1,69 +1,70 @@
-import type { ValueOrPromise } from '../utils';
-import type { StructDeserializationContext, StructOptions, StructSerializationContext } from './context';
-import type { StructFieldValue } from './field-value';
-import type { StructValue } from './struct-value';
-
-/**
- * A field definition is a bridge between its type and its runtime value.
- *
- * `Struct` record fields in a list of `StructFieldDefinition`s.
- *
- * When `Struct#create` or `Struct#deserialize` are called, each field's definition
- * crates its own type of `StructFieldValue` to manage the field value in that `Struct` instance.
- *
- * One `StructFieldDefinition` can represents multiple similar types, just returns the corresponding
- * `StructFieldValue` when `createValue` was called.
- *
- * @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>,
-        context: StructSerializationContext,
-        struct: StructValue,
-        value: TValue,
-    ): StructFieldValue<this>;
-
-    /**
-     * When implemented in derived classes, creates a `StructFieldValue` by parsing `context`.
-     */
-    public abstract deserialize(
-        options: Readonly<StructOptions>,
-        context: StructDeserializationContext,
-        struct: StructValue,
-    ): ValueOrPromise<StructFieldValue<this>>;
-}
+// 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>>;
+}

package/src/basic/field-value.ts

@@ -1,73 +1,67 @@
-import type { StructOptions, StructSerializationContext } from './context';
-import type { StructFieldDefinition } from './definition';
-import type { StructValue } from './struct-value';
-
-/**
- * Field runtime value manages one field of one `Struct` instance.
- *
- * If one `StructFieldDefinition` needs to change other field's semantics
- * It can override other fields' `StructFieldValue` in its own `StructFieldValue`'s constructor
- */
-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 serialization context of the associated `Struct` instance */
-    public readonly context: StructSerializationContext;
-
-    /** Gets the associated `Struct` instance */
-    public readonly struct: StructValue;
-
-    protected value: TDefinition['TValue'];
-
-    public constructor(
-        definition: TDefinition,
-        options: Readonly<StructOptions>,
-        context: StructSerializationContext,
-        struct: StructValue,
-        value: TDefinition['TValue'],
-    ) {
-        this.definition = definition;
-        this.options = options;
-        this.context = context;
-        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, returns the current value of this field
-     */
-    public get(): TDefinition['TValue'] {
-        return this.value;
-    }
-
-    /**
-     * When implemented in derived classes, update the current value of this field
-     */
-    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,
-        context: StructSerializationContext
-    ): 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;
+
+    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,4 +1,5 @@
-export * from './context';
-export * from './definition';
-export * from './field-value';
-export * from './struct-value';
+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

@@ -0,0 +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,
+};

package/src/basic/stream.ts

@@ -0,0 +1,19 @@
+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>;
+}

package/src/basic/struct-value.ts

@@ -1,45 +1,39 @@
-import type { StructFieldValue } from './field-value';
-
-/**
- * Manages the initialization process of a struct value
- */
-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 {
-        // TODO: TypeScript 4.2 will allow this behavior
-        // https://github.com/microsoft/TypeScript/pull/26797
-        // @ts-expect-error Type 'symbol' cannot be used as an index type. ts(2538)
-        this.fieldValues[key] = value;
-
-        Object.defineProperty(this.value, key, {
-            configurable: true,
-            enumerable: true,
-            get() { return value.get(); },
-            set(v) { value.set(v); },
-        });
-    }
-
-    /**
-     * Gets a previously `StructFieldValue` for `key`
-     *
-     * @param key The field name
-     */
-    public get(key: PropertyKey): StructFieldValue {
-        // TODO: TypeScript 4.2 will allow this behavior
-        // https://github.com/microsoft/TypeScript/pull/26797
-        // @ts-expect-error Type 'symbol' cannot be used as an index type. ts(2538)
-        return this.fieldValues[key];
-    }
-}
+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]!;
+    }
+}

package/src/index.ts

@@ -1,5 +1,17 @@
-export * from './basic';
-export * from './struct';
-export { Struct as default } from './struct';
-export * from './types';
-export * from './utils';
+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';