@adobe/data 0.4.6 → 0.4.8

package/dist/ecs/store/select.d.ts

@@ -0,0 +1,44 @@
+import { StringKeyof } from "../../types/types.js";
+import { CoreComponents } from "../core-components.js";
+/**
+ * Comparison operators for declarative where clauses
+ */
+type ComparisonOperator = "==" | "!=" | "<" | ">" | ">=" | "<=";
+/**
+ * Represents a comparison operation in a declarative where clause
+ */
+type ComparisonOperation<T> = {
+    [P in ComparisonOperator]?: T;
+};
+/**
+ * Represents a condition that can be either a direct value, comparison operation, or nested conditions
+ */
+type WhereCondition<T> = T extends object ? {
+    [K in keyof T]?: WhereCondition<T[K]>;
+} | ComparisonOperation<T> : T | ComparisonOperation<T>;
+/**
+ * Declarative where clause structure that allows for JSON-based filtering
+ * Each key in the object represents a component field to filter on
+ * The value can either be a direct value (equality check), a comparison operation, or nested conditions
+ */
+export type WhereClause<T extends CoreComponents> = {
+    [K in keyof T]?: WhereCondition<T[K]>;
+};
+type OrderClause<T extends CoreComponents> = {
+    [K in keyof T]?: boolean;
+};
+export type SelectOptions<C extends CoreComponents, T extends CoreComponents> = {
+    /**
+     * Components that the entities must not have.
+     */
+    without?: StringKeyof<C>[];
+    /**
+     * Filter the results by the given condition using a declarative where clause.
+     */
+    where?: WhereClause<T>;
+    /**
+     * Order results by the given components ascending or descending.
+     */
+    order?: OrderClause<T>;
+};
+export {};

package/dist/ecs/store/select.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=select.js.map

package/dist/ecs/store/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../../src/ecs/store/select.ts"],"names":[],"mappings":""}

package/dist/ecs/transaction-ecs/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./transaction-types.js";
+export * from "./transaction-ecs.js";

package/dist/ecs/transaction-ecs/index.js

@@ -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 "./transaction-types.js";
+export * from "./transaction-ecs.js";
+//# sourceMappingURL=index.js.map

package/dist/ecs/transaction-ecs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ecs/transaction-ecs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;WAoBW;AACX,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC"}

package/dist/ecs/transaction-ecs/transaction-ecs.d.ts

@@ -0,0 +1,11 @@
+import { ECS, ECSArchetypes, ECSComponents, ECSResources } from "../ecs/ecs-types.js";
+import { TransactionECS } from "./transaction-types.js";
+/**
+ * Creates a new TransactionECS.
+ * Transactional ECS instances do not allow direct write access.
+ * Instead you use transactions to make changes to the ECS.
+ * They also provide observability for changes to the ECS.
+ */
+export declare function createTransactionECS<C extends ECSComponents, //  name => Component Value Type
+A extends ECSArchetypes, //  name => Entity Values Type
+R extends ECSResources>(ecs?: ECS<C, A, R>): TransactionECS<C, A, R>;

package/dist/ecs/transaction-ecs/transaction-ecs.js

