@yume-chan/struct 0.0.23 → 1.0.0

package/esm/utils.js

@@ -1,16 +1,17 @@
-/**
- * Returns a (fake) value of the given type.
- */
-export function placeholder() {
-    return undefined;
-}
-const { TextEncoder, TextDecoder } = globalThis;
-const Utf8Encoder = new TextEncoder();
-const Utf8Decoder = new TextDecoder();
+// This library can't use `@types/node` or `lib: dom`
+// because they will pollute the global scope
+// So `TextEncoder` and `TextDecoder` types are not available
+export const { TextEncoder, TextDecoder } = globalThis;
+const SharedEncoder = /* #__PURE__ */ new TextEncoder();
+const SharedDecoder = /* #__PURE__ */ new TextDecoder();
+/* #__NO_SIDE_EFFECTS__ */
 export function encodeUtf8(input) {
-    return Utf8Encoder.encode(input);
+    return SharedEncoder.encode(input);
 }
+/* #__NO_SIDE_EFFECTS__ */
 export function decodeUtf8(buffer) {
-    return Utf8Decoder.decode(buffer);
+    // `TextDecoder` has internal states in stream mode,
+    // but this method is not for stream mode, so the instance can be reused
+    return SharedDecoder.decode(buffer);
 }
 //# sourceMappingURL=utils.js.map

package/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAgDA;;GAEG;AACH,MAAM,UAAU,WAAW;IACvB,OAAO,SAAyB,CAAC;AACrC,CAAC;AA2BD,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,UAAwC,CAAC;AAE9E,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AACtC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC,MAAM,UAAU,UAAU,CAAC,KAAa;IACpC,OAAO,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAqC;IAC5D,OAAO,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,6CAA6C;AAC7C,6DAA6D;AAsB7D,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GACrC,UAAwC,CAAC;AAE7C,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,WAAW,EAAE,CAAC;AACxD,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,WAAW,EAAE,CAAC;AAExD,0BAA0B;AAC1B,MAAM,UAAU,UAAU,CAAC,KAAa;IACpC,OAAO,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,UAAU,CAAC,MAAqC;IAC5D,oDAAoD;IACpD,wEAAwE;IACxE,OAAO,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yume-chan/struct",
-  "version": "0.0.23",
+  "version": "1.0.0",
   "description": "C-style structure serializer and deserializer.",
   "keywords": [
     "structure",
@@ -26,25 +26,22 @@
   "type": "module",
   "main": "esm/index.js",
   "types": "esm/index.d.ts",
+  "sideEffects": false,
   "dependencies": {
-    "@yume-chan/dataview-bigint-polyfill": "^0.0.23",
-    "tslib": "^2.6.2"
+    "@yume-chan/async": "^4.0.2",
+    "@yume-chan/no-data-view": "^1.0.0"
   },
   "devDependencies": {
-    "@jest/globals": "^30.0.0-alpha.3",
-    "@yume-chan/eslint-config": "^1.0.0",
+    "@types/node": "^22.10.0",
+    "prettier": "^3.4.1",
+    "typescript": "^5.7.2",
     "@yume-chan/tsconfig": "^1.0.0",
-    "cross-env": "^7.0.3",
-    "eslint": "^8.57.0",
-    "jest": "^30.0.0-alpha.3",
-    "prettier": "^3.2.5",
-    "ts-jest": "^29.1.2",
-    "typescript": "^5.4.2"
+    "@yume-chan/eslint-config": "^1.0.0",
+    "@yume-chan/test-runner": "^1.0.0"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json",
-    "build:watch": "tsc -b tsconfig.build.json",
-    "test": "cross-env NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" TS_JEST_DISABLE_VER_CHECKER=true jest --coverage",
-    "lint": "eslint src/**/*.ts --fix && prettier src/**/*.ts --write --tab-width 4"
+    "lint": "run-eslint && prettier src/**/*.ts --write --tab-width 4",
+    "test": "run-test"
   }
 }

package/src/bipedal.ts

