@nnilky/structo 1.0.5 → 1.0.8

package/dist/utilities/remember.d.ts

@@ -0,0 +1,18 @@
+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 data = st.createRememberedValue<ArrayBuffer>()
+ * st.object({
+ *   data: data.save(st.bytes(1024))
+ *   checksum: crc32(data.load())
+ * })
+ * ```
+ */
+export declare function createRememberedValue<T>(): {
+    save: (serializer: Serializer<T>) => Serializer<T>;
+    load: (behaviour?: "pop" | "retain") => Serializer<T>;
+};

package/dist/utilities/remember.js

@@ -0,0 +1,75 @@
+/**
+ * createRememberedValue lets you save and recall a value when serializing
+ *
+ * This is useful for checksums and other values calculated from a writen value
+ *
+ * ```
+ * const data = st.createRememberedValue<ArrayBuffer>()
+ * st.object({
+ *   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,
+            read: (ctx) => {
+                const value = serializer.read(ctx);
+                stack.push(value);
+                return value;
+            },
+            write: (ctx, value) => {
+                serializer.write(ctx, value);
+                stack.push(value);
+                return value;
+            },
+        };
+    }
+    /**
+     * 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: 0,
+            read: () => {
+                if (behaviour === "pop") {
+                    return stack.pop();
+                }
+                else {
+                    return stack.at(-1);
+                }
+            },
+            write: () => { },
+        };
+    }
+    return { save: save, load: load };
+}

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

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

package/dist/utilities/remember.test.js

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "bun:test";
+import { encodeTest, encodeSnapshotTest } from "../utils.test";
+import * as st from "../index";
+describe("st.remember", () => {
+    it("encodes correctly", () => {
+        const v = st.createRememberedValue();
+        const spec = st.object({
+            a: v.save(st.u32()),
+            b: st.list(v.load(), st.u8()),
+        });
+        encodeTest(spec, {
+            a: 3,
+            b: [1, 3, 4],
+        });
+    });
+    it("multiple runs function", () => {
+        const v = st.createRememberedValue();
+        const spec = st.object({
+            a: v.save(st.u32()),
+            b: st.list(v.load(), st.u8()),
+        });
+        encodeTest(spec, { a: 3, b: [1, 3, 4] });
+        encodeTest(spec, { a: 3, b: [1, 3, 4] });
+        encodeTest(spec, { a: 3, b: [1, 3, 4] });
+    });
+    it("omitted serializer doesn't write data ", () => {
+        const v = st.createRememberedValue();
+        const spec = st.object({
+            a: v.save(st.u32()),
+            b: v.load(),
+        });
+        const output = st.write(spec, { a: 3, b: 0 });
+        expect(spec.size).toBe(4);
+        expect(output.byteLength).toBe(4);
+    });
+    it("serializer is used write data ", () => {
+        const v = st.createRememberedValue();
+        const spec = st.object({
+            a: v.save(st.u32()),
+            b: v.load(),
+        });
+        encodeTest(spec, { a: 3, b: 0 }, { a: 3, b: 3 });
+    });
+    it("handles recursive objects", () => {
+        const size = st.createRememberedValue();
+        //@ts-expect-error, recursive types
+        const Node = st.lazy(() => st.object({
+            size: size.save(st.u32()),
+            children: st.list(size.load(), Node),
+        }));
+        encodeTest(Node, {
+            size: 2,
+            children: [
+                { size: 0, children: [] },
+                {
+                    size: 1,
+                    children: [{ size: 0, children: [] }],
+                },
+            ],
+        });
+    });
+    it("snapshots are correct", () => {
+        const v = st.createRememberedValue();
+        encodeSnapshotTest(st.object({
+            a: v.save(st.u32()),
+            b: st.list(v.load(), st.u8()),
+        }), {
+            a: 3,
+            b: [1, 3, 4],
+        });
+    });
+});

package/dist/utils.test.d.ts

@@ -1 +1,9 @@
-export {};
+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 encodeTest: <TIn, TOut>(serializer: st.Serializer<TIn, TOut>, value: TIn, expected?: TOut) => void;
+export declare const encodeFailTest: <TIn, TOut>(serializer: st.Serializer<TIn, TOut>, value: TIn) => void;
+export declare const expectEncodeSize: <TIn, TOut>(serializer: st.Serializer<TIn, TOut>, size: number, value: TIn) => void;
+export declare const encodeSnapshotTest: <T>(serializer: st.Serializer<T>, value: T) => void;
+export declare const expectError: (callback: () => void) => void;
+export declare const bytes: (bytes: number[]) => ArrayBuffer;

package/dist/utils.test.js

@@ -1 +1,42 @@
-export {};
+//@ts-ignore TODO
+import { describe, it, expect } from "bun:test";
+import * as st from "./index";
+export const randint = (start, end) => {
+    const range = end - start;
+    return Math.floor(start + range * Math.random());
+};
+export const randbigint = (start, end) => {
+    const range = end - start;
+    const offset = BigInt(Math.floor(Number(range) * Math.random()));
+    return start + offset;
+};
+export const encodeTest = (serializer, value, expected) => {
+    const data = st.write(serializer, value);
+    const newValue = st.read(serializer, data);
+    expect(newValue).toEqual((expected ?? value));
+};
+export const encodeFailTest = (serializer, value) => {
+    expectError(() => {
+        st.write(serializer, value);
+    });
+};
+export const expectEncodeSize = (serializer, size, value) => {
+    const data = st.write(serializer, value);
+    expect(data.byteLength).toEqual(size);
+};
+export const encodeSnapshotTest = (serializer, value) => {
+    const data = st.write(serializer, value);
+    expect(data).toMatchSnapshot();
+};
+export const expectError = (callback) => {
+    try {
+        callback();
+    }
+    catch {
+        return;
+    }
+    throw new Error("Expected Error");
+};
+export const bytes = (bytes) => {
+    return new Uint8Array(bytes).buffer;
+};

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

@@ -1,18 +1,24 @@
 {
   "name": "@nnilky/structo",
   "description": "A library for serializing and deserializing binary content",
-  "keywords": ["binary", "library", "utility", "web", "node"],
+  "keywords": [
+    "binary",
+    "library",
+    "utility",
+    "web",
+    "node"
+  ],
   "license": "ISC",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "author": "Ben Brady",
   "private": false,
-  "publishConfig": {"access": "public"},
-
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ben-Brady/structo-ts.git"
   },
-
   "readme": "README.md",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,13 +44,6 @@
     "./dist/**/*.js.map",
     "./dist/**/*.js"
   ],
-
-  "scripts": {
-    "build": "tsc",
-    "prepublish": "tsc",
-    "check": "tsc --noEmit",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "@types/node": "^25.9.2",
@@ -52,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"
+  }
+}