@chr33s/pdf-restructure 5.0.0

package/test/pointer.test.ts

@@ -0,0 +1,248 @@
+import { describe, expect, test } from "vitest";
+import { DecodeStream, EncodeStream, Pointer, Struct, VoidPointer, uint8 } from "../src/index.js";
+
+describe("Pointer", () => {
+  describe("decode", () => {
+    test("should handle null pointers", () => {
+      const stream = new DecodeStream(new Uint8Array([0]));
+      const pointer = new Pointer(uint8, uint8);
+      expect(pointer.decode(stream, { _startOffset: 50 })).to.equal(null);
+    });
+
+    test("should use local offsets from start of parent by default", () => {
+      const stream = new DecodeStream(new Uint8Array([1, 53]));
+      const pointer = new Pointer(uint8, uint8);
+      expect(pointer.decode(stream, { _startOffset: 0 })).to.equal(53);
+    });
+
+    test("should support immediate offsets", () => {
+      const stream = new DecodeStream(new Uint8Array([1, 53]));
+      const pointer = new Pointer(uint8, uint8, { type: "immediate" });
+      expect(pointer.decode(stream, {})).to.equal(53);
+    });
+
+    test("should support offsets relative to the parent", () => {
+      const stream = new DecodeStream(new Uint8Array([0, 0, 1, 53]));
+      stream.pos = 2;
+      const pointer = new Pointer(uint8, uint8, { type: "parent" });
+      expect(pointer.decode(stream, { parent: { _startOffset: 2 } })).to.equal(53);
+    });
+
+    test("should support global offsets", () => {
+      const stream = new DecodeStream(new Uint8Array([1, 2, 4, 0, 0, 0, 53]));
+      const pointer = new Pointer(uint8, uint8, { type: "global" });
+      stream.pos = 2;
+      expect(pointer.decode(stream, { parent: { parent: { _startOffset: 2 } } })).to.equal(53);
+    });
+
+    test("should support offsets relative to a property on the parent", () => {
+      const stream = new DecodeStream(new Uint8Array([1, 0, 0, 0, 0, 53]));
+      const pointer = new Pointer(uint8, uint8, { relativeTo: "parent.ptr" });
+      expect(pointer.decode(stream, { _startOffset: 0, parent: { ptr: 4 } })).to.equal(53);
+    });
+
+    test("should support returning pointer if there is no decode type", () => {
+      const stream = new DecodeStream(new Uint8Array([4]));
+      const pointer = new Pointer(uint8, "void");
+      expect(pointer.decode(stream, { _startOffset: 0 })).to.equal(4);
+    });
+
+    test("should support decoding pointers lazily", () => {
+      const stream = new DecodeStream(new Uint8Array([1, 53]));
+      const struct = new Struct({
+        ptr: new Pointer(uint8, uint8, { lazy: true }),
+      });
+
+      const res = struct.decode(stream);
+      const descriptor = Object.getOwnPropertyDescriptor(res, "ptr");
+      expect(typeof descriptor?.get).to.equal("function");
+      expect(descriptor?.enumerable).to.equal(true);
+      expect(res.ptr).to.equal(53);
+    });
+  });
+
+  describe("size", () => {
+    test("should add to local pointerSize", () => {
+      const pointer = new Pointer(uint8, uint8);
+      const ctx: any = { pointerSize: 0 };
+      expect(pointer.size(10, ctx)).to.equal(1);
+      expect(ctx.pointerSize).to.equal(1);
+    });
+
+    test("should add to immediate pointerSize", () => {
+      const pointer = new Pointer(uint8, uint8, { type: "immediate" });
+      const ctx: any = { pointerSize: 0 };
+      expect(pointer.size(10, ctx)).to.equal(1);
+      expect(ctx.pointerSize).to.equal(1);
+    });
+
+    test("should add to parent pointerSize", () => {
+      const pointer = new Pointer(uint8, uint8, { type: "parent" });
+      const ctx: any = { parent: { pointerSize: 0 } };
+      expect(pointer.size(10, ctx)).to.equal(1);
+      expect(ctx.parent.pointerSize).to.equal(1);
+    });
+
+    test("should add to global pointerSize", () => {
+      const pointer = new Pointer(uint8, uint8, { type: "global" });
+      const ctx: any = { parent: { parent: { parent: { pointerSize: 0 } } } };
+      expect(pointer.size(10, ctx)).to.equal(1);
+      expect(ctx.parent.parent.parent.pointerSize).to.equal(1);
+    });
+
+    test("should handle void pointers", () => {
+      const pointer = new Pointer(uint8, "void");
+      const ctx: any = { pointerSize: 0 };
+      expect(pointer.size(new VoidPointer(uint8, 50), ctx)).to.equal(1);
+      expect(ctx.pointerSize).to.equal(1);
+    });
+
+    test("should throw if no type and not a void pointer", () => {
+      const pointer = new Pointer(uint8, "void");
+      const ctx: any = { pointerSize: 0 };
+      expect(() => pointer.size(30, ctx)).to.throw();
+    });
+
+    test("should return a fixed size without a value", () => {
+      const pointer = new Pointer(uint8, uint8);
+      expect(pointer.size()).to.equal(1);
+    });
+  });
+
+  describe("encode", () => {
+    test("should handle null pointers", () => {
+      const stream = new EncodeStream(new Uint8Array(1));
+      const ptr = new Pointer(uint8, uint8);
+      const ctx: any = {
+        pointerSize: 0,
+        startOffset: 0,
+        pointerOffset: 0,
+        pointers: [],
+      };
+
+      ptr.encode(stream, null, ctx);
+      expect(ctx.pointerSize).to.equal(0);
+      expect(stream.buffer.subarray(0, stream.pos)).to.deep.equal(new Uint8Array([0]));
+    });
+
+    test("should handle local offsets", () => {
+      const stream = new EncodeStream(new Uint8Array(1));
+      const ptr = new Pointer(uint8, uint8);
+      const ctx: any = {
+        pointerSize: 0,
+        startOffset: 0,
+        pointerOffset: 1,
+        pointers: [],
+      };
+
+      ptr.encode(stream, 10, ctx);
+      expect(ctx.pointerOffset).to.equal(2);
+      expect(ctx.pointers).to.deep.equal([{ type: uint8, val: 10, parent: ctx }]);
+      expect(stream.buffer.subarray(0, stream.pos)).to.deep.equal(new Uint8Array([1]));
+    });
+
+    test("should handle immediate offsets", () => {
+      const stream = new EncodeStream(new Uint8Array(1));
+      const ptr = new Pointer(uint8, uint8, { type: "immediate" });
+      const ctx: any = {
+        pointerSize: 0,
+        startOffset: 0,
+        pointerOffset: 1,
+        pointers: [],
+      };
+
+      ptr.encode(stream, 10, ctx);
+      expect(ctx.pointerOffset).to.equal(2);
+      expect(ctx.pointers).to.deep.equal([{ type: uint8, val: 10, parent: ctx }]);
+      expect(stream.buffer.subarray(0, stream.pos)).to.deep.equal(new Uint8Array([0]));
+    });
+
+    test("should handle offsets relative to parent", () => {
+      const stream = new EncodeStream(new Uint8Array(1));
+      const ptr = new Pointer(uint8, uint8, { type: "parent" });
+      const ctx: any = {
+        parent: {
+          pointerSize: 0,
+          startOffset: 3,
+          pointerOffset: 5,
+          pointers: [],
+        },
+      };
+
+      ptr.encode(stream, 10, ctx);
+      expect(ctx.parent.pointerOffset).to.equal(6);
+      expect(ctx.parent.pointers).to.deep.equal([{ type: uint8, val: 10, parent: ctx }]);
+      expect(stream.buffer.subarray(0, stream.pos)).to.deep.equal(new Uint8Array([2]));
+    });
+
+    test("should handle global offsets", () => {
+      const stream = new EncodeStream(new Uint8Array(1));
+      const ptr = new Pointer(uint8, uint8, { type: "global" });
+      const ctx: any = {
+        parent: {
+          parent: {
+            parent: {
+              pointerSize: 0,
+              startOffset: 3,
+              pointerOffset: 5,
+              pointers: [],
+            },
+          },
+        },
+      };
+
+      ptr.encode(stream, 10, ctx);
+      expect(ctx.parent.parent.parent.pointerOffset).to.equal(6);
+      expect(ctx.parent.parent.parent.pointers).to.deep.equal([
+        { type: uint8, val: 10, parent: ctx },
+      ]);
+      expect(stream.buffer.subarray(0, stream.pos)).to.deep.equal(new Uint8Array([5]));
+    });
+
+    test("should support offsets relative to a property on the parent", () => {
+      const stream = new EncodeStream(new Uint8Array(1));
+      const ptr = new Pointer(uint8, uint8, { relativeTo: "ptr" });
+      const ctx: any = {
+        pointerSize: 0,
+        startOffset: 0,
+        pointerOffset: 10,
+        pointers: [],
+        val: { ptr: 4 },
+      };
+
+      ptr.encode(stream, 10, ctx);
+      expect(ctx.pointerOffset).to.equal(11);
+      expect(ctx.pointers).to.deep.equal([{ type: uint8, val: 10, parent: ctx }]);
+      expect(stream.buffer.subarray(0, stream.pos)).to.deep.equal(new Uint8Array([6]));
+    });
+
+    test("should support void pointers", () => {
+      const stream = new EncodeStream(new Uint8Array(1));
+      const ptr = new Pointer(uint8, "void");
+      const ctx: any = {
+        pointerSize: 0,
+        startOffset: 0,
+        pointerOffset: 1,
+        pointers: [],
+      };
+
+      ptr.encode(stream, new VoidPointer(uint8, 55), ctx);
+      expect(ctx.pointerOffset).to.equal(2);
+      expect(ctx.pointers).to.deep.equal([{ type: uint8, val: 55, parent: ctx }]);
+      expect(stream.buffer.subarray(0, stream.pos)).to.deep.equal(new Uint8Array([1]));
+    });
+
+    test("should throw if not a void pointer instance", () => {
+      const stream = new EncodeStream(new Uint8Array(10));
+      const ptr = new Pointer(uint8, "void");
+      const ctx: any = {
+        pointerSize: 0,
+        startOffset: 0,
+        pointerOffset: 1,
+        pointers: [],
+      };
+
+      expect(() => ptr.encode(stream, 44, ctx)).to.throw();
+    });
+  });
+});

