@nnilky/structo 1.0.4 → 1.0.7

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/array.test.js

@@ -1,22 +1,18 @@
 import { describe, it } from "bun:test";
-import { expectEncode, expectError } from "../utils.test";
+import { encodeTest, encodeFailTest } from "../../utils.test";
 import * as st from "../../index";
 describe("st.array", () => {
     it("encode correctly", () => {
-        const spec = st.array(4, st.u16());
-        expectEncode(spec, [1, 2, 3, 4]);
+        encodeTest(st.array(4, st.u16()), [1, 2, 3, 4]);
     });
     it("works on empty lists", () => {
-        const spec = st.array(0, st.u16());
-        expectEncode(spec, []);
+        encodeTest(st.array(0, st.u16()), []);
     });
     it("throws error on invalid size", () => {
-        const spec = st.array(2, st.u16());
-        expectError(() => st.write(spec, [1]));
+        encodeFailTest(st.array(2, st.u16()), [1]);
     });
     it("throws error on invalid value", () => {
-        const spec = st.array(2, st.u16());
-        expectError(() => st.write(spec, [1, -1]));
-        expectError(() => st.write(spec, [2 ** 16 + 1, 0]));
+        encodeFailTest(st.array(2, st.u16()), [1, -1]);
+        encodeFailTest(st.array(2, st.u16()), [2 ** 16 + 1, 0]);
     });
 });

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,38 @@
+import { describe, it } from "bun:test";
+import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../../utils.test";
+import * as st from "../../index";
+describe("st.exhuastiveArray", () => {
+    it("encode correctly", () => {
+        const spec = st.exhuastiveArray(st.u32());
+        encodeTest(spec, [1, 2, 3, 4]);
+    });
+    it("works on empty arrays", () => {
+        const spec = st.exhuastiveArray(st.u32());
+        encodeTest(spec, []);
+    });
+    it("accepts large array", () => {
+        const spec = st.exhuastiveArray(st.u32());
+        encodeTest(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()),
+        });
+        encodeTest(spec, { a: 1, b: 2, c: [3, 4, 5, 6, 7] });
+    });
+    it("throws error on invalid value", () => {
+        encodeFailTest(st.exhuastiveArray(st.u16()), [-1]);
+    });
+    it("nested arrays encode correctly", () => {
+        encodeTest(st.exhuastiveArray(st.exhuastiveArray(st.u16())), //
+        [[1, 2]]);
+    });
+    it(`matches snapshots`, () => {
+        encodeSnapshotTest(st.exhuastiveArray(st.string(st.u16())), //
+        ["foo", "bar", "baz"]);
+        encodeSnapshotTest(st.exhuastiveArray(st.u8()), //
+        [0, 1, 2, 3]);
+    });
+});

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

@@ -14,6 +14,8 @@ type InferObject<T> = T extends Record<string, Serializer<any>> ? {
  *     createdAt: st.f64(),
  * })
  * ```
+ *
+ * Note: Using st.lazy affects the performance of fastObject as it prevents discovery of subobjects, avoid when performance is a requirement
  */
 export declare function fastObject<T extends Record<string, Serializer<any>>>(definition: T): Serializer<InferObject<T>>;
 export {};

package/dist/datatypes/containers/fastObject.js

@@ -11,6 +11,8 @@ const definitionSymbol = Symbol();
  *     createdAt: st.f64(),
  * })
  * ```
