@nnilky/structo 1.0.7 → 1.0.9

package/dist/transforms/index.js

@@ -1,12 +1,11 @@
-export { pipe } from "./pipe";
-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 { toAscii } from "./toAscii";
-export { toBytes } from "./toBytes";
-export { toHex } from "./toHex";
-export { toBase64 } from "./toBase64";
-export { toTypedArray } from "./toTypedArray";
+export { pipe } from "./pipe.js";
+export { encode } from "./encode.js";
+export { modify } from "./modify.js";
+export { literal } from "./literal.js";
+export { enum } from "./enum.js";
+export { offset } from "./offset.js";
+export { toAscii } from "./toAscii.js";
+export { toBytes } from "./toBytes.js";
+export { toHex } from "./toHex.js";
+export { toBase64 } from "./toBase64.js";
+export { toTypedArray } from "./toTypedArray.js";

package/dist/transforms/literal.d.ts

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

package/dist/transforms/literal.js

@@ -1,12 +1,15 @@
-import { encode } from "./encode";
+import { encode } from "./encode.js";
 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/literal.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
-import * as st from "../index";
-import { encodeTest, encodeFailTest } from "../utils.test";
+import * as st from "../index.js";
+import { encodeTest, encodeFailTest } from "../utils.test.js";
 describe("st.literal", () => {
     it("encode correctly", () => {
         encodeTest(st.pipe(st.u8(), st.literal(0)), //

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>;
+import type { Transform } from "./pipe.js";
+/**
+ * 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.js";
+import * as st from "../index.js";
+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.js";
+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.js";
+import * as st from "../index.js";
+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.d.ts

@@ -1,4 +1,4 @@
-import type { Serializer } from "../types";
+import type { Serializer } from "../types.js";
 export type Transform<T = any, TNext = T> = (type: Serializer<TNext>) => Serializer<T>;
 export declare function pipe<TStart, T1>(type: Serializer<TStart>, p1: Transform<T1, TStart>): Serializer<T1>;
 export declare function pipe<TStart, T1, T2>(type: Serializer<TStart>, p1: Transform<T1, TStart>, p2: Transform<T2, T1>): Serializer<T2>;

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.d.ts

@@ -1 +1 @@
-export declare function toAscii(): import("./pipe").Transform<string, ArrayBuffer>;
+export declare function toAscii(): import("./pipe.js").Transform<string, ArrayBuffer>;

package/dist/transforms/toAscii.js

@@ -1,8 +1,11 @@
-import { encode } from "./encode";
+import { encode } from "./encode.js";
 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/toAscii.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "bun:test";
-import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../utils.test";
-import * as st from "../index";
+import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../utils.test.js";
+import * as st from "../index.js";
 describe("st.toAscii", () => {
     it("encode correctly", () => {
         encodeTest(st.pipe(st.bytes(5), st.toAscii()), //

package/dist/transforms/toBase64.d.ts

@@ -1 +1 @@
-export declare function toBase64(): import("./pipe").Transform<string, ArrayBuffer>;
+export declare function toBase64(): import("./pipe.js").Transform<string, ArrayBuffer>;

package/dist/transforms/toBase64.js

@@ -1,4 +1,7 @@
-import { encode } from "./encode";
+import { encode } from "./encode.js";
 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/toBase64.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "bun:test";
-import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../utils.test";
-import * as st from "../index";
+import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../utils.test.js";
+import * as st from "../index.js";
 describe("st.toBase64", () => {
     it("encode correctly", () => {
         encodeTest(st.pipe(st.bytes(1), st.toBase64()), //

package/dist/transforms/toBytes.d.ts

@@ -10,4 +10,4 @@
  *
  * `ArrayBuffer([0, 255, c])` => `[0, 255, ArrayBuffer([0, 255, 0])]`
  */
-export declare function toBytes(): import("./pipe").Transform<number[], ArrayBuffer>;
+export declare function toBytes(): import("./pipe.js").Transform<number[], ArrayBuffer>;

package/dist/transforms/toBytes.js

@@ -1,4 +1,4 @@
-import { encode } from "./encode";
+import { encode } from "./encode.js";
 /**
  * Converts an ArrayBuffer to the byte digits
  *
@@ -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/toBytes.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "bun:test";
-import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../utils.test";
-import * as st from "../index";
+import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../utils.test.js";
+import * as st from "../index.js";
 describe("st.toBytes", () => {
     it("encode correctly", () => {
         encodeTest(st.pipe(st.bytes(3), st.toBytes()), //

package/dist/transforms/toHex.d.ts

@@ -10,4 +10,4 @@
  *
  * `ArrayBuffer([0, 255, 0])` => `00FF00`
  */
-export declare function toHex(): import("./pipe").Transform<string, ArrayBuffer>;
+export declare function toHex(): import("./pipe.js").Transform<string, ArrayBuffer>;

package/dist/transforms/toHex.js

@@ -1,4 +1,4 @@
-import { encode } from "./encode";
+import { encode } from "./encode.js";
 /**
  * Converts an ArrayBuffer to uppercase hex
  *
@@ -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/toHex.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "bun:test";
-import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../utils.test";
-import * as st from "../index";
+import { encodeTest, encodeSnapshotTest, encodeFailTest } from "../utils.test.js";
+import * as st from "../index.js";
 describe("st.toHex", () => {
     it("encode correctly", () => {
         encodeTest(st.pipe(st.bytes(3), st.toHex()), //

package/dist/transforms/toTypedArray.d.ts

@@ -12,5 +12,5 @@ type TypedArrayConstructor<T extends TypedArray> = new (array: ArrayBuffer) => T
  * )
  * ```
  */
-export declare function toTypedArray<T extends TypedArray>(arrayType: TypedArrayConstructor<T>): import("./pipe").Transform<T, ArrayBuffer>;
+export declare function toTypedArray<T extends TypedArray>(arrayType: TypedArrayConstructor<T>): import("./pipe.js").Transform<T, ArrayBuffer>;
 export {};

package/dist/transforms/toTypedArray.js

@@ -1,4 +1,4 @@
-import { encode } from "./encode";
+import { encode } from "./encode.js";
 /**
  * Converts an `ArrayBuffer` to a `TypedArray`
  *
@@ -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/transforms/toTypedArray.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "bun:test";
-import { encodeTest, encodeSnapshotTest, expectError } from "../utils.test";
-import * as st from "../index";
+import { encodeTest, encodeSnapshotTest, expectError } from "../utils.test.js";
+import * as st from "../index.js";
 describe("st.toArrayBuffer", () => {
     it("encode correctly", () => {
         encodeTest(st.pipe(st.bytes(6), //

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 { createRememberedValue } from "./remember";
+export { lazy } from "./lazy.js";
+export { createReference } from "./reference.js";
+export { createRememberedValue } from "./remember.js";

package/dist/utilities/index.js

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

package/dist/utilities/lazy.d.ts

@@ -1,2 +1,2 @@
-import type { Serializer } from "../types";
+import type { Serializer } from "../types.js";
 export declare function lazy<TIn, TOut = TIn>(type: () => Serializer<TIn, TOut>): Serializer<TIn, TOut>;

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "bun:test";
-import { encodeTest } from "../utils.test";
-import * as st from "../index";
+import { encodeTest } from "../utils.test.js";
+import * as st from "../index.js";
 describe("st.lazy", () => {
     it("encodes correctly", () => {
         const spec = st.lazy(() => st.object({

package/dist/utilities/reference.d.ts

@@ -0,0 +1,18 @@
+import type { Serializer } from "../types.js";
+/**
+ * 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.js";
+import * as st from "../index.js";
+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],
+        });
+    });
+});