@@ -0,0 +1,55 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import { isPromiseLike } from "@yume-chan/async";
+
+function advance<T>(
+    iterator: Iterator<unknown, T, unknown>,
+    next: unknown,
+): MaybePromiseLike<T> {
+    while (true) {
+        const { done, value } = iterator.next(next);
+        if (done) {
+            return value;
+        }
+        if (isPromiseLike(value)) {
+            return value.then(
+                (value) => advance(iterator, { resolved: value }),
+                (error: unknown) => advance(iterator, { error }),
+            );
+        }
+        next = value;
+    }
+}
+
+export function bipedal<This, T, A extends unknown[]>(
+    fn: (
+        this: This,
+        then: <U>(value: U | PromiseLike<U>) => Iterable<unknown, U, unknown>,
+        ...args: A
+    ) => Generator<unknown, T, unknown>,
+): { (this: This, ...args: A): MaybePromiseLike<T> } {
+    return function (this: This, ...args: A) {
+        const iterator = fn.call(
+            this,
+            function* <U>(
+                value: U | PromiseLike<U>,
+            ): Generator<
+                PromiseLike<U>,
+                U,
+                { resolved: U } | { error: unknown }
+            > {
+                if (isPromiseLike(value)) {
+                    const result = yield value;
+                    if ("resolved" in result) {
+                        return result.resolved;
+                    } else {
+                        throw result.error;
+                    }
+                }
+
+                return value;
+            },
+            ...args,
+        ) as never;
+        return advance(iterator, undefined);
+    };
+}

package/src/buffer.ts

