@adobe/data 0.1.3 → 0.2.1

package/src/observe/with-map.ts

@@ -0,0 +1,36 @@
+/*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 } from "./types.js";
+
+/**
+ * Creates a new Observe function that converts the original observe functions notify values into a new value at each notification.
+ */
+export function withMap<T, U>(
+  observable: Observe<T>,
+  map: (value: T) => U
+): Observe<U> {
+  return (observer) => {
+    return observable((value) => {
+      observer(map(value));
+    });
+  };
+}

package/src/observe/with-optional.ts

@@ -0,0 +1,47 @@
+/*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 } from "./types.js";
+
+/**
+ * Creates a new Observe function that may be undefined but will always yield a result or undefined synchronously when called.
+ */
+export const withOptional = <T>(
+  observable: Observe<T>
+): Observe<T | undefined> => {
+  return (observer) => {
+    let notified = false as boolean;
+    const notify = (value?: T) => {
+      notified = true;
+      observer(value);
+    };
+
+    const unobserverInternal = observable((value) => {
+      notify(value);
+    });
+
+    if (!notified) {
+      notify();
+    }
+
+    return unobserverInternal;
+  };
+};

package/src/observe/with-unwrap.ts

@@ -0,0 +1,54 @@
+/*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, Unobserve } from "./types.js";
+
+/**
+ * Unwraps a nested observable to provide a single observable with the inner observable's values.
+ */
+
+export function withUnwrap<T>(
+  observable: Observe<Observe<T>>
+): Observe<T> {
+  return (observer) => {
+    let currentUnsubscribe: Unobserve | null = null; // Track the current subscription
+
+    const unsubscribe = observable((innerObservable) => {
+      // Unsubscribe from the current inner observable before subscribing to the new one
+      if (currentUnsubscribe) {
+        currentUnsubscribe();
+      }
+
+      // Subscribe to the new inner observable and update the currentUnsubscribe
+      currentUnsubscribe = innerObservable((value) => {
+        observer(value);
+      });
+    });
+
+    // Return a new unsubscribe function that unsubscribes from both the outer and current inner observables
+    return () => {
+      unsubscribe(); // Unsubscribe from the outer observable
+      if (currentUnsubscribe) {
+        currentUnsubscribe(); // Ensure we unsubscribe from the current inner observable
+      }
+    };
+  };
+}

package/src/old-ecs/action-ecs/action-ecs.test.ts

