@adobe/data 0.1.2 → 0.2.0

package/src/typed-buffer/structs/create-read-struct.test.ts

@@ -0,0 +1,202 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+import { describe, it, expect } from "vitest";
+import { createReadStruct } from "./create-read-struct.js";
+import { createDataView32 } from "../../internal/data-view-32/create-data-view-32.js";
+import type { StructLayout } from "./struct-layout.js";
+
+describe("ReadStruct", () => {
+    it("Vec2 array root", () => {
+        const layout = {
+            "type": "array",
+            "size": 8,
+            "fields": {
+                "0": {
+                    "offset": 0,
+                    "type": "f32"
+                },
+                "1": {
+                    "offset": 4,
+                    "type": "f32"
+                }
+            }
+        } as const satisfies StructLayout;
+        const read = createReadStruct(layout);
+
+        const data = createDataView32(new ArrayBuffer(16));
+        data.f32[0] = 1.5;
+        data.f32[1] = 2.5;
+        data.f32[2] = 3.5;
+        data.f32[3] = 4.5;
+        const result = read(data, 0);
+        expect(result).toEqual([1.5, 2.5]);
+
+        // Test with offset
+        const result2 = read(data, 1);
+        expect(result2).toEqual([3.5, 4.5]);
+    });
+
+    it("Vec2 object root", () => {
+        const layout = {
+            "type": "object",
+            "size": 8,
+            "fields": {
+                "x": {
+                    "offset": 0,
+                    "type": "f32"
+                },
+                "y": {
+                    "offset": 4,
+                    "type": "f32"
+                }
+            }
+        } as const satisfies StructLayout;
+        const read = createReadStruct(layout);
+
+        const data = createDataView32(new ArrayBuffer(16));
+        data.f32[0] = 1.5;
+        data.f32[1] = 2.5;
+        data.f32[2] = 3.5;
+        data.f32[3] = 4.5;
+        const result = read(data, 0);
+        expect(result).toEqual({ x: 1.5, y: 2.5 });
+
+        // Test with offset
+        const result2 = read(data, 1);
+        expect(result2).toEqual({ x: 3.5, y: 4.5 });
+    });
+
+    it("Complex struct with nested arrays and primitives", () => {
+        const layout = {
+            type: "object",
+            size: 48,  // Total size rounded to vec4 (16 bytes)
+            fields: {
+                position: {
+                    offset: 0,
+                    type: {
+                        type: "array",
+                        size: 16,  // vec3 padded to vec4
+                        fields: {
+                            "0": { offset: 0, type: "f32" },
+                            "1": { offset: 4, type: "f32" },
+                            "2": { offset: 8, type: "f32" }
+                        }
+                    }
+                },
+                color: {
+                    offset: 16,  // Aligned to vec4
+                    type: {
+                        type: "array",
+                        size: 16,
+                        fields: {
+                            "0": { offset: 0, type: "f32" },
+                            "1": { offset: 4, type: "f32" },
+                            "2": { offset: 8, type: "f32" },
+                            "3": { offset: 12, type: "f32" }
+                        }
+                    }
+                },
+                age: {
+                    offset: 32,  // Aligned to vec4
+                    type: "u32"
+                },
+                charge: {
+                    offset: 36,
+                    type: "i32"
+                }
+            }
+        } as const satisfies StructLayout;
+        const read = createReadStruct(layout);
+
+        const data = createDataView32(new ArrayBuffer(96));  // Space for 2 structs
+        // position
+        data.f32[0] = 1;
+        data.f32[1] = 2;
+        data.f32[2] = 3;
+        // color
+        data.f32[4] = 1;
+        data.f32[5] = 0;
+        data.f32[6] = 0;
+        data.f32[7] = 1;
+        // age
+        data.u32[8] = 42;
+        // charge
+        data.i32[9] = -5;
+
+        // Second struct for offset testing
+        data.f32[12] = 4;
+        data.f32[13] = 5;
+        data.f32[14] = 6;
+        data.f32[16] = 0;
+        data.f32[17] = 1;
+        data.f32[18] = 0;
+        data.f32[19] = 1;
+        data.u32[20] = 24;
+        data.i32[21] = 3;
+
+        const result = read(data, 0);
+        expect(result).toEqual({
+            position: [1, 2, 3],
+            color: [1, 0, 0, 1],
+            age: 42,
+            charge: -5
+        });
+
+        // Test with offset
+        const result2 = read(data, 1);
+        expect(result2).toEqual({
+            position: [4, 5, 6],
+            color: [0, 1, 0, 1],
+            age: 24,
+            charge: 3
+        });
+    });
+
+    it("should only destructure used view types", () => {
+        // f32 only
+        const vec2Layout = {
+            type: "array",
+            size: 8,
+            fields: {
+                "0": { offset: 0, type: "f32" },
+                "1": { offset: 4, type: "f32" }
+            }
+        } as const satisfies StructLayout;
+        const readVec2 = createReadStruct(vec2Layout);
+        expect(readVec2.toString()).toMatch(/const { f32: __f32 } = data/);
+        expect(readVec2.toString()).not.toMatch(/i32: __i32/);
+        expect(readVec2.toString()).not.toMatch(/u32: __u32/);
+
+        // i32 and u32 only
+        const mixedLayout = {
+            type: "object",
+            size: 8,
+            fields: {
+                a: { offset: 0, type: "i32" },
+                b: { offset: 4, type: "u32" }
+            }
+        } as const satisfies StructLayout;
+        const readMixed = createReadStruct(mixedLayout);
+        expect(readMixed.toString()).not.toMatch(/f32: __f32/);
+        expect(readMixed.toString()).toMatch(/const { (?=.*i32: __i32)(?=.*u32: __u32).*? } = data/);
+    });
+}); 