+ *
+ * Note: Using st.lazy affects the performance of fastObject as it prevents discovery of subobjects, avoid when performance is a requirement
  */
 export function fastObject(definition) {
     let serializers = [];

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

@@ -0,0 +1,45 @@
+//@ts-ignore TODO
+import { describe, it, expect } from "bun:test";
+import { bytes, encodeTest, encodeSnapshotTest } from "../../utils.test";
+import * as st from "../../index";
+describe("st.fastObject", () => {
+    const spec = st.fastObject({
+        a: st.u8(),
+        b: st.u8(),
+    });
+    it("encodes correctly", () => {
+        st.write(spec, { b: 2, a: 1 });
+    });
+    it("encodes nest correctly", () => {
+        st.write(st.fastObject({
+            a: st.fastObject({
+                cat: st.u8(),
+                puppy: st.string(st.u8()),
+            }),
+            b: st.u8(),
+        }), {
+            a: { cat: 1, puppy: "woof" },
+            b: 3,
+        });
+    });
+    it("encode in correct order", () => {
+        const data = st.write(spec, { b: 2, a: 1 });
+        const arr = new Uint8Array(data);
+        expect(arr[0]).toBe(1);
+        expect(arr[1]).toBe(2);
+    });
+    it("encodes empty", () => {
+        encodeTest(st.fastObject({}), {});
+    });
+    it(`matches snapshots`, () => {
+        encodeSnapshotTest(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

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

package/dist/datatypes/containers/object.js

@@ -21,7 +21,13 @@ export function object(definition) {
             if (size)
                 ctx.alloc(size);
             for (let i = 0; i < entires.length; i++) {
-                entires[i][1].write(ctx, value[entires[i][0]]);
+                const key = entires[i][0];
+                try {
+                    entires[i][1].write(ctx, value[key]);
+                }
+                catch (e) {
+                    throw new Error(`Failed to encode key '${key}'`, { cause: e });
+                }
             }
         },
         read: (ctx) => {

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

@@ -1,33 +1,45 @@
 //@ts-ignore TODO
-import { describe, it, expect } from "bun:test";
-import { bytes, expectEncode, expectEncodeSnapshot } from "../utils.test";
+import { describe, it, expect, expectTypeOf } from "bun:test";
+import { bytes, encodeTest, encodeSnapshotTest } from "../../utils.test";
 import * as st from "../../index";
 describe("st.object", () => {
-    const test = st.object({
-        a: st.u8(),
-        b: st.u8(),
-    });
     it("encodes correctly", () => {
-        st.write(test, { b: 2, a: 1 });
+        encodeTest(st.object({ a: st.u8(), b: st.u8() }), //
+        { b: 2, a: 1 });
+    });
+    it("encodes nested correctly", () => {
+        encodeTest(st.object({
+            a: st.object({ a: st.u8() }),
+            b: st.u8(),
+        }), //
+        { a: { a: 2 }, b: 1 });
     });
     it("encode in correct order", () => {
-        const data = st.write(test, { b: 2, a: 1 });
+        const data = st.write(st.object({
+            a: st.u8(),
+            b: st.u8(),
+        }), { b: 2, a: 1 });
         const arr = new Uint8Array(data);
         expect(arr[0]).toBe(1);
         expect(arr[1]).toBe(2);
     });
     it("encodes empty", () => {
-        expectEncode(st.object({}), {});
+        encodeTest(st.object({}), {});
     });
     it(`matches snapshots`, () => {
-        expectEncodeSnapshot(st.object({
+        encodeSnapshotTest(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",
             buffer: bytes([19, 87, 19, 83]),
         });
     });
+    // Type Tests
+    expectTypeOf(st.object({
+        number: st.u32(),
+        string: st.string(st.u32()),
+    })).toEqualTypeOf();
 });

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/containers/string.d.ts

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

package/dist/datatypes/containers/string.js

@@ -0,0 +1,24 @@
+export function string(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 size = bytes.byteLength;
+            ctx.alloc(size + lengthSize);
+            length.write(ctx, size);
+            const arr = new Uint8Array(ctx.buffer, ctx.offset);
+            arr.set(bytes);
+            ctx.offset += size;
+        },
+        read: (ctx) => {
+            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/containers/string.test.js

@@ -0,0 +1,24 @@
+import { describe, it } from "bun:test";
+import { expectEncode, expectError } from "../utils.test";
+import * as st from "../../index";
+describe("st.string", () => {
+    const string_u8 = st.string(st.u8());
+    const string_u32 = st.string(st.u32());
+    it("encode correctly", () => {
+        expectEncode(string_u8, "foo");
+    });
+    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,26 @@
+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<Tag extends PropertyKey, //
+Variants extends Record<Tag, Serializer<any>>>(tag: Serializer<Tag>, variants: Variants & Record<Exclude<keyof Variants, Tag>, never>): Serializer<{
+    [K in keyof Variants]: {
+        type: K;
+        value: InferInput<Variants[K]>;
+    };
+}[keyof Variants], {
+    [K in keyof Variants]: {
+        type: K;
+        value: InferOutput<Variants[K]>;
+    };
+}[keyof Variants]>;

package/dist/datatypes/containers/taggedUnion.js

@@ -0,0 +1,35 @@
+/**
+ * `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 ${String(value.type)}`);
+            //@ts-expect-error
+            tag.write(ctx, value.type);
+            const variant = variants[value.type];
+            //@ts-expect-error
+            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];
+            //@ts-expect-error
+            const value = variant.read(ctx);
+            return { type, value };
+        },
+    };
+}

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

@@ -0,0 +1,67 @@
+import { describe, expectTypeOf, it } from "bun:test";
+import { encodeTest, expectEncodeSize, encodeSnapshotTest, encodeFailTest } 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(),
+        });
+        encodeTest(spec, { type: 1, value: "s" });
+        encodeTest(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(),
+        });
+        encodeTest(spec, { type: "foo", value: "woof" });
+        encodeTest(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(),
+        });
+        //@ts-expect-error, intended
+        encodeFailTest(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(),
+        });
+        //@ts-expect-error, intended
+        encodeFailTest(spec, { type: "unknown", value: "woof" });
+    });
+    it("throws error on invalid value", () => {
+        const spec = st.taggedUnion(st.string(st.u8()), {
+            foo: st.string(st.u8()),
+        });
+        //@ts-expect-error, intended
+        encodeFailTest(spec, { type: "foo", value: 0 });
+    });
+    it("encodes varying sizes", () => {
+        const spec = st.taggedUnion(st.u8(), {
+            1: st.string(st.u8()),
+            2: st.u8(),
+        });
+        encodeTest(spec, { type: 1, value: "s" });
+        expectEncodeSize(spec, 5, { type: 1, value: "foo" });
+        expectEncodeSize(spec, 2, { type: 2, value: 52 });
+    });
+    it("encodes snapshots", () => {
+        encodeSnapshotTest(st.taggedUnion(st.u32(), {
+            0: st.list(st.u8(), st.f64()),
+            3: st.u32(),
+        }), { type: 0, value: [1] });
+    });
+    expectTypeOf(st.taggedUnion(st.u32(), {
+        0: st.u8(),
+        1: st.string(st.u32()),
+    })).toEqualTypeOf();
+    () => {
+        //@ts-expect-error, must be same type as tags
+        st.taggedUnion(st.string(st.u8()), { 0: st.u8(), 1: st.string(st.u32()) });
+    };
+});

package/dist/datatypes/index.d.ts

@@ -1,16 +1,13 @@
 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 { taggedUnion } from "./containers/taggedUnion";
+export { exhuastiveArray } from "./containers/exhuastiveArray";
+export { bytes } from "./values/bytes";
+export { sizedBytes } from "./values/sizedbytes";
 export { string } from "./values/string";
-export { buffer } from "./values/buffer";
-export { byteLiteral } from "./values/byteliteral";
-export { createRememberedValue } from "./utilities/remember";
-export { type Transform as Pipeline, pipe } from "./transforms/pipe";
-export { positionOffset } from "./transforms/readOffset";
-export { transform } from "./transforms/transform";

package/dist/datatypes/index.js

@@ -1,16 +1,13 @@
 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 { taggedUnion } from "./containers/taggedUnion";
+export { exhuastiveArray } from "./containers/exhuastiveArray";
+export { bytes } from "./values/bytes";
+export { sizedBytes } from "./values/sizedbytes";
 export { string } from "./values/string";
-export { buffer } from "./values/buffer";
-export { byteLiteral } from "./values/byteliteral";
-export { createRememberedValue } from "./utilities/remember";
-export { pipe } from "./transforms/pipe";
-export { positionOffset } from "./transforms/readOffset";
-export { transform } from "./transforms/transform";