@adobe/data 0.2.1 → 0.2.3

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

@@ -1,274 +0,0 @@
-/*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

@@ -1,178 +0,0 @@
-/*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

@@ -1,29 +0,0 @@
-/*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/src/old-ecs/action-ecs/sequential-action.ts

@@ -1,60 +0,0 @@
-/*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 '../../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<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) {
-            //  then write them into the multiframe transaction (persisting this set of updates into database)
-            sequence = (sequence?.update ?? action)(arg);
-        }
-        //  everything succeeded, finalize this transaction.
-        sequence?.commit();
-    }
-    catch (e) {
-        //  cancel the sequence
-        sequence?.cancel();
-        //  allow the async iterable iterator to finalize and close any open resources
-        argProvider.throw?.(e);
-    }
-}