@@ -0,0 +1,260 @@
+import { bipedal } from "./bipedal.js";
+import type { Field } from "./field.js";
+
+export interface Converter<From, To> {
+    convert: (value: From) => To;
+    back: (value: To) => From;
+}
+
+export interface BufferLengthConverter<K, KT> extends Converter<KT, number> {
+    field: K;
+}
+
+export interface BufferLike {
+    (length: number): Field<Uint8Array, never, never>;
+    <U>(
+        length: number,
+        converter: Converter<Uint8Array, U>,
+    ): Field<U, never, never>;
+
+    <K extends string>(lengthField: K): Field<Uint8Array, K, Record<K, number>>;
+    <K extends string, U>(
+        lengthField: K,
+        converter: Converter<Uint8Array, U>,
+    ): Field<U, K, Record<K, number>>;
+
+    <K extends string, KT>(
+        length: BufferLengthConverter<K, KT>,
+    ): Field<Uint8Array, K, Record<K, KT>>;
+    <K extends string, KT, U>(
+        length: BufferLengthConverter<K, KT>,
+        converter: Converter<Uint8Array, U>,
+    ): Field<U, K, Record<K, KT>>;
+
+    <KOmitInit extends string, KS>(
+        length: Field<number, KOmitInit, KS>,
+    ): Field<Uint8Array, KOmitInit, KS>;
+    <KOmitInit extends string, KS, U>(
+        length: Field<number, KOmitInit, KS>,
+        converter: Converter<Uint8Array, U>,
+    ): Field<U, KOmitInit, KS>;
+}
+
+export const EmptyUint8Array = new Uint8Array(0);
+
+export const buffer: BufferLike = function (
+    lengthOrField:
+        | string
+        | number
+        | Field<number, never, unknown>
+        | BufferLengthConverter<string, unknown>,
+    converter?: Converter<Uint8Array, unknown>,
+): Field<unknown, string, Record<string, unknown>> {
+    if (typeof lengthOrField === "number") {
+        if (converter) {
+            if (lengthOrField === 0) {
+                return {
+                    size: 0,
+                    serialize: () => {},
+                    deserialize: () => converter.convert(EmptyUint8Array),
+                };
+            }
+
+            return {
+                size: lengthOrField,
+                serialize: (value, { buffer, index }) => {
+                    buffer.set(
+                        converter.back(value).slice(0, lengthOrField),
+                        index,
+                    );
+                },
+                deserialize: bipedal(function* (then, { reader }) {
+                    const array = yield* then(
+                        reader.readExactly(lengthOrField),
+                    );
+                    return converter.convert(array);
+                }),
+            };
+        }
+
+        if (lengthOrField === 0) {
+            return {
+                size: 0,
+                serialize: () => {},
+                deserialize: () => EmptyUint8Array,
+            };
+        }
+
+        return {
+            size: lengthOrField,
+            serialize: (value, { buffer, index }) => {
+                buffer.set(
+                    (value as Uint8Array).slice(0, lengthOrField),
+                    index,
+                );
+            },
+            deserialize: ({ reader }) => reader.readExactly(lengthOrField),
+        };
+    }
+
+    // Some Field type might be `function`s
+    if (
+        (typeof lengthOrField === "object" ||
+            typeof lengthOrField === "function") &&
+        "serialize" in lengthOrField
+    ) {
+        if (converter) {
+            return {
+                size: 0,
+                dynamicSize(value) {
+                    const array = converter.back(value);
+                    const lengthFieldSize =
+                        lengthOrField.dynamicSize?.(array.length) ??
+                        lengthOrField.size;
+                    return lengthFieldSize + array.length;
+                },
+                serialize(value, context) {
+                    const array = converter.back(value);
+                    const lengthFieldSize =
+                        lengthOrField.dynamicSize?.(array.length) ??
+                        lengthOrField.size;
+                    lengthOrField.serialize(array.length, context);
+                    context.buffer.set(array, context.index + lengthFieldSize);
+                },
+                deserialize: bipedal(function* (then, context) {
+                    const length = yield* then(
+                        lengthOrField.deserialize(context),
+                    );
+                    const array = yield* then(
+                        context.reader.readExactly(length),
+                    );
+                    return converter.convert(array);
+                }),
+            };
+        }
+
+        return {
+            size: 0,
+            dynamicSize(value) {
+                const lengthFieldSize =
+                    lengthOrField.dynamicSize?.((value as Uint8Array).length) ??
+                    lengthOrField.size;
+                return lengthFieldSize + (value as Uint8Array).length;
+            },
+            serialize(value, context) {
+                const lengthFieldSize =
+                    lengthOrField.dynamicSize?.((value as Uint8Array).length) ??
+                    lengthOrField.size;
+                lengthOrField.serialize((value as Uint8Array).length, context);
+                context.buffer.set(
+                    value as Uint8Array,
+                    context.index + lengthFieldSize,
+                );
+            },
+            deserialize: bipedal(function* (then, context) {
+                const length = yield* then(lengthOrField.deserialize(context));
+                return context.reader.readExactly(length);
+            }),
+        };
+    }
+
+    if (typeof lengthOrField === "string") {
+        if (converter) {
+            return {
+                size: 0,
+                preSerialize: (value, runtimeStruct) => {
+                    runtimeStruct[lengthOrField] = converter.back(value).length;
+                },
+                dynamicSize: (value) => {
+                    return converter.back(value).length;
+                },
+                serialize: (value, { buffer, index }) => {
+                    buffer.set(converter.back(value), index);
+                },
+                deserialize: bipedal(function* (
+                    then,
+                    { reader, runtimeStruct },
+                ) {
+                    const length = runtimeStruct[lengthOrField] as number;
+                    if (length === 0) {
+                        return converter.convert(EmptyUint8Array);
+                    }
+
+                    const value = yield* then(reader.readExactly(length));
+                    return converter.convert(value);
+                }),
+            };
+        }
+
+        return {
+            size: 0,
+            preSerialize: (value, runtimeStruct) => {
+                runtimeStruct[lengthOrField] = (value as Uint8Array).length;
+            },
+            dynamicSize: (value) => {
+                return (value as Uint8Array).length;
+            },
+            serialize: (value, { buffer, index }) => {
+                buffer.set(value as Uint8Array, index);
+            },
+            deserialize: ({ reader, runtimeStruct }) => {
+                const length = runtimeStruct[lengthOrField] as number;
+                if (length === 0) {
+                    return EmptyUint8Array;
+                }
+
+                return reader.readExactly(length);
+            },
+        };
+    }
+
+    if (converter) {
+        return {
+            size: 0,
+            preSerialize: (value, runtimeStruct) => {
+                const length = converter.back(value).length;
+                runtimeStruct[lengthOrField.field] = lengthOrField.back(length);
+            },
+            dynamicSize: (value) => {
+                return converter.back(value).length;
+            },
+            serialize: (value, { buffer, index }) => {
+                buffer.set(converter.back(value), index);
+            },
+            deserialize: bipedal(function* (then, { reader, runtimeStruct }) {
+                const rawLength = runtimeStruct[lengthOrField.field];
+                const length = lengthOrField.convert(rawLength);
+                if (length === 0) {
+                    return converter.convert(EmptyUint8Array);
+                }
+
+                const value = yield* then(reader.readExactly(length));
+                return converter.convert(value);
+            }),
+        };
+    }
+
+    return {
+        size: 0,
+        preSerialize: (value, runtimeStruct) => {
+            runtimeStruct[lengthOrField.field] = lengthOrField.back(
+                (value as Uint8Array).length,
+            );
+        },
+        dynamicSize: (value) => {
+            return (value as Uint8Array).length;
+        },
+        serialize: (value, { buffer, index }) => {
+            buffer.set(value as Uint8Array, index);
+        },
+        deserialize: ({ reader, runtimeStruct }) => {
+            const rawLength = runtimeStruct[lengthOrField.field];
+            const length = lengthOrField.convert(rawLength);
+            if (length === 0) {
+                return EmptyUint8Array;
+            }
+
+            return reader.readExactly(length);
+        },
+    };
+} as never;