package/test/reserved.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "vitest";
+import { DecodeStream, EncodeStream, Reserved, uint16, uint8 } from "../src/index.js";
+
+describe("Reserved", () => {
+  test("should have a default count of 1", () => {
+    const reserved = new Reserved(uint8);
+    expect(reserved.size()).to.equal(1);
+  });
+
+  test("should allow custom counts and types", () => {
+    const reserved = new Reserved(uint16, 10);
+    expect(reserved.size()).to.equal(20);
+  });
+
+  test("should decode", () => {
+    const stream = new DecodeStream(new Uint8Array([0, 0]));
+    const reserved = new Reserved(uint16);
+    expect(reserved.decode(stream)).to.equal(undefined);
+    expect(stream.pos).to.equal(2);
+  });
+
+  test("should encode", () => {
+    const reserved = new Reserved(uint16);
+    const stream = new EncodeStream(new Uint8Array(2));
+    reserved.encode(stream);
+    expect(stream.buffer).to.deep.equal(new Uint8Array([0, 0]));
+  });
+});

package/test/string.test.ts

@@ -0,0 +1,114 @@
+import { Buffer } from "node:buffer";
+import { describe, expect, test } from "vitest";
+import { DecodeStream, String as StringT, uint8 } from "../src/index.js";
+
+describe("String", () => {
+  describe("decode", () => {
+    test("should decode fixed length", () => {
+      const string = new StringT(7);
+      expect(string.fromBuffer(Buffer.from("testing"))).to.equal("testing");
+    });
+
+    test("should decode length from parent key", () => {
+      const stream = new DecodeStream(Buffer.from("testing"));
+      const string = new StringT("len");
+      expect(string.decode(stream, { len: 7 })).to.equal("testing");
+    });
+
+    test("should decode length as number before string", () => {
+      const string = new StringT(uint8);
+      expect(string.fromBuffer(Buffer.from("\x07testing", "binary"))).to.equal("testing");
+    });
+
+    test("should decode utf8", () => {
+      const string = new StringT(4, "utf8");
+      expect(string.fromBuffer(Buffer.from("🍻"))).to.equal("🍻");
+    });
+
+    test("should decode encoding computed from function", () => {
+      const string = new StringT(4, () => "utf8");
+      expect(string.fromBuffer(Buffer.from("🍻"))).to.equal("🍻");
+    });
+
+    test("should decode null-terminated string and read past terminator", () => {
+      const stream = new DecodeStream(Buffer.from("🍻\x00"));
+      const string = new StringT(undefined, "utf8");
+      expect(string.decode(stream)).to.equal("🍻");
+      expect(stream.pos).to.equal(5);
+    });
+
+    test("should decode remainder of buffer when null-byte missing", () => {
+      const string = new StringT(undefined, "utf8");
+      expect(string.fromBuffer(Buffer.from("🍻"))).to.equal("🍻");
+    });
+  });
+
+  describe("size", () => {
+    test("should use string length", () => {
+      const string = new StringT(7);
+      expect(string.size("testing")).to.equal(7);
+    });
+
+    test("should use correct encoding", () => {
+      const string = new StringT(10, "utf8");
+      expect(string.size("🍻")).to.equal(4);
+    });
+
+    test("should use encoding from function", () => {
+      const string = new StringT(10, () => "utf8");
+      expect(string.size("🍻")).to.equal(4);
+    });
+
+    test("should add size of length field before string", () => {
+      const string = new StringT(uint8, "utf8");
+      expect(string.size("🍻")).to.equal(5);
+    });
+
+    test("should work with utf16be encoding", () => {
+      const string = new StringT(10, "utf16be");
+      expect(string.size("🍻")).to.equal(4);
+    });
+
+    test("should take null-byte into account", () => {
+      const string = new StringT(undefined, "utf8");
+      expect(string.size("🍻")).to.equal(5);
+    });
+
+    test("should use defined length if no value given", () => {
+      const array = new StringT(10);
+      expect(array.size()).to.equal(10);
+    });
+  });
+
+  describe("encode", () => {
+    test("should encode using string length", () => {
+      const string = new StringT(7);
+      expect(string.toBuffer("testing")).to.deep.equal(Buffer.from("testing"));
+    });
+
+    test("should encode length as number before string", () => {
+      const string = new StringT(uint8);
+      expect(string.toBuffer("testing")).to.deep.equal(Buffer.from("\x07testing", "binary"));
+    });
+
+    test("should encode length as number before utf8 string", () => {
+      const string = new StringT(uint8, "utf8");
+      expect(string.toBuffer("testing 😜")).to.deep.equal(Buffer.from("\x0ctesting 😜", "utf8"));
+    });
+
+    test("should encode utf8", () => {
+      const string = new StringT(4, "utf8");
+      expect(string.toBuffer("🍻")).to.deep.equal(Buffer.from("🍻"));
+    });
+
+    test("should encode encoding computed from function", () => {
+      const string = new StringT(4, () => "utf8");
+      expect(string.toBuffer("🍻")).to.deep.equal(Buffer.from("🍻"));
+    });
+
+    test("should encode null-terminated string", () => {
+      const string = new StringT(undefined, "utf8");
+      expect(string.toBuffer("🍻")).to.deep.equal(Buffer.from("🍻\x00"));
+    });
+  });
+});

