@adobe/data 0.1.3 → 0.2.0

package/src/ecs/entity-location-table/create-entity-location-table.test.ts

@@ -0,0 +1,170 @@
+/*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 './create-entity-location-table.js';
+import { Entity } from '../entity.js';
+
+describe('createEntityLocationTable', () => {
+    it('should create entities with increasing ids starting from 0', () => {
+        const table = createEntityLocationTable();
+        
+        const entity0 = table.create({ archetype: 1, row: 10 });
+        const entity1 = table.create({ archetype: 2, row: 20 });
+        const entity2 = table.create({ archetype: 3, row: 30 });
+
+        expect(entity0).toBe(0);
+        expect(entity1).toBe(1);
+        expect(entity2).toBe(2);
+    });
+
+    it('should store and retrieve entity locations correctly', () => {
+        const table = createEntityLocationTable();
+        
+        const entity = table.create({ archetype: 42, row: 123 });
+        const location = table.locate(entity);
+
+        expect(location).toEqual({ archetype: 42, row: 123 });
+    });
+
+    it('should reuse deleted entity ids', () => {
+        const table = createEntityLocationTable();
+        
+        const entity0 = table.create({ archetype: 1, row: 10 });
+        const entity1 = table.create({ archetype: 2, row: 20 });
+        const entity2 = table.create({ archetype: 3, row: 30 });
+
+        // Delete entity1
+        table.delete(entity1);
+
+        // Create a new entity - should reuse entity1's id
+        const entity3 = table.create({ archetype: 4, row: 40 });
+        expect(entity3).toBe(1);
+
+        // Verify the new entity's location
+        const location = table.locate(entity3);
+        expect(location).toEqual({ archetype: 4, row: 40 });
+    });
+
+    it('should reuse multiple deleted entities in LIFO order', () => {
+        const table = createEntityLocationTable();
+        
+        // Create initial entities
+        const entity0 = table.create({ archetype: 1, row: 10 });
+        const entity1 = table.create({ archetype: 2, row: 20 });
+        const entity2 = table.create({ archetype: 3, row: 30 });
+        const entity3 = table.create({ archetype: 4, row: 40 });
+
+        // Delete entities in sequence
+        table.delete(entity1); // First deletion
+        table.delete(entity2); // Second deletion
+        table.delete(entity0); // Third deletion
+
+        // Recreate entities - should get IDs in reverse deletion order
+        const newEntity1 = table.create({ archetype: 5, row: 50 });
+        expect(newEntity1).toBe(0); // Should get entity0's id (last deleted)
+        expect(table.locate(newEntity1)).toEqual({ archetype: 5, row: 50 });
+
+        const newEntity2 = table.create({ archetype: 6, row: 60 });
+        expect(newEntity2).toBe(2); // Should get entity2's id (second-to-last deleted)
+        expect(table.locate(newEntity2)).toEqual({ archetype: 6, row: 60 });
+
+        const newEntity3 = table.create({ archetype: 7, row: 70 });
+        expect(newEntity3).toBe(1); // Should get entity1's id (first deleted)
+        expect(table.locate(newEntity3)).toEqual({ archetype: 7, row: 70 });
+
+        // Creating one more should create a new ID since free list is empty
+        const newEntity4 = table.create({ archetype: 8, row: 80 });
+        expect(newEntity4).toBe(4); // Should get a new ID
+        expect(table.locate(newEntity4)).toEqual({ archetype: 8, row: 80 });
+    });
+
+    it('should return invalid location for out of bounds or deleted entities', () => {
+        const table = createEntityLocationTable();
+        
+        // Out of bounds
+        const outOfBoundsLocation = table.locate(999);
+        expect(outOfBoundsLocation).toEqual(null);
+
+        // Deleted entity
+        const entity = table.create({ archetype: 1, row: 10 });
+        table.delete(entity);
+        const deletedLocation = table.locate(entity);
+        expect(deletedLocation).toBe(null);
+    });
+
+    it('should grow capacity when adding many entities', () => {
+        const initialCapacity = 16;
+        const table = createEntityLocationTable(initialCapacity);
+        const entities: Entity[] = [];
+
+        // Create more entities than initial capacity
+        for (let i = 0; i < initialCapacity + 5; i++) {
+            const entity = table.create({ archetype: i, row: i * 10 });
+            entities.push(entity);
+            // Verify entity was created correctly
+            expect(entity).toBe(i);
+            const location = table.locate(entity);
+            expect(location).toEqual({ archetype: i, row: i * 10 });
+        }
+
+        // Delete some entities that span across the initial capacity boundary
+        table.delete(initialCapacity - 1);
+        table.delete(initialCapacity);
+        table.delete(initialCapacity + 1);
+
+        // Create new entities and verify they reuse the deleted IDs
+        const newEntity1 = table.create({ archetype: 100, row: 1000 });
+        const newEntity2 = table.create({ archetype: 101, row: 1010 });
+        const newEntity3 = table.create({ archetype: 102, row: 1020 });
+
+        // Verify the entities were reused in LIFO order
+        expect(newEntity1).toBe(initialCapacity + 1);
+        expect(newEntity2).toBe(initialCapacity);
+        expect(newEntity3).toBe(initialCapacity - 1);
+
+        // Verify their locations are correct
+        expect(table.locate(newEntity1)).toEqual({ archetype: 100, row: 1000 });
+        expect(table.locate(newEntity2)).toEqual({ archetype: 101, row: 1010 });
+        expect(table.locate(newEntity3)).toEqual({ archetype: 102, row: 1020 });
+    });
+
+    it('should update entity locations correctly', () => {
+        const table = createEntityLocationTable();
+        
+        // Create an initial entity
+        const entity = table.create({ archetype: 1, row: 10 });
+        expect(table.locate(entity)).toEqual({ archetype: 1, row: 10 });
+
+        // Update the entity location
+        table.update(entity, { archetype: 2, row: 20 });
+        expect(table.locate(entity)).toEqual({ archetype: 2, row: 20 });
+
+        // Update again to verify multiple updates work
+        table.update(entity, { archetype: 3, row: 30 });
+        expect(table.locate(entity)).toEqual({ archetype: 3, row: 30 });
+
+        // Create another entity and verify the first one remains unchanged
+        const entity2 = table.create({ archetype: 4, row: 40 });
+        expect(table.locate(entity)).toEqual({ archetype: 3, row: 30 });
+        expect(table.locate(entity2)).toEqual({ archetype: 4, row: 40 });
+    });
+}); 

package/src/ecs/entity-location-table/create-entity-location-table.ts

@@ -0,0 +1,96 @@
+/*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 { grow } from "../../internal/array-buffer-like/grow.js";
+import { EntityLocationTable } from "./entity-location-table.js";
+import { EntityLocation } from "./entity-location.js";
+import { Entity } from "../entity.js";
+
+export const createEntityLocationTable = (initialCapacity: number = 16): EntityLocationTable => {
+
+    /**
+     * The index of the first free entity in the free list or -1 if the free list is empty.
+     */
+    let freeListHead = -1;
+    /**
+     * The next index to use for a new entity once the free list is exhausted.
+     */
+    let nextIndex = 0;
+    let capacity = Math.max(initialCapacity, 16);
+
+    const array = new ArrayBuffer(capacity * 2 * 4, { maxByteLength: 1024 * 1024 * 1024 });
+    const entities = new Int32Array(array);
+
+    const createEntity = ({ archetype, row }: EntityLocation): Entity => {
+        let entity: number;
+        if (freeListHead >= 0) {
+            entity = freeListHead;
+            const index = freeListHead << 1;
+            freeListHead = entities[index + 1];
+        }
+        else {
+            entity = nextIndex++;
+            if (nextIndex >= capacity) {
+                capacity *= 2;
+                grow(array, capacity * 2 * 4);
+            }
+        }
+
+        const index = entity << 1;
+        entities[index + 0] = archetype;
+        entities[index + 1] = row;
+
+        return entity;
+    }
+
+    const deleteEntity = (entity: Entity) => {
+        const index = entity << 1;
+        entities[index + 0] = -1;
+        entities[index + 1] = freeListHead;
+        freeListHead = entity;
+    }
+
+    const locateEntity = (entity: Entity): EntityLocation | null => {
+        if (entity >= nextIndex) {
+            return null;
+        }
+        const index = entity << 1;
+        const archetype = entities[index + 0];
+        if (archetype < 0) {
+            return null;
+        }
+        const row = entities[index + 1];
+        return { archetype, row };
+    }
+
+    const updateEntity = (entity: Entity, location: EntityLocation) => {
+        const index = entity << 1;
+        entities[index + 0] = location.archetype;
+        entities[index + 1] = location.row;
+    }
+
+    return {
+        create: createEntity,
+        delete: deleteEntity,
+        locate: locateEntity,
+        update: updateEntity,
+    };
+}

