@adobe/data 0.1.2

package/ecs/action-ecs/action-types.d.ts

@@ -0,0 +1,106 @@
+import { FromSchema, Schema } from "../../core/index.js";
+import { Observe } from "../../observe/types.js";
+import { Expand, Simplify } from "../../types/types.js";
+import { Archetype, ECSArchetypes, ECSComponents, ECSResources } from "../ecs/ecs-types.js";
+import { Entity } from "../index.js";
+import { Transaction, TransactionECS, TransactionObservables } from "../transaction-ecs/transaction-types.js";
+export type ECSActionFunctions = Record<string, ActionFunction>;
+export type AsyncArgsProvider<T> = () => Promise<T> | AsyncGenerator<T>;
+/**
+ * Represents an ECS with actions that can be applied to it.
+ * Actions are functions that can be applied to the ECS to change its state.
+ * They are defined in advance using the withActions method.
+ * These actions are implemented using transactions which are applied to the
+ * underlying TransactionECS.
+ */
+export interface ActionECS<C extends ECSComponents = ECSComponents, //  name => Component Value Type
+A extends ECSArchetypes = {}, //  name => Entity Values Type
+R extends ECSResources = {}, //  name => Resource Value Type
+F extends ECSActionFunctions = {}> extends Omit<TransactionECS<C, A, R>, "createTransaction" | "withComponents" | "withArchetypes" | "withResources"> {
+    apply(action: Action<F>): void;
+    readonly actions: {
+        [K in keyof F]: ToActionFunction<F[K]>;
+    };
+    readonly actionSequences: {
+        [K in keyof F]: (...args: Parameters<ToActionFunction<F[K]>>) => ActionSequence<Parameters<ToActionFunction<F[K]>>>;
+    };
+    withComponents<S extends {
+        [K: string]: Schema;
+    }, T = {
+        -readonly [K in keyof S]: FromSchema<S[K]>;
+    }>(components: S): ActionECS<Simplify<C & T>, A, R, F>;
+    withArchetypes<S extends {
+        [K: string]: ReadonlyArray<keyof C>;
+    }>(archetypes: S): ActionECS<C, Simplify<A & {
+        -readonly [AN in keyof S]: Archetype<Expand<{
+            id: Entity;
+        } & {
+            [PN in S[AN][number]]: C[PN];
+        }>>;
+    }>, R, F>;
+    withResources<S extends {
+        [K: string]: unknown;
+    }>(resources: S): ActionECS<C, A, Simplify<R & S>, F>;
+    withActions<S extends {
+        [K: string]: TransactionFunction<C, A, R, F>;
+    }>(transactionFunctions: S): ActionECS<C, A, R, Simplify<F & S>>;
+    observe: ActionECSObservables<C, A, R, F>;
+    /**
+     * The number of transient actions that are currently in progress.
+     * This is used for debugging.
+     */
+    getTransientActionCount: () => number;
+}
+export type ActionECSObservables<C extends ECSComponents = ECSComponents, //  name => Component Value Type
+A extends ECSArchetypes = ECSArchetypes, //  name => Entity Values Type
+R extends ECSResources = ECSResources, //  name => Resource Value Type
+F extends ECSActionFunctions = ECSActionFunctions> = TransactionObservables<C, A, R> & {
+    actions: Observe<Action<F>>;
+};
+/**
+ * Represents an action which can be applied to an ActionECS.
+ */
+export type Action<F extends ECSActionFunctions = any> = {
+    type: "transient" | "commit" | "cancel";
+    /**
+     * The unique time in UTC milliseconds when the action was created.
+     */
+    createdTime: number;
+    /**
+     * The unique identifier for the user creating the action.
+     */
+    createdBy: string;
+    /**
+     * The name of the action.
+     */
+    name: keyof F;
+    /**
+     * The semantic arguments for the action.
+     */
+    args: Parameters<ToActionFunction<F[keyof F]>>;
+};
+/**
+ * Gets the action type for the given ECS.
+ */
+export type ActionFor<ECS extends ActionECS<any, any, any, any>> = ECS extends ActionECS<infer C, infer A, infer R, infer F> ? Action<F> : never;
+/**
+ * Compares two actions to determine their correct application order.
+ * Transient actions are always applied after non-transient actions.
+ * Actions are then sorted by time ascending.
+ * Actions are then sorted by user ascending.
+ * @returns 0 if the actions are equal, -1 if a should be applied before b, 1 if b should be applied before a.
+ */
+export declare function compareActionOrder(a: Action, b: Action): number;
+export declare function isSameAction(a: Action, b: Action): boolean;
+export type TransactionFunction<C extends ECSComponents = any, //  name => Component Value Type
+A extends ECSArchetypes = any, //  name => Entity Values Type
+R extends ECSResources = any, //  name => Resource Value Type
+F extends ECSActionFunctions = any> = (this: F, t: Transaction<C, A, R>, ...args: any[]) => void;
+export type ToActionFunction<F> = F extends (t: Transaction<any, any, any>, ...args: infer Args) => void ? ActionFunction<(Args | [AsyncArgsProvider<Args>])> : never;
+type ActionFunction<Args extends any[] = any[]> = (...args: Args) => void;
+export type ActionSequence<Args extends any[] = any[]> = {
+    update: (...args: Args) => ActionSequence<Args>;
+    commit: () => void;
+    cancel: () => void;
+};
+export {};