package/src/field.ts

@@ -0,0 +1,27 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+
+import type { AsyncExactReadable } from "./readable.js";
+
+export interface SerializeContext {
+    buffer: Uint8Array;
+    index: number;
+    littleEndian: boolean;
+}
+
+export interface DeserializeContext<S> {
+    reader: AsyncExactReadable;
+    littleEndian: boolean;
+    runtimeStruct: S;
+}
+
+export interface Field<T, OmitInit extends string, S> {
+    __invariant?: OmitInit;
+
+    size: number;
+
+    dynamicSize?(value: T): number;
+    preSerialize?(value: T, runtimeStruct: S): void;
+    serialize(value: T, context: SerializeContext): void;
+
+    deserialize(context: DeserializeContext<S>): MaybePromiseLike<T>;
+}

package/src/index.ts

@@ -10,9 +10,11 @@ declare global {
     }
 }
 
-export * from "./basic/index.js";
+export * from "./bipedal.js";
+export * from "./buffer.js";
+export * from "./field.js";
+export * from "./number.js";
+export * from "./readable.js";
+export * from "./string.js";
 export * from "./struct.js";
-export { Struct as default } from "./struct.js";
-export * from "./sync-promise.js";
-export * from "./types/index.js";
 export * from "./utils.js";

package/src/number.ts

@@ -0,0 +1,123 @@
+import {
+    getInt16,
+    getInt32,
+    getInt64,
+    getInt8,
+    getUint16,
+    getUint32,
+    getUint64,
+    setInt16,
+    setInt32,
+    setInt64,
+    setUint16,
+    setUint32,
+    setUint64,
+} from "@yume-chan/no-data-view";
+
+import { bipedal } from "./bipedal.js";
+import type { Field } from "./field.js";
+
+export interface NumberField<T> extends Field<T, never, never> {
+    <const U>(infer?: U): Field<U, never, never>;
+}
+
+/* #__NO_SIDE_EFFECTS__ */
+function factory<T>(
+    size: number,
+    serialize: Field<T, never, never>["serialize"],
+    deserialize: Field<T, never, never>["deserialize"],
+): NumberField<T> {
+    const result = () => result;
+    result.size = size;
+    result.serialize = serialize;
+    result.deserialize = deserialize;
+    return result as never;
+}
+
+export const u8 = factory<number>(
+    1,
+    (value, { buffer, index }) => {
+        buffer[index] = value;
+    },
+    bipedal(function* (then, { reader }) {
+        const data = yield* then(reader.readExactly(1));
+        return data[0]!;
+    }),
+);
+
+export const s8 = factory<number>(
+    1,
+    (value, { buffer, index }) => {
+        buffer[index] = value;
+    },
+    bipedal(function* (then, { reader }) {
+        const data = yield* then(reader.readExactly(1));
+        return getInt8(data, 0);
+    }),
+);
+
+export const u16 = factory<number>(
+    2,
+    (value, { buffer, index, littleEndian }) => {
+        setUint16(buffer, index, value, littleEndian);
+    },
+    bipedal(function* (then, { reader, littleEndian }) {
+        const data = yield* then(reader.readExactly(2));
+        return getUint16(data, 0, littleEndian);
+    }),
+);
+
+export const s16 = factory<number>(
+    2,
+    (value, { buffer, index, littleEndian }) => {
+        setInt16(buffer, index, value, littleEndian);
+    },
+    bipedal(function* (then, { reader, littleEndian }) {
+        const data = yield* then(reader.readExactly(2));
+        return getInt16(data, 0, littleEndian);
+    }),
+);
+
+export const u32 = factory<number>(
+    4,
+    (value, { buffer, index, littleEndian }) => {
+        setUint32(buffer, index, value, littleEndian);
+    },
+    bipedal(function* (then, { reader, littleEndian }) {
+        const data = yield* then(reader.readExactly(4));
+        return getUint32(data, 0, littleEndian);
+    }),
+);
+
+export const s32 = factory<number>(
+    4,
+    (value, { buffer, index, littleEndian }) => {
+        setInt32(buffer, index, value, littleEndian);
+    },
+    bipedal(function* (then, { reader, littleEndian }) {
+        const data = yield* then(reader.readExactly(4));
+        return getInt32(data, 0, littleEndian);
+    }),
+);
+
+export const u64 = factory<bigint>(
+    8,
+    (value, { buffer, index, littleEndian }) => {
+        setUint64(buffer, index, value, littleEndian);
+    },
+    bipedal(function* (then, { reader, littleEndian }) {
+        const data = yield* then(reader.readExactly(8));
+        return getUint64(data, 0, littleEndian);
+    }),
+);
+
+export const s64 = factory<bigint>(
+    8,
+    (value, { buffer, index, littleEndian }) => {
+        setInt64(buffer, index, value, littleEndian);
+    },
+    bipedal(function* (then, { reader, littleEndian }) {
+        const data = yield* then(reader.readExactly(8));
+        return getInt64(data, 0, littleEndian);
+    }),
+);