package/src/ecs/entity-location-table/entity-location-table.ts

@@ -0,0 +1,30 @@
+/*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 { Entity } from "../entity.js";
+import { EntityLocation } from "./entity-location.js";
+
+export interface EntityLocationTable {
+    create: (location: EntityLocation) => Entity;
+    update: (entity: Entity, location: EntityLocation) => void;
+    delete: (entity: Entity) => void;
+    locate: (entity: Entity) => EntityLocation | null;
+}

package/{core/schema/schema.js → src/ecs/entity-location-table/entity-location.ts}

@@ -19,16 +19,16 @@ 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.*/
-;
-const mySchema = {
-    type: 'object',
+import { FromSchema, Schema } from "../../schema/schema.js";
+import { U32Schema } from "../../schema/u32.js";
+
+export const EntityLocationSchema = {
+    type: "object",
     properties: {
-        a: { type: 'number' },
-        b: { type: 'string' },
-        c: { enum: [1, 2, 3] }
+        archetype: U32Schema,
+        row: U32Schema
     },
-    required: ['a', 'c'],
-    additionalProperties: false,
-};
-export {};
-//# sourceMappingURL=schema.js.map
+    required: ["archetype", "row"]
+} as const satisfies Schema;
+
+export type EntityLocation = FromSchema<typeof EntityLocationSchema>;