package/ecs/action-ecs/action-types.js

@@ -0,0 +1,19 @@
+/**
+ * Compares two actions to determine their correct application order.
+ * Transient actions are always applied after non-transient actions.
+ * Actions are then sorted by time ascending.
+ * Actions are then sorted by user ascending.
+ * @returns 0 if the actions are equal, -1 if a should be applied before b, 1 if b should be applied before a.
+ */
+export function compareActionOrder(a, b) {
+    if (a.createdTime !== b.createdTime) {
+        return a.createdTime - b.createdTime;
+    }
+    return a.createdBy.localeCompare(b.createdBy, undefined, {
+        sensitivity: "variant",
+    });
+}
+export function isSameAction(a, b) {
+    return a.createdTime === b.createdTime && a.createdBy === b.createdBy;
+}
+//# sourceMappingURL=action-types.js.map

package/ecs/action-ecs/action-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-types.js","sourceRoot":"","sources":["../../../src/ecs/action-ecs/action-types.ts"],"names":[],"mappings":"AAwIA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAS,EAAE,CAAS;IACrD,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QACpC,OAAO,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;IACvC,CAAC;IACD,OAAO,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE;QACvD,WAAW,EAAE,SAAS;KACvB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,OAAO,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,CAAC;AACxE,CAAC"}

package/ecs/action-ecs/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./action-ecs.js";
+export { type ActionECS, type Action, type ActionSequence, type ActionFor, } from "./action-types.js";

package/ecs/action-ecs/index.js

@@ -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 "./action-ecs.js";
+//# sourceMappingURL=index.js.map

package/ecs/action-ecs/index.js.map

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

package/ecs/core-ecs/core-ecs-serialization.test.d.ts

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

package/ecs/core-ecs/core-ecs-serialization.test.js

