@adobe/data 0.1.3 → 0.2.0

package/src/ecs/archetype/archetype.ts

@@ -0,0 +1,39 @@
+/*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 { CoreComponents } from "../core-components.js";
+import { Entity } from "../entity.js";
+import { Table, ReadonlyTable } from "../../table/index.js";
+
+export type EntityInsertValues<C> = Omit<C, "id">;
+export type ArchetypeId = number;
+
+interface BaseArchetype<C> {
+    readonly id: ArchetypeId;
+    readonly components: ReadonlySet<string>;
+}
+
+export interface ReadonlyArchetype<C extends CoreComponents> extends BaseArchetype<C>, ReadonlyTable<C> {
+}
+
+export interface Archetype<C extends CoreComponents = CoreComponents> extends BaseArchetype<C>, Table<C> {
+    insert: (rowData: EntityInsertValues<C>) => Entity;
+}

package/src/ecs/archetype/create-archetype.test.ts

@@ -0,0 +1,115 @@
+/*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 { createArchetype } from '../archetype/index.js';
+import { createEntityLocationTable } from '../entity-location-table/index.js';
+import { EntitySchema } from '../entity.js';
+import { U32Schema } from '../../schema/u32.js';
+
+describe('createArchetype', () => {
+    it('should create an archetype with basic components', () => {
+        const entityLocationTable = createEntityLocationTable();
+        const components = {
+            id: EntitySchema,
+            value: U32Schema,
+        };
+        const id = 1;
+
+        const archetype = createArchetype(components, id, entityLocationTable);
+
+        // Verify basic properties
+        expect(archetype.id).toBe(id);
+        expect(archetype.rows).toBe(0);
+        expect(archetype.components).toEqual(new Set(['id', 'value']));
+        expect(archetype.columns).toHaveProperty('id');
+        expect(archetype.columns).toHaveProperty('value');
+    });
+
+    it('should create entities with correct ids and data', () => {
+        const entityLocationTable = createEntityLocationTable();
+        const components = {
+            id: EntitySchema,
+            value: U32Schema,
+        };
+        const id = 1;
+
+        const archetype = createArchetype(components, id, entityLocationTable);
+
+        // Create first entity
+        const entity1 = archetype.insert({ value: 42 });
+        expect(entity1).toBe(0); // First entity should have id 0
+        expect(archetype.rows).toBe(1);
+        expect(archetype.columns.id.get(0)).toBe(0);
+        expect(archetype.columns.value.get(0)).toBe(42);
+
+        // Create second entity
+        const entity2 = archetype.insert({ value: 100 });
+        expect(entity2).toBe(1); // Second entity should have id 1
+        expect(archetype.rows).toBe(2);
+        expect(archetype.columns.id.get(1)).toBe(1);
+        expect(archetype.columns.value.get(1)).toBe(100);
+
+        // Verify entity locations in EntityLocationTable
+        const location1 = entityLocationTable.locate(entity1);
+        expect(location1).toEqual({ archetype: id, row: 0 });
+
+        const location2 = entityLocationTable.locate(entity2);
+        expect(location2).toEqual({ archetype: id, row: 1 });
+    });
+
+    it('should handle multiple component types', () => {
+        const entityLocationTable = createEntityLocationTable();
+        const components = {
+            id: EntitySchema,
+            health: U32Schema,
+            mana: U32Schema,
+            level: U32Schema,
+        };
+        const id = 2;
+
+        const archetype = createArchetype(components, id, entityLocationTable);
+
+        // Verify components are set up correctly
+        expect(archetype.components).toEqual(new Set(['id', 'health', 'mana', 'level']));
+        expect(archetype.columns).toHaveProperty('health');
+        expect(archetype.columns).toHaveProperty('mana');
+        expect(archetype.columns).toHaveProperty('level');
+
+        // Create an entity with all components
+        const entity = archetype.insert({
+            health: 100,
+            mana: 50,
+            level: 5,
+        });
+
+        expect(entity).toBe(0);
+        expect(archetype.rows).toBe(1);
+        expect(archetype.columns.health.get(0)).toBe(100);
+        expect(archetype.columns.mana.get(0)).toBe(50);
+        expect(archetype.columns.level.get(0)).toBe(5);
+        expect(archetype.columns.id.get(0)).toBe(0);
+
+        // Verify entity location
+        const location = entityLocationTable.locate(entity);
+        expect(location).toEqual({ archetype: id, row: 0 });
+    });
+}); 

package/src/ecs/archetype/create-archetype.ts

@@ -0,0 +1,52 @@
+/*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 { FromSchema } from "../../schema/schema.js";
+import * as TABLE from "../../table/index.js";
+import { Archetype } from "./archetype.js";
+import { CoreComponents } from "../core-components.js";
+import { EntityLocationTable } from "../entity-location-table/entity-location-table.js";
+import { Entity, EntitySchema } from "../entity.js";
+
+export const createArchetype = <C extends { id: typeof EntitySchema }>(
+    components: C,
+    id: number,
+    entityLocationTable: EntityLocationTable,
+): Archetype<CoreComponents & { [K in keyof C]: FromSchema<C[K]> }> => {
+    const table = TABLE.createTable(components);
+    const createEntity = (rowData: Omit<{ [K in keyof C]: FromSchema<C[K]> }, "id">): Entity => {
+        // add the row (excluding entity id)
+        const row = TABLE.addRow(archetype as any, rowData);
+        // create the entity lookup record
+        const entity = entityLocationTable.create({ archetype: archetype.id, row });
+        // set the entity id for the row (since it wasn't present in the row data)
+        archetype.columns.id.set(row, entity as any);
+        return entity;
+    }
+
+    const archetype = {
+        id,
+        ...table,
+        components: new Set(Object.keys(components) as (keyof C & string)[]),
+        insert: createEntity,
+    } as const satisfies Archetype<{ [K in keyof C]: FromSchema<C[K]> }> as Archetype<CoreComponents & { [K in keyof C]: FromSchema<C[K]> }>;
+    return archetype;
+}

package/src/ecs/archetype/delete-row.test.ts

@@ -0,0 +1,110 @@
+/*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 { createEntityLocationTable } from '../entity-location-table/index.js';
+import { createArchetype, deleteRow } from './index.js';
+import { EntitySchema } from '../entity.js';
+import { U32Schema } from '../../schema/u32.js';
+
+describe('Archetype_deleteRow', () => {
+    it('should delete a row from the middle and update moved entity location', () => {
+        const entityLocationTable = createEntityLocationTable();
+        const archetype = createArchetype(
+            { 
+                id: EntitySchema,
+                value: U32Schema 
+            },
+            1,
+            entityLocationTable
+        );
+
+        // Create three entities
+        const entity1 = archetype.insert({ value: 100 });
+        const entity2 = archetype.insert({ value: 200 });
+        const entity3 = archetype.insert({ value: 300 });
+
+        // Delete the middle entity (entity2)
+        deleteRow(archetype, entity2, entityLocationTable);
+
+        // Verify entity3 was moved to position 1
+        expect(archetype.columns.id.get(1)).toBe(entity3);
+        expect(archetype.columns.value.get(1)).toBe(300);
+
+        // Verify entity location table was updated for the moved entity
+        const movedEntityLocation = entityLocationTable.locate(entity3);
+        expect(movedEntityLocation).toEqual({ archetype: 1, row: 1 });
+
+        // Verify total rows decreased
+        expect(archetype.rows).toBe(2);
+
+        // Verify entity1 is unchanged
+        expect(archetype.columns.id.get(0)).toBe(entity1);
+        expect(archetype.columns.value.get(0)).toBe(100);
+    });
+
+    it('should handle deleting the last row without moving entities', () => {
+        const entityLocationTable = createEntityLocationTable();
+        const archetype = createArchetype(
+            { 
+                id: EntitySchema,
+                value: U32Schema 
+            },
+            1,
+            entityLocationTable
+        );
+
+        // Create two entities
+        const entity1 = archetype.insert({ value: 100 });
+        const entity2 = archetype.insert({ value: 200 });
+
+        // Delete the last entity (entity2)
+        deleteRow(archetype, entity2, entityLocationTable);
+
+        // Verify total rows decreased
+        expect(archetype.rows).toBe(1);
+
+        // Verify entity1 is unchanged
+        expect(archetype.columns.id.get(0)).toBe(entity1);
+        expect(archetype.columns.value.get(0)).toBe(100);
+    });
+
+    it('should handle deleting the only row', () => {
+        const entityLocationTable = createEntityLocationTable();
+        const archetype = createArchetype(
+            { 
+                id: EntitySchema,
+                value: U32Schema 
+            },
+            1,
+            entityLocationTable
+        );
+
+        // Create one entity
+        const entity1 = archetype.insert({ value: 100 });
+
+        // Delete the only entity
+        deleteRow(archetype, 0, entityLocationTable);
+
+        // Verify total rows is zero
+        expect(archetype.rows).toBe(0);
+    });
+}); 

package/src/ecs/archetype/delete-row.ts

@@ -0,0 +1,37 @@
+/*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 * as TABLE from "../../table/index.js";
+import { Archetype } from "./archetype.js";
+import { CoreComponents } from "../core-components.js";
+import { EntityLocationTable } from "../entity-location-table/entity-location-table.js";
+
+/**
+ * Deletes a row from the archetype and updates the entity location table for any row which may have been moved into it's position.
+ * Does NOT modify the deleted row's entity location.
+ */
+export const deleteRow = <C extends CoreComponents>(archetype: Archetype<C>, row: number, entityLocationTable: EntityLocationTable): void => {
+    const movedARowToFillHole = TABLE.deleteRow(archetype, row);
+    if (movedARowToFillHole) {
+        const movedId = archetype.columns.id.get(row);
+        entityLocationTable.update(movedId, { archetype: archetype.id, row });
+    }
+}

package/src/ecs/archetype/index.ts

@@ -0,0 +1,24 @@
+/*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.*/
+export * from "./archetype.js";
+export * from "./create-archetype.js";
+export * from "./delete-row.js";

package/src/ecs/component-schemas.ts

@@ -0,0 +1,24 @@
+/*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 { Schema } from "../schema/schema.js";
+
+export type ComponentSchemas = { readonly [K: string]: Schema };