@adobe/data 0.2.1 → 0.2.3

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

@@ -1,250 +0,0 @@
-/*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

@@ -1,281 +0,0 @@
-/*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/src/ecs/database/transactional-store/index.ts

@@ -1,22 +0,0 @@
-/*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 "./transactional-store.js";

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

@@ -1,80 +0,0 @@
-/*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>;
-}