@@ -0,0 +1,230 @@
+/*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, expect, test } from "vitest";
+import { createCoreECS } from "./core-ecs.js";
+const createEcsWithMassAndSize = (data, precision = 2) => {
+    return createCoreECS({ data })
+        .withComponents({
+        mass: { type: "number", minimum: 0, precision },
+        size: { enum: ["small", "medium", "large"] },
+    })
+        .withResources({
+        gravity: 9.8,
+    });
+};
+const createEcsWithMassAndSizeAndShape = (data) => {
+    return createCoreECS({ data })
+        .withComponents({
+        mass: { type: "number", minimum: 0, precision: 2 },
+        shape: { enum: ["circle", "square", "triangle"] },
+        size: { enum: ["small", "medium", "large"] },
+    })
+        .withResources({
+        gravity: 9.8,
+    });
+};
+describe("ecs-functions", () => {
+    test("toJSON with base64 encoded binary data, mass is float64array", () => {
+        const ecs = createEcsWithMassAndSize();
+        const physical = ecs.getArchetype("id", "mass", "size");
+        for (let i = 1; i < 10; i++) {
+            ecs.createEntity(physical, {
+                mass: 3123123123121.232 / i,
+                size: "medium",
+            });
+        }
+        const data = ecs.toJSON();
+        expect(data).toEqual({
+            ecs: true,
+            version: 4,
+            components: {
+                id: { type: "integer", minimum: +0, maximum: 4294967295 },
+                mass: { type: "number", minimum: +0, precision: 2 },
+                size: { enum: ["small", "medium", "large"] },
+                gravity: {},
+            },
+            entities: [1, +0, 2, +0, 2, 1, 2, 2, 2, 3, 2, 4, 2, 5, 2, 6, 2, 7, 2, 8],
+            tables: [
+                { rows: +0, columns: { id: [] } },
+                { rows: 1, columns: { gravity: [9.8], id: [+0] } },
+                {
+                    rows: 9,
+                    columns: {
+                        //  id is not base 64 encoded because the json is shorter.
+                        id: [1, 2, 3, 4, 5, 6, 7, 8, 9],
+                        //  mass is base 64 encoded because the encoded form is shorter.
+                        //  This one is longer than the 
+                        mass: "24mdJ0W5hkLbiZ0nRbl2QiQN0jRcTG5C24mdJ0W5ZkLiB37s0C1iQiQN0jRcTF5CQwu0CE/4WULbiZ0nRblWQm2zNiPoMlRC",
+                        //  size could be compressed efficiently by any general compression algorithm.
+                        //  we don't expect large data sets to use strings for components so we don't compress it.
+                        size: [
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                        ],
+                    },
+                },
+            ],
+        });
+    });
+    test("toJSON with base64 encoded binary data, mass is float32array", () => {
+        const precision = 1;
+        const ecs = createEcsWithMassAndSize(undefined, precision);
+        const physical = ecs.getArchetype("id", "mass", "size");
+        for (let i = 1; i < 10; i++) {
+            ecs.createEntity(physical, {
+                mass: 3123123123121.232 / i,
+                size: "medium",
+            });
+        }
+        const data = ecs.toJSON();
+        expect(data).toEqual({
+            ecs: true,
+            version: 4,
+            components: {
+                id: { type: "integer", minimum: +0, maximum: 4294967295 },
+                mass: { type: "number", minimum: +0, precision: 1 },
+                size: { enum: ["small", "medium", "large"] },
+                gravity: {},
+            },
+            entities: [1, +0, 2, +0, 2, 1, 2, 2, 2, 3, 2, 4, 2, 5, 2, 6, 2, 7, 2, 8],
+            tables: [
+                { rows: +0, columns: { id: [] } },
+                { rows: 1, columns: { gravity: [9.8], id: [+0] } },
+                {
+                    rows: 9,
+                    columns: {
+                        //  id is not base 64 encoded because the json is shorter.
+                        id: [1, 2, 3, 4, 5, 6, 7, 8, 9],
+                        //  mass is base 64 encoded because the encoded form is shorter.
+                        mass: "Kco1VCnKtVPiYnJTKco1U4duEVPiYvJSeMLPUinKtVJBl6FS",
+                        //  size could be compressed efficiently by any general compression algorithm.
+                        //  we don't expect large data sets to use strings for components so we don't compress it.
+                        size: [
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                            "medium",
+                        ],
+                    },
+                },
+            ],
+        });
+    });
+    test("toJSON and fromJSON round trip", () => {
+        const ecs = createEcsWithMassAndSize();
+        const physical = ecs.getArchetype("id", "mass", "size");
+        for (let i = 1; i < 10; i++) {
+            ecs.createEntity(physical, {
+                mass: 3123123123121.232 / i,
+                size: "medium",
+            });
+        }
+        const data = ecs.toJSON();
+        const ecs2 = createEcsWithMassAndSize(data);
+        const data2 = ecs2.toJSON();
+        expect(data2).toEqual(data);
+    });
+    test("toJSON and fromJSON round trip with new components", () => {
+        const ecs = createEcsWithMassAndSize();
+        const physical = ecs.getArchetype("id", "mass", "size");
+        for (let i = 1; i < 10; i++) {
+            ecs.createEntity(physical, {
+                mass: 3123123123121.232 / i,
+                size: "medium",
+            });
+        }
+        const data = ecs.toJSON();
+        const ecs2 = createEcsWithMassAndSizeAndShape(data);
+        const physicalAndShaped = ecs2.getArchetype("id", "mass", "size", "shape");
+        ecs2.createEntity(physicalAndShaped, {
+            mass: 98,
+            size: "medium",
+            shape: "circle",
+        });
+        const data2 = ecs2.toJSON();
+        const ecs3 = createEcsWithMassAndSizeAndShape(data2);
+        const data3 = ecs3.toJSON();
+        expect(data3).toEqual(data2);
+    });
+    test("verify entity data consistency when changing archetypes", () => {
+        const ecs = createEcsWithMassAndSizeAndShape();
+        const initialArchetype = ecs.getArchetype("id", "mass");
+        const targetArchetype = ecs.getArchetype("id", "mass", "shape");
+        // Create 100 entities with just mass
+        const entities = [];
+        for (let i = 0; i < 100; i++) {
+            const entity = ecs.createEntity(initialArchetype, {
+                mass: i + 1.5
+            });
+            entities.push(entity);
+        }
+        // Update each entity one by one, adding the shape component
+        for (let i = 0; i < entities.length; i++) {
+            const entity = entities[i];
+            const expectedMass = i + 1.5;
+            // Update entity to add shape component
+            ecs.updateEntity(entity, {
+                mass: expectedMass,
+                shape: "circle"
+            });
+            // Verify the entity data immediately after update
+            const entityData = ecs.getEntityValues(entity);
+            if (!entityData) {
+                throw new Error(`Entity ${entity} not found after update`);
+            }
+            if (entityData.mass !== expectedMass) {
+                throw new Error(`Entity ${entity} has incorrect mass. Expected ${expectedMass}, got ${entityData.mass}`);
+            }
+            if (entityData.shape !== "circle") {
+                throw new Error(`Entity ${entity} has incorrect shape. Expected "circle", got ${entityData.shape}`);
+            }
+            // Also verify all previously updated entities still have correct data
+            for (let j = 0; j <= i; j++) {
+                const prevEntity = entities[j];
+                const prevData = ecs.getEntityValues(prevEntity);
+                if (!prevData) {
+                    throw new Error(`Previously updated entity ${prevEntity} not found`);
+                }
+                const prevExpectedMass = j + 1.5;
+                if (prevData.mass !== prevExpectedMass) {
+                    throw new Error(`Previously updated entity ${prevEntity} has incorrect mass. Expected ${prevExpectedMass}, got ${prevData.mass}`);
+                }
+                if (prevData.shape !== "circle") {
+                    throw new Error(`Previously updated entity ${prevEntity} has incorrect shape. Expected "circle", got ${prevData.shape}`);
+                }
+            }
+        }
+    });
+});
+//# sourceMappingURL=core-ecs-serialization.test.js.map

package/ecs/core-ecs/core-ecs-serialization.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-ecs-serialization.test.js","sourceRoot":"","sources":["../../../src/ecs/core-ecs/core-ecs-serialization.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;WAoBW;AAEX,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,wBAAwB,GAAG,CAAC,IAAc,EAAE,YAAmB,CAAC,EAAE,EAAE;IACxE,OAAO,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;SAC3B,cAAc,CAAC;QACd,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE;QAC/C,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE;KACpC,CAAC;SACV,aAAa,CAAC;QACb,OAAO,EAAE,GAAG;KACb,CAAC,CAAC;AACP,CAAC,CAAC;AAEF,MAAM,gCAAgC,GAAG,CAAC,IAAc,EAAE,EAAE;IAC1D,OAAO,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;SAC3B,cAAc,CAAC;QACd,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;QAClD,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE;QACjD,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE;KACpC,CAAC;SACV,aAAa,CAAC;QACb,OAAO,EAAE,GAAG;KACb,CAAC,CAAC;AACP,CAAC,CAAC;AAEF,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,IAAI,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACxE,MAAM,GAAG,GAAG,wBAAwB,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE;gBACzB,IAAI,EAAE,iBAAiB,GAAG,CAAC;gBAC3B,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;YACnB,GAAG,EAAE,IAAI;YACT,OAAO,EAAE,CAAC;YACV,UAAU,EAAE;gBACV,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;gBACzD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;gBACnD,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE;gBAC5C,OAAO,EAAE,EAAE;aACZ;YACD,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACxE,MAAM,EAAE;gBACN,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;gBACjC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE;gBAClD;oBACE,IAAI,EAAE,CAAC;oBACP,OAAO,EAAE;wBACP,0DAA0D;wBAC1D,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;wBAC/B,gEAAgE;wBAChE,gCAAgC;wBAChC,IAAI,EAAE,kGAAkG;wBACxG,8EAA8E;wBAC9E,0FAA0F;wBAC1F,IAAI,EAAE;4BACJ,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;yBACT;qBACF;iBACF;aACF;SACF,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACxE,MAAM,SAAS,GAAG,CAAC,CAAC;QACpB,MAAM,GAAG,GAAG,wBAAwB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC3D,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE;gBACzB,IAAI,EAAE,iBAAiB,GAAG,CAAC;gBAC3B,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;YACnB,GAAG,EAAE,IAAI;YACT,OAAO,EAAE,CAAC;YACV,UAAU,EAAE;gBACV,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;gBACzD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;gBACnD,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE;gBAC5C,OAAO,EAAE,EAAE;aACZ;YACD,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACxE,MAAM,EAAE;gBACN,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;gBACjC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE;gBAClD;oBACE,IAAI,EAAE,CAAC;oBACP,OAAO,EAAE;wBACP,0DAA0D;wBAC1D,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;wBAC/B,gEAAgE;wBAChE,IAAI,EAAE,kDAAkD;wBACxD,8EAA8E;wBAC9E,0FAA0F;wBAC1F,IAAI,EAAE;4BACJ,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;4BACR,QAAQ;yBACT;qBACF;iBACF;aACF;SACF,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,gCAAgC,EAAE,GAAG,EAAE;QAC1C,MAAM,GAAG,GAAG,wBAAwB,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE;gBACzB,IAAI,EAAE,iBAAiB,GAAG,CAAC;gBAC3B,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC9D,MAAM,GAAG,GAAG,wBAAwB,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE;gBACzB,IAAI,EAAE,iBAAiB,GAAG,CAAC;gBAC3B,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,gCAAgC,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,iBAAiB,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC3E,IAAI,CAAC,YAAY,CAAC,iBAAiB,EAAE;YACnC,IAAI,EAAE,EAAE;YACR,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,QAAQ;SAChB,CAAC,CAAC;QAEH,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,gCAAgC,CAAC,KAAK,CAAC,CAAC;QAErD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACnE,MAAM,GAAG,GAAG,gCAAgC,EAAE,CAAC;QAC/C,MAAM,gBAAgB,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxD,MAAM,eAAe,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAEhE,qCAAqC;QACrC,MAAM,QAAQ,GAAG,EAAE,CAAC;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,gBAAgB,EAAE;gBAChD,IAAI,EAAE,CAAC,GAAG,GAAG;aACd,CAAC,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC;QAED,4DAA4D;QAC5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,YAAY,GAAG,CAAC,GAAG,GAAG,CAAC;YAE7B,uCAAuC;YACvC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE;gBACvB,IAAI,EAAE,YAAY;gBAClB,KAAK,EAAE,QAAQ;aAChB,CAAC,CAAC;YAEH,kDAAkD;YAClD,MAAM,UAAU,GAAG,GAAG,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YAC/C,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,MAAM,IAAI,KAAK,CAAC,UAAU,MAAM,yBAAyB,CAAC,CAAC;YAC7D,CAAC;YAED,IAAI,UAAU,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,UAAU,MAAM,iCAAiC,YAAY,SAAS,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3G,CAAC;YACD,IAAI,UAAU,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,UAAU,MAAM,gDAAgD,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;YACtG,CAAC;YAED,sEAAsE;YACtE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5B,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;gBAC/B,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;gBACjD,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,MAAM,IAAI,KAAK,CAAC,6BAA6B,UAAU,YAAY,CAAC,CAAC;gBACvE,CAAC;gBACD,MAAM,gBAAgB,GAAG,CAAC,GAAG,GAAG,CAAC;gBAEjC,IAAI,QAAQ,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;oBACvC,MAAM,IAAI,KAAK,CAAC,6BAA6B,UAAU,iCAAiC,gBAAgB,SAAS,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;gBACpI,CAAC;gBACD,IAAI,QAAQ,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAChC,MAAM,IAAI,KAAK,CAAC,6BAA6B,UAAU,gDAAgD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;gBAC3H,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/ecs/core-ecs/core-ecs-types.d.ts

@@ -0,0 +1,141 @@
+import { Data, FromSchema, Schema } from "../../core/index.js";
+import { DeepReadonly, Simplify } from "../../types/types.js";
+import { NativeArray } from "../../cache/managed-array.js";
+/**
+ * An Entity represents a single object within the ECS.
+ * It is a unique positive integer identifier that can be used to access the components of the entity.
+ */
+export type Entity = number;
+/**
+ * Represents all of an entities values for the given ECS components.
+ * This will always contain an id property which is the entity id.
+ * All other components are optional.
+ */
+export type EntityValues<C> = {
+    id: number;
+} & {
+    [K in keyof C]?: C[K] | undefined;
+};
+/**
+ * Represents the values you can use when creating an entity.
+ * You cannot provide an id as this is always generated by the ECS.
+ */
+export type EntityCreateValues<A> = Omit<A, "id">;
+/**
+ * Represents the values you can use when updating an entity.
+ * Providing a value of undefined for a component will delete it.
+ */
+export type EntityUpdateValues<C> = Omit<{
+    [K in keyof C]?: C[K] | undefined;
+}, "id">;
+/**
+ * The JSON data type that is used to serialize and deserialize ECS data.
+ */
+export type ECSJSON = {
+    ecs: true;
+    version: number;
+    components: Record<string, Schema>;
+    entities: readonly number[];
+    tables: {
+        rows: number;
+        columns: Record<string, Data>;
+    }[];
+};
+export type CoreComponents = {
+    id: number;
+};
+export type CoreResources = {
+    [K: string]: Data;
+};
+export interface CoreECS<C extends CoreComponents = CoreComponents, R extends CoreResources = {}> extends CoreECSRead<C, R>, CoreECSWrite<C, R> {
+    /**
+     * Creates new components within this ecs and returns the same ecs with the new expanded type information.
+     */
+    withComponents<S extends {
+        readonly [K: string]: DeepReadonly<Schema>;
+    }, T = {
+        -readonly [K in keyof S]: FromSchema<S[K]>;
+    }>(components: S): CoreECS<Simplify<C & T>, R>;
+    withResources<T extends {
+        readonly [K: string]: Data;
+    }>(resources: T): CoreECS<C, Simplify<R & T>>;
+}
+export interface CoreECSRead<C extends CoreComponents = CoreComponents, R extends CoreResources = {}> {
+    components: {
+        readonly [K in keyof C]: Schema;
+    };
+    resources: R;
+    /**
+     * Returns the component value for the given entity.
+     * @param component the component to read.
+     * @param id if not provided, uses the component own entity id as with resources.
+     */
+    getComponentValue<Name extends keyof C>(id: Entity, component: Name): C[Name] | undefined;
+    getArchetype<Components extends (keyof C)[]>(...components: Components): CoreArchetype<{
+        [K in Components[number]]: C[K];
+    }>;
+    getEntityValues(id: Entity): EntityValues<C> | undefined;
+    getEntityArchetype(id: Entity): CoreArchetype;
+    countEntities<T extends CoreComponents>(archetype: CoreArchetype<T>): number;
+    selectEntities<T extends CoreComponents>(archetype: CoreArchetype<T>): Entity[];
+    toJSON(): ECSJSON;
+}
+export interface CoreECSWrite<C extends CoreComponents = CoreComponents, R extends CoreResources = {}> {
+    createEntity(): Entity;
+    createEntity<T extends CoreComponents>(archetype: CoreArchetype<T>, values: Omit<T, "id">): Entity;
+    createBatch<T extends CoreComponents>(archetype: CoreArchetype<T>, count: number): Table<T>;
+    /**
+     * Sets the value of a component for the given entity.
+     * @param component the component to write.
+     * @param value the value of the component or undefined to delete the component.
+     * @param id if not provided, uses the components own entity id as with resources.
+     */
+    setComponentValue<Name extends keyof C>(id: Entity, component: Name, value: C[Name] | undefined): void;
+    /**
+     * Gets the tables for the given archetype in read or write mode.
+     * @param exact if true, only returns the single table that exactly matches the archetype.
+     */
+    getTables<T extends CoreComponents>(archetype: CoreArchetype<T>, options: {
+        mode: "read" | "write";
+        exact?: boolean;
+    }): Table<C>[];
+    updateEntity(id: Entity, values: EntityUpdateValues<C>): void;
+    deleteEntity(id: Entity): void;
+}
+export interface CoreArchetype<C = {
+    [K: string]: unknown;
+}> {
+    readonly components: (keyof C)[];
+}
+/**
+ * A Table represents a collection of entities with the same exact archetype.
+ */
+export interface Table<C = {
+    [K: string]: unknown;
+}> {
+    readonly rows: number;
+    readonly columns: {
+        [K in keyof C]: Column<C[K]>;
+    };
+}
+/**
+ * A column represents an array of values for a single component.
+ * Each row in the column corresponds to a single entity within the containing Table.
+ * The ECS stores data as a structure of arrays.
+ */
+export interface Column<T> {
+    get(row: number): T;
+    set(row: number, value: T): void;
+    /**
+     * Allows unsafe direct access to the underlying native array if present.
+     * Not present for constant columns.
+     * For numeric tuples, the array will be of the form [a0, a1, a2, b0, b1, b2, ...]
+     */
+    native?: NativeArray<T extends number[] ? number : T>;
+    /**
+     * Is every value in this column the same?
+     */
+    constant: boolean;
+    toJSON(length: number): Data;
+    fromJSON(data: Data, length: number): void;
+}

package/ecs/core-ecs/core-ecs-types.js

@@ -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 {};
+//# sourceMappingURL=core-ecs-types.js.map

package/ecs/core-ecs/core-ecs-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-ecs-types.js","sourceRoot":"","sources":["../../../src/ecs/core-ecs/core-ecs-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;WAoBW"}

package/ecs/core-ecs/core-ecs.d.ts

@@ -0,0 +1,7 @@
+import { MemoryAllocator } from "../../cache/memory-allocator.js";
+import { CoreECS, CoreComponents, ECSJSON, CoreResources } from "./core-ecs-types.js";
+export declare const DELETE: unknown;
+export declare function createCoreECS<C extends CoreComponents, R extends CoreResources>(options?: {
+    data?: ECSJSON;
+    allocator?: MemoryAllocator;
+}): CoreECS<CoreComponents, {}>;