@adobe/data 0.1.2 → 0.2.0

package/src/old-ecs/transaction-ecs/transaction-ecs.ts

@@ -0,0 +1,283 @@
+/*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 { Data } from "../../index.js";
+import { FromSchema, Schema } from "../../schema/schema.js";
+import {
+  Archetype,
+  ECS,
+  ECSArchetypes,
+  ECSComponents,
+  ECSResources,
+  SelectOptions,
+} from "../ecs/ecs-types.js";
+import { createECS } from "../ecs/ecs.js";
+import {
+  CoreComponents,
+  Entity,
+  EntityValues,
+} from "../core-ecs/core-ecs-types.js";
+import {
+  Transaction,
+  TransactionChanges,
+  TransactionCommit,
+  TransactionECS,
+  TransactionOptions,
+} from "./transaction-types.js";
+import { createECSTransaction } from "./transactions.js";
+import { Observe } from "../../observe/types.js";
+import { equalsShallow } from "../../equals-shallow.js";
+
+//  we want to cache this a well on each array.
+function isASubsetOfB(a: readonly any[], b: readonly any[]) {
+  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<
+  C extends ECSComponents, //  name => Component Value Type
+  A extends ECSArchetypes, //  name => Entity Values Type
+  R extends ECSResources, //  name => Resource Value Type
+>(ecs: ECS<C, A, R> = createECS()): TransactionECS<C, A, R> {
+  const { components, archetypes, resources, ...rest } = ecs;
+  const withComponents = <
+    S extends { [K: string]: Schema },
+    T = { [K in keyof S]: FromSchema<S[K]> },
+  >(
+    newComponents: S
+  ): any => {
+    ecs.withComponents(newComponents);
+    return tecs as any;
+  };
+  const withArchetypes = <S extends { [K: string]: ReadonlyArray<keyof C> }>(
+    newArchetypes: S
+  ): any => {
+    ecs.withArchetypes(newArchetypes);
+    return tecs as any;
+  };
+  const withResources = <S extends { [K: string]: Data }>(
+    newResources: S
+  ): any => {
+    ecs.withResources(newResources);
+    return tecs as any;
+  };
+  const transactionObservers = new Set<
+    (transaction: TransactionCommit<C>) => void
+  >();
+  const notifyTransactions = (
+    transaction: TransactionCommit<C>,
+    changed: TransactionChanges<C>
+  ) => {
+    //  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<() => void>();
+    const addObservers = <K>(map: Map<K, Set<() => void>>, key: K) => {
+      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: (transaction: TransactionCommit<C>) => void
+  ) => {
+    transactionObservers.add(callback);
+    return () => transactionObservers.delete(callback);
+  };
+  const createTransaction = (
+    options?: TransactionOptions
+  ): Transaction<C, A, R> => {
+    return createECSTransaction(
+      tecs,
+      ecs,
+      { undoable: true, createdTime: Date.now(), createdBy: "", ...options },
+      notifyTransactions
+    );
+  };
+  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);
+    };
+  };
+  const entityObservers = new Map<Entity, Set<() => void>>();
+  const observeEntityChanges = (entity: Entity) => (callback: () => void) => {
+    return addToMapSet(entity, entityObservers, callback);
+  };
+  function observeEntityValues<K extends keyof A>(
+    id: Entity,
+    archetype: Archetype<K> & Partial<EntityValues<C>>
+  ): Observe<A[K] | null | undefined>;
+  function observeEntityValues(
+    id: Entity
+  ): Observe<EntityValues<C> | undefined>;
+  function observeEntityValues<A>(
+    id: Entity,
+    archetype?: Archetype<A> & Partial<EntityValues<C>>
+  ) {
+    return (callback: (value: A | null | undefined) => void) => {
+      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<keyof C, Set<() => void>>();
+  const resourceObservables = new Map<keyof R, Observe<R[keyof R]>>();
+
+  const observeResource = <K extends keyof R>(key: K) => {
+    // Return cached observable if it exists
+    const cached = resourceObservables.get(key);
+    if (cached) {
+      return cached as Observe<R[K]>;
+    }
+
+    // Create new observable
+    const observable = (callback: (value: R[K]) => void) => {
+      const notify = () => {
+        callback(resources[key]);
+      };
+      //  callback immediately to get the current value.
+      notify();
+      //  callback again whenever the resource changes.
+      const resourceChanges = observeComponent(key as keyof C);
+      return resourceChanges(notify);
+    };
+
+    // Cache the observable
+    resourceObservables.set(key, observable);
+    return observable;
+  };
+
+  const observeComponent =
+    <K extends keyof C>(component: K) =>
+      (callback: () => void) => {
+        return addToMapSet(component, componentObservers, callback);
+      };
+  const archetypeObservers = new Map<Archetype<unknown>, Set<() => void>>();
+  const observeArchetypeChanges =
+    <A extends CoreComponents>(archetype: Archetype<A>) =>
+      (callback: () => void) => {
+        return addToMapSet(archetype, archetypeObservers, callback);
+      };
+
+  const observeArchetypeEntities = <A extends CoreComponents>(
+    archetype: Archetype<A>,
+    options?: Omit<SelectOptions<C, A>, "components">
+  ): Observe<Entity[]> => {
+    return (callback) => {
+      let lastValue: Entity[] | undefined;
+      const notify = () => {
+        const newValue = ecs.selectEntities(archetype, options);
+        if (!lastValue || !equalsShallow(lastValue, newValue)) {
+          lastValue = newValue;
+          callback(newValue);
+        }
+      };
+      notify();
+      return observeArchetypeChanges(archetype)(notify);
+    };
+  };
+
+  const createResourceObserver = () => {
+    const handler = {
+      get(target: any, prop: string | symbol) {
+        if (typeof prop === 'string' && prop in resources) {
+          return observeResource(prop as keyof R);
+        }
+        return target[prop];
+      },
+      apply(target: any, thisArg: any, args: any[]) {
+        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,
+  } as const satisfies TransactionECS<C, A, R>;
+  return tecs;
+}

package/src/old-ecs/transaction-ecs/transaction-types.ts

@@ -0,0 +1,248 @@
+/*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 { Data } from "../../index.js";
+import { Observe } from "../../observe/types.js";
+import { FromSchema, Schema } from "../../schema/schema.js";
+import { Simplify } from "../../types/types.js";
+import {
+  EntityCreateValues,
+  Entity,
+  EntityValues,
+  EntityUpdateValues,
+  CoreComponents,
+} from "../core-ecs/core-ecs-types.js";
+import {
+  Archetype,
+  ECS,
+  ECSArchetypes,
+  ECSComponents,
+  ECSResources,
+  ECSWrite,
+  SelectOptions,
+} from "../ecs/ecs-types.js";
+
+export interface TransactionECS<
+  C extends ECSComponents, //  name => Component Value Type
+  A extends ECSArchetypes, //  name => Entity Values Type
+  R extends ECSResources, //  name => Resource Value Type
+> extends Pick<
+  ECS<C, A, R>,
+  | "components"
+  | "archetypes"
+  | "getComponentValue"
+  | "getArchetype"
+  | "getEntityValues"
+  | "countEntities"
+  | "selectEntities"
+  | "selectEntityValues"
+  | "toJSON"
+>,
+  TransactionProvider<C, A, R> {
+  resources: { +readonly [K in keyof R]: R[K] };
+
+  withComponents<
+    S extends { [K: string]: Schema },
+    T = { -readonly [K in keyof S]: FromSchema<S[K]> },
+  >(
+    components: S
+  ): TransactionECS<Simplify<C & T>, A, R>;
+  withArchetypes<S extends { [K: string]: ReadonlyArray<keyof C> }>(
+    archetypes: S
+  ): TransactionECS<
+    C,
+    Simplify<A & { [AN in keyof S]: Archetype<{ [PN in S[AN][number]]: C[PN] }> }>,
+    R
+  >;
+  withResources<S extends { [K: string]: Data }>(
+    resources: S
+  ): TransactionECS<C, A, Simplify<R & S>>;
+
+  observe: TransactionObservables<C, A, R>;
+}
+
+export interface TransactionObservables<
+  C extends ECSComponents = any, //  name => Component Value Type
+  A extends ECSArchetypes = any, //  name => Entity Values Type
+  R extends ECSResources = any, //  name => Resource Value Type
+> {
+  transactions: Observe<TransactionCommit<C>>;
+  resource: {
+    // function call resource (legacy)
+    <K extends keyof R>(key: K): Observe<R[K]>;
+  } & {
+    // property access resource (new)
+    [K in keyof R]: Observe<R[K]>;
+  };
+
+  entityValues<A extends Archetype>(
+    id: Entity,
+    archetype: A & Partial<EntityValues<C>>
+  ): Observe<EntityValuesFor<A> | null | undefined>;
+  entityValues(id: Entity): Observe<EntityValues<C> | undefined>;
+
+  entityChanges(entity: Entity): Observe<void>;
+  componentChanges<K extends keyof C>(component: K): Observe<void>;
+  archetypeChanges<A extends CoreComponents>(
+    archetype: Archetype<A>
+  ): Observe<void>;
+
+  archetypeEntities<A extends CoreComponents>(
+    archetype: Archetype<A>,
+    options?: Omit<SelectOptions<C, A>, "components">
+  ): Observe<Entity[]>;
+}
+
+/**
+ * Options when creating an ECSTransaction.
+ */
+export interface TransactionOptions {
+  /**
+   * Will this transaction be added to the undo stack?
+   * Defaults to true.
+   */
+  undoable?: boolean;
+  /**
+   * When was this transactions created in UTC time.
+   */
+  createdTime?: number;
+  /**
+   * The unique identifier for the user creating the transaction.
+   */
+  createdBy?: string;
+}
+
+interface TransactionProvider<
+  C extends ECSComponents, //  name => Component Value Type
+  A extends ECSArchetypes, //  name => Entity Values Type
+  R extends ECSResources, //  name => Resource Value Type
+> {
+  createTransaction(options?: TransactionOptions): Transaction<C, A, R>;
+}
+
+/**
+ * Type alias for a CreateOperation in the ECS (Entity Component System).
+ * Represents an operation to create a new entity with the specified components.
+ * @template C - Components used by the entity.
+ */
+export type TransactionCreateOperation<C> = {
+  type: "create";
+  values: EntityCreateValues<C>;
+};
+
+/**
+ * Type alias for an UpdateOperation in the ECS (Entity Component System).
+ * Represents an operation to update an existing entity with the specified components.
+ * @template C - Components used by the entity.
+ */
+export type TransactionUpdateOperation<C> = {
+  type: "update";
+  entity: Entity;
+  values: EntityUpdateValues<C>;
+};
+
+/**
+ * Type alias for a DeleteOperation in the ECS (Entity Component System).
+ * Represents an operation to delete an existing entity.
+ */
+export type TransactionDeleteOperation = { type: "delete"; entity: Entity };
+
+/**
+ * Type alias for a WriteOperation in the ECS (Entity Component System).
+ * Represents an operation to create, update, or delete an entity.
+ * @template C - Components used by the entity.
+ */
+export type TransactionWriteOperation<C> =
+  | TransactionCreateOperation<C>
+  | TransactionUpdateOperation<C>
+  | TransactionDeleteOperation;
+
+/**
+ * Represents a completed transaction in the ECS, which can either be a commit or a cancel.
+ * @template C - Components used in the transaction.
+ */
+export type TransactionComplete<C> = TransactionCommit<C> | TransactionCancel;
+
+/**
+ * Represents a committed transaction in the ECS.
+ * @template C - Components used in the transaction.
+ */
+export interface TransactionCommit<C> {
+  committed: true; // Indicates that the transaction has been committed
+  options: TransactionOptions; // Options for the transaction
+  redoOperations: TransactionWriteOperation<C>[]; // Operations to redo the transaction
+  undoOperations: TransactionWriteOperation<C>[]; // Operations to undo the transaction
+}
+
+/**
+ * Represents a cancelled transaction in the ECS.
+ */
+export interface TransactionCancel {
+  committed: false; // Indicates that the transaction has been cancelled
+  options: TransactionOptions; // Options for the transaction
+}
+
+export interface Transaction<
+  C extends ECSComponents, //  name => Component Value Type
+  A extends ECSArchetypes, //  name => Entity Values Type
+  R extends ECSResources, //  name => Resource Value Type
+> extends TransactionProvider<C, A, R>,
+  ECSWrite<C> {
+  readonly ecs: TransactionECS<C, A, R>;
+  readonly options: Required<TransactionOptions>;
+  readonly resources: { -readonly [K in keyof R]: R[K] };
+  batch(operations: TransactionWriteOperation<C>[]): this;
+  commit(): TransactionCommit<C>;
+  cancel(): TransactionCancel;
+}
+
+/**
+ * @internal
+ */
+export interface TransactionChanges<C extends ECSComponents> {
+  readonly entities: Set<Entity>;
+  readonly components: Set<keyof C>;
+  readonly archetypes: Set<Archetype>;
+}
+
+/**
+ * @internal
+ */
+export type TransactionCommitFor<ECS> =
+  ECS extends TransactionECS<infer C, infer A, infer R>
+  ? TransactionCommit<C>
+  : never;
+/**
+ * @internal
+ */
+export type TransactionFor<ECS> =
+  ECS extends TransactionECS<infer C, infer A, infer R>
+  ? Transaction<C, A, R>
+  : never;
+/**
+ * @internal
+ */
+export type EntityValuesFor<T> =
+  T extends TransactionECS<infer C, infer A, infer R>
+  ? EntityValues<C>
+  : T extends Archetype<infer E>
+  ? E
+  : never;