@nnilky/structo 1.0.4 → 1.0.5

package/README.md

@@ -94,7 +94,7 @@ export function list<T>(options: {
 ```ts
 const Bits = st.pipe(
     st.u32()
-    st.transform(v => v * 8)
+    st.modify(v => v * 8)
 )
 ```
 

package/dist/datatypes/containers/array.d.ts

@@ -1,2 +1,10 @@
 import type { Serializer } from "../../types";
+/**
+ * `st.array` is a fixed length array, akin to a C array.
+ *
+ * ```
+ * st.array(16, st.f64())
+ * ```
+ *
+ */
 export declare function array<T>(size: number, type: Serializer<T>): Serializer<T[]>;

package/dist/datatypes/containers/array.js

@@ -1,3 +1,11 @@
+/**
+ * `st.array` is a fixed length array, akin to a C array.
+ *
+ * ```
+ * st.array(16, st.f64())
+ * ```
+ *
+ */
 export function array(size, type) {
     const { read: readType, write: writeType, size: typeSize } = type;
     return {

package/dist/datatypes/containers/exhuastiveArray.d.ts

@@ -0,0 +1,9 @@
+import * as st from "../..";
+/**
+ * exhuastiveArray is read until the end of the data
+ *
+ * ```py
+ * exhuastiveArray(st.u32())
+ * ```
+ */
+export declare function exhuastiveArray<T>(type: st.Serializer<T>): st.Serializer<T[]>;

package/dist/datatypes/containers/exhuastiveArray.js

@@ -0,0 +1,24 @@
+import * as st from "../..";
+/**
+ * exhuastiveArray is read until the end of the data
+ *
+ * ```py
+ * exhuastiveArray(st.u32())
+ * ```
+ */
+export function exhuastiveArray(type) {
+    return {
+        read(ctx) {
+            let arr = [];
+            while (ctx.offset < ctx.view.byteLength) {
+                arr.push(type.read(ctx));
+            }
+            return arr;
+        },
+        write(ctx, value) {
+            for (let i = 0; i < value.length; i++) {
+                type.write(ctx, value[i]);
+            }
+        },
+    };
+}

package/dist/datatypes/containers/exhuastiveArray.test.js

@@ -0,0 +1,41 @@
+import { describe, it } from "bun:test";
+import { expectEncode, expectEncodeSnapshot, expectError } from "../utils.test";
+import * as st from "../../index";
+describe("st.exhuastiveArray", () => {
+    it("encode correctly", () => {
+        const spec = st.exhuastiveArray(st.u32());
+        expectEncode(spec, [1, 2, 3, 4]);
+    });
+    it("works on empty arrays", () => {
+        const spec = st.exhuastiveArray(st.u32());
+        expectEncode(spec, []);
+    });
+    it("accepts large array", () => {
+        const spec = st.exhuastiveArray(st.u32());
+        expectEncode(spec, Array.from({ length: 10000 }, (_, i) => i));
+    });
+    it("works composed", () => {
+        const spec = st.object({
+            a: st.u32(),
+            b: st.u8(),
+            c: st.exhuastiveArray(st.u32()),
+        });
+        expectEncode(spec, { a: 1, b: 2, c: [3, 4, 5, 6, 7] });
+    });
+    it("throws error on invalid value", () => {
+        const spec = st.exhuastiveArray(st.u16());
+        expectError(() => {
+            st.write(spec, [-1]);
+        });
+    });
+    it("nested arrays encode correctly", () => {
+        expectEncode(st.exhuastiveArray(st.exhuastiveArray(st.u16())), //
+        [[1, 2]]);
+    });
+    it(`matches snapshots`, () => {
+        expectEncodeSnapshot(st.exhuastiveArray(st.string(st.u16())), //
+        ["foo", "bar", "baz"]);
+        expectEncodeSnapshot(st.exhuastiveArray(st.u8()), //
+        [0, 1, 2, 3]);
+    });
+});

package/dist/datatypes/containers/fastObject.test.js

@@ -0,0 +1,33 @@
+//@ts-ignore TODO
+import { describe, it, expect } from "bun:test";
+import { bytes, expectEncode, expectEncodeSnapshot } from "../utils.test";
+import * as st from "../../index";
+describe("st.fastObject", () => {
+    const test = st.fastObject({
+        a: st.u8(),
+        b: st.u8(),
+    });
+    it("encodes correctly", () => {
+        st.write(test, { b: 2, a: 1 });
+    });
+    it("encode in correct order", () => {
+        const data = st.write(test, { b: 2, a: 1 });
+        const arr = new Uint8Array(data);
+        expect(arr[0]).toBe(1);
+        expect(arr[1]).toBe(2);
+    });
+    it("encodes empty", () => {
+        expectEncode(st.fastObject({}), {});
+    });
+    it(`matches snapshots`, () => {
+        expectEncodeSnapshot(st.fastObject({
+            number: st.u32(),
+            puppy: st.string(st.s32()),
+            buffer: st.bytes(4),
+        }), {
+            number: 1,
+            puppy: "woof woof bark bark",
+            buffer: bytes([19, 87, 19, 83]),
+        });
+    });
+});

package/dist/datatypes/containers/list.d.ts

@@ -1,5 +1,12 @@
 import type { Serializer } from "../../types";
-export declare function list<T>(options: {
-    type: Serializer<T>;
-    length: Serializer<number>;
-}): Serializer<T[]>;
+/**
+ * `st.list` is a dynamically sized array
+ *
+ * Note: Length is read/writen first, then the values in order
+ *
+ * ```
+ * st.list(st.u32(), User)
+ * ```
+ *
+ */
+export declare function list<T>(length: Serializer<number>, type: Serializer<T>): Serializer<T[]>;

package/dist/datatypes/containers/list.js

@@ -1,20 +1,28 @@
-export function list(options) {
-    const { read: readLength, write: writeLength } = options.length;
-    const { read: readType, write: writeType, size: sizeType } = options.type;
+/**
+ * `st.list` is a dynamically sized array
+ *
+ * Note: Length is read/writen first, then the values in order
+ *
+ * ```
+ * st.list(st.u32(), User)
+ * ```
+ *
+ */
+export function list(length, type) {
     return {
         write: (ctx, value) => {
-            writeLength(ctx, value.length);
-            if (sizeType)
-                ctx.alloc(value.length * sizeType);
+            length.write(ctx, value.length);
+            if (type.size)
+                ctx.alloc(value.length * type.size);
             for (const v of value) {
-                writeType(ctx, v);
+                type.write(ctx, v);
             }
         },
         read: (ctx) => {
-            const size = readLength(ctx);
+            const size = length.read(ctx);
             const arr = new Array(size);
             for (let i = 0; i < size; i++) {
-                arr[i] = readType(ctx);
+                arr[i] = type.read(ctx);
             }
             return arr;
         },

package/dist/datatypes/containers/list.test.js

@@ -3,29 +3,27 @@ import { expectEncode, expectEncodeSnapshot, expectError } from "../utils.test";
 import * as st from "../../index";
 describe("st.list", () => {
     it("encode correctly", () => {
-        const spec = st.list({ type: st.u16(), length: st.u8() });
+        const spec = st.list(st.u8(), st.u32());
         expectEncode(spec, [1, 2, 3, 4]);
     });
     it("works on empty lists", () => {
-        const spec = st.list({ type: st.u16(), length: st.u8() });
+        const spec = st.list(st.u8(), st.u32());
         expectEncode(spec, []);
     });
     it("throws error on too large array", () => {
-        const spec = st.list({ type: st.u16(), length: st.u8() });
+        const spec = st.list(st.u8(), st.u32());
         expectError(() => {
             st.write(spec, Array.from({ length: 10000 }, () => 0));
         });
     });
     it("throws error on invalid value", () => {
-        const spec = st.list({ type: st.u16(), length: st.u8() });
+        const spec = st.list(st.u8(), st.u16());
         expectError(() => {
             st.write(spec, [-1]);
         });
     });
     it(`matches snapshots`, () => {
-        expectEncodeSnapshot(st.list({
-            type: st.string(st.u16()),
-            length: st.s32(),
-        }), ["foo", "bar", "baz"]);
+        expectEncodeSnapshot(st.list(st.s32(), st.string(st.u16())), //
+        ["foo", "bar", "baz"]);
     });
 });

package/dist/datatypes/containers/object.test.js

@@ -23,7 +23,7 @@ describe("st.object", () => {
         expectEncodeSnapshot(st.object({
             number: st.u32(),
             puppy: st.string(st.s32()),
-            buffer: st.buffer(4),
+            buffer: st.bytes(4),
         }), {
             number: 1,
             puppy: "woof woof bark bark",

package/dist/datatypes/containers/sizedbytes.d.ts

@@ -0,0 +1,2 @@
+import type { Serializer } from "../../types";
+export declare function sizedBytes(length: Serializer<number>): Serializer<ArrayBuffer>;

package/dist/datatypes/containers/{sizedbuffer.js → sizedbytes.js}

@@ -1,4 +1,4 @@
-export function sizedBuffer(length) {
+export function sizedBytes(length) {
     return {
         write: (ctx, value) => {
             length.write(ctx, value.byteLength);

package/dist/datatypes/containers/{sizedbuffer.test.js → sizedbytes.test.js}

@@ -1,25 +1,25 @@
 import { describe, it } from "bun:test";
 import { bytes, expectEncode, expectError } from "../utils.test";
 import * as st from "../../index";
-describe("st.buffer", () => {
+describe("st.sizedBytes", () => {
     it("encode correctly", () => {
-        const buffer = st.sizedBuffer(st.u8());
+        const buffer = st.sizedBytes(st.u8());
         expectEncode(buffer, bytes([1, 2]));
     });
     it("encodes empty correctly", () => {
-        const spec = st.sizedBuffer(st.u8());
+        const spec = st.sizedBytes(st.u8());
         expectEncode(spec, bytes([]));
     });
     it("holds large data", () => {
         const size = 1024 * 1024 * 8; // 8MB
-        const spec = st.sizedBuffer(st.u32());
+        const spec = st.sizedBytes(st.u32());
         const data = new Uint8Array(size);
         data.set([3, 4], 1000);
         data.set([3, 4], 2000);
         expectEncode(spec, data.buffer);
     });
     it("errors on invalid length", () => {
-        const spec = st.sizedBuffer(st.u8());
+        const spec = st.sizedBytes(st.u8());
         expectError(() => {
             st.write(spec, bytes(Array.from({ length: 256 }, () => 0)));
         });

package/dist/datatypes/{values → containers}/string.js

@@ -1,21 +1,23 @@
 export function string(length) {
-    const { read: readLength, write: writeLength, size: lengthSize = 0 } = length;
     const encoder = new TextEncoder();
     const decoder = new TextDecoder();
+    const lengthSize = length.size ?? 0;
     return {
         write: (ctx, value) => {
+            if (typeof value !== "string")
+                throw new Error("Expected String to encoder");
             const bytes = encoder.encode(value);
-            const length = bytes.byteLength;
-            ctx.alloc(length + lengthSize);
-            writeLength(ctx, length);
+            const size = bytes.byteLength;
+            ctx.alloc(size + lengthSize);
+            length.write(ctx, size);
             const arr = new Uint8Array(ctx.buffer, ctx.offset);
             arr.set(bytes);
-            ctx.offset += length;
+            ctx.offset += size;
         },
         read: (ctx) => {
-            const length = readLength(ctx);
-            const section = ctx.buffer.slice(ctx.offset, ctx.offset + length);
-            ctx.offset += length;
+            const size = length.read(ctx);
+            const section = ctx.buffer.slice(ctx.offset, ctx.offset + size);
+            ctx.offset += size;
             return decoder.decode(section);
         },
     };

package/dist/datatypes/{values → containers}/string.test.js

@@ -10,6 +10,12 @@ describe("st.string", () => {
     it("works on empty strings", () => {
         expectEncode(string_u32, "");
     });
+    it("errors on numbers", () => {
+        expectError(() => {
+            //@ts-expect-error, intentional mistake
+            st.write(st.string(st.u8()), 8);
+        });
+    });
     it("errors on too long strings", () => {
         expectError(() => {
             st.write(string_u8, "A".repeat(256));

package/dist/datatypes/containers/taggedUnion.d.ts

@@ -0,0 +1,22 @@
+import type { InferInput, InferOutput, Serializer } from "../../types";
+/**
+ * `st.taggedUnion` is a union type with a kind
+ *
+ * Note: `tag` is read/writen first, then the value
+ *
+ * ```
+ * st.taggedUnion(st.u32(), {
+ *     0: MovementPacket,
+ *     1: ClickPacket,
+ *     2: MouseMovePacket,
+ * })
+ * ```
+ *
+ */
+export declare function taggedUnion<TTag extends string | number, TType extends Serializer<any>>(tag: Serializer<TTag>, variants: Record<TTag, TType>): Serializer<{
+    type: TTag;
+    value: InferInput<TType>;
+}, {
+    type: TTag;
+    value: InferOutput<TType>;
+}>;

package/dist/datatypes/containers/taggedUnion.js

@@ -0,0 +1,33 @@
+/**
+ * `st.taggedUnion` is a union type with a kind
+ *
+ * Note: `tag` is read/writen first, then the value
+ *
+ * ```
+ * st.taggedUnion(st.u32(), {
+ *     0: MovementPacket,
+ *     1: ClickPacket,
+ *     2: MouseMovePacket,
+ * })
+ * ```
+ *
+ */
+export function taggedUnion(tag, variants) {
+    return {
+        write: (ctx, value) => {
+            if (!(value.type in variants))
+                throw new Error(`Unknown type ${value.type}`);
+            tag.write(ctx, value.type);
+            const variant = variants[value.type];
+            variant.write(ctx, value.value);
+        },
+        read: (ctx) => {
+            const type = tag.read(ctx);
+            if (!(type in variants))
+                throw new Error(`Unknown type ${tag}`);
+            const variant = variants[type];
+            const value = variant.read(ctx);
+            return { type, value };
+        },
+    };
+}

package/dist/datatypes/containers/taggedUnion.test.js

@@ -0,0 +1,63 @@
+import { describe, it } from "bun:test";
+import { expectEncode, expectEncodeSize, expectEncodeSnapshot, expectError } from "../utils.test";
+import * as st from "../../index";
+describe("st.taggedUnion", () => {
+    it("encode correctly", () => {
+        const spec = st.taggedUnion(st.u8(), {
+            1: st.string(st.u8()),
+            2: st.u8(),
+        });
+        expectEncode(spec, { type: 1, value: "s" });
+        expectEncode(spec, { type: 2, value: 52 });
+    });
+    it("encode with string tag", () => {
+        const spec = st.taggedUnion(st.string(st.u8()), {
+            foo: st.string(st.u8()),
+            bar: st.u8(),
+        });
+        expectEncode(spec, { type: "foo", value: "woof" });
+        expectEncode(spec, { type: "bar", value: 52 });
+    });
+    it("throws error on invalid tag", () => {
+        const spec = st.taggedUnion(st.string(st.u8()), {
+            foo: st.string(st.u8()),
+            bar: st.u8(),
+        });
+        expectError(() => {
+            st.write(spec, { type: "unknown", value: "woof" });
+        });
+    });
+    it("throws error on invalid type", () => {
+        const spec = st.taggedUnion(st.string(st.u8()), {
+            foo: st.string(st.u8()),
+            bar: st.u8(),
+        });
+        expectError(() => {
+            st.write(spec, { type: "unknown", value: "woof" });
+        });
+    });
+    it("throws error on invalid value", () => {
+        const spec = st.taggedUnion(st.string(st.u8()), {
+            foo: st.string(st.u8()),
+        });
+        expectError(() => {
+            //@ts-expect-error
+            st.write(spec, { type: "foo", value: 0 });
+        });
+    });
+    it("encodes varying sizes", () => {
+        const spec = st.taggedUnion(st.u8(), {
+            1: st.string(st.u8()),
+            2: st.u8(),
+        });
+        expectEncode(spec, { type: 1, value: "s" });
+        expectEncodeSize(spec, 5, { type: 1, value: "foo" });
+        expectEncodeSize(spec, 2, { type: 2, value: 52 });
+    });
+    it("encodes snapshots", () => {
+        expectEncodeSnapshot(st.taggedUnion(st.u32(), {
+            0: st.list(st.u8(), st.f64()),
+            3: st.u32(),
+        }), { type: 0, value: [1] });
+    });
+});

package/dist/datatypes/index.d.ts

@@ -1,16 +1,20 @@
 export { u64Bigint, s64Bigint } from "./numbers/bigints";
-export { f32, f64 } from "./numbers/floats";
+export { f16, f32, f64 } from "./numbers/floats";
 export { s8, s16, s32, s64 } from "./numbers/sints";
 export { u8, u16, u32, u64 } from "./numbers/uints";
 export { array } from "./containers/array";
 export { fastObject } from "./containers/fastObject";
 export { object } from "./containers/object";
 export { list } from "./containers/list";
-export { sizedBuffer } from "./containers/sizedbuffer";
-export { string } from "./values/string";
-export { buffer } from "./values/buffer";
-export { byteLiteral } from "./values/byteliteral";
-export { createRememberedValue } from "./utilities/remember";
+export { sizedBytes } from "./containers/sizedbytes";
+export { taggedUnion } from "./containers/taggedUnion";
+export { exhuastiveArray } from "./containers/exhuastiveArray";
+export { string } from "./containers/string";
+export { bytes } from "./values/bytes";
+export { bytesLiteral } from "./values/byteliteral";
 export { type Transform as Pipeline, pipe } from "./transforms/pipe";
-export { positionOffset } from "./transforms/readOffset";
-export { transform } from "./transforms/transform";
+export { fixedOffset } from "./transforms/fixedOffset";
+export { modify } from "./transforms/modify";
+export { encode } from "./transforms/encode";
+export { noAdvance } from "./transforms/noAdvance";
+export { createRememberedValue } from "./utilities/remember";

package/dist/datatypes/index.js

@@ -1,16 +1,20 @@
 export { u64Bigint, s64Bigint } from "./numbers/bigints";
-export { f32, f64 } from "./numbers/floats";
+export { f16, f32, f64 } from "./numbers/floats";
 export { s8, s16, s32, s64 } from "./numbers/sints";
 export { u8, u16, u32, u64 } from "./numbers/uints";
 export { array } from "./containers/array";
 export { fastObject } from "./containers/fastObject";
 export { object } from "./containers/object";
 export { list } from "./containers/list";
-export { sizedBuffer } from "./containers/sizedbuffer";
-export { string } from "./values/string";
-export { buffer } from "./values/buffer";
-export { byteLiteral } from "./values/byteliteral";
-export { createRememberedValue } from "./utilities/remember";
+export { sizedBytes } from "./containers/sizedbytes";
+export { taggedUnion } from "./containers/taggedUnion";
+export { exhuastiveArray } from "./containers/exhuastiveArray";
+export { string } from "./containers/string";
+export { bytes } from "./values/bytes";
+export { bytesLiteral } from "./values/byteliteral";
 export { pipe } from "./transforms/pipe";
-export { positionOffset } from "./transforms/readOffset";
-export { transform } from "./transforms/transform";
+export { fixedOffset } from "./transforms/fixedOffset";
+export { modify } from "./transforms/modify";
+export { encode } from "./transforms/encode";
+export { noAdvance } from "./transforms/noAdvance";
+export { createRememberedValue } from "./utilities/remember";

package/dist/datatypes/numbers/bigints.d.ts

@@ -1,3 +1,13 @@
 import type { Serializer } from "../../types";
+/**
+ * 64bit unsigned interger
+ *
+ * This version uses bigints to ensure accuracy is not lost
+ */
 export declare function u64Bigint(endian?: "little" | "big"): Serializer<number | bigint, bigint>;
+/**
+ * 64bit signed interger
+ *
+ * This version uses bigints to ensure accuracy is not lost
+ */
 export declare function s64Bigint(endian?: "little" | "big"): Serializer<number | bigint, bigint>;

package/dist/datatypes/numbers/bigints.js

@@ -3,6 +3,11 @@ const checkValue = (value, start, end) => {
         throw new Error("Out of Range");
     }
 };
+/**
+ * 64bit unsigned interger
+ *
+ * This version uses bigints to ensure accuracy is not lost
+ */
 export function u64Bigint(endian = "little") {
     return {
         size: 8,
@@ -19,6 +24,11 @@ export function u64Bigint(endian = "little") {
         },
     };
 }
+/**
+ * 64bit signed interger
+ *
+ * This version uses bigints to ensure accuracy is not lost
+ */
 export function s64Bigint(endian = "little") {
     return {
         size: 8,

package/dist/datatypes/numbers/floats.d.ts

@@ -1,3 +1,7 @@
 import type { Serializer } from "../../types";
+/** 16bit float */
+export declare function f16(endian?: "little" | "big"): Serializer<number>;
+/** 32bit float */
 export declare function f32(endian?: "little" | "big"): Serializer<number>;
+/** 64bit float */
 export declare function f64(endian?: "little" | "big"): Serializer<number>;

package/dist/datatypes/numbers/floats.js

@@ -1,3 +1,20 @@
+/** 16bit float */
+export function f16(endian = "little") {
+    return {
+        size: 2,
+        write: (ctx, value) => {
+            ctx.alloc(2);
+            ctx.view.setFloat16(ctx.offset, value, endian === "little");
+            ctx.offset += 2;
+        },
+        read: (ctx) => {
+            const value = ctx.view.getFloat16(ctx.offset, endian === "little");
+            ctx.offset += 2;
+            return value;
+        },
+    };
+}
+/** 32bit float */
 export function f32(endian = "little") {
     return {
         size: 4,
@@ -13,6 +30,7 @@ export function f32(endian = "little") {
         },
     };
 }
+/** 64bit float */
 export function f64(endian = "little") {
     return {
         size: 8,