@adobe/data 0.1.2 → 0.2.0

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

@@ -0,0 +1,189 @@
+/*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 { Simplify } from "../../types/types.js";
+import { CoreComponents, ECSJSON, Table } from "../core-ecs/core-ecs-types.js";
+import {
+  EntityCreateValues,
+  Entity,
+  EntityValues,
+  EntityUpdateValues,
+} from "../core-ecs/core-ecs-types.js";
+
+export type ECSComponents = CoreComponents;
+
+/**
+ * Represents a runtime handle to an ECS Archetype.
+ * An archetype represents a set of components that are required to be present on an entity.
+ * These instances cannot be created directly or persisted but are returned from the ECS API.
+ */
+export interface Archetype<EntityType = any> {
+  readonly components: readonly (keyof EntityType)[];
+}
+
+export type ECSResources = {};
+
+export type TypeFromComponents<
+  C extends ECSComponents,
+  T extends (keyof C)[],
+> = { [K in T[number]]: C[K] };
+
+export type ECSArchetypes = {};
+
+/**
+ * Comparison operators for declarative where clauses
+ */
+type ComparisonOperator = "==" | "!=" | "<" | ">" | ">=" | "<=";
+
+/**
+ * Represents a comparison operation in a declarative where clause
+ */
+type ComparisonOperation<T> = {
+  [P in ComparisonOperator]?: T;
+};
+
+/**
+ * Represents a condition that can be either a direct value, comparison operation, or nested conditions
+ */
+type WhereCondition<T> = T extends object
+  ? { [K in keyof T]?: WhereCondition<T[K]> } | ComparisonOperation<T>
+  : T | ComparisonOperation<T>;
+
+/**
+ * Declarative where clause structure that allows for JSON-based filtering
+ * Each key in the object represents a component field to filter on
+ * The value can either be a direct value (equality check), a comparison operation, or nested conditions
+ */
+export type WhereClause<T extends CoreComponents> = {
+  [K in keyof T]?: WhereCondition<T[K]>;
+};
+
+type SelectOrder<T extends CoreComponents> = { [K in keyof T]?: boolean };
+export type SelectOptions<C extends CoreComponents, T extends CoreComponents> = {
+  /**
+   * Order results by the given components ascending or descending.
+   */
+  order?: SelectOrder<T>;
+  /**
+   * Components to include in the results.
+   */
+  components?: (keyof T)[];
+  /**
+   * Do not return any rows for entities that contain these components.
+   */
+  without?: (keyof C)[];
+  /**
+   * Filter the results by the given condition using a declarative where clause.
+   */
+  where?: WhereClause<T>;
+}
+
+/**
+ * An Entity Component System (ECS) is a data structure that stores entities and their components.
+ * This interface is used for low level ECS instances that allow fast, direct read and write access.
+ */
+export interface ECS<
+  C extends ECSComponents = ECSComponents, //  name => Component Value Type
+  A extends ECSArchetypes = ECSArchetypes, //  name => Archetype
+  R extends ECSResources = ECSResources, //  name => Resource Value Type
+> extends ECSWrite<C> {
+  components: { readonly [K in keyof C]: Schema };
+  archetypes: A;
+  resources: { -readonly [K in keyof R]: R[K] };
+
+  withComponents<
+    S extends { [K: string]: Schema },
+    T = { [K in keyof S]: FromSchema<S[K]> },
+  >(
+    components: S
+  ): ECS<Simplify<C & T>, A, R>;
+  withArchetypes<S extends { [K: string]: ReadonlyArray<keyof C> }>(
+    archetypes: S
+  ): ECS<
+    C,
+    Simplify<A & { -readonly [AN in keyof S]: Archetype<{ [PN in S[AN][number]]: C[PN] }> }>,
+    R
+  >;
+  withResources<S extends { [K: string]: Data }>(
+    resources: S
+  ): ECS<C, A, Simplify<R & S>>;
+
+  getComponentValue<Name extends keyof C>(
+    id: Entity,
+    component: Name
+  ): C[Name] | undefined;
+  getArchetype<AC extends (keyof C)[]>(
+    ...components: AC
+  ): Archetype<TypeFromComponents<C, AC>>;
+  getEntityArchetype(id: Entity): Archetype;
+  /**
+   * @returns
+   *  The entity values if this entity contains all of the archetype components.
+   *  Null if the entity exists but does not contain all of the archetype components.
+   *  Undefined if the entity does not exist.
+   */
+  getEntityValues<A>(id: Entity, archetype: Archetype<A>): A & Partial<EntityValues<C>> | null | undefined;
+  /**
+   * @returns The entity values if this entity exists otherwise undefined.
+   */
+  getEntityValues(id: Entity): EntityValues<C> | undefined;
+
+  countEntities<T extends CoreComponents>(archetype: Archetype<T>): number;
+  selectEntities<T extends CoreComponents, P extends Partial<T>>(archetype: Archetype<T>, options?: Omit<SelectOptions<C, T>, "components">): Entity[];
+  getTables(): Table[];
+  getTables<T>(
+    archetype: Archetype<T>,
+    options: { mode: "read" | "write"; exact?: boolean }
+  ): Table<T>[];
+
+  selectEntityValues<T extends CoreComponents, P extends Partial<T>>(archetype: Archetype<T>, options: SelectOptions<C, T>): P[];
+  selectEntityValues<T extends CoreComponents>(archetype: Archetype<T>): Simplify<T & EntityValues<C>>[];
+
+  createBatch<T>(archetype: Archetype<T>, count: number): Table<T>;
+
+  toJSON(): ECSJSON;
+}
+
+export interface ECSWrite<
+  C extends ECSComponents, //  name => Component Value Type
+> {
+  /**
+   * 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;
+  createEntity(): Entity;
+  createEntity<T>(
+    archetype: Archetype<T>,
+    values: EntityCreateValues<T>
+  ): Entity;
+  updateEntity(id: Entity, values: EntityUpdateValues<C>): void;
+  deleteEntity(id: Entity): void;
+}

package/src/old-ecs/ecs/ecs-where-functions.ts

@@ -0,0 +1,95 @@
+/*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 { EntityValues, CoreComponents } from "../core-ecs/core-ecs-types.js";
+import { WhereClause } from "./ecs-types.js";
+
+/**
+ * Converts a declarative where clause to a predicate function
+ */
+export function whereClauseToPredicate<T extends CoreComponents>(whereClause: WhereClause<T>): (entity: EntityValues<T>) => boolean {
+  // Helper function to get nested value
+  function getNestedValue(obj: any, path: string[]): any {
+    return path.reduce((current, key) => current && current[key], obj);
+  }
+
+  // Helper function to check conditions recursively
+  function checkCondition(value: any, condition: any): boolean {
+    // If condition is a direct value, check for equality
+    if (typeof condition !== 'object' || condition === null) {
+      return value === condition;
+    }
+
+    // If condition is an object but not a comparison operation, it's a nested path
+    if (!('==' in condition || '!=' in condition || '<' in condition || '>' in condition || '<=' in condition || '>=' in condition)) {
+      // Recursively check all nested conditions
+      return Object.entries(condition).every(([key, subCondition]) =>
+        checkCondition(value[key], subCondition)
+      );
+    }
+
+    // Handle comparison operations
+    for (const [op, compareValue] of Object.entries(condition)) {
+      switch (op) {
+        case "==":
+          if (value !== compareValue) return false;
+          break;
+        case "!=":
+          if (value === compareValue) return false;
+          break;
+        case "<":
+          if (typeof value === 'number' && typeof compareValue === 'number') {
+            if (!(value < compareValue)) return false;
+          }
+          break;
+        case ">":
+          if (typeof value === 'number' && typeof compareValue === 'number') {
+            if (!(value > compareValue)) return false;
+          }
+          break;
+        case "<=":
+          if (typeof value === 'number' && typeof compareValue === 'number') {
+            if (!(value <= compareValue)) return false;
+          }
+          break;
+        case ">=":
+          if (typeof value === 'number' && typeof compareValue === 'number') {
+            if (!(value >= compareValue)) return false;
+          }
+          break;
+      }
+    }
+    return true;
+  }
+
+  return (entity: EntityValues<T>) => {
+    for (const [key, condition] of Object.entries(whereClause)) {
+      const fieldKey = key as keyof T;
+      const value = entity[fieldKey];
+
+      if (!checkCondition(value, condition)) {
+        return false;
+      }
+    }
+    return true;
+  };
+}