@adobe/data 0.1.3 → 0.2.0

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

@@ -0,0 +1,205 @@
+/*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 } from "../archetype/index.js";
+import { CoreComponents } from "../core-components.js";
+import { ResourceComponents } from "../store/resource-components.js";
+import { Store } from "../store/index.js";
+import { Database, ToTransactionFunctions, TransactionDeclarations } from "./database.js";
+import { Entity } from "../entity.js";
+import { EntityValues } from "../store/core/index.js";
+import { TransactionResult } from "./transactional-store/index.js";
+import { mapEntries } from "../../internal/object/index.js";
+import { StringKeyof } from "../../types/types.js";
+import { Observe, withMap } from "../../observe/index.js";
+import { createTransactionalStore } from "./transactional-store/create-transactional-store.js";
+import { isPromise } from "../../internal/promise/is-promise.js";
+import { isAsyncGenerator } from "../../internal/async-generator/is-async-generator.js";
+
+export function createDatabase<
+    C extends CoreComponents,
+    R extends ResourceComponents,
+    TD extends TransactionDeclarations<C, R>
+>(
+    ds: Store<C, R>,
+    transactionDeclarations: TD,
+): Database<C, R, ToTransactionFunctions<TD>> {
+    type T = ToTransactionFunctions<TD>;
+
+    const transactionalStore = createTransactionalStore(ds);
+
+    //  variables to track the observers
+    const componentObservers = new Map<StringKeyof<C>, Set<() => void>>();
+    const archetypeObservers = new Map<ArchetypeId, Set<() => void>>();
+    const entityObservers = new Map<Entity, Set<(values: EntityValues<C> | null) => void>>();
+    const transactionObservers = new Set<(transaction: TransactionResult<C>) => void>();
+
+    //  observation interface
+    const observeEntity = (entity: Entity) => (observer: (values: EntityValues<C> | null) => void) => {
+        // Call immediately with current values
+        observer(ds.read(entity));
+        // Add to observers for future changes
+        return addToMapSet(entity, entityObservers)(observer);
+    };
+    const observeArchetype = (archetype: ArchetypeId) => addToMapSet(archetype, archetypeObservers);
+    const observeComponent = mapEntries(ds.componentSchemas, ([component]) => addToMapSet(component, componentObservers));
+    
+    // Resource observation - resources are stored as entities with specific archetypes
+    const observeResource = Object.fromEntries(
+        Object.entries(ds.resources).map(([resource]) => {
+            const archetype = ds.ensureArchetype(["id" as StringKeyof<C>, resource as unknown as StringKeyof<C>]);
+            const resourceId = archetype.columns.id.get(0);
+            return [resource, withMap(observeEntity(resourceId), (values) => values?.[resource as unknown as StringKeyof<C>])];
+        })
+    ) as { [K in StringKeyof<R>]: Observe<R[K]>; };
+    
+    const observe: Database<C, R>["observe"] = {
+        component: observeComponent,
+        resource: observeResource,
+        transactions: (notify) => {
+            transactionObservers.add(notify);
+            return () => {
+                transactionObservers.delete(notify);
+            }
+        },
+        entity: observeEntity,
+        archetype: observeArchetype,
+    };
+
+    const { execute: transactionDatabaseExecute, resources, ...rest } = transactionalStore;
+
+    const execute = (handler: (db: Store<C, R>) => void) => {
+        const result = transactionDatabaseExecute(handler);
+        
+        // Notify transaction observers
+        for (const transactionObserver of transactionObservers) {
+            transactionObserver(result);
+        }
+        
+        // Notify component observers
+        for (const changedComponent of result.changedComponents) {
+            const observers = componentObservers.get(changedComponent as StringKeyof<C>);
+            if (observers) {
+                for (const observer of observers) {
+                    observer();
+                }
+            }
+        }
+        
+        // Notify archetype observers
+        for (const changedArchetype of result.changedArchetypes) {
+            const observers = archetypeObservers.get(changedArchetype);
+            if (observers) {
+                for (const observer of observers) {
+                    observer();
+                }
+            }
+        }
+        
+        // Notify entity observers
+        for (const changedEntity of result.changedEntities) {
+            const observers = entityObservers.get(changedEntity);
+            if (observers) {
+                const values = ds.read(changedEntity);
+                for (const observer of observers) {
+                    observer(values);
+                }
+            }
+        }
+
+        return result.value;
+    }
+
+    const transactions = {} as T;
+
+    function handleNext(
+        asyncArgs: AsyncGenerator<any>,
+        transaction: (db: Store<C, R>, args: any) => void,
+        execute: (handler: (db: Store<C, R>) => void) => any
+    ) {
+        asyncArgs.next().then((result: IteratorResult<any>) => {
+            const { value, done } = result;
+            if (!done || value !== undefined) {
+                execute((db: Store<C, R>) => transaction(db, value));
+            }
+            if (done) {
+                return;
+            }
+            handleNext(asyncArgs, transaction, execute); // loop
+        }).catch((error: unknown) => {
+            console.error('AsyncGenerator error:', error);
+        });
+    }
+    for (const [name, transactionUntyped] of Object.entries(transactionDeclarations)) {
+        const transaction = transactionUntyped as (db: Store<C, R>, args: any) => void;
+        Object.defineProperty(transactions, name, {
+            value: (args: unknown) => {
+                // Check if args is an AsyncArgsProvider function
+                if (typeof args === 'function') {
+                    const asyncArgsProvider = args as () => Promise<any> | AsyncGenerator<any>;
+                    const asyncResult = asyncArgsProvider();
+                    
+                    if (isAsyncGenerator(asyncResult)) {
+                        const asyncArgs = asyncResult;
+                        handleNext(asyncArgs, transaction, execute);
+                    }
+                    else if (isPromise(asyncResult)) {
+                        asyncResult.then(asyncArgs => execute((db) => transaction(db, asyncArgs)))
+                            .catch(error => {
+                                console.error('Promise error:', error);
+                            });
+                    }
+                    else {
+                        // Function returned a synchronous value
+                        execute((db) => transaction(db, asyncResult));
+                    }
+                }
+                else {
+                    // Synchronous argument
+                    return execute((db) => transaction(db, args));
+                }
+            },
+            writable: false,
+            enumerable: true,
+            configurable: false
+        });
+    }
+
+    // Return the complete observable store
+    return {
+        ...rest,
+        resources,
+        transactions,
+        observe,
+    } as Database<C, R, T>;
+}
+
+const addToMapSet = <K, T>(key: K, map: Map<K, Set<T>>) => (value: T) => {
+    let set = map.get(key);
+    if (set) {
+        set.add(value);
+    } else {
+        map.set(key, (set = new Set([value])));
+    }
+    return () => {
+        set!.delete(value);
+    };
+};

package/src/ecs/database/database.ts

@@ -0,0 +1,81 @@
+/*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 } 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 { EntityValues } from "../store/core/index.js";
+import { Observe } from "../../observe/index.js";
+import { TransactionResult } from "./transactional-store/index.js";
+import { StringKeyof } from "../../types/types.js";
+
+export type TransactionDeclaration<
+    C extends CoreComponents = CoreComponents,
+    R extends ResourceComponents = never,
+    Input extends any | void = any
+> = (db: Store<C, R>, input: Input) => void | Entity
+
+export type TransactionDeclarations<
+    C extends CoreComponents = CoreComponents,
+    R extends ResourceComponents = never,
+> = {
+    readonly [name: string]: TransactionDeclaration<C, R>
+}
+
+export type AsyncArgsProvider<T> = () => Promise<T> | AsyncGenerator<T>;
+
+/**
+ * Converts from TransactionDeclarations to TransactionFunctions by removing the initial database argument.
+ */
+export type ToTransactionFunctions<T> = {
+    [K in keyof T]:
+      T[K] extends (db: Store<any, any>, ...rest: infer R) => infer Rtn
+        ? R extends []               // only the db param → no args
+          ? () => Rtn
+          : R extends [infer A]      // db + one extra → widen extra to A | string
+            ? (arg: A | AsyncArgsProvider<A>) => Rtn
+            : never                  // more than one extra arg – not covered here
+        : never;
+  };
+
+export type TransactionFunctions = { readonly [K: string]: (args?: any) => void | Entity };
+
+export interface Database<
+    C extends CoreComponents = CoreComponents,
+    R extends ResourceComponents = never,
+    T extends TransactionFunctions = never,
+> extends ReadonlyStore<C, R> {
+    readonly transactions: T;
+    readonly observe: {
+        readonly component: { readonly [K in StringKeyof<C>]: Observe<void> };
+        readonly resource: { readonly [K in StringKeyof<R>]: Observe<R[K]> };
+        readonly transactions: Observe<TransactionResult<C>>;
+        entity(id: Entity): Observe<EntityValues<C> | null>;
+        archetype(id: ArchetypeId): Observe<void>;
+    }
+}
+
+type TestTransactionFunctions = ToTransactionFunctions<{
+    test1: (db: Store<any, any>, arg: number) => void;
+    test2: (db: Store<any, any>) => void;
+}>

