@adobe/data 0.1.2 → 0.2.0

package/src/ecs/database/transactional-store/create-transactional-store.test.ts

@@ -0,0 +1,250 @@
+/*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 { createTransactionalStore } from "./create-transactional-store.js";
+import { createStore } from "../../store/create-store.js";
+import { F32Schema } from "../../../schema/f32.js";
+import { Schema } from "../../../schema/schema.js";
+
+// Test schemas
+const positionSchema = {
+    type: "object",
+    properties: {
+        x: F32Schema,
+        y: F32Schema,
+        z: F32Schema,
+    }
+} as const satisfies Schema;
+
+const healthSchema = {
+    type: "object",
+    properties: {
+        current: F32Schema,
+        max: F32Schema,
+    }
+} as const satisfies Schema;
+
+describe("createTransactionalStore", () => {
+    it("should create transactional store with basic components", () => {
+        const baseStore = createStore(
+            { position: positionSchema, health: healthSchema },
+            { time: { delta: 0.016, elapsed: 0 } }
+        );
+        
+        const store = createTransactionalStore(baseStore);
+
+        expect(store).toBeDefined();
+        expect(store.componentSchemas).toHaveProperty("id");
+        expect(store.componentSchemas).toHaveProperty("position");
+        expect(store.componentSchemas).toHaveProperty("health");
+        expect(store.resources).toHaveProperty("time");
+    });
+
+    it("should execute transactions successfully", () => {
+        const baseStore = createStore(
+            { position: positionSchema, health: healthSchema },
+            { time: { delta: 0.016, elapsed: 0 } }
+        );
+        
+        const store = createTransactionalStore(baseStore);
+
+        const result = store.execute((transactionStore) => {
+            // Create an entity
+            const archetype = transactionStore.ensureArchetype(["id", "position"]);
+            const entity = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+
+            // Update the entity
+            transactionStore.update(entity, { position: { x: 10, y: 20, z: 30 } });
+
+            // Update resources
+            transactionStore.resources.time = { delta: 0.032, elapsed: 1 };
+        });
+
+        expect(result).toBeDefined();
+        expect(result.redo).toHaveLength(3); // insert + update
+        expect(result.undo).toHaveLength(3); // delete + insert with old values
+        expect(result.changedEntities.size).toBe(2);
+        expect(result.changedComponents.size).toBe(2); // position
+        expect(result.changedArchetypes.size).toBe(2);
+    });
+
+    it("should rollback on error", () => {
+        const baseStore = createStore(
+            { position: positionSchema, health: healthSchema },
+            { time: { delta: 0.016, elapsed: 0 } }
+        );
+        
+        const store = createTransactionalStore(baseStore);
+
+        // Create initial entity in a transaction
+        let entity: number = -1;
+        store.execute((transactionStore) => {
+            const archetype = transactionStore.ensureArchetype(["id", "position"]);
+            entity = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+        });
+
+        // Verify initial state
+        const initialData = store.read(entity);
+        expect(initialData?.position).toEqual({ x: 1, y: 2, z: 3 });
+
+        // Execute transaction that throws an error
+        expect(() => {
+            store.execute((transactionStore) => {
+                // Update entity
+                transactionStore.update(entity, { position: { x: 10, y: 20, z: 30 } });
+                
+                // This should cause rollback
+                throw new Error("Transaction failed");
+            });
+        }).toThrow("Transaction failed");
+
+        // Verify rollback occurred
+        const finalData = store.read(entity);
+        expect(finalData?.position).toEqual({ x: 1, y: 2, z: 3 });
+    });
+
+    it("should combine multiple updates to the same entity", () => {
+        const baseStore = createStore(
+            { position: positionSchema, health: healthSchema },
+            { time: { delta: 0.016, elapsed: 0 } }
+        );
+        
+        const store = createTransactionalStore(baseStore);
+
+        const result = store.execute((transactionStore) => {
+            const archetype = transactionStore.ensureArchetype(["id", "position", "health"]);
+            const entity = archetype.insert({ 
+                position: { x: 1, y: 2, z: 3 },
+                health: { current: 100, max: 100 }
+            });
+
+            // Multiple updates to the same entity should be combined
+            transactionStore.update(entity, { position: { x: 10, y: 20, z: 30 } });
+            transactionStore.update(entity, { health: { current: 50, max: 100 } });
+        });
+
+        // Should have combined updates
+        expect(result.redo).toHaveLength(2); // insert + combined update
+        expect(result.undo).toHaveLength(2); // delete + insert with old values
+        
+        const updateOperation = result.redo.find(op => op.type === "update");
+        expect(updateOperation?.type).toBe("update");
+        if (updateOperation?.type === "update") {
+            expect(updateOperation.values).toHaveProperty("position");
+            expect(updateOperation.values).toHaveProperty("health");
+        }
+    });
+
+    it("should track changed entities, components, and archetypes", () => {
+        const baseStore = createStore(
+            { position: positionSchema, health: healthSchema },
+            { time: { delta: 0.016, elapsed: 0 } }
+        );
+        
+        const store = createTransactionalStore(baseStore);
+
+        const result = store.execute((transactionStore) => {
+            // Create entities in different archetypes
+            const posArchetype = transactionStore.ensureArchetype(["id", "position"]);
+            const healthArchetype = transactionStore.ensureArchetype(["id", "health"]);
+            
+            const entity1 = posArchetype.insert({ position: { x: 1, y: 2, z: 3 } });
+            const entity2 = healthArchetype.insert({ health: { current: 100, max: 100 } });
+
+            // Update resources
+            transactionStore.resources.time = { delta: 0.032, elapsed: 1 };
+        });
+
+        expect(result.changedEntities.size).toBe(3);
+        expect(result.changedComponents.size).toBe(3); // position, health
+        expect(result.changedArchetypes.size).toBe(3); // two different archetypes
+    });
+
+    it("should preserve base store functionality", () => {
+        const baseStore = createStore(
+            { position: positionSchema, health: healthSchema },
+            { time: { delta: 0.016, elapsed: 0 } }
+        );
+        
+        const store = createTransactionalStore(baseStore);
+
+        // Verify all base store methods are available
+        expect(store.componentSchemas).toBeDefined();
+        expect(store.resources).toBeDefined();
+        expect(store.queryArchetypes).toBeDefined();
+        expect(store.ensureArchetype).toBeDefined();
+        expect(store.locate).toBeDefined();
+        expect(store.read).toBeDefined();
+        expect(store.execute).toBeDefined();
+
+        // Verify we can use the store normally for read operations
+        const archetypes = store.queryArchetypes(["id"]);
+        expect(archetypes.length).toBeGreaterThan(0);
+        
+        // Verify we can create entities through transactions
+        store.execute((transactionStore) => {
+            const archetype = transactionStore.ensureArchetype(["id", "position"]);
+            const entity = archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+            expect(store.read(entity)).toBeDefined();
+        });
+    });
+
+    it("should support transient transactions", () => {
+        const baseStore = createStore(
+            { position: positionSchema, health: healthSchema },
+            { time: { delta: 0.016, elapsed: 0 } }
+        );
+        
+        const store = createTransactionalStore(baseStore);
+
+        // Execute a regular transaction (non-transient)
+        const regularResult = store.execute((transactionStore) => {
+            const archetype = transactionStore.ensureArchetype(["id", "position"]);
+            archetype.insert({ position: { x: 1, y: 2, z: 3 } });
+        });
+
+        expect(regularResult.transient).toBe(false);
+
+        // Execute a transient transaction
+        const transientResult = store.execute((transactionStore) => {
+            const archetype = transactionStore.ensureArchetype(["id", "position"]);
+            archetype.insert({ position: { x: 10, y: 20, z: 30 } });
+        }, { transient: true });
+
+        expect(transientResult.transient).toBe(true);
+
+        // Both transactions should have the same structure but different transient flags
+        expect(regularResult).toHaveProperty("value");
+        expect(regularResult).toHaveProperty("redo");
+        expect(regularResult).toHaveProperty("undo");
+        expect(regularResult).toHaveProperty("changedEntities");
+        expect(regularResult).toHaveProperty("changedComponents");
+        expect(regularResult).toHaveProperty("changedArchetypes");
+        
+        expect(transientResult).toHaveProperty("value");
+        expect(transientResult).toHaveProperty("redo");
+        expect(transientResult).toHaveProperty("undo");
+        expect(transientResult).toHaveProperty("changedEntities");
+        expect(transientResult).toHaveProperty("changedComponents");
+        expect(transientResult).toHaveProperty("changedArchetypes");
+    });
+}); 

package/src/ecs/database/transactional-store/create-transactional-store.ts

@@ -0,0 +1,281 @@
+/*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 { ArchetypeId, EntityInsertValues } from "../../archetype/index.js";
+import { CoreComponents } from "../../core-components.js";
+import { ResourceComponents } from "../../store/resource-components.js";
+import { Store } from "../../store/index.js";
+import { Entity } from "../../entity.js";
+import { EntityUpdateValues } from "../../store/core/index.js";
+import { TransactionalStore, TransactionResult, TransactionWriteOperation } from "./transactional-store.js";
+import { StringKeyof } from "../../../types/types.js";
+
+// Sentinel value used to indicate a component should be deleted
+const DELETE: unknown = "_$_DELETE_$_";
+
+export function createTransactionalStore<C extends CoreComponents, R extends ResourceComponents>(
+    store: Store<C, R>,
+): TransactionalStore<C, R> {
+
+    // Transaction state (mutable during transaction execution)
+    let undoOperationsInReverseOrder: TransactionWriteOperation<C>[] = [];
+    let redoOperations: TransactionWriteOperation<C>[] = [];
+    const changed = {
+        entities: new Set<Entity>(),
+        components: new Set<keyof C>(),
+        archetypes: new Set<ArchetypeId>(),
+    };
+
+    // Wrap archetype creation to track operations
+    const wrapArchetype = (archetype: any) => {
+        const { id } = archetype;
+        return {
+            ...archetype,
+            insert: (values: EntityInsertValues<C>) => {
+                const entity = archetype.insert(values);
+                redoOperations.push({
+                    type: "insert",
+                    values: values,
+                });
+                undoOperationsInReverseOrder.push({ type: "delete", entity });
+                changed.entities.add(entity);
+                changed.archetypes.add(id);
+                for (const key in values) {
+                    changed.components.add(key as keyof C);
+                }
+                return entity;
+            },
+        };
+    };
+
+    // Create wrapped archetypes for transaction tracking
+    const wrappedArchetypes = new Map<ArchetypeId, any>();
+    
+    const getWrappedArchetype = (archetype: any) => {
+        if (!wrappedArchetypes.has(archetype.id)) {
+            wrappedArchetypes.set(archetype.id, wrapArchetype(archetype));
+        }
+        return wrappedArchetypes.get(archetype.id);
+    };
+
+    // Transaction-aware update function
+    const updateEntity = (entity: Entity, values: EntityUpdateValues<C>) => {
+        const oldValues = store.read(entity);
+        if (!oldValues) {
+            throw new Error(`Entity not found: ${entity}`);
+        }
+
+        const replacedValues: any = {};
+        for (const name in values) {
+            let newValue = (values as any)[name];
+            if (newValue === DELETE) {
+                newValue = undefined;
+            }
+            let oldValue = (oldValues as any)[name];
+            if (newValue !== oldValue) {
+                if (oldValue === undefined) {
+                    oldValue = DELETE;
+                }
+                replacedValues[name] = oldValue;
+                changed.components.add(name as keyof C);
+            }
+        }
+
+        changed.entities.add(entity);
+        const location = store.locate(entity);
+        if (location) {
+            changed.archetypes.add(location.archetype);
+        }
+
+        // Perform the actual update
+        store.update(entity, values as any);
+
+        // Check if archetype changed after update
+        const newLocation = store.locate(entity);
+        if (newLocation) {
+            changed.archetypes.add(newLocation.archetype);
+        }
+
+        // Add operations with potential combining
+        addUpdateOperationsMaybeCombineLast(undoOperationsInReverseOrder, redoOperations, entity, values, replacedValues);
+    };
+
+    // Transaction-aware delete function
+    const deleteEntity = (entity: Entity) => {
+        const location = store.locate(entity);
+        if (location) {
+            changed.archetypes.add(location.archetype);
+        }
+        changed.entities.add(entity);
+        
+        const oldValues = store.read(entity);
+        if (!oldValues) {
+            throw new Error(`Entity not found: ${entity}`);
+        }
+
+        const { id: _ignore, ...oldValuesWithoutId } = oldValues as any;
+        for (const key in oldValuesWithoutId) {
+            changed.components.add(key as keyof C);
+        }
+
+        store.delete(entity);
+        redoOperations.push({ type: "delete", entity });
+        undoOperationsInReverseOrder.push({ type: "insert", values: oldValuesWithoutId });
+    };
+
+    const resources = {} as { [K in keyof R]: R[K] };
+    for (const name of Object.keys(store.resources)) {
+        const resourceId = name as keyof C;
+        const archetype = store.ensureArchetype(["id", resourceId] as StringKeyof<C>[]);
+        const entityId = archetype.columns.id.get(0);
+        Object.defineProperty(resources, name, {
+            get: Object.getOwnPropertyDescriptor(store.resources, name)!.get,
+            set: (newValue) => {
+                updateEntity(entityId, { [resourceId]: newValue } as any);
+            },
+            enumerable: true,
+        });
+    }
+
+
+    // Create transaction-aware store
+    const transactionStore: Store<C, R> = {
+        ...store,
+        resources,
+        ensureArchetype: (componentNames) => {
+            const archetype = store.ensureArchetype(componentNames);
+            return getWrappedArchetype(archetype);
+        },
+        update: updateEntity,
+        delete: deleteEntity,
+    };
+
+    // Execute transaction function
+    const execute = (
+        transactionFunction: (store: Store<C, R>) => Entity | void,
+        options?: {
+            transient?: boolean;
+        }
+    ): TransactionResult<C> => {
+        // Reset transaction state
+        undoOperationsInReverseOrder = [];
+        redoOperations = [];
+        changed.entities.clear();
+        changed.components.clear();
+        changed.archetypes.clear();
+
+        try {
+            // Execute the transaction
+            const value = transactionFunction(transactionStore);
+
+            // Return the transaction result
+            const result: TransactionResult<C> = {
+                value: value ?? undefined,
+                transient: options?.transient ?? false,
+                redo: [...redoOperations],
+                undo: [...undoOperationsInReverseOrder.reverse()],
+                changedEntities: new Set(changed.entities),
+                changedComponents: new Set(changed.components),
+                changedArchetypes: new Set(changed.archetypes),
+            };
+
+            return result;
+        } catch (error) {
+            // Rollback on error by applying undo operations in reverse
+            applyWriteOperations(store, undoOperationsInReverseOrder.reverse());
+            throw error;
+        } finally {
+            // Clean up transaction state
+            undoOperationsInReverseOrder = [];
+            redoOperations = [];
+            changed.entities.clear();
+            changed.components.clear();
+            changed.archetypes.clear();
+            wrappedArchetypes.clear();
+        }
+    };
+
+    // Create the transactional store interface
+    const transactionalStore: TransactionalStore<C, R> = {
+        ...store,
+        execute,
+    };
+
+    return transactionalStore as any;
+}
+
+// Helper function to combine update operations for the same entity
+function addUpdateOperationsMaybeCombineLast<C>(
+    undoOperationsInReverseOrder: TransactionWriteOperation<C>[],
+    redoOperations: TransactionWriteOperation<C>[],
+    entity: Entity,
+    values: EntityUpdateValues<C>,
+    replacedValues: EntityUpdateValues<C>
+) {
+    const lastUndoOperation: TransactionWriteOperation<C> | undefined =
+        undoOperationsInReverseOrder[undoOperationsInReverseOrder.length - 1];
+    
+    if (
+        lastUndoOperation?.type === "update" &&
+        lastUndoOperation.entity === entity
+    ) {
+        // Combine with previous update operation
+        const lastRedoOperation = redoOperations[redoOperations.length - 1];
+        if (lastRedoOperation?.type === "update") {
+            lastRedoOperation.values = { ...lastRedoOperation.values, ...values };
+            lastUndoOperation.values = {
+                ...replacedValues,
+                ...lastUndoOperation.values,
+            };
+        }
+    } else {
+        // Add new update operations
+        redoOperations.push({ type: "update", entity, values });
+        undoOperationsInReverseOrder.push({
+            type: "update",
+            entity,
+            values: replacedValues,
+        });
+    }
+}
+
+// Helper function to apply write operations for rollback
+function applyWriteOperations<C extends CoreComponents, R extends ResourceComponents>(
+    store: Store<C, R>, 
+    operations: TransactionWriteOperation<C>[]
+): void {
+    for (const operation of operations) {
+        switch (operation.type) {
+            case "insert": {
+                const componentNames = ["id", ...Object.keys(operation.values)] as StringKeyof<C>[];
+                const archetype = store.ensureArchetype(componentNames);
+                archetype.insert(operation.values);
+                break;
+            }
+            case "update":
+                store.update(operation.entity, operation.values);
+                break;
+            case "delete":
+                store.delete(operation.entity);
+                break;
+        }
+    }
+} 

package/{ecs/ecs/ecs-types.js → src/ecs/database/transactional-store/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=ecs-types.js.map
+export * from "./transactional-store.js";

package/src/ecs/database/transactional-store/transactional-store.ts

@@ -0,0 +1,80 @@
+/*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 { ArchetypeId, EntityInsertValues } from "../../archetype/index.js";
+import { CoreComponents } from "../../core-components.js";
+import { ResourceComponents } from "../../store/resource-components.js";
+import { ReadonlyStore, Store } from "../../store/index.js";
+import { Entity } from "../../entity.js";
+import { EntityUpdateValues } from "../../store/core/index.js";
+
+export interface TransactionalStore<
+    C extends CoreComponents = CoreComponents,
+    R extends ResourceComponents = never
+> extends ReadonlyStore<C, R> {
+    /**
+     * Execute a transaction on the store.
+     * The transactionFunction must NOT directly mutate archetype rows as those changes would not be captured.
+     * Instead, use the store's update and delete and archetype insert methods to make changes.
+     * @param transactionFunction - A function that takes the store as an argument and performs some operations on it.
+     * @returns A promise that resolves when the transaction is complete.
+     */
+    execute(
+        transactionFunction: (store: Store<C, R>) => Entity | void,
+        options?: {
+            transient?: boolean;
+        }
+    ): TransactionResult<C>;
+}
+
+export type TransactionInsertOperation<C> = {
+    type: "insert";
+    values: EntityInsertValues<C>;
+};
+
+export type TransactionUpdateOperation<C> = {
+    type: "update";
+    entity: Entity;
+    values: EntityUpdateValues<C>;
+};
+
+export type TransactionDeleteOperation = {
+    type: "delete";
+    entity: Entity
+};
+
+export type TransactionWriteOperation<C> =
+    | TransactionInsertOperation<C>
+    | TransactionUpdateOperation<C>
+    | TransactionDeleteOperation;
+
+export interface TransactionResult<C> {
+    /**
+     * The Entity value if any returned by the transaction function.
+     */
+    readonly value: Entity | void;
+    readonly transient: boolean;
+    readonly redo: TransactionWriteOperation<C>[];
+    readonly undo: TransactionWriteOperation<C>[];
+    readonly changedEntities: Set<Entity>;
+    readonly changedComponents: Set<keyof C>;
+    readonly changedArchetypes: Set<ArchetypeId>;
+}