package/src/typed-buffer/structs/create-read-struct.ts

@@ -0,0 +1,77 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+import { memoizeFactory } from "../../internal/function/memoize-factory.js";
+import type { ReadStruct } from "./read-struct.js";
+import type { StructLayout } from "./struct-layout.js";
+import { getFieldOffset } from "./get-field-offset.js";
+
+type ViewType = 'f32' | 'i32' | 'u32';
+type ViewTypes = Record<ViewType, boolean>;
+
+const generateStructBody = (
+    layout: StructLayout,
+    parentOffset = '',
+    indent = '    ',
+    usedViews: ViewTypes = { f32: false, i32: false, u32: false }
+): [string, ViewTypes] => {
+    if (typeof layout === 'string') {
+        usedViews[layout as ViewType] = true;
+        return [`__${layout}[${parentOffset}]`, usedViews];
+    }
+
+    const entries = layout.type === 'array' ?
+        Object.entries(layout.fields).sort((a, b) => +a[0] - +b[0]) :
+        Object.entries(layout.fields);
+
+    let body = '';
+    for (const [name, field] of entries) {
+        const fieldOffset = getFieldOffset(field, parentOffset);
+        const [value] = typeof field.type === 'string' ?
+            [(`__${field.type}[${fieldOffset}]`), usedViews[field.type as ViewType] = true] :
+            generateStructBody(field.type, fieldOffset, indent + '    ', usedViews);
+
+        if (layout.type === 'array') {
+            body += `\n${indent}${value},`;
+        } else {
+            body += `\n${indent}${name}: ${value},`;
+        }
+    }
+    return [layout.type === 'array' ? 
+        `[${body}\n${indent.slice(4)}]` : 
+        `{${body}\n${indent.slice(4)}}`,
+        usedViews
+    ];
+};
+
+
+export const createReadStruct = memoizeFactory(<T = unknown>(layout: StructLayout): ReadStruct<T> => {
+    const [body, usedViews] = generateStructBody(layout);
+    const views = Object.entries(usedViews)
+        .filter(([, used]) => used)
+        .map(([type]) => `${type}: __${type}`)
+        .join(', ');
+
+    const code = `const { ${views} } = data;
+index *= ${layout.size / 4};
+return ${body};`;
+    return new Function('data', 'index', code) as ReadStruct<T>;
+});

package/src/typed-buffer/structs/create-write-struct.ts

@@ -0,0 +1,73 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+import { memoizeFactory } from "../../internal/function/memoize-factory.js";
+import type { StructLayout } from "./struct-layout.js";
+import type { WriteStruct } from "./write-struct.js";
+import { getFieldOffset } from "./get-field-offset.js";
+
+type ViewType = 'f32' | 'i32' | 'u32';
+type ViewTypes = Record<ViewType, boolean>;
+
+const generateStructBody = (
+    layout: StructLayout,
+    parentOffset = '',
+    valueRef = 'value',
+    indent = '    ',
+    usedViews: ViewTypes = { f32: false, i32: false, u32: false }
+): [string, ViewTypes] => {
+    if (typeof layout === 'string') {
+        usedViews[layout as ViewType] = true;
+        return [`__${layout}[${parentOffset}] = ${valueRef};`, usedViews];
+    }
+
+    const entries = layout.type === 'array' ?
+        Object.entries(layout.fields).sort((a, b) => +a[0] - +b[0]) :
+        Object.entries(layout.fields);
+
+    let body = '';
+    for (const [name, field] of entries) {
+        const fieldOffset = getFieldOffset(field, parentOffset);
+        const nextValueRef = layout.type === 'array' ? `${valueRef}[${name}]` : `${valueRef}.${name}`;
+
+        if (typeof field.type === 'string') {
+            usedViews[field.type as ViewType] = true;
+            body += `\n${indent}__${field.type}[${fieldOffset}] = ${nextValueRef};`;
+        } else {
+            const [nestedBody] = generateStructBody(field.type, fieldOffset, nextValueRef, indent + '    ', usedViews);
+            body += `\n${indent}${nestedBody}`;
+        }
+    }
+    return [body, usedViews];
+};
+
+export const createWriteStruct = memoizeFactory(<T = unknown>(layout: StructLayout): WriteStruct<T> => {
+    const [body, usedViews] = generateStructBody(layout);
+    const views = Object.entries(usedViews)
+        .filter(([, used]) => used)
+        .map(([type]) => `${type}: __${type}`)
+        .join(', ');
+
+    const code = `const { ${views} } = data;
+index *= ${layout.size / 4};
+${body};`;
+    return new Function('data', 'index', 'value', code) as WriteStruct<T>;
+});