package/src/ecs/entity-location-table/index.ts

@@ -0,0 +1,23 @@
+/*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 "./entity-location-table.js";
+export * from "./create-entity-location-table.js";

package/src/ecs/entity.ts

@@ -0,0 +1,26 @@
+/*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 { U32Schema } from "../schema/u32.js";
+
+export const EntitySchema = U32Schema;
+export type Entity = FromSchema<typeof EntitySchema>;

package/src/ecs/index.ts

@@ -0,0 +1,26 @@
+/*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 "./database/index.js";
+export * from "./store/index.js";
+export * from "./archetype/index.js";
+
+

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

@@ -0,0 +1,71 @@
+/*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 { Entity } from "../../entity.js";
+import { Archetype, ReadonlyArchetype } from "../../archetype/archetype.js";
+import { Schema } from "../../../schema/schema.js";
+import { EntityLocation } from "../../entity-location-table/entity-location.js";
+import { CoreComponents } from "../../core-components.js";
+import { StringKeyof } from "../../../types/index.js";
+
+export type EntityValues<C> = CoreComponents & { readonly [K in StringKeyof<C>]?: C[K] }
+export type EntityUpdateValues<C> = Partial<Omit<C, "id">>;
+
+export type QueryOptions<Include, Exclude> =
+    Extract<Include, Exclude> extends never
+        ? { exclude?: readonly Exclude[] }
+        : { exclude?: never };
+
+export interface ReadonlyCore<
+    C extends CoreComponents = CoreComponents,
+> {
+    readonly componentSchemas: { readonly [K in StringKeyof<C>]: Schema };
+
+    queryArchetypes<
+        Include extends StringKeyof<C>,
+        Exclude extends StringKeyof<C> = never
+    >(
+        include: readonly Include[],
+        options?: QueryOptions<Include, Exclude>
+    ): readonly ReadonlyArchetype<CoreComponents & Pick<C, Include>>[];
+
+    ensureArchetype: <const CC extends StringKeyof<C>>(components: readonly CC[]) => ReadonlyArchetype<CoreComponents & { [K in CC]: C[K]}>;
+    locate: (entity: Entity) => EntityLocation | null;
+    read: (entity: Entity) => EntityValues<C> | null;
+}
+
+/**
+ * This is the main interface for the low level ECS Core.
+ */
+export interface Core<
+    C extends CoreComponents = CoreComponents,
+> extends ReadonlyCore<C> {
+    queryArchetypes<
+        Include extends StringKeyof<C>,
+        Exclude extends StringKeyof<C> = never
+    >(
+        include: Include[],
+        options?: QueryOptions<Include, Exclude>
+    ): readonly Archetype<CoreComponents & Pick<C, Include>>[];
+    ensureArchetype: <const CC extends StringKeyof<C>>(components: readonly CC[]) => Archetype<CoreComponents & { [K in CC]: C[K]}>;
+    delete: (entity: Entity) => void;
+    update: (entity: Entity, values: EntityUpdateValues<C>) => void;
+}