@nnilky/structo 1.0.7 → 1.0.8

package/README.md

@@ -21,9 +21,9 @@ const Entity = st.object({
 ```
 
 - Lightweight, base size is <1KB and each datatype is a few hundred bytes
-- Fast, from [benchmarks](./benchmark) only 2-
-- Supports Web/Node.js compatible
-- Easily implemented
+- Fast![benchmarks](./benchmark) show only 1.5-5x slower than ideal implementaiton
+- Designed for both Web/Node.js compatible
+- Easily implement your own serializers
 
 Each serializer is completely seperate from the base library, meaning you only pay for what you use.
 

package/dist/datatypes/containers/array.js

@@ -7,6 +7,7 @@
  *
  */
 export function array(size, type) {
+    const SHOW_ERRORS = size < 4096;
     const { read: readType, write: writeType, size: typeSize } = type;
     return {
         size: type.size ? size * type.size : undefined,
@@ -16,13 +17,21 @@ export function array(size, type) {
             if (typeSize)
                 ctx.alloc(size * typeSize);
             for (let i = 0; i < size; i++) {
+                if (SHOW_ERRORS)
+                    ctx.stack.push(`[${i}]`);
                 writeType(ctx, value[i]);
+                if (SHOW_ERRORS)
+                    ctx.stack.pop();
             }
         },
         read: (ctx) => {
             const arr = new Array(size);
             for (let i = 0; i < size; i++) {
+                if (SHOW_ERRORS)
+                    ctx.stack.push(`[${i}]`);
                 arr[i] = readType(ctx);
+                if (SHOW_ERRORS)
+                    ctx.stack.pop();
             }
             return arr;
         },

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

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

package/dist/datatypes/containers/exhuastiveArray.js

@@ -1,23 +1,34 @@
-import * as st from "../..";
+import * as st from "../../index";
 /**
  * exhuastiveArray is read until the end of the data
  *
  * ```py
- * exhuastiveArray(st.u32())
+ * exhuastiveArray(st.string(st.u8()))
  * ```
  */
 export function exhuastiveArray(type) {
     return {
         read(ctx) {
             let arr = [];
+            let i = 0;
             while (ctx.offset < ctx.view.byteLength) {
+                const TRACK_STACK = i++ < 4096;
+                if (TRACK_STACK)
+                    ctx.stack.push(`[${arr.length - 1}]`);
                 arr.push(type.read(ctx));
+                if (TRACK_STACK)
+                    ctx.stack.pop();
             }
             return arr;
         },
         write(ctx, value) {
+            const TRACK_STACK = value.length < 4096;
             for (let i = 0; i < value.length; i++) {
+                if (TRACK_STACK)
+                    ctx.stack.push(`[${i}]`);
                 type.write(ctx, value[i]);
+                if (TRACK_STACK)
+                    ctx.stack.pop();
             }
         },
     };

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

@@ -3,7 +3,7 @@ type InferObject<T> = T extends Record<string, Serializer<any>> ? {
     [Key in keyof T]: InferInput<T[Key]>;
 } : never;
 /**
- * `fastObject` is equivelent to object but it uses eval to improve performance
+ * `fastObject` is equivelent to object but it uses eval to improve performance, additionally it omits error reporting
  *
  * This means that is should be avoided in scenarios where CSP is required (so can't be the default), but should be fine for all other cases
  *
@@ -15,7 +15,7 @@ type InferObject<T> = T extends Record<string, Serializer<any>> ? {
  * })
  * ```
  *
- * Note: Using st.lazy affects the performance of fastObject as it prevents discovery of subobjects, avoid when performance is a requirement
+ * 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

@@ -1,6 +1,6 @@
 const definitionSymbol = Symbol();
 /**
- * `fastObject` is equivelent to object but it uses eval to improve performance
+ * `fastObject` is equivelent to object but it uses eval to improve performance, additionally it omits error reporting
  *
  * This means that is should be avoided in scenarios where CSP is required (so can't be the default), but should be fine for all other cases
  *
@@ -12,7 +12,7 @@ const definitionSymbol = Symbol();
  * })
  * ```
  *
- * Note: Using st.lazy affects the performance of fastObject as it prevents discovery of subobjects, avoid when performance is a requirement
+ * 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/list.js

@@ -12,17 +12,29 @@ export function list(length, type) {
     return {
         write: (ctx, value) => {
             length.write(ctx, value.length);
-            if (type.size)
+            const TRACK_STACK = value.length < 4096;
+            if (type.size) {
                 ctx.alloc(value.length * type.size);
-            for (const v of value) {
+            }
+            for (let i = 0; i < value.length; i++) {
+                if (TRACK_STACK)
+                    ctx.stack.push(`[${i}]`);
+                const v = value[i];
                 type.write(ctx, v);
+                if (TRACK_STACK)
+                    ctx.stack.pop();
             }
         },
         read: (ctx) => {
             const size = length.read(ctx);
+            const TRACK_STACK = size < 4096;
             const arr = new Array(size);
             for (let i = 0; i < size; i++) {
+                if (TRACK_STACK)
+                    ctx.stack.push(`[${i}]`);
                 arr[i] = type.read(ctx);
+                if (TRACK_STACK)
+                    ctx.stack.pop();
             }
             return arr;
         },

package/dist/datatypes/containers/object.js

@@ -21,19 +21,19 @@ export function object(definition) {
             if (size)
                 ctx.alloc(size);
             for (let i = 0; i < entires.length; i++) {
-                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 });
-                }
+                const [key, serializer] = entires[i];
+                ctx.stack.push(`.${key}`);
+                serializer.write(ctx, value[key]);
+                ctx.stack.pop();
             }
         },
         read: (ctx) => {
             const output = new Array(entires.length);
             for (let i = 0; i < entires.length; i++) {
-                output[i] = [entires[i][0], entires[i][1].read(ctx)];
+                const [key, serializer] = entires[i];
+                ctx.stack.push(`.${key}`);
+                output[i] = [key, serializer.read(ctx)];
+                ctx.stack.pop();
             }
             return Object.fromEntries(output);
         },

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

@@ -12,6 +12,9 @@ describe("st.string", () => {
         //@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,4 @@
-export type { InferInput as Infer, InferInput, InferOutput, ReaderContext, WriterContext, Serializer, } from "./types";
+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";

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

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

package/dist/transforms/encode.js

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

package/dist/transforms/enum.js

@@ -1,13 +1,16 @@
 import { encode } from "./encode";
 export function enum_(values) {
-    return encode((v) => {
-        if (!values.includes(v))
-            throw new Error(`Invalid enum variant: ${v}`);
-        return v;
-    }, (v) => {
-        if (!values.includes(v))
-            throw new Error(`Invalid enum variant: ${v}`);
-        return v;
+    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/index.d.ts

@@ -3,8 +3,7 @@ export { encode } from "./encode";
 export { modify } from "./modify";
 export { literal } from "./literal";
 export { enum } from "./enum";
-export { fixedOffset } from "./fixedOffset";
-export { noAdvance } from "./noAdvance";
+export { offset } from "./offset";
 export { toAscii } from "./toAscii";
 export { toBytes } from "./toBytes";
 export { toHex } from "./toHex";

package/dist/transforms/index.js

@@ -3,8 +3,7 @@ export { encode } from "./encode";
 export { modify } from "./modify";
 export { literal } from "./literal";
 export { enum } from "./enum";
-export { fixedOffset } from "./fixedOffset";
-export { noAdvance } from "./noAdvance";
+export { offset } from "./offset";
 export { toAscii } from "./toAscii";
 export { toBytes } from "./toBytes";
 export { toHex } from "./toHex";

package/dist/transforms/literal.js

@@ -1,12 +1,15 @@
 import { encode } from "./encode";
 export function literal(value) {
-    return encode((v) => {
-        if (v !== value)
-            throw new Error(`Invalid literal variant: ${v}`);
-        return v;
-    }, (v) => {
-        if (v !== value)
-            throw new Error(`Invalid literal variant: ${v}`);
-        return v;
+    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/modify.d.ts

@@ -1,2 +1,20 @@
 import type { Transform } from "./pipe";
-export declare function modify<T>(callback: (value: T) => T): Transform<T>;
+/**
+ * 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

@@ -1,7 +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: (ctx, value) => type.write(ctx, callback(value)),
+        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/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>;

package/dist/transforms/offset.js

@@ -0,0 +1,20 @@
+export function offset(behaviour, offset) {
+    return (type) => ({
+        size: type.size,
+        read: (ctx) => {
+            let start = ctx.offset;
+            const offsetValue = typeof offset === "number" ? offset : offset.read(ctx);
+            ctx.offset = behaviour === "absolute" ? offsetValue : ctx.offset + offsetValue;
+            const value = type.read(ctx);
+            ctx.offset = start;
+            return value;
+        },
+        write: (ctx, value) => {
+            let start = ctx.offset;
+            const offsetValue = typeof offset === "number" ? offset : offset.read(ctx);
+            ctx.offset = behaviour === "absolute" ? offsetValue : ctx.offset + offsetValue;
+            type.write(ctx, value);
+            ctx.offset = start;
+        },
+    });
+}

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

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

package/dist/transforms/offset.test.js

@@ -0,0 +1,39 @@
+import { describe, it } from "bun:test";
+import { encodeTest } from "../utils.test";
+import * as st from "../index";
+describe("st.offset(relative)", () => {
+    it("encodes correctly with fixed offset", () => {
+        const spec = st.object({
+            foo: st.u32(),
+            bar: st.pipe(st.u32(), st.offset("relative", -4)),
+        });
+        encodeTest(spec, { foo: 1, bar: 5 }, { foo: 5, bar: 5 });
+    });
+    it("encodes correctly with read offset", () => {
+        const offset = st.createRememberedValue();
+        const spec = st.object({
+            foo: st.u32(),
+            offset: offset.save(st.s16()),
+            bar: st.pipe(st.u32(), st.offset("relative", offset.load())),
+        });
+        encodeTest(spec, { foo: 0, offset: -6, bar: 5 }, { foo: 5, offset: -6, bar: 5 });
+    });
+});
+describe("st.offset(absolute)", () => {
+    it("encodes correctly with fixed offset", () => {
+        const spec = st.object({
+            foo: st.u32(),
+            bar: st.pipe(st.u32(), st.offset("absolute", 0)),
+        });
+        encodeTest(spec, { foo: 0, bar: 5 }, { foo: 5, bar: 5 });
+    });
+    it("encodes correctly with read offset", () => {
+        const offset = st.createRememberedValue();
+        const spec = st.object({
+            foo: st.u32(),
+            offset: offset.save(st.u32()),
+            bar: st.pipe(st.u32(), st.offset("absolute", offset.load())),
+        });
+        encodeTest(spec, { foo: 0, offset: 0, bar: 5 }, { foo: 5, offset: 0, bar: 5 });
+    });
+});

package/dist/transforms/pipe.js

@@ -6,7 +6,7 @@
  *   ageInMonths: st.pipe(
  *     st.u32(),
  *     st.modify(v => v * 12),
- *     st.offset(-8),
+ *     st.offset("relative", -8),
  *   )})
  * ```
  */

package/dist/transforms/toAscii.js

@@ -1,8 +1,11 @@
 import { encode } from "./encode";
 export function toAscii() {
-    return encode((v) => new Uint8Array(Array.from(v).map((char) => validateAscii(char.charCodeAt(0)))).buffer, (v) => Array.from(new Uint8Array(v))
-        .map((v) => String.fromCharCode(v))
-        .join(""));
+    return encode({
+        encode: (v) => new Uint8Array(Array.from(v).map((char) => validateAscii(char.charCodeAt(0)))).buffer,
+        decode: (v) => Array.from(new Uint8Array(v))
+            .map((v) => String.fromCharCode(v))
+            .join(""),
+    });
 }
 const validateAscii = (v) => {
     if (v >= 0 && v <= 127)

package/dist/transforms/toBase64.js

@@ -1,4 +1,7 @@
 import { encode } from "./encode";
 export function toBase64() {
-    return encode((v) => Uint8Array.fromBase64(v).buffer, (v) => new Uint8Array(v).toBase64());
+    return encode({
+        encode: (v) => Uint8Array.fromBase64(v).buffer,
+        decode: (v) => new Uint8Array(v).toBase64(),
+    });
 }

package/dist/transforms/toBytes.js

@@ -12,7 +12,10 @@ import { encode } from "./encode";
  * `ArrayBuffer([0, 255, c])` => `[0, 255, ArrayBuffer([0, 255, 0])]`
  */
 export function toBytes() {
-    return encode((v) => new Uint8Array(v.map(validateByte)).buffer, (v) => Array.from(new Uint8Array(v)));
+    return encode({
+        encode: (v) => new Uint8Array(v.map(validateByte)).buffer,
+        decode: (v) => Array.from(new Uint8Array(v)),
+    });
 }
 const validateByte = (v) => {
     if (v >= 0 && v <= 255)

package/dist/transforms/toHex.js

@@ -12,5 +12,8 @@ import { encode } from "./encode";
  * `ArrayBuffer([0, 255, 0])` => `00FF00`
  */
 export function toHex() {
-    return encode((v) => Uint8Array.fromHex(v).buffer, (v) => new Uint8Array(v).toHex().toUpperCase());
+    return encode({
+        encode: (v) => Uint8Array.fromHex(v).buffer,
+        decode: (v) => new Uint8Array(v).toHex().toUpperCase(),
+    });
 }

package/dist/transforms/toTypedArray.js

@@ -10,5 +10,8 @@ import { encode } from "./encode";
  * ```
  */
 export function toTypedArray(arrayType) {
-    return encode((v) => v.buffer, (v) => new arrayType(v));
+    return encode({
+        encode: (v) => v.buffer,
+        decode: (v) => new arrayType(v),
+    });
 }

package/dist/types.d.ts

@@ -3,13 +3,16 @@ export type Serializer<TIn, TOut = TIn> = {
     write: (ctx: WriterContext, value: TIn) => void;
     read: (ctx: ReaderContext) => TOut;
 };
+export type SerializationContext = WriterContext | ReaderContext;
 export interface WriterContext {
+    stack: string[];
     buffer: ArrayBuffer;
     view: DataView;
     offset: number;
     alloc: (length: number) => void;
 }
 export interface ReaderContext {
+    stack: string[];
     buffer: ArrayBuffer;
     view: DataView;
     offset: number;

package/dist/utilities/index.d.ts

@@ -1,2 +1,3 @@
 export { lazy } from "./lazy";
+export { createReference } from "./reference";
 export { createRememberedValue } from "./remember";

package/dist/utilities/index.js

@@ -1,2 +1,3 @@
 export { lazy } from "./lazy";
+export { createReference } from "./reference";
 export { createRememberedValue } from "./remember";

package/dist/utilities/lazy.js

@@ -1,11 +1,11 @@
 export function lazy(type) {
     let _size;
     let resolve = () => {
-        const t = type();
-        _size = t.size ?? undefined;
-        serializer.read = t.read;
-        serializer.write = t.write;
         resolve = () => { };
+        const { size, write, read } = type();
+        _size = size ?? undefined;
+        serializer.read = read;
+        serializer.write = write;
     };
     const serializer = {
         get size() {

package/dist/utilities/reference.d.ts

@@ -0,0 +1,18 @@
+import type { Serializer } from "../types";
+/**
+ * createReference lets you defer writing a value until later, useful for lengths and sizes
+ *
+ * ---
+ * ```
+ * const length = st.createReference<number>()
+ * st.object({
+ *   length: length.pointer(st.u32()),
+ *   type: st.u8(),
+ *   data: st.sizedBytes(length.deref())
+ * })
+ * ```
+ */
+export declare function createReference<T>(): {
+    pointer: (serializer: Serializer<T>) => Serializer<T>;
+    deref: () => Serializer<T>;
+};

package/dist/utilities/reference.js

@@ -0,0 +1,91 @@
+/**
+ * createReference lets you defer writing a value until later, useful for lengths and sizes
+ *
+ * ---
+ * ```
+ * const length = st.createReference<number>()
+ * st.object({
+ *   length: length.pointer(st.u32()),
+ *   type: st.u8(),
+ *   data: st.sizedBytes(length.deref())
+ * })
+ * ```
+ */
+export function createReference() {
+    const readStack = [];
+    const writeStack = [];
+    /**
+     * When reading: reads the value normal and saves it for later
+     *
+     * When writing: omits this value, it is written by deref
+     *
+     * ---
+     * ```
+     * const length = st.createReference<number>()
+     * st.object({
+     *   length: length.pointer(st.u32()),
+     *   type: st.u8(),
+     *   data: st.sizedBytes(length.deref())
+     * })
+     * ```
+     */
+    function pointer(serializer) {
+        const size = serializer.size;
+        if (size === undefined)
+            throw new Error("Serializer must be sized");
+        return {
+            size,
+            read: (ctx) => {
+                const value = serializer.read(ctx);
+                readStack.push(value);
+                return value;
+            },
+            write: (ctx, value) => {
+                writeStack.push({
+                    offset: ctx.offset,
+                    serializer,
+                });
+                ctx.offset += size;
+                return value;
+            },
+        };
+    }
+    /**
+     * When reading: gets the value stored in pointer
+     *
+     * When writing: saves the value into the pointer
+     *
+     * By default the value is removed from the pointer,
+     * but you can retain it to ensure the next value is
+     *
+     * ---
+     * ```
+     * const length = st.createReference<number>()
+     * st.object({
+     *   length: length.pointer(st.u32()),
+     *   type: st.u8(),
+     *   data: st.sizedBytes(length.deref())
+     * })
+     * ```
+     */
+    function deref() {
+        return {
+            size: 0,
+            read: () => {
+                if (readStack.length === 0)
+                    throw new Error("Read Stack Empty");
+                return readStack.pop();
+            },
+            write: (ctx, value) => {
+                if (writeStack.length === 0)
+                    throw new Error("Write Stack is emtpy");
+                const { offset, serializer } = writeStack.pop();
+                const start = ctx.offset;
+                ctx.offset = offset;
+                serializer.write(ctx, value);
+                ctx.offset = start;
+            },
+        };
+    }
+    return { pointer, deref };
+}

package/dist/utilities/reference.test.d.ts

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

package/dist/utilities/reference.test.js

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import { encodeTest, encodeSnapshotTest, expectError } from "../utils.test";
+import * as st from "../index";
+describe("st.createReference", () => {
+    it("encodes correctly", () => {
+        const length = st.createReference();
+        const spec = st.object({
+            length: length.pointer(st.u32()),
+            numbers: st.list(length.deref(), st.u8()),
+        });
+        expect(spec.size).toBe(undefined);
+        encodeTest(spec, //
+        { length: 0, numbers: [1, 3, 4] }, { length: 3, numbers: [1, 3, 4] });
+    });
+    it("cant create reference to pointer", () => {
+        const length = st.createReference();
+        expectError(() => {
+            length.pointer(st.sizedBytes(st.u8()));
+        });
+    });
+    it("multiple runs function", () => {
+        const v = st.createReference();
+        const spec = st.object({
+            a: v.pointer(st.u32()),
+            b: st.list(v.deref(), st.u8()),
+        });
+        for (let i = 0; i < 3; i++) {
+            encodeTest(spec, //
+            { a: NaN, b: [1, 3, 4] }, { a: 3, b: [1, 3, 4] });
+        }
+    });
+    it("handles recursive objects", () => {
+        const size = st.createReference();
+        //@ts-expect-error, recursive types
+        const Node = st.lazy(() => st.object({
+            size: size.pointer(st.u32()),
+            children: st.list(size.deref(), Node),
+        }));
+        encodeTest(Node, {
+            size: NaN,
+            children: [
+                { size: NaN, children: [] },
+                { size: NaN, children: [{ size: NaN, children: [] }] },
+            ],
+        }, {
+            size: 2,
+            children: [
+                { size: 0, children: [] },
+                { size: 1, children: [{ size: 0, children: [] }] },
+            ],
+        });
+    });
+    it("snapshots are correct", () => {
+        const v = st.createReference();
+        encodeSnapshotTest(st.object({
+            a: v.pointer(st.u32()),
+            b: st.list(v.deref(), st.u8()),
+        }), {
+            a: 3,
+            b: [1, 3, 4],
+        });
+    });
+});

package/dist/utilities/remember.d.ts

@@ -2,16 +2,17 @@ import type { Serializer } from "../types";
 /**
  * createRememberedValue lets you save and recall a value when serializing
  *
+ * This is useful for checksums and other values calculated from a writen value
+ *
  * ```
- * const length = st.createRememberedValue<number>()
+ * const data = st.createRememberedValue<ArrayBuffer>()
  * st.object({
- *   length: length.save(st.u32()),
- *   type: st.u8(),
- *   data: st.sizedBytes(length.load())
+ *   data: data.save(st.bytes(1024))
+ *   checksum: crc32(data.load())
  * })
  * ```
  */
 export declare function createRememberedValue<T>(): {
     save: (serializer: Serializer<T>) => Serializer<T>;
-    load: (serializer?: Serializer<T>) => Serializer<T>;
+    load: (behaviour?: "pop" | "retain") => Serializer<T>;
 };

package/dist/utilities/remember.js

@@ -1,17 +1,30 @@
 /**
  * createRememberedValue lets you save and recall a value when serializing
  *
+ * This is useful for checksums and other values calculated from a writen value
+ *
  * ```
- * const length = st.createRememberedValue<number>()
+ * const data = st.createRememberedValue<ArrayBuffer>()
  * st.object({
- *   length: length.save(st.u32()),
- *   type: st.u8(),
- *   data: st.sizedBytes(length.load())
+ *   data: data.save(st.bytes(1024))
+ *   checksum: crc32(data.load())
  * })
  * ```
  */
 export function createRememberedValue() {
     const stack = [];
+    /**
+     * Transparently writes/reads the underlying value but stores the value written.
+     *
+     * ---
+     * ```
+     * const data = st.createRememberedValue<ArrayBuffer>()
+     * st.object({
+     *   data: data.save(st.bytes(1024))
+     *   checksum: crc32(data.load())
+     * })
+     * ```
+     * */
     function save(serializer) {
         return {
             size: serializer.size,
@@ -27,11 +40,35 @@ export function createRememberedValue() {
             },
         };
     }
-    function load(serializer) {
+    /**
+     * Retrieves the last value written by `.save()`
+     *
+     * By default, the value is forgotten when written so that memory isn't leaked.
+     * It can be retained by setting `behaviour` to `"retain"`
+     *
+     * When writing this type does nothing
+     *
+     * ---
+     * ```
+     * const data = st.createRememberedValue<ArrayBuffer>()
+     * st.object({
+     *   data: data.save(st.bytes(1024))
+     *   checksum: crc32(data.load())
+     * })
+     * ```
+     */
+    function load(behaviour = "pop") {
         return {
-            size: serializer?.size ?? 0,
-            read: () => stack.pop(),
-            write: (ctx) => serializer && serializer.write(ctx, stack.pop()),
+            size: 0,
+            read: () => {
+                if (behaviour === "pop") {
+                    return stack.pop();
+                }
+                else {
+                    return stack.at(-1);
+                }
+            },
+            write: () => { },
         };
     }
     return { save: save, load: load };

package/dist/utilities/remember.test.js

@@ -37,7 +37,7 @@ describe("st.remember", () => {
         const v = st.createRememberedValue();
         const spec = st.object({
             a: v.save(st.u32()),
-            b: v.load(st.u8()),
+            b: v.load(),
         });
         encodeTest(spec, { a: 3, b: 0 }, { a: 3, b: 3 });
     });
@@ -68,9 +68,5 @@ describe("st.remember", () => {
             a: 3,
             b: [1, 3, 4],
         });
-        encodeSnapshotTest(st.object({
-            a: v.save(st.u32()),
-            b: v.load(st.u8()),
-        }), { a: 3, b: 0 });
     });
 });

package/dist/write.js

@@ -1,6 +1,12 @@
 export function write(serializer, value) {
     const ctx = createdWriterContext(serializer);
-    serializer.write(ctx, value);
+    try {
+        serializer.write(ctx, value);
+    }
+    catch (e) {
+        const path = ctx.stack.join("") ?? "root";
+        throw new Error(`Serialization error at value${path}`, { cause: e });
+    }
     if (ctx.buffer.byteLength === ctx.offset) {
         return ctx.buffer;
     }
@@ -13,6 +19,7 @@ export function createdWriterContext(type) {
         let buffer = new ArrayBuffer(type.size);
         const view = new DataView(buffer);
         return {
+            stack: [],
             offset: 0,
             buffer,
             view,
@@ -24,6 +31,7 @@ export function createdWriterContext(type) {
         let buffer = new ArrayBuffer(bufferLength);
         const view = new DataView(buffer);
         return {
+            stack: [],
             offset: 0,
             buffer,
             view,

package/package.json

@@ -9,7 +9,7 @@
     "node"
   ],
   "license": "ISC",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "author": "Ben Brady",
   "private": false,
   "publishConfig": {
@@ -44,12 +44,6 @@
     "./dist/**/*.js.map",
     "./dist/**/*.js"
   ],
-  "scripts": {
-    "build": "tsc",
-    "prepublish": "tsc",
-    "check": "tsc --noEmit",
-    "test": "bun test src --only-failures --coverage"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "@types/node": "^25.9.2",
@@ -57,5 +51,11 @@
     "jest": "^30.4.2",
     "typescript": "^6.0.3"
   },
-  "packageManager": "pnpm@10.13.1"
-}
+  "scripts": {
+    "build": "tsc",
+    "prepublish": "tsc",
+    "check": "tsc --noEmit",
+    "test": "bun test src --only-failures",
+    "test:coverage": "bun test src --only-failures --coverage"
+  }
+}