@adobe/data 0.1.3 → 0.2.1

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

@@ -0,0 +1,274 @@
+/*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 { isAsyncGenerator } from "../../internal/async-generator/is-async-generator.js";
+import { createObservableEvent } from "../../observe/create-observable-event.js";
+import { SequentialActionResult } from "./sequential-action.js";
+import {
+  ECSArchetypes,
+  ECSComponents,
+  ECSResources,
+} from "../ecs/ecs-types.js";
+import { createTransactionECS } from "../transaction-ecs/transaction-ecs.js";
+import {
+  TransactionCommit,
+  TransactionECS,
+} from "../transaction-ecs/transaction-types.js";
+import {
+  Action,
+  ActionECS,
+  AsyncArgsProvider,
+  ECSActionFunctions,
+  ToActionFunction,
+  compareActionOrder,
+  isSameAction,
+} from "./action-types.js";
+
+let lastTime = 0;
+function uniqueTime() {
+  const currentTime = Date.now();
+  lastTime = Math.max(currentTime, lastTime + 1);
+  return lastTime;
+}
+
+interface AppliedActions<
+  C extends ECSComponents = any,
+  F extends ECSActionFunctions = any,
+> {
+  action: Action<F>;
+  commit: TransactionCommit<C>;
+}
+
+export function createActionECS<
+  C extends ECSComponents,
+  A extends ECSArchetypes,
+  R extends ECSResources,
+  F extends ECSActionFunctions = {},
+>(
+  options: {
+    ecs?: TransactionECS<C, A, R>,
+    /**
+     * A unique user identifier for the current user.
+     */
+    user?: string;
+    /**
+     * A function which returns a unique, increasing time in UTC milliseconds.
+     * The function cannot return the same value twice but must increment if needed.
+     */
+    getUniqueTimeMs?: () => number;
+    /**
+     * Maximum time in milliseconds to wait for applied actions to be reordered.
+     */
+    maxSynchronizeDurationMs?: number;
+  } = {}
+): ActionECS<C, A, R, F> {
+  const {
+    ecs = createTransactionECS(),
+    getUniqueTimeMs = uniqueTime,
+    user = "",
+    maxSynchronizeDurationMs = 5000,
+  } = options;
+  const {
+    createTransaction,
+    observe,
+    withComponents,
+    withArchetypes,
+    withResources,
+    ...rest
+  } = ecs;
+  const transactionFunctions = {} as any;
+  const actions = {} as any;
+  const actionSequences = {} as any;
+
+  //  these are only stored in memory.
+  const applied: AppliedActions<C, F>[] = [];
+
+  const getInsertIndex = (action: Action<F>): number => {
+    for (let i = applied.length - 1; i >= 0; i--) {
+      if (isSameAction(action, applied[i].action)) {
+        return i;
+      }
+      const sort = compareActionOrder(action, applied[i].action);
+      if (sort >= 0) {
+        return i + 1;
+      }
+    }
+    return 0;
+  };
+
+  const [observeActions, notifyActions] = createObservableEvent<Action<F>>();
+
+  const apply = (newAction: Action<F>): void => {
+    const index = getInsertIndex(newAction);
+    const actionAtIndex = applied[index]?.action;
+    const isSame = actionAtIndex && isSameAction(newAction, actionAtIndex);
+    const mainTransaction = ecs.createTransaction({ undoable: false, createdBy: newAction.createdBy, createdTime: newAction.createdTime });
+    for (let i = applied.length - 1; i >= index && i < applied.length; i--) {
+      mainTransaction.batch(applied[i].commit.undoOperations);
+    }
+    applied.splice(index, isSame ? 1 : 0, { action: newAction, commit: undefined as any });
+    for (let i = index; i < applied.length; i++) {
+      const oldAction = applied[i];
+      if (!oldAction) {
+        console.error(`Missing applied action. Shouldn't happen. Notify codeowner!`, { index, i, newAction, applied });
+        continue;
+      }
+      const { action: reapplyAction } = oldAction;
+      if (reapplyAction.type !== "cancel") {
+        const childTransaction = mainTransaction.createTransaction();
+        transactionFunctions[reapplyAction.name](childTransaction, ...reapplyAction.args);
+        oldAction.commit = childTransaction.commit();
+      }
+    }
+    mainTransaction.commit();
+    //  notify action observers
+    notifyActions(newAction);
+    pruneOldActions(newAction.createdTime);
+  };
+
+  const pruneOldActions = (currentTime: number) => {
+    const canPrune = (action: Action<F>) =>
+      action.type !== "transient" &&
+      action.createdTime < currentTime - maxSynchronizeDurationMs;
+    //  remove any actions which are no longer needed because they are older than the maxSynchronizeDurationMs
+    while (applied.length > 0 && canPrune(applied[0].action)) {
+      applied.shift();
+    }
+  };
+
+  /**
+   * Implements async execution of actions.
+   * If the argProvider is an async generator, then the action is executed as a sequence.
+   * If the argProvider is a promise, then the action is executed directly once awaited.
+   */
+  const execute = async <K extends keyof F>(action: K, argProvider: AsyncArgsProvider<Parameters<ToActionFunction<F[K]>>>): Promise<void> => {
+    const argsGeneratorOrPromise = await argProvider();
+    if (isAsyncGenerator(argsGeneratorOrPromise)) {
+      let sequence: SequentialActionResult<any> | undefined;
+      try {
+        for await (const args of argsGeneratorOrPromise) {
+          sequence = sequence?.update(...args) ?? actionSequences[action](...args);
+        }
+        sequence?.commit();
+      }
+      catch (e) {
+        // cancel the sequence
+        sequence?.cancel();
+        // rethrow the error
+        throw e;
+      }
+    } else {
+      // args is still a promise so we must await it.
+      const args = await argsGeneratorOrPromise;
+      actions[action](...args);
+    }
+  }
+
+  const getTransientActionCount = () => {
+    return applied.reduce((acc, a) => acc + (a.action.type === "transient" ? 1 : 0), 0);
+  }
+
+  const actionECS = {
+    ...rest,
+    apply,
+    getTransientActionCount,
+    actions,
+    actionSequences,
+    withComponents: (newComponents: any) => {
+      withComponents(newComponents);
+      return actionECS as any;
+    },
+    withArchetypes: (newArchetypes: any) => {
+      withArchetypes(newArchetypes);
+      return actionECS as any;
+    },
+    withResources: (newResources: any) => {
+      withResources(newResources);
+      return actionECS as any;
+    },
+    withActions: <S>(newTransactionFunctions: S): any => {
+      for (const name in newTransactionFunctions) {
+        const action = newTransactionFunctions[name];
+        if (transactionFunctions[name]) {
+          throw new Error(`Action already exists: ${name}`);
+        }
+        transactionFunctions[name] = action;
+        actions[name] = (...args: any) => {
+          const firstArg = args[0];
+          // handle new async execution pattern.
+          if (typeof firstArg === "function") {
+            return execute(name, firstArg as any);
+          }
+
+          const createdTime = getUniqueTimeMs();
+          apply({ type: "commit", createdTime, createdBy: user, name, args });
+        };
+        actionSequences[name] = (...originalArgs: any) => {
+          const createdTime = getUniqueTimeMs();
+          if (typeof originalArgs[0] === "function") {
+            throw new Error("Cannot use a function as argument to a sequence. For async execution you want to use ecs.actions instead of ecs.actionSequences.");
+          }
+          let args = originalArgs;
+          const sequence = {
+            update: (...updateArgs: any) => {
+              args = updateArgs;
+              apply({
+                type: "transient",
+                createdTime,
+                createdBy: user,
+                name,
+                args,
+              });
+              return sequence;
+            },
+            commit: () => {
+              apply({
+                type: "commit",
+                createdTime,
+                createdBy: user,
+                name,
+                args,
+              });
+            },
+            cancel: () => {
+              apply({
+                type: "cancel",
+                createdTime,
+                createdBy: user,
+                name,
+                args,
+              });
+            },
+          };
+          sequence.update(...originalArgs);
+          return sequence;
+        };
+      }
+      return actionECS as any;
+    },
+    observe: {
+      ...observe,
+      actions: observeActions,
+    },
+  };
+
+  return actionECS;
+}

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

