@adobe/data 0.1.3 → 0.2.1

package/src/ecs/store/core/create-core.test.ts

@@ -0,0 +1,440 @@
+/*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 { createCore } from "./create-core.js";
+import { Schema } from "../../../schema/schema.js";
+import type { Entity } from "../../entity.js";
+import { F32Schema } from "../../../schema/f32.js";
+
+// Shared test schemas
+export const positionSchema = {
+    type: "object",
+    properties: {
+        x: F32Schema,
+        y: F32Schema,
+        z: F32Schema,
+    }
+} as const satisfies Schema;
+
+export const healthSchema = {
+    type: "object",
+    properties: {
+        current: F32Schema,
+        max: F32Schema,
+    }
+} as const satisfies Schema;
+
+export const nameSchema = {
+    type: "string",
+    maxLength: 50,
+} as const satisfies Schema;
+
+// Reusable test suite for any core-like interface
+export function createCoreTestSuite(
+    name: string,
+    factory: typeof createCore = createCore
+) {
+    describe(name, () => {
+        it("should create with basic components", () => {
+            const core = factory({
+                position: positionSchema,
+                health: healthSchema,
+            });
+
+            expect(core).toBeDefined();
+            expect(core.componentSchemas).toHaveProperty("id");
+            expect(core.componentSchemas).toHaveProperty("position");
+            expect(core.componentSchemas).toHaveProperty("health");
+            expect(core.componentSchemas.id).toBeDefined();
+            expect(core.componentSchemas.position).toBeDefined();
+            expect(core.componentSchemas.health).toBeDefined();
+        });
+
+        it("should query archetypes correctly", () => {
+            const core = factory({
+                position: positionSchema,
+                health: healthSchema,
+            });
+
+            // Create entities with different component combinations
+            const archetype1 = core.ensureArchetype(["id", "position"]);
+            const entity1 = archetype1.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            const archetype2 = core.ensureArchetype(["id", "health"]);
+            const entity2 = archetype2.insert({ health: { current: 100, max: 100 } });
+
+            const archetype3 = core.ensureArchetype(["id", "position", "health"]);
+            const entity3 = archetype3.insert({ 
+                position: { x: 0, y: 0, z: 0 },
+                health: { current: 50, max: 100 }
+            });
+
+            // Query for position component
+            const positionArchetypes = core.queryArchetypes(["position"]);
+            expect(positionArchetypes).toHaveLength(2);
+            expect(positionArchetypes.some(a => a.components.has("position"))).toBe(true);
+            expect(positionArchetypes.some(a => a.components.has("health"))).toBe(true);
+
+            // Query for health component
+            const healthArchetypes = core.queryArchetypes(["health"]);
+            expect(healthArchetypes).toHaveLength(2);
+            expect(healthArchetypes.some(a => a.components.has("position"))).toBe(true);
+            expect(healthArchetypes.some(a => a.components.has("health"))).toBe(true);
+
+            // Query for both components
+            const bothArchetypes = core.queryArchetypes(["position", "health"]);
+            expect(bothArchetypes).toHaveLength(1);
+            expect(bothArchetypes[0].components.has("position")).toBe(true);
+            expect(bothArchetypes[0].components.has("health")).toBe(true);
+        });
+
+        it("should query archetypes with exclude option", () => {
+            const core = factory({
+                position: positionSchema,
+                health: healthSchema,
+            });
+
+            // Create entities with different component combinations
+            const archetype1 = core.ensureArchetype(["id", "position"]);
+            const entity1 = archetype1.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            const archetype2 = core.ensureArchetype(["id", "health"]);
+            const entity2 = archetype2.insert({ health: { current: 100, max: 100 } });
+
+            const archetype3 = core.ensureArchetype(["id", "position", "health"]);
+            const entity3 = archetype3.insert({ 
+                position: { x: 0, y: 0, z: 0 },
+                health: { current: 50, max: 100 }
+            });
+
+            // Query for position but exclude health
+            const positionOnlyArchetypes = core.queryArchetypes(["position"], { exclude: ["health"] });
+            expect(positionOnlyArchetypes).toHaveLength(1);
+            expect(positionOnlyArchetypes[0].components.has("position")).toBe(true);
+            expect((positionOnlyArchetypes[0].components as Set<string>).has("health")).toBe(false);
+        });
+
+        it("should ensure archetype creates new archetype when needed", () => {
+            const core = factory({
+                position: positionSchema,
+                health: healthSchema,
+            });
+
+            // First call should create new archetype
+            const archetype1 = core.ensureArchetype(["id", "position"]);
+            expect(archetype1).toBeDefined();
+            expect(archetype1.components.has("id")).toBe(true);
+            expect(archetype1.components.has("position")).toBe(true);
+            expect((archetype1.components as Set<string>).has("health")).toBe(false);
+
+            // Second call with same components should return same archetype
+            const archetype2 = core.ensureArchetype(["id", "position"]);
+            expect(archetype2).toBe(archetype1);
+
+            // Different components should create new archetype
+            const archetype3 = core.ensureArchetype(["id", "health"]);
+            expect(archetype3).not.toBe(archetype1);
+            expect(archetype3.components.has("id")).toBe(true);
+            expect(archetype3.components.has("health")).toBe(true);
+            expect(archetype3.components.has("position")).toBe(false);
+        });
+
+        it("should throw error when ensuring archetype without id", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            expect(() => {
+                core.ensureArchetype(["position"]);
+            }).toThrow("id is required");
+        });
+
+        it("should locate entities correctly", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const archetype = core.ensureArchetype(["id", "position"]);
+            const entity = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            const location = core.locate(entity);
+            expect(location).not.toBeNull();
+            expect(location?.archetype).toBe(archetype.id);
+            expect(location?.row).toBeGreaterThanOrEqual(0);
+        });
+
+        it("should return null when locating non-existent entity", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const location = core.locate(999 as Entity);
+            expect(location).toBeNull();
+        });
+
+        it("should read entity data correctly", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const archetype = core.ensureArchetype(["id", "position"]);
+            const entity = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            const data = core.read(entity);
+            expect(data).not.toBeNull();
+            expect(data?.id).toBe(entity);
+            expect(data?.position).toEqual({ x: 1, y: 2, z: 3 });
+        });
+
+        it("should return null when reading non-existent entity", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const data = core.read(999 as Entity);
+            expect(data).toBeNull();
+        });
+
+        it("should delete entities correctly", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const archetype = core.ensureArchetype(["id", "position"]);
+            const entity = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            // Verify entity exists
+            expect(core.locate(entity)).not.toBeNull();
+            expect(core.read(entity)).not.toBeNull();
+
+            // Delete entity
+            core.delete(entity);
+
+            // Verify entity is deleted
+            expect(core.locate(entity)).toBeNull();
+            expect(core.read(entity)).toBeNull();
+        });
+
+        it("should handle deleting non-existent entity gracefully", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            expect(() => {
+                core.delete(999 as Entity);
+            }).not.toThrow();
+        });
+
+        it("should update entity within same archetype", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const archetype = core.ensureArchetype(["id", "position"]);
+            const entity = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            // Update position
+            core.update(entity, { position: { x: 10, y: 20, z: 30 } });
+
+            // Verify update
+            const data = core.read(entity);
+            expect(data?.position).toEqual({ x: 10, y: 20, z: 30 });
+        });
+
+        it("should move entity to new archetype when adding components", () => {
+            const core = factory({
+                position: positionSchema,
+                health: healthSchema,
+            });
+
+            const archetype1 = core.ensureArchetype(["id", "position"]);
+            const entity = archetype1.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            // Add health component
+            core.update(entity, { health: { current: 100, max: 100 } });
+
+            // Verify entity moved to new archetype
+            const location = core.locate(entity);
+            expect(location).not.toBeNull();
+            expect(location?.archetype).not.toBe(archetype1.id);
+
+            const data = core.read(entity);
+            expect(data?.position).toEqual({ x: 1, y: 2, z: 3 });
+            expect(data?.health).toEqual({ current: 100, max: 100 });
+        });
+
+        it("should move entity to new archetype when removing components", () => {
+            const core = factory({
+                position: positionSchema,
+                health: healthSchema,
+            });
+
+            const archetype1 = core.ensureArchetype(["id", "position", "health"]);
+            const entity = archetype1.insert({ 
+                position: { x: 1, y: 2, z: 3 },
+                health: { current: 100, max: 100 }
+            });
+
+            // Remove health component
+            core.update(entity, { health: undefined });
+
+            // Verify entity moved to new archetype
+            const location = core.locate(entity);
+            expect(location).not.toBeNull();
+            expect(location?.archetype).not.toBe(archetype1.id);
+
+            const data = core.read(entity);
+            expect(data?.position).toEqual({ x: 1, y: 2, z: 3 });
+            expect(data?.health).toBeUndefined();
+        });
+
+        it("should throw error when updating non-existent entity", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            expect(() => {
+                core.update(999 as Entity, { position: { x: 1, y: 2, z: 3 } });
+            }).toThrow("Entity not found");
+        });
+
+        it("should handle complex component updates", () => {
+            const core = factory({
+                position: positionSchema,
+                health: healthSchema,
+            });
+
+            const archetype = core.ensureArchetype(["id", "position", "health"]);
+            const entity = archetype.insert({ 
+                position: { x: 1, y: 2, z: 3 },
+                health: { current: 100, max: 100 }
+            });
+
+            // Update both components
+            core.update(entity, { 
+                position: { x: 10, y: 20, z: 30 },
+                health: { current: 50, max: 100 }
+            });
+
+            const data = core.read(entity);
+            expect(data?.position).toEqual({ x: 10, y: 20, z: 30 });
+            expect(data?.health).toEqual({ current: 50, max: 100 });
+        });
+
+        it("should handle mixed add/remove operations", () => {
+            const core = factory({
+                position: positionSchema,
+                health: healthSchema,
+            });
+
+            const archetype1 = core.ensureArchetype(["id", "position"]);
+            const entity = archetype1.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            // Add health and update position
+            core.update(entity, { 
+                position: { x: 10, y: 20, z: 30 },
+                health: { current: 100, max: 100 }
+            });
+
+            const data = core.read(entity);
+            expect(data?.position).toEqual({ x: 10, y: 20, z: 30 });
+            expect(data?.health).toEqual({ current: 100, max: 100 });
+        });
+
+        it("should maintain entity count correctly", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const archetype = core.ensureArchetype(["id", "position"]);
+            const entity1 = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+            const entity2 = archetype.insert({ position: { x: 4, y: 5, z: 6 } });
+
+            // Verify both entities exist
+            expect(core.locate(entity1)).not.toBeNull();
+            expect(core.locate(entity2)).not.toBeNull();
+
+            // Delete one entity
+            core.delete(entity1);
+
+            // Verify only one entity remains
+            expect(core.locate(entity1)).toBeNull();
+            expect(core.locate(entity2)).not.toBeNull();
+        });
+
+        it("should handle empty component updates", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const archetype = core.ensureArchetype(["id", "position"]);
+            const entity = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            // Update with empty object
+            core.update(entity, {});
+
+            // Verify entity still exists with original data
+            const data = core.read(entity);
+            expect(data?.position).toEqual({ x: 1, y: 2, z: 3 });
+        });
+
+        it("should handle large number of entities", () => {
+            const core = factory({
+                position: positionSchema,
+            });
+
+            const archetype = core.ensureArchetype(["id", "position"]);
+            const entities: Entity[] = [];
+
+            // Create many entities
+            for (let i = 0; i < 100; i++) {
+                const entity = archetype.insert({ position: { x: i, y: i, z: i } });
+                entities.push(entity);
+            }
+
+            // Verify all entities exist
+            for (const entity of entities) {
+                expect(core.locate(entity)).not.toBeNull();
+            }
+
+            // Delete some entities
+            for (let i = 0; i < 50; i++) {
+                core.delete(entities[i]);
+            }
+
+            // Verify remaining entities exist
+            for (let i = 50; i < 100; i++) {
+                expect(core.locate(entities[i])).not.toBeNull();
+            }
+
+            // Verify deleted entities don't exist
+            for (let i = 0; i < 50; i++) {
+                expect(core.locate(entities[i])).toBeNull();
+            }
+        });
+    });
+}
+
+// Original core-specific tests
+describe("createCore", () => {
+    createCoreTestSuite("Core functionality");
+}); 

package/src/ecs/store/core/create-core.ts

@@ -0,0 +1,168 @@
+/*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, Schema } from "../../../schema/schema.js";
+import { createEntityLocationTable } from "../../entity-location-table/index.js";
+import * as ARCHETYPE from "../../archetype/index.js";
+import * as TABLE from "../../../table/index.js";
+import { Archetype } from "../../archetype/archetype.js";
+import { CoreComponents } from "../../core-components.js";
+import { Entity, EntitySchema } from "../../entity.js";
+import { Core, EntityUpdateValues, EntityValues, QueryOptions } from "./core.js";
+import { Assert, Equal, Simplify, StringKeyof } from "../../../types/index.js";
+import { ComponentSchemas } from "../../component-schemas.js";
+
+export function createCore<NC extends ComponentSchemas>(newComponentSchemas: NC): Core<Simplify<CoreComponents & { [K in StringKeyof<NC>]: FromSchema<NC[K]> }>> {
+    type C = CoreComponents & { [K in StringKeyof<NC>]: FromSchema<NC[K]> };
+
+    const componentSchemas: { readonly [K in StringKeyof<C>]: Schema } = { id: EntitySchema, ...newComponentSchemas };
+    const entityLocationTable = createEntityLocationTable();
+    const archetypes = [] as unknown as Archetype<C>[] & { readonly [x: string]: Archetype<C> };
+
+    const queryArchetypes = <
+        Include extends StringKeyof<C>,
+        Exclude extends StringKeyof<C> = never
+    >(
+        include: readonly Include[],
+        options?: QueryOptions<Include, Exclude>
+    ): readonly Archetype<CoreComponents & Pick<C, Include>>[] =>{
+        const results: Archetype<CoreComponents & Pick<C, Include>>[] = [];
+        for (const archetype of archetypes) {
+            const hasAllRequired = include.every(comp => archetype.columns[comp] !== undefined);
+            const hasNoExcluded = !options?.exclude || options.exclude.every(comp => archetype.columns[comp] === undefined);
+            if (hasAllRequired && hasNoExcluded) {
+                results.push(archetype as unknown as Archetype<CoreComponents & Pick<C, Include>>);
+            }
+        }
+        return results;
+    }
+
+    const ensureArchetype = <CC extends StringKeyof<C>>(componentNames: readonly CC[]): Archetype<CoreComponents & { [K in CC]: C[K] }> => {
+        for (const archetype of queryArchetypes(componentNames)) {
+            if (archetype.components.size === componentNames.length) {
+                return archetype as unknown as Archetype<CoreComponents & { [K in CC]: C[K] }>;
+            }
+        }
+        const id = archetypes.length;
+        const archetypeComponentSchemas: { [K in CC]: Schema } = {} as { [K in CC]: Schema };
+        let hasId = false;
+        for (const comp of componentNames) {
+            if (comp === "id") {
+                hasId = true;
+            }
+            archetypeComponentSchemas[comp] = componentSchemas[comp];
+        }
+        if (!hasId) {
+            throw new Error("id is required");
+        }
+        const archetype = ARCHETYPE.createArchetype(archetypeComponentSchemas as any, id, entityLocationTable);
+        archetypes.push(archetype as unknown as Archetype<C>);
+        return archetype as unknown as Archetype<CoreComponents & { [K in CC]: C[K] }>;
+    }
+
+    const { locate } = entityLocationTable;
+
+    const selectEntity = (entity: Entity): EntityValues<C> | null => {
+        const location = locate(entity);
+        return location !== null ? TABLE.getRowData(archetypes[location.archetype], location.row) : null;
+    }
+
+    const deleteEntity = (entity: Entity) => {
+        const location = locate(entity);
+        if (location !== null) {
+            const archetype = archetypes[location.archetype];
+            ARCHETYPE.deleteRow(archetype, location.row, entityLocationTable);
+            entityLocationTable.delete(entity);
+        }
+    }
+
+    const updateEntity = (entity: Entity, components: EntityUpdateValues<C>) => {
+        const currentLocation = locate(entity);
+        if (currentLocation === null) {
+            throw "Entity not found";
+        }
+        const currentArchetype = archetypes[currentLocation.archetype];
+        let newArchetype = currentArchetype;
+        let addComponents: null | StringKeyof<C>[] = null;
+        let removeComponents: null | StringKeyof<C>[] = null;
+        for (const key in components) {
+            if ((components as any)[key as any] === undefined) {
+                (removeComponents ??= []).push(key as StringKeyof<C>);
+                // we remove the delete components so we can use this object for the new row data
+                delete (components as any)[key as any];
+            }
+            else if (!currentArchetype.components.has(key as StringKeyof<C>)) {
+                (addComponents ??= []).push(key as StringKeyof<C>);
+            }
+        }
+        if (addComponents || removeComponents) {
+            // currently changing archetype requires a set, but later we should have an edge map for better performance
+            // Alternatively we can have a faster path using addComponent and deleteComponent.
+            const newComponents = new Set(currentArchetype.components);
+            if (addComponents) {
+                for (const comp of addComponents) {
+                    newComponents.add(comp);
+                }
+            }
+            if (removeComponents) {
+                for (const comp of removeComponents) {
+                    newComponents.delete(comp);
+                }
+            }
+            newArchetype = ensureArchetype(Array.from(newComponents) as StringKeyof<C>[]) as unknown as Archetype<C>;
+        }
+        if (newArchetype !== currentArchetype) {
+            // create a new row in the new archetype
+            const currentData = TABLE.getRowData(currentArchetype, currentLocation.row);
+            // deletes the row from the current archetype (this will update the entity location table for any row which may have been moved into it's position)
+            ARCHETYPE.deleteRow(currentArchetype, currentLocation.row, entityLocationTable);
+            const newRow = TABLE.addRow(newArchetype, { ...currentData, ...components });
+            // update the entity location table for the entity so it points to the new archetype and row
+            entityLocationTable.update(entity, { archetype: newArchetype.id, row: newRow });
+        } else {
+            TABLE.updateRow(newArchetype, currentLocation.row, components as any);
+        }
+    }
+
+    const core: Core<C> = {
+        componentSchemas: componentSchemas,
+        queryArchetypes,
+        ensureArchetype,
+        locate,
+        read: selectEntity,
+        delete: deleteEntity,
+        update: updateEntity,
+    };
+    return core as any;
+}
+
+type TestType = ReturnType<typeof createCore<{ position: { type: "number"}, health: { type: "string"} }>>
+type CheckTestType = Assert<Equal<TestType, Core<{
+    id: number;
+    position: number;
+    health: string;
+}>>>
+type TestTypeComponents = TestType["componentSchemas"]
+type CheckComponents = Assert<Equal<TestTypeComponents, {
+    readonly id: Schema;
+    readonly position: Schema;
+    readonly health: Schema;
+}>>;

package/{cache/async-cache.js → src/ecs/store/core/index.ts}

@@ -19,5 +19,4 @@ 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 {};
-//# sourceMappingURL=async-cache.js.map
+export * from "./core.js";