package/src/{basic/stream.ts → readable.ts}

@@ -1,11 +1,10 @@
-import type { ValueOrPromise } from "../utils.js";
-
 // TODO: allow over reading (returning a `Uint8Array`, an `offset` and a `length`) to avoid copying
 
+import type { MaybePromiseLike } from "@yume-chan/async";
+
 export class ExactReadableEndedError extends Error {
     constructor() {
         super("ExactReadable ended");
-        Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 
@@ -30,5 +29,5 @@ export interface AsyncExactReadable {
      * 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 {@link ExactReadableEndedError}.
      */
-    readExactly(length: number): ValueOrPromise<Uint8Array>;
+    readExactly(length: number): MaybePromiseLike<Uint8Array>;
 }

package/src/string.ts

@@ -0,0 +1,43 @@
+import type { BufferLengthConverter } from "./buffer.js";
+import { buffer } from "./buffer.js";
+import type { Field } from "./field.js";
+import { decodeUtf8, encodeUtf8 } from "./utils.js";
+
+export interface String {
+    (length: number): Field<string, never, never> & {
+        as: <T>(infer: T) => Field<T, never, never>;
+    };
+
+    <K extends string>(
+        lengthField: K,
+    ): Field<string, K, Record<K, number>> & {
+        as: <T>(infer: T) => Field<T, K, Record<K, number>>;
+    };
+
+    <const K extends string, KT>(
+        length: BufferLengthConverter<K, KT>,
+    ): Field<string, K, Record<K, KT>> & {
+        as: <T>(infer: T) => Field<T, K, Record<K, KT>>;
+    };
+
+    <KOmitInit extends string, KS>(
+        length: Field<number, KOmitInit, KS>,
+    ): Field<string, KOmitInit, KS>;
+}
+
+// Rollup doesn't support `/* #__NO_SIDE_EFFECTS__ */ export const a = () => {}
+/* #__NO_SIDE_EFFECTS__ */
+function _string(
+    lengthOrField: string | number | BufferLengthConverter<string, unknown>,
+): Field<string, string, Record<string, unknown>> & {
+    as: <T>(infer: T) => Field<T, string, Record<string, unknown>>;
+} {
+    const field = buffer(lengthOrField as never, {
+        convert: decodeUtf8,
+        back: encodeUtf8,
+    });
+    (field as never as { as: unknown }).as = () => field;
+    return field as never;
+}
+
+export const string: String = _string as never;