package/src/ecs/database/index.ts

@@ -0,0 +1,24 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+export * from "./create-database.js";
+export * from "./database.js";
+export * from "./observe-dependent-value.js";

package/src/ecs/database/observe-dependent-value.test.ts

@@ -0,0 +1,198 @@
+/*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, vi } from 'vitest';
+import { observeDependentValue } from './observe-dependent-value.js';
+import { createStore } from '../store/create-store.js';
+import { createDatabase } from './create-database.js';
+import { ToReadonlyStore } from '../store/index.js';
+
+describe('observeDependentValue', () => {
+    it('should compute and observe dependent values from resources', async () => {
+        // Create a store with three resources
+        const store = createStore(
+            {},
+            {
+                a: 10,
+                b: 20,
+                c: 30
+            }
+        );
+        type TestStore = ToReadonlyStore<typeof store>;
+
+        // Create the database
+        const database = createDatabase(store, {
+            updateA: (store, value: number) => {
+                store.resources.a = value;
+            },
+            updateB: (store, value: number) => {
+                store.resources.b = value;
+            },
+            updateC: (store, value: number) => {
+                store.resources.c = value;
+            },
+            updateAB: (store, values: { a: number; b: number }) => {
+                store.resources.a = values.a;
+                store.resources.b = values.b;
+            }
+        });
+
+        type TestDatabase = typeof database;
+
+        // Create a compute function that sums resources 'a' and 'b'
+        const computeSum = (db: TestStore) => {
+            return db.resources.a + db.resources.b;
+        };
+
+        // Create the dependent value observable
+        const sumObservable = observeDependentValue(database, computeSum);
+
+        // Track observed values
+        const observedValues: number[] = [];
+        const unsubscribe = sumObservable((value) => {
+            observedValues.push(value);
+        });
+
+        // Should immediately provide the initial computed value
+        expect(observedValues).toEqual([30]); // 10 + 20
+
+        // Update resource 'a'
+        database.transactions.updateA(15);
+        await Promise.resolve();
+
+        // Should recompute and notify with new value
+        expect(observedValues).toEqual([30, 35]); // 15 + 20
+
+        // Update resource 'b'
+        database.transactions.updateB(25);
+        await Promise.resolve();
+
+        // Should recompute and notify with new value
+        expect(observedValues).toEqual([30, 35, 40]); // 15 + 25
+
+        // Update resource 'c' (not used in computation)
+        database.transactions.updateC(50);
+        await Promise.resolve();
+
+        // Should NOT recompute since 'c' is not used in the computation
+        expect(observedValues).toEqual([30, 35, 40]);
+
+        // Update both 'a' and 'b' in same transaction
+        database.transactions.updateAB({ a: 5, b: 10 });
+        await Promise.resolve();
+
+        // Should recompute once with final values
+        expect(observedValues).toEqual([30, 35, 40, 15]); // 5 + 10
+
+        // Test unsubscribe
+        unsubscribe();
+
+        // Update after unsubscribe
+        database.transactions.updateA(100);
+        await Promise.resolve();
+
+        // Should not notify after unsubscribe
+        expect(observedValues).toEqual([30, 35, 40, 15]);
+    });
+
+    it('should handle multiple observers correctly', async () => {
+        const store = createStore({}, { a: 1, b: 2, c: 3 });
+        const database = createDatabase(store, {
+            updateA: (store, value: number) => { store.resources.a = value; },
+            updateB: (store, value: number) => { store.resources.b = value; }
+        });
+
+        const sumObservable = observeDependentValue(database, (store) => {
+            return store.resources.a + store.resources.b;
+        });
+
+        const values1: number[] = [];
+        const values2: number[] = [];
+
+        const unsubscribe1 = sumObservable((value) => values1.push(value));
+        const unsubscribe2 = sumObservable((value) => values2.push(value));
+
+        // Both observers should get initial value
+        expect(values1).toEqual([3]);
+        expect(values2).toEqual([3]);
+
+        // Update a resource
+        database.transactions.updateA(5);
+        await Promise.resolve();
+
+        // Both observers should get updated value
+        expect(values1).toEqual([3, 7]);
+        expect(values2).toEqual([3, 7]);
+
+        // Unsubscribe one observer
+        unsubscribe1();
+
+        // Update again
+        database.transactions.updateB(8);
+        await Promise.resolve();
+
+        // Only remaining observer should get update
+        expect(values1).toEqual([3, 7]); // No more updates
+        expect(values2).toEqual([3, 7, 13]); // Gets new update
+
+        unsubscribe2();
+    });
+
+    it('should handle complex computed values', async () => {
+        const store = createStore({}, { 
+            count: 5, 
+            multiplier: 2, 
+            offset: 10 
+        });
+        const database = createDatabase(store, {
+            updateCount: (store, value: number) => { store.resources.count = value; },
+            updateMultiplier: (store, value: number) => { store.resources.multiplier = value; }
+        });
+
+        type TestDatabase = typeof database;
+
+        const complexObservable = observeDependentValue(database, (store) => {
+            return (store.resources.count * store.resources.multiplier) + store.resources.offset;
+        });
+
+        const values: number[] = [];
+        const unsubscribe = complexObservable((value) => values.push(value));
+
+        // Initial: (5 * 2) + 10 = 20
+        expect(values).toEqual([20]);
+
+        // Update count
+        database.transactions.updateCount(3);
+        await Promise.resolve();
+
+        // New: (3 * 2) + 10 = 16
+        expect(values).toEqual([20, 16]);
+
+        // Update multiplier
+        database.transactions.updateMultiplier(4);
+        await Promise.resolve();
+
+        // New: (3 * 4) + 10 = 22
+        expect(values).toEqual([20, 16, 22]);
+
+        unsubscribe();
+    });
+}); 

package/src/ecs/database/observe-dependent-value.ts

@@ -0,0 +1,78 @@
+/*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 { Observe, withDeduplicate, withMap, withBatch, fromArray, withLazy } from "../../observe/index.js";
+import { Database } from "./database.js";
+import { ReadonlyStore, Store } from "../store/index.js";
+
+/**
+ * Creates an observe function that is computed based on the stores resources.
+ */
+export function observeDependentValue<
+    D extends Database<any, any, any>,
+    T,
+>(db: D, compute: (store: D extends Database<infer C, infer R, any> ? ReadonlyStore<C, R> : never) => T): Observe<T> {
+    return withLazy(() => {
+        const resourcesUsed = determineResourcesUsed(db, compute);
+        
+        // Create observables for only the resources that are actually used
+        const resourceObservables = 
+            resourcesUsed.map(resource => (db.observe.resource as any)[resource]);
+        
+        // Use fromArray to combine the resource observables, batch notifications, then map and deduplicate
+        return withDeduplicate(
+            withMap(
+                withBatch(fromArray(resourceObservables)),
+                (_resources) => {
+                    return compute(db as any);
+                }
+            )
+        );
+    });
+}
+
+function determineResourcesUsed<D extends Database<any, any, any>>(db: D, compute: (db: D extends Database<infer C, infer R, any> ? Store<C, R> : never) => any): string[] {
+    const accessedResources = new Set<string>();
+    
+    // Create a proxy that tracks which resource properties are accessed
+    const resourceProxy = new Proxy(db.resources, {
+        get(target, prop) {
+            if (typeof prop === 'string') {
+                accessedResources.add(prop);
+            }
+            return (target as any)[prop];
+        }
+    });
+    
+    // Create a database object with our proxied resources
+    const dbProxy = { ...db, resources: resourceProxy };
+    
+    // Call the compute function with our proxied database
+    // This will track which resources are accessed
+    try {
+        compute(dbProxy as any);
+    } catch (error) {
+        // Ignore errors during dependency detection
+        // The actual computation will happen later with the real database
+    }
+    
+    return Array.from(accessedResources);
+}