@nnilky/structo 1.0.5 → 1.0.8

package/dist/datatypes/numbers/sints.test.js

@@ -1,21 +1,21 @@
 //@ts-ignore TODO
 import { describe, it, expect } from "bun:test";
-import { expectEncode, expectEncodeSnapshot, expectError, randint } from "../utils.test";
+import { encodeTest, encodeSnapshotTest, expectError, randint, encodeFailTest, } from "../../utils.test";
 import * as st from "../../index";
 function test_sint(options) {
     const { name, range: [start, end], serializer, size, disableRangeCheck, } = options;
     describe(name, () => {
         it(`works in bounds`, () => {
-            expectEncode(serializer, start);
+            encodeTest(serializer, start);
             for (let i = 0; i < 100; i++) {
-                expectEncode(serializer, randint(start, end));
+                encodeTest(serializer, randint(start, end));
             }
-            expectEncode(serializer, end);
+            encodeTest(serializer, end);
         });
         if (!disableRangeCheck) {
             it(`errors outside bounds`, () => {
-                expectError(() => st.write(serializer, start - 1));
-                expectError(() => st.write(serializer, end + 1));
+                encodeFailTest(serializer, start - 1);
+                encodeFailTest(serializer, end + 1);
             });
         }
         it(`errors on decimal`, () => {
@@ -33,11 +33,11 @@ function test_sint(options) {
             expectValueSize(end);
         });
         it(`matches snapshots`, () => {
-            expectEncodeSnapshot(serializer, 0);
-            expectEncodeSnapshot(serializer, start);
-            expectEncodeSnapshot(serializer, start + 10);
-            expectEncodeSnapshot(serializer, end - 10);
-            expectEncodeSnapshot(serializer, end);
+            encodeSnapshotTest(serializer, 0);
+            encodeSnapshotTest(serializer, start);
+            encodeSnapshotTest(serializer, start + 10);
+            encodeSnapshotTest(serializer, end - 10);
+            encodeSnapshotTest(serializer, end);
         });
     });
 }

package/dist/datatypes/numbers/uints.test.js

@@ -1,21 +1,21 @@
 //@ts-ignore TODO
 import { describe, it, expect } from "bun:test";
-import { expectEncode, expectEncodeSnapshot, expectError, randint } from "../utils.test";
+import { encodeTest, encodeSnapshotTest, expectError, randint, encodeFailTest, } from "../../utils.test";
 import * as st from "../../index";
 function test_uint(options) {
     const { name, range: [start, end], serializer, size, disableMaxCheck, } = options;
     describe(name, () => {
         it(`works in bounds`, () => {
-            expectEncode(serializer, start);
+            encodeTest(serializer, start);
             for (let i = 0; i < 100; i++) {
-                expectEncode(serializer, randint(start, end));
+                encodeTest(serializer, randint(start, end));
             }
-            expectEncode(serializer, end);
+            encodeTest(serializer, end);
         });
         it(`errors outside bounds`, () => {
-            expectError(() => st.write(serializer, start - 1));
+            encodeFailTest(serializer, start - 1);
             if (!disableMaxCheck) {
-                expectError(() => st.write(serializer, end + 1));
+                encodeFailTest(serializer, end + 1);
             }
         });
         it(`errors on decimal`, () => {
@@ -33,11 +33,11 @@ function test_uint(options) {
             expectValueSize(end);
         });
         it(`matches snapshots`, () => {
-            expectEncodeSnapshot(serializer, 0);
-            expectEncodeSnapshot(serializer, start);
-            expectEncodeSnapshot(serializer, start + 10);
-            expectEncodeSnapshot(serializer, end - 10);
-            expectEncodeSnapshot(serializer, end);
+            encodeSnapshotTest(serializer, 0);
+            encodeSnapshotTest(serializer, start);
+            encodeSnapshotTest(serializer, start + 10);
+            encodeSnapshotTest(serializer, end - 10);
+            encodeSnapshotTest(serializer, end);
         });
     });
 }

package/dist/datatypes/values/bytes.test.js

@@ -1,14 +1,14 @@
 import { describe, it } from "bun:test";
-import { bytes, expectEncode, expectError } from "../utils.test";
+import { bytes, encodeFailTest, encodeTest } from "../../utils.test";
 import * as st from "../../index";
 describe("st.bytes", () => {
     const buffer = st.bytes(2);
     it("encode correctly", () => {
-        expectEncode(buffer, bytes([1, 2]));
+        encodeTest(buffer, bytes([1, 2]));
     });
     it("encodes empty correctly", () => {
         const spec = st.bytes(0);
-        expectEncode(spec, bytes([]));
+        encodeTest(spec, bytes([]));
     });
     it("holds large data", () => {
         const size = 1024 * 1024 * 8; // 8MB
@@ -16,7 +16,7 @@ describe("st.bytes", () => {
         const data = new Uint8Array(size);
         data.set([3, 4], 1000);
         data.set([3, 4], 2000);
-        expectEncode(spec, data.buffer);
+        encodeTest(spec, data.buffer);
     });
     it("large data writes work", () => {
         const size = 1024 * 1024 * 8; // 8MB
@@ -28,7 +28,7 @@ describe("st.bytes", () => {
         const data = new Uint8Array(size);
         data.set([3, 4], 1000);
         data.set([3, 4], 2000);
-        expectEncode(spec, {
+        encodeTest(spec, {
             before: 1,
             data: data.buffer,
             after: 2,
@@ -36,8 +36,6 @@ describe("st.bytes", () => {
     });
     it("errors on invalid length", () => {
         const spec = st.bytes(5);
-        expectError(() => {
-            st.write(spec, bytes([1, 2, 3, 4]));
-        });
+        encodeFailTest(spec, bytes([1, 2, 3, 4]));
     });
 });

package/dist/datatypes/values/json.d.ts

@@ -0,0 +1,10 @@
+import type { Serializer } from "../../types";
+/**
+ * `st.json` stores JSON data using a string serializer
+ *
+ * ```
+ * st.json(st.string(st.u32()))
+ * ```
+ *
+ */
+export declare function json(type: Serializer<string>): Serializer<any>;

package/dist/datatypes/values/json.js

@@ -0,0 +1,21 @@
+/**
+ * `st.json` stores JSON data using a string serializer
+ *
+ * ```
+ * st.json(st.string(st.u32()))
+ * ```
+ *
+ */
+export function json(type) {
+    return {
+        size: type.size,
+        write: (ctx, value) => {
+            const json = JSON.stringify(value);
+            type.write(ctx, json);
+        },
+        read: (ctx) => {
+            const value = type.read(ctx);
+            return JSON.parse(value);
+        },
+    };
+}

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

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

package/dist/datatypes/values/sizedbytes.js

@@ -0,0 +1,17 @@
+export function sizedBytes(length) {
+    return {
+        write: (ctx, value) => {
+            length.write(ctx, value.byteLength);
+            const bytes = new Uint8Array(value);
+            ctx.alloc(value.byteLength);
+            new Uint8Array(ctx.view.buffer).set(bytes, ctx.offset);
+            ctx.offset += value.byteLength;
+        },
+        read: (ctx) => {
+            const size = length.read(ctx);
+            const slice = ctx.buffer.slice(ctx.offset, ctx.offset + size);
+            ctx.offset += size;
+            return slice;
+        },
+    };
+}

package/dist/datatypes/values/sizedbytes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/datatypes/values/sizedbytes.test.js

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

package/dist/datatypes/values/string.d.ts

@@ -0,0 +1,14 @@
+import type { Serializer } from "../../types";
+/**
+ * `st.json` stores string data by writing/reading the length and then reading that many bytes
+ *
+ * The type passed in is the type used to store it's length
+ *
+ * Note: The length stored is the byte length, not string length
+ *
+ * ```
+ * st.string(st.u32())
+ * ```
+ *
+ */
+export declare function string(length: Serializer<number>): Serializer<string>;

package/dist/datatypes/values/string.js

@@ -0,0 +1,36 @@
+/**
+ * `st.json` stores string data by writing/reading the length and then reading that many bytes
+ *
+ * The type passed in is the type used to store it's length
+ *
+ * Note: The length stored is the byte length, not string length
+ *
+ * ```
+ * st.string(st.u32())
+ * ```
+ *
+ */
+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");
+            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/values/string.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/datatypes/values/string.test.js

@@ -0,0 +1,21 @@
+import { describe, it } from "bun:test";
+import { encodeFailTest, encodeTest } from "../../utils.test";
+import * as st from "../../index";
+describe("st.string", () => {
+    it("encode correctly", () => {
+        encodeTest(st.string(st.u8()), "foo");
+    });
+    it("works on empty strings", () => {
+        encodeTest(st.string(st.u32()), "");
+    });
+    it("errors on numbers", () => {
+        //@ts-expect-error, intentional mistake
+        encodeFailTest(st.string(st.u8()), 8);
+    });
+    it("works on long strings", () => {
+        encodeTest(st.string(st.u32()), "A".repeat(2 ** 24));
+    });
+    it("errors on too long strings", () => {
+        encodeFailTest(st.string(st.u8()), "A".repeat(256));
+    });
+});

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export type { InferInput as Infer, InferInput, InferOutput, ReaderContext, WriterContext, Serializer, } from "./types";
-export * from "./datatypes/index";
+export type { InferOutput as Infer, InferInput, InferOutput, ReaderContext, WriterContext, Serializer, } from "./types";
 export { read, createReaderContext } from "./read";
 export { write, createdWriterContext } from "./write";
+export * from "./datatypes/index";
+export * from "./transforms/index";
+export * from "./utilities/index";

package/dist/index.js

@@ -1,3 +1,5 @@
-export * from "./datatypes/index";
 export { read, createReaderContext } from "./read";
 export { write, createdWriterContext } from "./write";
+export * from "./datatypes/index";
+export * from "./transforms/index";
+export * from "./utilities/index";

package/dist/read.d.ts

@@ -1,7 +1,3 @@
-import type { Serializer } from "./types";
+import type { Serializer, ReaderContext } from "./types";
 export declare function read<TIn, TOut>(serializer: Serializer<TIn, TOut>, buffer: ArrayBuffer): TOut;
-export declare function createReaderContext(buffer: ArrayBuffer): {
-    offset: number;
-    buffer: ArrayBuffer;
-    view: DataView<ArrayBuffer>;
-};
+export declare function createReaderContext(buffer: ArrayBuffer): ReaderContext;

package/dist/read.js

@@ -1,8 +1,16 @@
 export function read(serializer, buffer) {
-    return serializer.read(createReaderContext(buffer));
+    const ctx = createReaderContext(buffer);
+    try {
+        return serializer.read(ctx);
+    }
+    catch (e) {
+        const path = ctx.stack.join("") ?? "root";
+        throw new Error(`Deserialization error at serializer${path}`, { cause: e });
+    }
 }
 export function createReaderContext(buffer) {
     return {
+        stack: [],
         offset: 0,
         buffer,
         view: new DataView(buffer),

package/dist/transforms/encode.d.ts

@@ -0,0 +1,5 @@
+import type { Transform } from "./pipe";
+export declare function encode<TIn, TOut>(options: {
+    encode: (value: TOut) => TIn;
+    decode: (value: TIn) => TOut;
+}): Transform<TOut, TIn>;

package/dist/transforms/encode.js

@@ -0,0 +1,8 @@
+export function encode(options) {
+    const { encode, decode } = options;
+    return (type) => ({
+        size: type.size,
+        read: (ctx) => decode(type.read(ctx)),
+        write: (ctx, value) => type.write(ctx, encode(value)),
+    });
+}

package/dist/transforms/enum.d.ts

@@ -0,0 +1,2 @@
+export declare function enum_<const T>(values: T[]): import("./pipe").Transform<T, any>;
+export { enum_ as enum };

package/dist/transforms/enum.js

@@ -0,0 +1,16 @@
+import { encode } from "./encode";
+export function enum_(values) {
+    return encode({
+        encode: (v) => {
+            if (!values.includes(v))
+                throw new Error(`Invalid enum variant: ${v}`);
+            return v;
+        },
+        decode: (v) => {
+            if (!values.includes(v))
+                throw new Error(`Invalid enum variant: ${v}`);
+            return v;
+        },
+    });
+}
+export { enum_ as enum };

package/dist/transforms/enum.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transforms/enum.test.js

@@ -0,0 +1,21 @@
+import { describe, it } from "node:test";
+import * as st from "../index";
+import { encodeTest, encodeFailTest } from "../utils.test";
+describe("st.enum", () => {
+    it("encode correctly", () => {
+        encodeTest(st.pipe(st.u8(), st.enum([0, 1, 2])), //
+        1);
+        encodeTest(st.pipe(st.string(st.u8()), st.enum(["foo", "bar", "woof"])), //
+        "foo");
+    });
+    it("invalid union variants error", () => {
+        //@ts-expect-error
+        encodeFailTest(st.pipe(st.u8(), st.enum([0, 1, 2])), 4);
+        //@ts-expect-error
+        encodeFailTest(st.pipe(st.string(st.u8()), st.enum(["A", "B", "C"])), "D");
+    });
+    () => {
+        //@ts-expect-error, invalid union variant
+        st.write(st.pipe(st.u8(), st.enum([0, 1, 2])), 4);
+    };
+});

package/dist/transforms/fixedOffset.d.ts

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

package/dist/transforms/fixedOffset.js

@@ -0,0 +1,18 @@
+export function fixedOffset(delta) {
+    return (type) => ({
+        size: type.size,
+        read: (ctx) => {
+            let start = ctx.offset;
+            ctx.offset += delta;
+            const value = type.read(ctx);
+            ctx.offset = start;
+            return value;
+        },
+        write: (ctx, value) => {
+            let start = ctx.offset;
+            ctx.offset += delta;
+            type.write(ctx, value);
+            ctx.offset = start;
+        },
+    });
+}

package/dist/transforms/index.d.ts

@@ -0,0 +1,11 @@
+export { type Transform as Pipeline, pipe } from "./pipe";
+export { encode } from "./encode";
+export { modify } from "./modify";
+export { literal } from "./literal";
+export { enum } from "./enum";
+export { offset } from "./offset";
+export { toAscii } from "./toAscii";
+export { toBytes } from "./toBytes";
+export { toHex } from "./toHex";
+export { toBase64 } from "./toBase64";
+export { toTypedArray } from "./toTypedArray";

package/dist/transforms/index.js

@@ -0,0 +1,11 @@
+export { pipe } from "./pipe";
+export { encode } from "./encode";
+export { modify } from "./modify";
+export { literal } from "./literal";
+export { enum } from "./enum";
+export { offset } from "./offset";
+export { toAscii } from "./toAscii";
+export { toBytes } from "./toBytes";
+export { toHex } from "./toHex";
+export { toBase64 } from "./toBase64";
+export { toTypedArray } from "./toTypedArray";

package/dist/transforms/literal.d.ts

@@ -0,0 +1 @@
+export declare function literal<const T>(value: T): import("./pipe").Transform<T, any>;

package/dist/transforms/literal.js

@@ -0,0 +1,15 @@
+import { encode } from "./encode";
+export function literal(value) {
+    return encode({
+        encode: (v) => {
+            if (v !== value)
+                throw new Error(`Invalid literal variant: ${v}`);
+            return v;
+        },
+        decode: (v) => {
+            if (v !== value)
+                throw new Error(`Invalid literal variant: ${v}`);
+            return v;
+        },
+    });
+}

package/dist/transforms/literal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transforms/literal.test.js

@@ -0,0 +1,23 @@
+import { describe, it } from "node:test";
+import * as st from "../index";
+import { encodeTest, encodeFailTest } from "../utils.test";
+describe("st.literal", () => {
+    it("encode correctly", () => {
+        encodeTest(st.pipe(st.u8(), st.literal(0)), //
+        0);
+        encodeTest(st.pipe(st.string(st.u8()), st.literal("foo")), //
+        "foo");
+    });
+    it("invalid literal errors", () => {
+        //@ts-expect-error
+        encodeFailTest(st.pipe(st.u8(), st.literal(0)), 2);
+        //@ts-expect-error
+        encodeFailTest(st.pipe(st.string(st.u8()), st.literal("A")), "B");
+    });
+    () => {
+        //@ts-expect-error, invalid union variant
+        st.write(st.pipe(st.u8(), st.literal(0)), 1);
+        //@ts-expect-error, invalid union variant
+        st.write(st.pipe(st.u8(), st.literal("foo")), "bar");
+    };
+});

package/dist/transforms/modify.d.ts

@@ -0,0 +1,20 @@
+import type { Transform } from "./pipe";
+/**
+ * A readonly modification function, useful for sizes or offsets.
+ *
+ * If you want a writable value, use `st.encode` instead
+ *
+ *
+ * ```ts
+ * length: length.save(st.u32())
+ * st.sizedBytes(
+ *   st.pipe(
+ *     length.load(),
+ *     st.modify(v => v - 8),
+ *   )
+ * ))
+ *
+ * st.pipe()
+ * ```
+ */
+export declare function modify<TIn, TOut>(callback: (value: TIn) => TOut): Transform<TOut, TIn>;

package/dist/transforms/modify.js

@@ -0,0 +1,27 @@
+/**
+ * A readonly modification function, useful for sizes or offsets.
+ *
+ * If you want a writable value, use `st.encode` instead
+ *
+ *
+ * ```ts
+ * length: length.save(st.u32())
+ * st.sizedBytes(
+ *   st.pipe(
+ *     length.load(),
+ *     st.modify(v => v - 8),
+ *   )
+ * ))
+ *
+ * st.pipe()
+ * ```
+ */
+export function modify(callback) {
+    return (type) => ({
+        size: type.size,
+        read: (ctx) => callback(type.read(ctx)),
+        write: () => {
+            throw new Error("Cannot write an encoded value");
+        },
+    });
+}

package/dist/transforms/modify.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transforms/modify.test.js

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "bun:test";
+import { encodeFailTest } from "../utils.test";
+import * as st from "../index";
+describe("st.modify", () => {
+    it("encodes correctly", () => {
+        const data = st.write(st.u32(), 10);
+        const output = st.read(st.pipe(st.u32(), st.modify((v) => v + 8)), data);
+        expect(output).toBe(18);
+    });
+    it("cannot be written", () => {
+        encodeFailTest(st.pipe(st.u32(), st.modify((v) => v + 8)), 3);
+    });
+    it("does not modify size", () => {
+        const spec = st.pipe(st.u32(), st.modify((v) => v + 8));
+        expect(spec.size).toBe(4);
+    });
+});

package/dist/transforms/noAdvance.d.ts

@@ -0,0 +1,16 @@
+import type { Serializer } from "../types";
+/**
+ * Whilst reading this type, don't advance the offset after reading
+ *
+ * This can be useful for taggedUnions where they key is the first value in all the variants
+ *
+ * ```
+ * st.object({
+ *     stringLength: st.pipe(
+ *         st.u16(),
+ *         st.noAdvance(),
+ *     ),
+ *     text: st.string(st.u16()),
+ * })
+ */
+export declare function noAdvance<T>(): (type: Serializer<T>) => Serializer<T>;

package/dist/transforms/noAdvance.js

@@ -0,0 +1,30 @@
+/**
+ * Whilst reading this type, don't advance the offset after reading
+ *
+ * This can be useful for taggedUnions where they key is the first value in all the variants
+ *
+ * ```
+ * st.object({
+ *     stringLength: st.pipe(
+ *         st.u16(),
+ *         st.noAdvance(),
+ *     ),
+ *     text: st.string(st.u16()),
+ * })
+ */
+export function noAdvance() {
+    return (type) => ({
+        size: type.size,
+        read: (ctx) => {
+            let start = ctx.offset;
+            const value = type.read(ctx);
+            ctx.offset = start;
+            return value;
+        },
+        write: (ctx, value) => {
+            let start = ctx.offset;
+            type.write(ctx, value);
+            ctx.offset = start;
+        },
+    });
+}

package/dist/transforms/noAdvance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transforms/noAdvance.test.js

@@ -0,0 +1,17 @@
+import { describe, it } from "node:test";
+import * as st from "../index";
+import { encodeTest } from "../utils.test";
+describe("st.noAdvance", () => {
+    it("encode correctly", () => {
+        encodeTest(st.object({
+            length: st.pipe(st.u8(), st.noAdvance()),
+            text: st.string(st.u8()),
+        }), //
+        { length: 3, text: "foo" });
+        encodeTest(st.object({
+            a: st.pipe(st.u16(), st.noAdvance()),
+            b: st.f16(),
+        }), //
+        { a: 0, b: 1 }, { a: 15360, b: 1 });
+    });
+});

package/dist/transforms/offset.d.ts

@@ -0,0 +1,2 @@
+import type { Serializer } from "../types";
+export declare function offset<TIn, TOut>(behaviour: "relative" | "absolute", offset: Serializer<number> | number): (type: Serializer<TIn, TOut>) => Serializer<TIn, TOut>;