@nnilky/structo 1.0.4 → 1.0.7

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

@@ -1,19 +1,19 @@
 import { describe, it, expect } from "bun:test";
-import { expectEncode, expectEncodeSnapshot, expectError, randbigint } from "../utils.test";
+import { encodeTest, encodeSnapshotTest, randbigint, encodeFailTest } from "../../utils.test";
 import * as st from "../../index";
 function test_bigint(options) {
     const { name, range: [start, end], serializer, size, } = options;
     describe(name, () => {
         it("works in bounds", () => {
-            expectEncode(serializer, start);
+            encodeTest(serializer, start);
             for (let i = 0; i < 100; i++) {
-                expectEncode(serializer, randbigint(start, end));
+                encodeTest(serializer, randbigint(start, end));
             }
-            expectEncode(serializer, end);
+            encodeTest(serializer, end);
         });
         it("outside bounds", () => {
-            expectError(() => st.write(serializer, start - 1n));
-            expectError(() => st.write(serializer, end + 1n));
+            encodeFailTest(serializer, start - 1n);
+            encodeFailTest(serializer, end + 1n);
         });
         it(`is right size`, () => {
             const expectValueSize = (value) => {
@@ -27,11 +27,11 @@ function test_bigint(options) {
             expectValueSize(end);
         });
         it(`matches snapshots`, () => {
-            expectEncodeSnapshot(serializer, 0n);
-            expectEncodeSnapshot(serializer, start);
-            expectEncodeSnapshot(serializer, start + 10n);
-            expectEncodeSnapshot(serializer, end - 10n);
-            expectEncodeSnapshot(serializer, end);
+            encodeSnapshotTest(serializer, 0n);
+            encodeSnapshotTest(serializer, start);
+            encodeSnapshotTest(serializer, start + 10n);
+            encodeSnapshotTest(serializer, end - 10n);
+            encodeSnapshotTest(serializer, end);
         });
     });
 }

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,

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

@@ -1,71 +1,73 @@
 //@ts-ignore TODO
 import { describe, it, expect } from "bun:test";
-import { expectEncode, expectEncodeSnapshot, expectError, randint } from "../utils.test";
+import { encodeTest, expectEncodeSize } from "../../utils.test";
 import * as st from "../../index";
-function test_sint(options) {
-    const { name, range: [start, end], serializer, size, } = options;
+function test_float(options) {
+    const { name, serializer, size } = options;
+    const expectEncodeApproximately = (value) => {
+        const data = st.write(serializer, value);
+        const newValue = st.read(serializer, data);
+        if (isNaN(value) && isNaN(newValue))
+            return;
+        if (value === newValue)
+            return;
+        if (Math.abs(value - newValue) < 0.000001)
+            return;
+        expect(false, "Failed comparsion tests");
+    };
     describe(name, () => {
         it(`works in bounds`, () => {
-            expectEncode(serializer, start);
             for (let i = 0; i < 100; i++) {
-                expectEncode(serializer, randint(start, end));
+                expectEncodeApproximately(Math.random());
             }
-            expectEncode(serializer, end);
         });
-        it(`errors outside bounds`, () => {
-            expectError(() => st.write(serializer, start - 1));
-            expectError(() => st.write(serializer, end + 1));
+        it(`works on Infinty`, () => {
+            encodeTest(serializer, Infinity);
+            encodeTest(serializer, -Infinity);
         });
-        it(`errors on decimal`, () => {
-            expectError(() => st.write(serializer, 0.1));
+        it(`works on NaN`, () => {
+            encodeTest(serializer, NaN);
+        });
+        it(`works on 0`, () => {
+            encodeTest(serializer, 0);
+        });
+        it(`works on -0`, () => {
+            encodeTest(serializer, -0);
         });
         it(`is right size`, () => {
-            const expectValueSize = (value) => {
-                const data = st.write(serializer, value);
-                expect(data.byteLength).toBe(size);
-            };
             for (let i = 0; i < 100; i++) {
-                expectValueSize(randint(start, end));
+                expectEncodeSize(serializer, size, Math.random());
             }
-            expectValueSize(start);
-            expectValueSize(end);
-        });
-        it(`matches snapshots`, () => {
-            expectEncodeSnapshot(serializer, 0);
-            expectEncodeSnapshot(serializer, start);
-            expectEncodeSnapshot(serializer, start + 10);
-            expectEncodeSnapshot(serializer, end - 10);
-            expectEncodeSnapshot(serializer, end);
         });
     });
 }
-test_sint({
-    name: "st.s8",
-    serializer: st.s8(),
-    range: [-128, 127],
-    size: 1,
-});
-test_sint({
-    name: "st.s16(little)",
-    serializer: st.s16("little"),
-    range: [-32_768, 32_767],
+test_float({
+    name: "st.f16(little)",
+    serializer: st.f16("little"),
     size: 2,
 });
-test_sint({
-    name: "st.s16(big)",
-    serializer: st.s16("big"),
-    range: [-32_768, 32_767],
+test_float({
+    name: "st.f16(big)",
+    serializer: st.f16("big"),
     size: 2,
 });
-test_sint({
-    name: "st.s32(little)",
-    serializer: st.s32("little"),
-    range: [-2_147_483_648, 2_147_483_647],
+test_float({
+    name: "st.f32(little)",
+    serializer: st.f32("little"),
     size: 4,
 });
-test_sint({
-    name: "st.s32(big)",
-    serializer: st.s32("big"),
-    range: [-2_147_483_648, 2_147_483_647],
+test_float({
+    name: "st.f32(big)",
+    serializer: st.f32("big"),
     size: 4,
 });
+test_float({
+    name: "st.f64(little)",
+    serializer: st.f64("little"),
+    size: 8,
+});
+test_float({
+    name: "st.f64(big)",
+    serializer: st.f64("big"),
+    size: 8,
+});

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

@@ -1,5 +1,9 @@
 import type { Serializer } from "../../types";
+/** 8bit signed integer */
 export declare function s8(): Serializer<number>;
+/** 16bit signed integer */
 export declare function s16(endian?: "little" | "big"): Serializer<number>;
+/** 32bit signed integer */
 export declare function s32(endian?: "little" | "big"): Serializer<number>;
+/** 64bit signed integer */
 export declare function s64(endian?: "little" | "big"): Serializer<number>;

package/dist/datatypes/numbers/sints.js

@@ -6,6 +6,7 @@ const checkValue = (value, start, end) => {
         throw new Error("Out of Range");
     }
 };
+/** 8bit signed integer */
 export function s8() {
     return {
         size: 1,
@@ -22,6 +23,7 @@ export function s8() {
         },
     };
 }
+/** 16bit signed integer */
 export function s16(endian = "little") {
     return {
         size: 2,
@@ -38,6 +40,7 @@ export function s16(endian = "little") {
         },
     };
 }
+/** 32bit signed integer */
 export function s32(endian = "little") {
     return {
         size: 4,
@@ -54,6 +57,7 @@ export function s32(endian = "little") {
         },
     };
 }
+/** 64bit signed integer */
 export function s64(endian = "little") {
     return {
         size: 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.d.ts

@@ -1,5 +1,9 @@
 import type { Serializer } from "../../types";
+/** 8bit unsigned integer */
 export declare function u8(): Serializer<number>;
+/** 16bit unsigned integer */
 export declare function u16(endian?: "little" | "big"): Serializer<number>;
+/** 32bit unsigned integer */
 export declare function u32(endian?: "little" | "big"): Serializer<number>;
+/** 64bit unsigned integer */
 export declare function u64(endian?: "little" | "big"): Serializer<number>;

package/dist/datatypes/numbers/uints.js

@@ -1,3 +1,4 @@
+/** 8bit unsigned integer */
 export function u8() {
     return {
         size: 1,
@@ -17,6 +18,7 @@ export function u8() {
         },
     };
 }
+/** 16bit unsigned integer */
 export function u16(endian = "little") {
     return {
         size: 2,
@@ -36,6 +38,7 @@ export function u16(endian = "little") {
         },
     };
 }
+/** 32bit unsigned integer */
 export function u32(endian = "little") {
     return {
         size: 4,
@@ -55,6 +58,7 @@ export function u32(endian = "little") {
         },
     };
 }
+/** 64bit unsigned integer */
 export function u64(endian = "little") {
     return {
         size: 8,

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/transforms/encode.d.ts

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

package/dist/datatypes/transforms/encode.js

@@ -0,0 +1,7 @@
+export function encode(encodeTo, encodeFrom) {
+    return (type) => ({
+        size: type.size,
+        read: (ctx) => encodeTo(type.read(ctx)),
+        write: (ctx, value) => type.write(ctx, encodeFrom(value)),
+    });
+}

package/dist/datatypes/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/datatypes/transforms/{readOffset.js → fixedOffset.js}

@@ -1,4 +1,4 @@
-export function positionOffset(delta) {
+export function fixedOffset(delta) {
     return (type) => ({
         size: type.size,
         read: (ctx) => {

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

@@ -0,0 +1,2 @@
+import type { Transform } from "./pipe";
+export declare function modify<T>(callback: (value: T) => T): Transform<T>;

package/dist/datatypes/transforms/modify.js

@@ -0,0 +1,7 @@
+export function modify(callback) {
+    return (type) => ({
+        size: type.size,
+        read: (ctx) => callback(type.read(ctx)),
+        write: (ctx, value) => type.write(ctx, callback(value)),
+    });
+}

package/dist/datatypes/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/datatypes/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/datatypes/transforms/pipe.js

@@ -1,3 +1,15 @@
+/**
+ * Pipe lets you chain modification functions together
+ * ```
+ * st.object({
+ *   age: st.u32(),
+ *   ageInMonths: st.pipe(
+ *     st.u32(),
+ *     st.modify(v => v * 12),
+ *     st.offset(-8),
+ *   )})
+ * ```
+ */
 export function pipe(type, ...pipeline) {
     //@ts-ignore
     return pipeline.reduce((v, func) => func(v), type);

package/dist/datatypes/utilities/remember.d.ts

@@ -1,5 +1,15 @@
 import type { Serializer } from "../../types";
+/**
+ * ```
+ * const length = st.createRememberedValue<number>()
+ * st.object({
+ *   length: length.save(st.u32()),
+ *   type: st.u8(),
+ *   data: st.sizedBytes(length.load())
+ * })
+ * ```
+ */
 export declare function createRememberedValue<T>(): {
     save: (serializer: Serializer<T>) => Serializer<T>;
-    load: () => Serializer<T>;
+    load: (serializer?: Serializer<T>) => Serializer<T>;
 };

package/dist/datatypes/utilities/remember.js

@@ -1,6 +1,16 @@
+/**
+ * ```
+ * const length = st.createRememberedValue<number>()
+ * st.object({
+ *   length: length.save(st.u32()),
+ *   type: st.u8(),
+ *   data: st.sizedBytes(length.load())
+ * })
+ * ```
+ */
 export function createRememberedValue() {
     const stack = [];
-    function store(serializer) {
+    function save(serializer) {
         return {
             size: serializer.size,
             read: (ctx) => {
@@ -15,12 +25,12 @@ export function createRememberedValue() {
             },
         };
     }
-    function load() {
+    function load(serializer) {
         return {
-            size: 0,
+            size: serializer?.size ?? 0,
             read: () => stack.pop(),
-            write: () => { },
+            write: (ctx) => serializer && serializer.write(ctx, stack.pop()),
         };
     }
-    return { save: store, load: load };
+    return { save: save, load: load };
 }

package/dist/datatypes/utilities/remember.test.d.ts

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

package/dist/datatypes/utilities/remember.test.js

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "bun:test";
+import { expectEncode, expectEncodeSnapshot } from "../utils.test";
+import * as st from "../../index";
+describe("st.remember", () => {
+    const v = st.createRememberedValue();
+    it("encodes correctly", () => {
+        const spec = st.object({
+            a: v.save(st.u32()),
+            b: st.list(v.load(), st.u8()),
+        });
+        expectEncode(spec, {
+            a: 3,
+            b: [1, 3, 4],
+        });
+    });
+    it("omitted serializer doesn't write data ", () => {
+        const spec = st.object({
+            a: v.save(st.u32()),
+            b: v.load(),
+        });
+        const output = st.write(spec, { a: 3, b: 0 });
+        expect(output.byteLength).toBe(4);
+    });
+    it("serializer is used write data ", () => {
+        const spec = st.object({
+            a: v.save(st.u32()),
+            b: v.load(st.u8()),
+        });
+        expectEncode(spec, { a: 3, b: 0 }, { a: 3, b: 3 });
+    });
+    it("snapshots are correct", () => {
+        expectEncodeSnapshot(st.object({
+            a: v.save(st.u32()),
+            b: st.list(v.load(), st.u8()),
+        }), {
+            a: 3,
+            b: [1, 3, 4],
+        });
+        expectEncodeSnapshot(st.object({
+            a: v.save(st.u32()),
+            b: v.load(st.u8()),
+        }), { a: 3, b: 0 });
+    });
+});

package/dist/datatypes/utils.test.d.ts

@@ -1,7 +1,8 @@
 import * as st from "../index";
 export declare const randint: (start: number, end: number) => number;
 export declare const randbigint: (start: bigint, end: bigint) => bigint;
-export declare const expectEncode: <T>(serializer: st.Serializer<T>, value: T) => void;
+export declare const expectEncode: <TIn, TOut>(serializer: st.Serializer<TIn, TOut>, value: TIn, expected?: TOut) => void;
+export declare const expectEncodeSize: <TIn, TOut>(serializer: st.Serializer<TIn, TOut>, size: number, value: TIn) => void;
 export declare const expectEncodeSnapshot: <T>(serializer: st.Serializer<T>, value: T) => void;
 export declare const expectError: (callback: () => void) => void;
 export declare const bytes: (bytes: number[]) => ArrayBuffer;

package/dist/datatypes/utils.test.js

@@ -10,10 +10,14 @@ export const randbigint = (start, end) => {
     const offset = BigInt(Math.floor(Number(range) * Math.random()));
     return start + offset;
 };
-export const expectEncode = (serializer, value) => {
+export const expectEncode = (serializer, value, expected) => {
     const data = st.write(serializer, value);
     const newValue = st.read(serializer, data);
-    expect(value).toEqual(newValue);
+    expect(newValue).toEqual((expected ?? value));
+};
+export const expectEncodeSize = (serializer, size, value) => {
+    const data = st.write(serializer, value);
+    expect(data.byteLength).toEqual(size);
 };
 export const expectEncodeSnapshot = (serializer, value) => {
     const data = st.write(serializer, value);

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

@@ -1,2 +1,2 @@
 import type { Serializer } from "../../types";
-export declare function byteLiteral(bytes: number[]): Serializer<number[]>;
+export declare function bytesLiteral(bytes: number[]): Serializer<number[]>;

package/dist/datatypes/values/byteliteral.js

@@ -1,4 +1,4 @@
-export function byteLiteral(bytes) {
+export function bytesLiteral(bytes) {
     const length = bytes.length;
     return {
         size: bytes.length,