@@ -0,0 +1,420 @@
+/*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 { createActionECS } from "./action-ecs.js";
+import { ActionECS, ActionFor } from "./action-types.js";
+import { EquivalentTypes, True } from "../../types/types.js";
+import { Transaction } from "../transaction-ecs/transaction-types.js";
+import { F32Schema } from "../../schema/f32.js";
+import { Tuple } from "../../schema/tuple.js";
+import { Archetype } from "../../old-ecs/index.js";
+import { FromSchema } from "../../schema/index.js";
+
+const user = "test";
+const createECSWithMassAndSize = () => {
+  return createActionECS({ user })
+    .withComponents({
+      mass: { type: "number", minimum: 0 },
+      size: { enum: ["small", "medium", "large"] },
+      checkCreatedTime: { type: "integer" },
+      checkCreatedBy: { type: "string" },
+    } as const)
+    .withArchetypes({
+      physical: ["id", "mass", "size"],
+      sized: ["id", "size"],
+      check: ["id", "checkCreatedTime", "checkCreatedBy"],
+    } as const)
+    .withResources({
+      gravity: 9.8,
+    })
+    .withActions({
+      createPhysical(t, mass: number, size: "small" | "medium" | "large") {
+        t.createEntity(t.ecs.archetypes.physical, { mass, size });
+      },
+      deletePhysical(t, entity: number) {
+        t.deleteEntity(entity);
+      },
+      setMass(t, entity: number, mass: number) {
+        t.setComponentValue(entity, "mass", mass);
+      },
+      setSize(t, entity: number, size: "small" | "medium" | "large") {
+        t.setComponentValue(entity, "size", size);
+      },
+      setGravity(t, gravity: number) {
+        t.resources.gravity = gravity;
+      },
+    })
+    .withActions({
+      //  higher order actions based on the previous actions
+      setMassAndSize(
+        this,
+        t,
+        entity: number,
+        mass: number,
+        size: "small" | "medium" | "large"
+      ) {
+        this.setMass(t, entity, mass);
+        this.setSize(t, entity, size);
+      },
+      checkTransactionOptions(this, t) {
+        t.createEntity(t.ecs.archetypes.check, {
+          checkCreatedTime: t.options.createdTime,
+          checkCreatedBy: t.options.createdBy,
+        });
+      }
+    });
+};
+
+//  some compile time type checks.
+type ECSType = ReturnType<typeof createECSWithMassAndSize>;
+type C = ECSType extends ActionECS<infer C, any, any, any> ? C : never;
+type A = ECSType extends ActionECS<any, infer A, any, any> ? A : never;
+type R = ECSType extends ActionECS<any, any, infer R, any> ? R : never;
+type Check_R = True<EquivalentTypes<R, { gravity: number }>>;
+type F = ECSType extends ActionECS<any, any, any, infer F> ? F : never;
+type SetMassAndSize = F["setMassAndSize"];
+type Check_SetMassAndSize = True<
+  SetMassAndSize extends (
+    t: Transaction<C, A, R>,
+    entity: number,
+    mass: number,
+    size: "small" | "medium" | "large"
+  ) => void
+  ? true
+  : false
+>;
+
+let FIRST_ENTITY: number;
+{
+  const ecs = createECSWithMassAndSize();
+  ecs.actions.createPhysical(1, "small");
+  FIRST_ENTITY = ecs.selectEntities(ecs.archetypes.physical)[0];
+}
+
+describe("ActionECS", () => {
+  test("can call an action to create an entity", () => {
+    const ecs = createECSWithMassAndSize();
+    ecs.actions.createPhysical(1, "small");
+    expect(ecs.selectEntityValues(ecs.archetypes.physical)).toEqual([
+      { id: FIRST_ENTITY, mass: 1, size: "small" },
+    ]);
+  });
+  test("calling an action includes createdTime and createdBy on options", () => {
+    const ecs = createECSWithMassAndSize();
+    ecs.actions.checkTransactionOptions();
+    const check = ecs.selectEntityValues(ecs.archetypes.check)[0];
+    expect(check).toEqual({
+      id: FIRST_ENTITY,
+      checkCreatedTime: expect.any(Number),
+      checkCreatedBy: user,
+    });
+  });
+  test("calling an apply action includes createdTime and createdBy on options", () => {
+    const ecs = createECSWithMassAndSize();
+    //  now we check that the time is exactly what we expect
+    const time = Date.now();
+    ecs.apply({ type: "commit", createdTime: time, createdBy: user, name: "checkTransactionOptions", args: [] });
+    const check = ecs.selectEntityValues(ecs.archetypes.check)[0];
+    expect(check).toEqual({
+      id: FIRST_ENTITY,
+      checkCreatedTime: time,
+      checkCreatedBy: user,
+    });
+  });
+  test("can call an action twice to create two entities", () => {
+    const ecs = createECSWithMassAndSize();
+    ecs.actions.createPhysical(1, "small");
+    ecs.actions.createPhysical(5, "large");
+    expect(ecs.selectEntityValues(ecs.archetypes.physical)).toEqual([
+      { id: FIRST_ENTITY, mass: 1, size: "small" },
+      { id: FIRST_ENTITY + 1, mass: 5, size: "large" },
+    ]);
+  });
+  test("can use higher order actions", () => {
+    const ecs = createECSWithMassAndSize();
+    ecs.actions.createPhysical(1, "small");
+    ecs.actions.setMassAndSize(FIRST_ENTITY, 10, "medium");
+    expect(ecs.selectEntityValues(ecs.archetypes.physical)).toEqual([
+      { id: FIRST_ENTITY, mass: 10, size: "medium" },
+    ]);
+  });
+  test("can call sequential actions and commit", () => {
+    const ecs = createECSWithMassAndSize();
+    ecs.actionSequences.setGravity(10).update(11).update(12).commit();
+    expect(ecs.resources.gravity).toBe(12);
+  });
+  test("can call sequential actions and cancel", () => {
+    const ecs = createECSWithMassAndSize();
+    ecs.actionSequences.setGravity(10).update(11).update(12).cancel();
+    expect(ecs.resources.gravity).toBe(9.8);
+  });
+  test("can execute sequential actions and commit", async () => {
+    const ecs = createECSWithMassAndSize();
+    expect(ecs.getTransientActionCount()).toBe(0)
+    await ecs.actions.setGravity(async function* () {
+      expect(ecs.getTransientActionCount()).toBe(0)
+      yield [10];
+      expect(ecs.resources.gravity).toBe(10); // in flight
+      expect(ecs.getTransientActionCount()).toBe(1)
+      yield [11];
+      expect(ecs.resources.gravity).toBe(11); // in flight
+      expect(ecs.getTransientActionCount()).toBe(1)
+      yield [12];
+      expect(ecs.resources.gravity).toBe(12); // in flight
+      expect(ecs.getTransientActionCount()).toBe(1)
+    });
+    expect(ecs.getTransientActionCount()).toBe(0)
+    expect(ecs.resources.gravity).toBe(12);
+  });
+  test("can execute sequential actions and throw an error which cancels", async () => {
+    const ecs = createECSWithMassAndSize();
+    let cleanup = false;
+    try {
+      await ecs.actions.setGravity(async function* () {
+        try {
+          yield [10];
+          yield [11];
+          yield [12];
+          throw new Error("test");
+        }
+        finally {
+          cleanup = true;
+        }
+      });
+    } catch (error) {
+      expect(cleanup).toBe(true);
+      expect(error).toBeInstanceOf(Error);
+      expect((error as any).message).toBe("test");
+    }
+    expect(ecs.resources.gravity).toBe(9.8);
+  });
+  test("can execute promise action and commit", async () => {
+    const ecs = createECSWithMassAndSize();
+    await ecs.actions.setGravity(async () => {
+      return [10];
+    });
+    expect(ecs.resources.gravity).toBe(10);
+  });
+  test("can use apply directly", () => {
+    const ecs = createECSWithMassAndSize();
+    const time = Date.now();
+    ecs.apply({
+      type: "commit",
+      createdTime: time,
+      createdBy: user,
+      name: "createPhysical",
+      args: [1, "small"],
+    });
+    expect(ecs.selectEntityValues(ecs.archetypes.physical)).toEqual([
+      { id: FIRST_ENTITY, mass: 1, size: "small" },
+    ]);
+  });
+  test("can resolve out of order apply calls", () => {
+    const ecs = createECSWithMassAndSize();
+    const time = Date.now();
+    //  this later one is applied first
+    ecs.apply({
+      type: "commit",
+      createdTime: time + 1,
+      createdBy: user,
+      name: "createPhysical",
+      args: [5, "large"],
+    });
+    //  this earlier one is applied second
+    ecs.apply({
+      type: "commit",
+      createdTime: time,
+      createdBy: user,
+      name: "createPhysical",
+      args: [1, "small"],
+    });
+    //  the entities are sorted and reapplied by updatedTime
+    expect(ecs.selectEntityValues(ecs.archetypes.physical)).toEqual([
+      { id: FIRST_ENTITY, mass: 1, size: "small" },
+      { id: FIRST_ENTITY + 1, mass: 5, size: "large" },
+    ]);
+  });
+  test("with subsequent updates, created order is still retained", () => {
+    //  we *could* change order later to use an updatedTime for final ordering
+    //  but would still have to roll back apply calls based on last ordering
+    const ecs = createECSWithMassAndSize();
+    const time = Date.now();
+    ecs.apply({
+      type: "transient",
+      createdTime: time,
+      createdBy: user,
+      name: "createPhysical",
+      args: [1, "small"],
+    });
+    ecs.apply({
+      type: "commit",
+      createdTime: time + 1,
+      createdBy: user,
+      name: "createPhysical",
+      args: [2, "medium"],
+    });
+    ecs.apply({
+      type: "transient",
+      createdTime: time,
+      createdBy: user,
+      name: "createPhysical",
+      args: [5, "large"],
+    });
+    ecs.apply({
+      type: "transient",
+      createdTime: time,
+      createdBy: user,
+      name: "createPhysical",
+      args: [10, "large"],
+    });
+    expect(ecs.selectEntityValues(ecs.archetypes.physical)).toEqual([
+      { id: FIRST_ENTITY, mass: 10, size: "large" },
+      { id: FIRST_ENTITY + 1, mass: 2, size: "medium" },
+    ]);
+  });
+  test("can observe actions", () => {
+    const ecs = createECSWithMassAndSize();
+    const actions: ActionFor<ECSType>[] = [];
+    ecs.observe.actions((action) => actions.push(action));
+    ecs.actions.createPhysical(1, "small");
+    ecs.actions.createPhysical(5, "large");
+    expect(actions).toEqual([
+      {
+        type: "commit",
+        createdTime: expect.any(Number),
+        createdBy: user,
+        name: "createPhysical",
+        args: [1, "small"],
+      },
+      {
+        type: "commit",
+        createdTime: expect.any(Number),
+        createdBy: user,
+        name: "createPhysical",
+        args: [5, "large"],
+      },
+    ]);
+  });
+});
+
+// sample ECS creation
+const Vector3Schema = Tuple(F32Schema, 3);
+const Vector4Schema = Tuple(F32Schema, 4);
+type Vector3 = FromSchema<typeof Vector3Schema>;
+type Vector4 = FromSchema<typeof Vector4Schema>;
+
+//  create an action ecs
+const ecs = createActionECS()
+  //  define components with schemas
+  .withComponents({
+    position: Vector3Schema,
+    velocity: Vector3Schema,
+    color: Vector4Schema,
+    size: { type: "number" },
+    health: { type: "number" },
+    player: { const: true },
+  } as const)
+  //  define archetypes with component names
+  .withArchetypes({
+    particle: ["position", "velocity", "color", "size"],
+    player: ["position", "health", "player"],
+  })
+  //  define resources with initial values
+  .withResources({
+    gravity: 9.8,
+  })
+  //  define actions with transactional functions
+  .withActions({
+    createParticle(t, props: { position: Vector3, velocity: Vector3, color: Vector4, size: number }) {
+      t.createEntity(t.ecs.archetypes.particle, props);
+    },
+    deleteParticle(t, entity: number) {
+      t.deleteEntity(entity);
+    },
+    createPlayer(t, position: Vector3) {
+      t.createEntity(t.ecs.archetypes.player, { position, health: 100, player: true });
+    },
+    movePlayer(t, entity: number, position: Vector3) {
+      t.setComponentValue(entity, "position", position);
+    },
+    setGravity(t, gravity: number) {
+      t.resources.gravity = gravity;
+    },
+  })
+
+//  call some actions to modify the ECS
+ecs.actions.createParticle({ position: [0, 0, 0], velocity: [0, 0, 0], color: [1, 0, 0, 0], size: 1 });
+ecs.actions.createParticle({ position: [1, 1, 1], velocity: [1, 1, 1], color: [1, 1, 1, 1], size: 2 });
+ecs.actions.createPlayer([10, 20, 0]);
+//  read out the player entity
+const playerEntity = ecs.selectEntities(ecs.archetypes.player)[0];
+ecs.actions.movePlayer(playerEntity, [10, 20, 0]);
+
+//  read some values from the ECS
+const particles = ecs.selectEntities(ecs.archetypes.particle);
+
+//  observe changes to the ECS
+ecs.observe.archetypeEntities(ecs.archetypes.player)((playerEntities) => {
+  for (const playerEntity of playerEntities) {
+    const player = ecs.getEntityValues(playerEntity);
+    // console.log("Player entity changed", player);
+  }
+});
+
+
+{
+  //  some type checks.
+  const ecs = createActionECS()
+    .withComponents({
+      position: { type: "string" },
+    } as const)
+    .withComponents({
+      size: { type: "number" },
+    } as const)
+    .withResources({
+      gravity: 9.8,
+    })
+    .withResources({
+      time: 0,
+    })
+    .withArchetypes({
+      position_size: ["id", "position", "size"],
+      position: ["id", "position"],
+    })
+
+  type Components = typeof ecs extends ActionECS<infer C, any, any> ? C : never;
+  type CheckComponents = True<EquivalentTypes<Components, {
+    id: number;
+    position: string;
+    size: number;
+  }>>;
+  type Resources = typeof ecs extends ActionECS<any, any, infer R> ? R : never;
+  type CheckResources = True<EquivalentTypes<Resources, { gravity: number; time: number }>>;
+
+  type Archetypes = typeof ecs extends ActionECS<any, infer A, any> ? A : never;
+  type CheckArchetypes = True<EquivalentTypes<Archetypes, {
+    position_size: Archetype<{ size: number; id: number; position: string; }>;
+    position: Archetype<{ id: number; position: string; }>;
+  }>>;
+
+}