package/test/struct.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, test } from "vitest";
+import {
+  DecodeStream,
+  EncodeStream,
+  Pointer,
+  String as StringT,
+  Struct,
+  uint8,
+} from "../src/index.js";
+
+describe("Struct", () => {
+  describe("decode", () => {
+    test("should decode into an object", () => {
+      const stream = new DecodeStream(new Uint8Array([0x05, 0x64, 0x65, 0x76, 0x6f, 0x6e, 0x15])); // \x05devon\x15
+      const struct = new Struct({
+        name: new StringT(uint8),
+        age: uint8,
+      });
+
+      expect(struct.decode(stream)).to.deep.equal({ name: "devon", age: 21 });
+    });
+
+    test("should support process hook", () => {
+      const stream = new DecodeStream(new Uint8Array([0x05, 0x64, 0x65, 0x76, 0x6f, 0x6e, 0x20])); // \x05devon\x20
+      const struct = new Struct({
+        name: new StringT(uint8),
+        age: uint8,
+      });
+
+      struct.process = function process() {
+        (this as any).canDrink = (this as any).age >= 21;
+      };
+
+      expect(struct.decode(stream)).to.deep.equal({
+        name: "devon",
+        age: 32,
+        canDrink: true,
+      });
+    });
+
+    test("should support function keys", () => {
+      const stream = new DecodeStream(new Uint8Array([0x05, 0x64, 0x65, 0x76, 0x6f, 0x6e, 0x20])); // \x05devon\x20
+      const struct = new Struct({
+        name: new StringT(uint8),
+        age: uint8,
+        canDrink() {
+          return (this as any).age >= 21;
+        },
+      });
+
+      expect(struct.decode(stream)).to.deep.equal({
+        name: "devon",
+        age: 32,
+        canDrink: true,
+      });
+    });
+  });
+
+  describe("size", () => {
+    test("should compute the correct size", () => {
+      const struct = new Struct({
+        name: new StringT(uint8),
+        age: uint8,
+      });
+
+      expect(struct.size({ name: "devon", age: 21 })).to.equal(7);
+    });
+
+    test("should compute the correct size with pointers", () => {
+      const struct = new Struct({
+        name: new StringT(uint8),
+        age: uint8,
+        ptr: new Pointer(uint8, new StringT(uint8)),
+      });
+
+      const size = struct.size({ name: "devon", age: 21, ptr: "hello" });
+      expect(size).to.equal(14);
+    });
+
+    test("should get the correct size when no value is given", () => {
+      const struct = new Struct({
+        name: new StringT(4),
+        age: uint8,
+      });
+
+      expect(struct.size()).to.equal(5);
+    });
+
+    test("should throw when getting non-fixed length size and no value is given", () => {
+      const struct = new Struct({
+        name: new StringT(uint8),
+        age: uint8,
+      });
+
+      expect(() => struct.size()).to.throw(/not a fixed size/i);
+    });
+  });
+
+  describe("encode", () => {
+    test("should encode objects to buffers", () => {
+      const struct = new Struct({
+        name: new StringT(uint8),
+        age: uint8,
+      });
+
+      const value = { name: "devon", age: 21 };
+      const stream = new EncodeStream(new Uint8Array(struct.size(value)));
+      struct.encode(stream, value);
+      expect(stream.buffer).to.deep.equal(
+        new Uint8Array([0x05, 0x64, 0x65, 0x76, 0x6f, 0x6e, 0x15]),
+      );
+    });
+
+    test("should support preEncode hook", () => {
+      const struct = new Struct({
+        nameLength: uint8,
+        name: new StringT("nameLength"),
+        age: uint8,
+      });
+
+      struct.preEncode = function preEncode() {
+        (this as any).nameLength = (this as any).name.length;
+      };
+
+      const value = { name: "devon", age: 21 } as any;
+      const stream = new EncodeStream(new Uint8Array(struct.size(value)));
+      struct.encode(stream, value);
+      expect(stream.buffer).to.deep.equal(
+        new Uint8Array([0x05, 0x64, 0x65, 0x76, 0x6f, 0x6e, 0x15]),
+      );
+    });
+
+    test("should encode pointer data after structure", () => {
+      const struct = new Struct({
+        name: new StringT(uint8),
+        age: uint8,
+        ptr: new Pointer(uint8, new StringT(uint8)),
+      });
+
+      const value = { name: "devon", age: 21, ptr: "hello" };
+      const stream = new EncodeStream(new Uint8Array(struct.size(value)));
+      struct.encode(stream, value);
+      // \x05devon\x15\x08\x05hello
+      expect(stream.buffer).to.deep.equal(
+        new Uint8Array([
+          0x05,
+          0x64,
+          0x65,
+          0x76,
+          0x6f,
+          0x6e, // \x05devon
+          0x15, // age: 21
+          0x08, // pointer offset
+          0x05,
+          0x68,
+          0x65,
+          0x6c,
+          0x6c,
+          0x6f, // \x05hello
+        ]),
+      );
+    });
+  });
+});