package/src/typed-buffer/structs/get-field-offset.ts

@@ -0,0 +1,36 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+import { StructLayout } from "./struct-layout.js";
+
+export const getFieldOffset = (field: StructLayout['fields'][string], parentOffset: string): string => {
+    const fieldOffset = field.offset / 4;
+    if (!parentOffset) {
+        return `index + ${fieldOffset}`;
+    }
+    // If parentOffset is a number, add it to fieldOffset
+    const match = parentOffset.match(/^index \+ (\d+)$/);
+    if (match) {
+        const parentNum = parseInt(match[1]);
+        return `index + ${parentNum + fieldOffset}`;
+    }
+    return `${parentOffset} + ${fieldOffset}`;
+};

package/src/typed-buffer/structs/get-struct-layout.test.ts

@@ -0,0 +1,146 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+import { describe, it, expect } from "vitest";
+import { getStructLayout } from "./get-struct-layout.js";
+import type { Schema } from "../../schema/schema.js";
+import { F32Schema } from "../../schema/f32.js";
+import { U32Schema } from "../../schema/u32.js";
+import { I32Schema } from "../../schema/i32.js";
+
+describe("getStructLayout", () => {
+    it("should handle primitive types", () => {
+        const schema: Schema = {
+            type: "object",
+            properties: {
+                a: F32Schema,
+                b: U32Schema,
+                c: I32Schema,
+            }
+        };
+
+        const layout = getStructLayout(schema);
+        expect(layout.type).toBe("object");
+        expect(layout.size).toBe(16);  // rounded to vec4
+        expect(layout.fields.a.offset).toBe(0);
+        expect(layout.fields.b.offset).toBe(4);
+        expect(layout.fields.c.offset).toBe(8);
+    });
+
+    it("should handle vec3 with proper padding", () => {
+        const schema: Schema = {
+            type: "array",
+            items: { type: "number", precision: 1 },
+            minItems: 3,
+            maxItems: 3
+        };
+
+        const layout = getStructLayout(schema)!;
+        expect(layout.type).toBe("array");
+        expect(layout.size).toBe(16);  // padded to vec4
+        expect(layout.fields["0"].offset).toBe(0);
+        expect(layout.fields["1"].offset).toBe(4);
+        expect(layout.fields["2"].offset).toBe(8);
+    });
+
+    it("should handle nested structs", () => {
+        const schema: Schema = {
+            type: "object",
+            properties: {
+                transform: {
+                    type: "object",
+                    properties: {
+                        position: {
+                            type: "array",
+                            items: F32Schema,
+                            minItems: 3,
+                            maxItems: 3
+                        },
+                        scale: F32Schema
+                    }
+                },
+                active: U32Schema
+            }
+        };
+
+        const layout = getStructLayout(schema)!;
+        expect(layout.type).toBe("object");
+        // transform (32 bytes) + active (4 bytes) = 36 bytes
+        // rounded up to largest member alignment (16 bytes) = 48 bytes
+        expect(layout.size).toBe(48);
+        
+        const transform = layout.fields.transform.type;
+        expect(typeof transform).not.toBe("string");
+        if (typeof transform !== "string") {
+            // position (vec3 = 16 bytes) + scale (4 bytes) = 20 bytes
+            // rounded up to largest member alignment (16 bytes) = 32 bytes
+            expect(transform.size).toBe(32);
+            const position = transform.fields.position.type;
+            expect(typeof position !== "string" && position.size).toBe(16);
+        }
+    });
+
+    it("should handle array of structs", () => {
+        const schema: Schema = {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    x: { type: "number", precision: 1 },
+                    y: { type: "number", precision: 1 }
+                }
+            },
+            minItems: 2,
+            maxItems: 2
+        };
+
+        const layout = getStructLayout(schema)!;
+        expect(layout.type).toBe("array");
+        expect(layout.size).toBe(32);  // 2 structs aligned to vec4
+        expect(layout.fields["0"].offset).toBe(0);
+        expect(layout.fields["1"].offset).toBe(16);  // aligned to vec4
+    });
+
+    it("should reject invalid schemas", () => {
+        // Non-fixed length array
+        expect(() => getStructLayout({
+            type: "array",
+            items: { type: "number", precision: 1 }
+        })).toThrow();
+
+        // Invalid primitive type
+        expect(() => getStructLayout({
+            type: "object",
+            properties: {
+                a: { type: "string" }
+            }
+        })).toThrow();
+
+        // Array length < 2
+        expect(() => getStructLayout({
+            type: "array",
+            items: { type: "number", precision: 1 },
+            minItems: 1,
+            maxItems: 1
+        })).toThrow();
+    });
+
+});