@@ -0,0 +1,184 @@
+import { createECS } from "../ecs/ecs.js";
+import { createECSTransaction } from "./transactions.js";
+import { arrayEquals } from "../../core/functions/array-equals.js";
+//  we want to cache this a well on each array.
+function isASubsetOfB(a, b) {
+    if (a !== b) {
+        const bSet = new Set(b);
+        for (const value of a) {
+            if (!bSet.has(value)) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Creates a new TransactionECS.
+ * Transactional ECS instances do not allow direct write access.
+ * Instead you use transactions to make changes to the ECS.
+ * They also provide observability for changes to the ECS.
+ */
+export function createTransactionECS(ecs = createECS()) {
+    const { components, archetypes, resources, ...rest } = ecs;
+    const withComponents = (newComponents) => {
+        ecs.withComponents(newComponents);
+        return tecs;
+    };
+    const withArchetypes = (newArchetypes) => {
+        ecs.withArchetypes(newArchetypes);
+        return tecs;
+    };
+    const withResources = (newResources) => {
+        ecs.withResources(newResources);
+        return tecs;
+    };
+    const transactionObservers = new Set();
+    const notifyTransactions = (transaction, changed) => {
+        //  notify all transaction observers.
+        for (const observer of transactionObservers) {
+            observer(transaction);
+        }
+        //  notify all observers of the entities and components that changed.
+        const observers = new Set();
+        const addObservers = (map, key) => {
+            const set = map.get(key);
+            if (set) {
+                for (const observer of set) {
+                    observers.add(observer);
+                }
+            }
+        };
+        for (const entity of changed.entities) {
+            addObservers(entityObservers, entity);
+        }
+        for (const name of changed.components) {
+            addObservers(componentObservers, name);
+        }
+        for (const archetype of changed.archetypes) {
+            for (const observedArchetype of archetypeObservers.keys()) {
+                const isSubset = isASubsetOfB(observedArchetype.components, archetype.components);
+                if (isSubset) {
+                    addObservers(archetypeObservers, observedArchetype);
+                }
+            }
+        }
+        for (const observer of observers) {
+            observer();
+        }
+    };
+    const transactions = (callback) => {
+        transactionObservers.add(callback);
+        return () => transactionObservers.delete(callback);
+    };
+    const createTransaction = (options) => {
+        return createECSTransaction(tecs, ecs, { undoable: true, createdTime: Date.now(), createdBy: "", ...options }, notifyTransactions);
+    };
+    const addToMapSet = (key, map, value) => {
+        let set = map.get(key);
+        if (set) {
+            set.add(value);
+        }
+        else {
+            map.set(key, (set = new Set([value])));
+        }
+        return () => {
+            set.delete(value);
+        };
+    };
+    const entityObservers = new Map();
+    const observeEntityChanges = (entity) => (callback) => {
+        return addToMapSet(entity, entityObservers, callback);
+    };
+    function observeEntityValues(id, archetype) {
+        return (callback) => {
+            const notify = () => {
+                callback(ecs.getEntityValues(id, archetype));
+            };
+            //  callback immediately to get the current value.
+            notify();
+            //  callback again whenever the entity changes.
+            const entityChanges = observeEntityChanges(id);
+            return entityChanges(notify);
+        };
+    }
+    const componentObservers = new Map();
+    const resourceObservables = new Map();
+    const observeResource = (key) => {
+        // Return cached observable if it exists
+        const cached = resourceObservables.get(key);
+        if (cached) {
+            return cached;
+        }
+        // Create new observable
+        const observable = (callback) => {
+            const notify = () => {
+                callback(resources[key]);
+            };
+            //  callback immediately to get the current value.
+            notify();
+            //  callback again whenever the resource changes.
+            const resourceChanges = observeComponent(key);
+            return resourceChanges(notify);
+        };
+        // Cache the observable
+        resourceObservables.set(key, observable);
+        return observable;
+    };
+    const observeComponent = (component) => (callback) => {
+        return addToMapSet(component, componentObservers, callback);
+    };
+    const archetypeObservers = new Map();
+    const observeArchetypeChanges = (archetype) => (callback) => {
+        return addToMapSet(archetype, archetypeObservers, callback);
+    };
+    const observeArchetypeEntities = (archetype, options) => {
+        return (callback) => {
+            let lastValue;
+            const notify = () => {
+                const newValue = ecs.selectEntities(archetype, options);
+                if (!lastValue || !arrayEquals(lastValue, newValue)) {
+                    lastValue = newValue;
+                    callback(newValue);
+                }
+            };
+            notify();
+            return observeArchetypeChanges(archetype)(notify);
+        };
+    };
+    const createResourceObserver = () => {
+        const handler = {
+            get(target, prop) {
+                if (typeof prop === 'string' && prop in resources) {
+                    return observeResource(prop);
+                }
+                return target[prop];
+            },
+            apply(target, thisArg, args) {
+                return target.apply(thisArg, args);
+            }
+        };
+        return new Proxy(observeResource, handler);
+    };
+    const tecs = {
+        ...rest,
+        withComponents,
+        withArchetypes,
+        withResources,
+        createTransaction,
+        observe: {
+            transactions,
+            resource: createResourceObserver(),
+            entityValues: observeEntityValues,
+            entityChanges: observeEntityChanges,
+            componentChanges: observeComponent,
+            archetypeChanges: observeArchetypeChanges,
+            archetypeEntities: observeArchetypeEntities,
+        },
+        components,
+        archetypes,
+        resources,
+    };
+    return tecs;
+}
+//# sourceMappingURL=transaction-ecs.js.map

package/dist/ecs/transaction-ecs/transaction-ecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-ecs.js","sourceRoot":"","sources":["../../../src/ecs/transaction-ecs/transaction-ecs.ts"],"names":[],"mappings":"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"}

package/dist/ecs/transaction-ecs/transaction-ecs.test.d.ts

@@ -0,0 +1 @@
+export {};