@@ -0,0 +1,178 @@
+/*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 { FromSchema, Schema } from "../../schema/schema.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 "../entity.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 = {}, //  name => Action Function
+> 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, //  name => Action Function
+> = 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, //  name => Action Function
+> = {
+  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 function compareActionOrder(a: Action, b: Action): number {
+  if (a.createdTime !== b.createdTime) {
+    return a.createdTime - b.createdTime;
+  }
+  return a.createdBy.localeCompare(b.createdBy, undefined, {
+    sensitivity: "variant",
+  });
+}
+
+export function isSameAction(a: Action, b: Action): boolean {
+  return a.createdTime === b.createdTime && a.createdBy === b.createdBy;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- any arg is allowed within action function
+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, //  name => Action Function
+> = (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;
+};

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

@@ -0,0 +1,29 @@
+/*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";
+export {
+  type ActionECS,
+  type Action,
+  type ActionSequence,
+  type ActionFor,
+} from "./action-types.js";
+export * from "./sequential-action.js";

package/{service/sequential-action.js → src/old-ecs/action-ecs/sequential-action.ts}

@@ -19,13 +19,29 @@ 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 '../../data.js';
+
+export type SequentialActionResult<Args extends Data[]> = {
+    update: (...args: Args) => SequentialActionResult<Args>;
+    cancel: () => void;
+    commit: () => void;
+};
+
+/**
+ * A function that represents a transient, sequential series of actions that must end with a commit or cancel.
+ * This is the only service action which can return a value other than void.
+ * It is intended to be used for multiframe transactions.
+ */
+export type SequentialAction<Args extends Data[]> = (...args: Args) => SequentialActionResult<Args>;
+
 /**
  * Executes a sequential action using an async iterable iterator that provides the arguments.
  * @param action - The action to execute.
  * @param argProvider - An async iterable iterator of arguments to pass to the action.
  */
-export async function executeSequentialAction(action, argProvider) {
-    let sequence;
+export async function executeSequentialAction<Arg extends Data>(action: SequentialAction<[Arg]>, argProvider: AsyncIterableIterator<Arg>) {
+    let sequence: SequentialActionResult<[Arg]> | undefined;
     try {
         //  get the next arguments from the arg provider
         for await (const arg of argProvider) {
@@ -41,5 +57,4 @@ export async function executeSequentialAction(action, argProvider) {
         //  allow the async iterable iterator to finalize and close any open resources
         argProvider.throw?.(e);
     }
-}
-//# sourceMappingURL=sequential-action.js.map
+}