@0xobelisk/ecs 1.2.0-pre.24

package/dist/index.mjs

@@ -0,0 +1,2287 @@
+// src/utils.ts
+function extractEntityIds(connection, options) {
+  const { idFields = ["nodeId", "entityId"], composite = false } = options || {};
+  return connection.edges.map((edge) => {
+    const node = edge.node;
+    if (composite) {
+      const idParts = idFields.map((field) => node[field] || "").filter(Boolean);
+      return idParts.join("|");
+    } else {
+      for (const field of idFields) {
+        if (node[field] !== void 0 && node[field] !== null) {
+          return node[field];
+        }
+      }
+      return Object.values(node)[0] || "";
+    }
+  }).filter(Boolean);
+}
+function calculateDelta(oldResults, newResults) {
+  const oldSet = new Set(oldResults);
+  const newSet = new Set(newResults);
+  const added = newResults.filter((id) => !oldSet.has(id));
+  const removed = oldResults.filter((id) => !newSet.has(id));
+  return {
+    added,
+    removed,
+    current: newResults
+  };
+}
+function findEntityIntersection(entitySets) {
+  if (entitySets.length === 0)
+    return [];
+  if (entitySets.length === 1)
+    return entitySets[0];
+  return entitySets.reduce((intersection, currentSet) => {
+    const currentSetLookup = new Set(currentSet);
+    return intersection.filter((id) => currentSetLookup.has(id));
+  });
+}
+function findEntityUnion(entitySets) {
+  const unionSet = /* @__PURE__ */ new Set();
+  entitySets.forEach((set) => {
+    set.forEach((id) => unionSet.add(id));
+  });
+  return Array.from(unionSet);
+}
+function extractIntersectionFromBatchResult(batchResult, componentTypes, options) {
+  const entitySets = componentTypes.map((type) => {
+    const connection = batchResult[type];
+    return connection ? extractEntityIds(connection, options) : [];
+  });
+  return findEntityIntersection(entitySets);
+}
+function extractUnionFromBatchResult(batchResult, componentTypes, options) {
+  const entitySets = componentTypes.map((type) => {
+    const connection = batchResult[type];
+    return connection ? extractEntityIds(connection, options) : [];
+  });
+  return findEntityUnion(entitySets);
+}
+function debounce(func, waitMs) {
+  let timeoutId = null;
+  return (...args) => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      func(...args);
+      timeoutId = null;
+    }, waitMs);
+  };
+}
+function normalizeComponentType(componentType) {
+  const singular = componentType.endsWith("s") ? componentType.slice(0, -1) : componentType;
+  const plural = componentType.endsWith("s") ? componentType : componentType + "s";
+  return { singular, plural };
+}
+function createCacheKey(operation, componentTypes, options) {
+  const sortedTypes = [...componentTypes].sort();
+  const optionsStr = options ? JSON.stringify(options) : "";
+  return `${operation}:${sortedTypes.join(",")}:${optionsStr}`;
+}
+function isValidEntityId(entityId) {
+  return typeof entityId === "string" && entityId.length > 0;
+}
+function isValidComponentType(componentType) {
+  return typeof componentType === "string" && componentType.length > 0;
+}
+function deepEqual(obj1, obj2) {
+  if (obj1 === obj2)
+    return true;
+  if (obj1 == null || obj2 == null)
+    return false;
+  if (typeof obj1 !== typeof obj2)
+    return false;
+  if (typeof obj1 !== "object")
+    return false;
+  const keys1 = Object.keys(obj1);
+  const keys2 = Object.keys(obj2);
+  if (keys1.length !== keys2.length)
+    return false;
+  for (const key of keys1) {
+    if (!keys2.includes(key))
+      return false;
+    if (!deepEqual(obj1[key], obj2[key]))
+      return false;
+  }
+  return true;
+}
+function safeJsonParse(json, defaultValue) {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return defaultValue;
+  }
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return JSON.stringify(error);
+}
+function createTimestamp() {
+  return Date.now();
+}
+function limitArray(array, limit) {
+  return limit > 0 ? array.slice(0, limit) : array;
+}
+function paginateArray(array, page, pageSize) {
+  const startIndex = (page - 1) * pageSize;
+  const endIndex = startIndex + pageSize;
+  const items = array.slice(startIndex, endIndex);
+  return {
+    items,
+    totalCount: array.length,
+    hasMore: endIndex < array.length,
+    page,
+    pageSize
+  };
+}
+
+// src/query.ts
+var ECSQuery = class {
+  constructor(graphqlClient, componentDiscoverer) {
+    this.queryCache = /* @__PURE__ */ new Map();
+    this.cacheTimeout = 5e3;
+    // 5 second cache timeout
+    this.availableComponents = [];
+    this.componentDiscoverer = null;
+    // Component primary key cache - pre-parsed during initialization
+    this.componentPrimaryKeys = /* @__PURE__ */ new Map();
+    this.graphqlClient = graphqlClient;
+    this.componentDiscoverer = componentDiscoverer || null;
+  }
+  /**
+   * Set available component list
+   */
+  setAvailableComponents(componentTypes) {
+    this.availableComponents = componentTypes;
+  }
+  /**
+   * Pre-parse and cache all component primary key information
+   */
+  initializeComponentMetadata(componentMetadataList) {
+    this.componentPrimaryKeys.clear();
+    for (const metadata of componentMetadataList) {
+      if (metadata.primaryKeys.length === 1) {
+        this.componentPrimaryKeys.set(metadata.name, metadata.primaryKeys[0]);
+      }
+    }
+  }
+  /**
+   * Get component's primary key field name (quickly retrieve from cache)
+   */
+  getComponentPrimaryKeyField(componentType) {
+    return this.componentPrimaryKeys.get(componentType) || "entityId";
+  }
+  /**
+   * Set component discoverer
+   */
+  setComponentDiscoverer(discoverer) {
+    this.componentDiscoverer = discoverer;
+  }
+  /**
+   * Get component field information
+   */
+  async getComponentFields(componentType) {
+    if (this.componentDiscoverer) {
+      try {
+        const metadata = this.componentDiscoverer.getComponentMetadata(componentType);
+        if (metadata) {
+          return metadata.fields.map((field) => field.name);
+        }
+      } catch (error) {
+      }
+    }
+    throw new Error(
+      `Unable to get field information for component ${componentType}. Please explicitly specify fields in QueryOptions or ensure component discoverer is properly configured.`
+    );
+  }
+  /**
+   * Get component's primary key fields
+   */
+  async getComponentPrimaryKeys(componentType) {
+    if (this.componentDiscoverer) {
+      try {
+        const metadata = this.componentDiscoverer.getComponentMetadata(componentType);
+        if (metadata && metadata.primaryKeys.length > 0) {
+          return metadata.primaryKeys;
+        }
+      } catch (error) {
+      }
+    }
+    throw new Error(
+      `Unable to get primary key information for component ${componentType}. Please explicitly specify idFields in QueryOptions or ensure component discoverer is properly configured.`
+    );
+  }
+  /**
+   * Get fields to use for queries (priority: user specified > dubhe config auto-parsed)
+   */
+  async getQueryFields(componentType, userFields) {
+    if (userFields && userFields.length > 0) {
+      return userFields;
+    }
+    return this.getComponentFields(componentType);
+  }
+  /**
+   * Check if entity exists
+   */
+  async hasEntity(entityId) {
+    if (!isValidEntityId(entityId))
+      return false;
+    try {
+      const tables = await this.getAvailableComponents();
+      for (const table of tables) {
+        try {
+          const condition = this.buildEntityCondition(table, entityId);
+          const component = await this.graphqlClient.getTableByCondition(
+            table,
+            condition
+          );
+          if (component)
+            return true;
+        } catch (error) {
+        }
+      }
+      return false;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Get all entity IDs (collected from all component tables)
+   */
+  async getAllEntities() {
+    try {
+      const tables = await this.getAvailableComponents();
+      const queries = await Promise.all(
+        tables.map(async (table) => {
+          const fields = await this.getQueryFields(table);
+          const primaryKey = this.componentPrimaryKeys.get(table) || "entityId";
+          return {
+            key: table,
+            tableName: table,
+            params: {
+              fields,
+              filter: {}
+            },
+            primaryKey
+            // Use cached primary key information
+          };
+        })
+      );
+      const batchResult = await this.graphqlClient.batchQuery(
+        queries.map((q) => ({
+          key: q.key,
+          tableName: q.tableName,
+          params: q.params
+        }))
+      );
+      return extractUnionFromBatchResult(batchResult, tables, {
+        idFields: void 0,
+        // Let extractEntityIds auto-infer
+        composite: false
+      });
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get entity count
+   */
+  async getEntityCount() {
+    const entities = await this.getAllEntities();
+    return entities.length;
+  }
+  /**
+   * Check if entity has specific component
+   */
+  async hasComponent(entityId, componentType) {
+    if (!isValidEntityId(entityId) || !isValidComponentType(componentType)) {
+      return false;
+    }
+    if (!this.isECSComponent(componentType)) {
+      return false;
+    }
+    try {
+      const condition = this.buildEntityCondition(componentType, entityId);
+      const component = await this.graphqlClient.getTableByCondition(
+        componentType,
+        condition
+      );
+      return component !== null;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Get specific component data of entity
+   */
+  async getComponent(entityId, componentType) {
+    if (!isValidEntityId(entityId) || !isValidComponentType(componentType)) {
+      return null;
+    }
+    if (!this.isECSComponent(componentType)) {
+      return null;
+    }
+    try {
+      const condition = this.buildEntityCondition(componentType, entityId);
+      const component = await this.graphqlClient.getTableByCondition(
+        componentType,
+        condition
+      );
+      return component;
+    } catch (error) {
+      return null;
+    }
+  }
+  /**
+   * Get all component types that entity has
+   */
+  async getComponents(entityId) {
+    if (!isValidEntityId(entityId))
+      return [];
+    try {
+      const tables = await this.getAvailableComponents();
+      const componentTypes = [];
+      await Promise.all(
+        tables.map(async (table) => {
+          const hasComp = await this.hasComponent(entityId, table);
+          if (hasComp) {
+            componentTypes.push(table);
+          }
+        })
+      );
+      return componentTypes;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Validate if component type is ECS-compliant
+   */
+  isECSComponent(componentType) {
+    return this.availableComponents.includes(componentType);
+  }
+  /**
+   * Build entity query condition (using cached primary key field name)
+   */
+  buildEntityCondition(componentType, entityId) {
+    const primaryKeyField = this.componentPrimaryKeys.get(componentType);
+    if (primaryKeyField) {
+      return { [primaryKeyField]: entityId };
+    } else {
+      return { entityId };
+    }
+  }
+  /**
+   * Filter and validate component type list, keeping only ECS-compliant components
+   */
+  filterValidECSComponents(componentTypes) {
+    const validComponents = componentTypes.filter((componentType) => {
+      if (!isValidComponentType(componentType)) {
+        return false;
+      }
+      if (!this.isECSComponent(componentType)) {
+        return false;
+      }
+      return true;
+    });
+    return validComponents;
+  }
+  /**
+   * Query all entities that have a specific component
+   */
+  async queryWith(componentType, options) {
+    if (!isValidComponentType(componentType))
+      return [];
+    if (!this.isECSComponent(componentType)) {
+      return [];
+    }
+    const cacheKey = createCacheKey("queryWith", [componentType], options);
+    const cached = this.getCachedResult(cacheKey);
+    if (cached && options?.cache !== false)
+      return cached;
+    try {
+      const queryFields = await this.getQueryFields(
+        componentType,
+        options?.fields
+      );
+      const primaryKeys = await this.getComponentPrimaryKeys(componentType);
+      const connection = await this.graphqlClient.getAllTables(componentType, {
+        first: options?.limit,
+        fields: queryFields,
+        orderBy: options?.orderBy
+      });
+      const result = extractEntityIds(connection, {
+        idFields: options?.idFields || primaryKeys,
+        composite: options?.compositeId
+      });
+      this.setCachedResult(cacheKey, result);
+      return result;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Query entities that have all specified components (intersection)
+   */
+  async queryWithAll(componentTypes, options) {
+    if (componentTypes.length === 0)
+      return [];
+    if (componentTypes.length === 1)
+      return this.queryWith(componentTypes[0], options);
+    const validTypes = this.filterValidECSComponents(componentTypes);
+    if (validTypes.length === 0)
+      return [];
+    const cacheKey = createCacheKey("queryWithAll", validTypes, options);
+    const cached = this.getCachedResult(cacheKey);
+    if (cached && options?.cache !== false)
+      return cached;
+    try {
+      const queries = await Promise.all(
+        validTypes.map(async (type) => {
+          const queryFields = await this.getQueryFields(type, options?.fields);
+          return {
+            key: type,
+            tableName: type,
+            params: {
+              fields: queryFields,
+              first: options?.limit,
+              orderBy: options?.orderBy
+            }
+          };
+        })
+      );
+      const batchResult = await this.graphqlClient.batchQuery(queries);
+      let idFields = options?.idFields;
+      if (!idFields && validTypes.length > 0) {
+        try {
+          idFields = await this.getComponentPrimaryKeys(validTypes[0]);
+        } catch (error) {
+        }
+      }
+      const result = extractIntersectionFromBatchResult(
+        batchResult,
+        validTypes,
+        {
+          idFields,
+          composite: options?.compositeId
+        }
+      );
+      this.setCachedResult(cacheKey, result);
+      return result;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Query entities that have any of the specified components (union)
+   */
+  async queryWithAny(componentTypes, options) {
+    if (componentTypes.length === 0)
+      return [];
+    if (componentTypes.length === 1)
+      return this.queryWith(componentTypes[0], options);
+    const validTypes = this.filterValidECSComponents(componentTypes);
+    if (validTypes.length === 0)
+      return [];
+    const cacheKey = createCacheKey("queryWithAny", validTypes, options);
+    const cached = this.getCachedResult(cacheKey);
+    if (cached && options?.cache !== false)
+      return cached;
+    try {
+      const queries = await Promise.all(
+        validTypes.map(async (type) => {
+          const queryFields = await this.getQueryFields(type, options?.fields);
+          return {
+            key: type,
+            tableName: type,
+            params: {
+              fields: queryFields,
+              first: options?.limit,
+              orderBy: options?.orderBy
+            }
+          };
+        })
+      );
+      const batchResult = await this.graphqlClient.batchQuery(queries);
+      let idFields = options?.idFields;
+      if (!idFields && validTypes.length > 0) {
+        try {
+          idFields = await this.getComponentPrimaryKeys(validTypes[0]);
+        } catch (error) {
+        }
+      }
+      const result = extractUnionFromBatchResult(batchResult, validTypes, {
+        idFields,
+        composite: options?.compositeId
+      });
+      this.setCachedResult(cacheKey, result);
+      return result;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Query entities that have include components but not exclude components
+   */
+  async queryWithout(includeTypes, excludeTypes, options) {
+    if (includeTypes.length === 0)
+      return [];
+    const validIncludeTypes = this.filterValidECSComponents(includeTypes);
+    if (validIncludeTypes.length === 0)
+      return [];
+    const validExcludeTypes = this.filterValidECSComponents(excludeTypes);
+    try {
+      const includedEntities = await this.queryWithAll(
+        validIncludeTypes,
+        options
+      );
+      if (validExcludeTypes.length === 0)
+        return includedEntities;
+      const excludedEntities = await this.queryWithAny(validExcludeTypes);
+      const excludedSet = new Set(excludedEntities);
+      return includedEntities.filter((entityId) => !excludedSet.has(entityId));
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Query components based on conditions
+   */
+  async queryWhere(componentType, predicate, options) {
+    if (!isValidComponentType(componentType))
+      return [];
+    if (!this.isECSComponent(componentType)) {
+      return [];
+    }
+    try {
+      const queryFields = await this.getQueryFields(
+        componentType,
+        options?.fields
+      );
+      const primaryKeys = await this.getComponentPrimaryKeys(componentType);
+      const connection = await this.graphqlClient.getAllTables(componentType, {
+        filter: predicate,
+        first: options?.limit,
+        fields: queryFields,
+        orderBy: options?.orderBy
+      });
+      return extractEntityIds(connection, {
+        idFields: options?.idFields || primaryKeys,
+        composite: options?.compositeId
+      });
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Range query
+   */
+  async queryRange(componentType, field, min, max, options) {
+    if (!isValidComponentType(componentType))
+      return [];
+    if (!this.isECSComponent(componentType)) {
+      return [];
+    }
+    const predicate = {
+      [field]: {
+        greaterThanOrEqualTo: min,
+        lessThanOrEqualTo: max
+      }
+    };
+    return this.queryWhere(componentType, predicate, options);
+  }
+  /**
+   * Paginated query
+   */
+  async queryPaged(componentTypes, page, pageSize) {
+    try {
+      const allResults = componentTypes.length === 1 ? await this.queryWith(componentTypes[0]) : await this.queryWithAll(componentTypes);
+      return paginateArray(allResults, page, pageSize);
+    } catch (error) {
+      return {
+        items: [],
+        totalCount: 0,
+        hasMore: false,
+        page,
+        pageSize
+      };
+    }
+  }
+  /**
+   * Create query builder
+   */
+  query() {
+    return new ECSQueryBuilder(this);
+  }
+  /**
+   * Get cached result
+   */
+  getCachedResult(cacheKey) {
+    const cached = this.queryCache.get(cacheKey);
+    if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
+      return cached.result;
+    }
+    return null;
+  }
+  /**
+   * Set cached result
+   */
+  setCachedResult(cacheKey, result) {
+    this.queryCache.set(cacheKey, {
+      result,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Clean expired cache
+   */
+  cleanExpiredCache() {
+    const now = Date.now();
+    for (const [key, cached] of this.queryCache.entries()) {
+      if (now - cached.timestamp >= this.cacheTimeout) {
+        this.queryCache.delete(key);
+      }
+    }
+  }
+  /**
+   * Get available component list
+   */
+  async getAvailableComponents() {
+    if (this.availableComponents.length > 0) {
+      return this.availableComponents;
+    }
+    return [];
+  }
+  /**
+   * Dispose resources
+   */
+  dispose() {
+    this.queryCache.clear();
+  }
+};
+var ECSQueryBuilder = class {
+  constructor(ecsQuery) {
+    this.includeTypes = [];
+    this.excludeTypes = [];
+    this.whereConditions = [];
+    this.orderByOptions = [];
+    this.ecsQuery = ecsQuery;
+  }
+  with(...componentTypes) {
+    this.includeTypes.push(...componentTypes);
+    return this;
+  }
+  without(...componentTypes) {
+    this.excludeTypes.push(...componentTypes);
+    return this;
+  }
+  where(componentType, predicate) {
+    this.whereConditions.push({ componentType, predicate });
+    return this;
+  }
+  orderBy(componentType, field, direction = "ASC") {
+    this.orderByOptions.push({ componentType, field, direction });
+    return this;
+  }
+  limit(count) {
+    this.limitValue = count;
+    return this;
+  }
+  offset(count) {
+    this.offsetValue = count;
+    return this;
+  }
+  async execute() {
+    try {
+      const options = {
+        limit: this.limitValue,
+        offset: this.offsetValue,
+        orderBy: this.orderByOptions.map((order) => ({
+          field: order.field,
+          direction: order.direction
+        }))
+      };
+      if (this.whereConditions.length > 0) {
+        const filteredResults = [];
+        for (const condition of this.whereConditions) {
+          const result = await this.ecsQuery.queryWhere(
+            condition.componentType,
+            condition.predicate,
+            options
+          );
+          filteredResults.push(result);
+        }
+        const intersection = filteredResults.reduce((acc, current) => {
+          const currentSet = new Set(current);
+          return acc.filter((id) => currentSet.has(id));
+        });
+        return intersection;
+      }
+      if (this.excludeTypes.length > 0) {
+        return this.ecsQuery.queryWithout(
+          this.includeTypes,
+          this.excludeTypes,
+          options
+        );
+      } else {
+        return this.ecsQuery.queryWithAll(this.includeTypes, options);
+      }
+    } catch (error) {
+      return [];
+    }
+  }
+};
+
+// src/subscription.ts
+import { Observable } from "@apollo/client";
+import pluralize from "pluralize";
+var ECSSubscription = class {
+  constructor(graphqlClient, componentDiscoverer) {
+    this.subscriptions = /* @__PURE__ */ new Map();
+    this.queryWatchers = /* @__PURE__ */ new Map();
+    this.componentDiscoverer = null;
+    this.availableComponents = [];
+    // Component primary key cache - consistent with implementation in query.ts
+    this.componentPrimaryKeys = /* @__PURE__ */ new Map();
+    this.graphqlClient = graphqlClient;
+    this.componentDiscoverer = componentDiscoverer || null;
+  }
+  /**
+   * Set available component list
+   */
+  setAvailableComponents(componentTypes) {
+    this.availableComponents = componentTypes;
+  }
+  /**
+   * Pre-parse and cache all component primary key information (consistent with query.ts)
+   */
+  initializeComponentMetadata(componentMetadataList) {
+    this.componentPrimaryKeys.clear();
+    for (const metadata of componentMetadataList) {
+      if (metadata.primaryKeys.length === 1) {
+        this.componentPrimaryKeys.set(metadata.name, metadata.primaryKeys[0]);
+      }
+    }
+  }
+  /**
+   * Get component's primary key field name (quickly retrieve from cache, consistent with query.ts)
+   */
+  getComponentPrimaryKeyField(componentType) {
+    return this.componentPrimaryKeys.get(componentType) || "entityId";
+  }
+  /**
+   * Set component discoverer
+   */
+  setComponentDiscoverer(discoverer) {
+    this.componentDiscoverer = discoverer;
+  }
+  /**
+   * Validate if component type is ECS-compliant
+   */
+  isECSComponent(componentType) {
+    return this.availableComponents.includes(componentType);
+  }
+  /**
+   * Get component field information (intelligent parsing)
+   */
+  async getComponentFields(componentType) {
+    if (this.componentDiscoverer) {
+      try {
+        const metadata = this.componentDiscoverer.getComponentMetadata(componentType);
+        if (metadata) {
+          return metadata.fields.map((field) => field.name);
+        }
+      } catch (error) {
+      }
+    }
+    return ["createdAt", "updatedAt"];
+  }
+  /**
+   * Get fields to use for queries (priority: user specified > dubhe config auto-parsed > default fields)
+   */
+  async getQueryFields(componentType, userFields) {
+    if (userFields && userFields.length > 0) {
+      return userFields;
+    }
+    return this.getComponentFields(componentType);
+  }
+  /**
+   * Listen to component added events
+   */
+  onComponentAdded(componentType, options) {
+    if (!isValidComponentType(componentType)) {
+      return new Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    if (!this.isECSComponent(componentType)) {
+      return new Observable((observer) => {
+        observer.error(
+          new Error(
+            `Component type ${componentType} is not ECS-compliant or not available`
+          )
+        );
+      });
+    }
+    return new Observable((observer) => {
+      let subscription = null;
+      this.getQueryFields(componentType, options?.fields).then((subscriptionFields) => {
+        const debouncedEmit = options?.debounceMs ? debounce(
+          (result) => observer.next(result),
+          options.debounceMs
+        ) : (result) => observer.next(result);
+        const observable = this.graphqlClient.subscribeToTableChanges(
+          componentType,
+          {
+            initialEvent: options?.initialEvent ?? false,
+            fields: subscriptionFields,
+            onData: (data) => {
+              try {
+                const pluralTableName = this.getPluralTableName(componentType);
+                const nodes = data?.listen?.query?.[pluralTableName]?.nodes;
+                if (nodes && Array.isArray(nodes)) {
+                  nodes.forEach((node) => {
+                    if (node) {
+                      const entityId = node.entityId || this.extractEntityId(node, componentType);
+                      if (entityId) {
+                        const result = {
+                          entityId,
+                          data: node,
+                          changeType: "added",
+                          timestamp: Date.now()
+                        };
+                        debouncedEmit(result);
+                      }
+                    }
+                  });
+                }
+              } catch (error) {
+                observer.error(error);
+              }
+            },
+            onError: (error) => {
+              observer.error(error);
+            },
+            onComplete: () => {
+              observer.complete();
+            }
+          }
+        );
+        subscription = observable.subscribe({});
+      }).catch((error) => {
+        observer.error(error);
+      });
+      return () => {
+        if (subscription) {
+          subscription.unsubscribe();
+        }
+      };
+    });
+  }
+  /**
+   * Listen to component removed events
+   */
+  onComponentRemoved(componentType, options) {
+    if (!isValidComponentType(componentType)) {
+      return new Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    if (!this.isECSComponent(componentType)) {
+      return new Observable((observer) => {
+        observer.error(
+          new Error(
+            `Component type ${componentType} is not ECS-compliant or not available`
+          )
+        );
+      });
+    }
+    return new Observable((observer) => {
+      let subscription = null;
+      let lastKnownEntities = /* @__PURE__ */ new Set();
+      try {
+        const debouncedEmit = options?.debounceMs ? debounce(
+          (result) => observer.next(result),
+          options.debounceMs
+        ) : (result) => observer.next(result);
+        this.initializeLastKnownEntities(componentType, lastKnownEntities);
+        const observable = this.graphqlClient.subscribeToTableChanges(
+          componentType,
+          {
+            initialEvent: false,
+            fields: ["updatedAt"],
+            // Removal detection only needs basic fields
+            onData: (data) => {
+              try {
+                const pluralTableName = this.getPluralTableName(componentType);
+                const nodes = data?.listen?.query?.[pluralTableName]?.nodes || [];
+                const currentEntities = new Set(
+                  nodes.map((node) => {
+                    const entityId = node.entityId || this.extractEntityId(node, componentType);
+                    return entityId;
+                  }).filter(Boolean)
+                );
+                const removedEntities = Array.from(lastKnownEntities).filter(
+                  (entityId) => !currentEntities.has(entityId)
+                );
+                removedEntities.forEach((entityId) => {
+                  const result = {
+                    entityId,
+                    data: null,
+                    changeType: "removed",
+                    timestamp: Date.now()
+                  };
+                  debouncedEmit(result);
+                });
+                lastKnownEntities = currentEntities;
+              } catch (error) {
+                observer.error(error);
+              }
+            },
+            onError: (error) => {
+              observer.error(error);
+            },
+            onComplete: () => {
+              observer.complete();
+            }
+          }
+        );
+        subscription = observable.subscribe({});
+      } catch (error) {
+        observer.error(error);
+      }
+      return () => {
+        if (subscription) {
+          subscription.unsubscribe();
+        }
+      };
+    });
+  }
+  /**
+   * Listen to component changed events (added, removed, modified)
+   */
+  onComponentChanged(componentType, options) {
+    if (!isValidComponentType(componentType)) {
+      return new Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    if (!this.isECSComponent(componentType)) {
+      return new Observable((observer) => {
+        observer.error(
+          new Error(
+            `Component type ${componentType} is not ECS-compliant or not available`
+          )
+        );
+      });
+    }
+    return new Observable((observer) => {
+      let subscription = null;
+      this.getQueryFields(componentType, options?.fields).then((subscriptionFields) => {
+        const debouncedEmit = options?.debounceMs ? debounce(
+          (result) => observer.next(result),
+          options.debounceMs
+        ) : (result) => observer.next(result);
+        const observable = this.graphqlClient.subscribeToTableChanges(
+          componentType,
+          {
+            initialEvent: options?.initialEvent ?? false,
+            fields: subscriptionFields,
+            onData: (data) => {
+              try {
+                const pluralTableName = this.getPluralTableName(componentType);
+                const nodes = data?.listen?.query?.[pluralTableName]?.nodes;
+                if (nodes && Array.isArray(nodes)) {
+                  nodes.forEach((node) => {
+                    if (node) {
+                      const entityId = node.entityId || this.extractEntityId(node, componentType);
+                      if (entityId) {
+                        const result = {
+                          entityId,
+                          data: node,
+                          changeType: "updated",
+                          timestamp: Date.now()
+                        };
+                        debouncedEmit(result);
+                      }
+                    }
+                  });
+                }
+              } catch (error) {
+                observer.error(error);
+              }
+            },
+            onError: (error) => {
+              observer.error(error);
+            },
+            onComplete: () => {
+              observer.complete();
+            }
+          }
+        );
+        subscription = observable.subscribe({});
+      }).catch((error) => {
+        observer.error(error);
+      });
+      return () => {
+        if (subscription) {
+          subscription.unsubscribe();
+        }
+      };
+    });
+  }
+  /**
+   * Listen to component changes with specific conditions
+   */
+  onComponentCondition(componentType, filter, options) {
+    if (!isValidComponentType(componentType)) {
+      return new Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    if (!this.isECSComponent(componentType)) {
+      return new Observable((observer) => {
+        observer.error(
+          new Error(
+            `Component type ${componentType} is not ECS-compliant or not available`
+          )
+        );
+      });
+    }
+    return new Observable((observer) => {
+      let subscription = null;
+      this.getQueryFields(componentType, options?.fields).then((subscriptionFields) => {
+        const debouncedEmit = options?.debounceMs ? debounce(
+          (result) => observer.next(result),
+          options.debounceMs
+        ) : (result) => observer.next(result);
+        const observable = this.graphqlClient.subscribeToFilteredTableChanges(
+          componentType,
+          filter,
+          {
+            initialEvent: options?.initialEvent ?? false,
+            fields: subscriptionFields,
+            onData: (data) => {
+              try {
+                const pluralTableName = this.getPluralTableName(componentType);
+                const nodes = data?.listen?.query?.[pluralTableName]?.nodes || [];
+                nodes.forEach((node) => {
+                  if (node) {
+                    const entityId = node.entityId || this.extractEntityId(node, componentType);
+                    if (entityId) {
+                      const result = {
+                        entityId,
+                        data: node,
+                        changeType: "updated",
+                        timestamp: Date.now()
+                      };
+                      debouncedEmit(result);
+                    }
+                  }
+                });
+              } catch (error) {
+                observer.error(error);
+              }
+            },
+            onError: (error) => {
+              observer.error(error);
+            },
+            onComplete: () => {
+              observer.complete();
+            }
+          }
+        );
+        subscription = observable.subscribe({});
+      }).catch((error) => {
+        observer.error(error);
+      });
+      return () => {
+        if (subscription) {
+          subscription.unsubscribe();
+        }
+      };
+    });
+  }
+  /**
+   * Listen to query result changes
+   */
+  watchQuery(componentTypes, options) {
+    const validTypes = componentTypes.filter(isValidComponentType);
+    if (validTypes.length === 0) {
+      return new Observable((observer) => {
+        observer.error(
+          new Error("No valid component types for query watching")
+        );
+      });
+    }
+    return new Observable((observer) => {
+      const watcher = new QueryWatcherImpl(
+        this.graphqlClient,
+        validTypes,
+        (changes) => {
+          const result = {
+            changes
+          };
+          if (options?.debounceMs) {
+            const debouncedEmit = debounce(
+              () => observer.next(result),
+              options.debounceMs
+            );
+            debouncedEmit();
+          } else {
+            observer.next(result);
+          }
+        },
+        options
+      );
+      return () => {
+        watcher.dispose();
+      };
+    });
+  }
+  /**
+   * Create real-time data stream
+   */
+  createRealTimeStream(componentType, initialFilter) {
+    if (!isValidComponentType(componentType)) {
+      return new Observable(
+        (observer) => {
+          observer.error(new Error(`Invalid component type: ${componentType}`));
+        }
+      );
+    }
+    return new Observable(
+      (observer) => {
+        try {
+          const subscription = this.graphqlClient.createRealTimeDataStream(
+            componentType,
+            { filter: initialFilter }
+          );
+          const streamSubscription = subscription.subscribe({
+            next: (connection) => {
+              const results = connection.edges.map((edge) => {
+                const node = edge.node;
+                const entityId = node.nodeId || node.entityId || Object.values(node)[0] || "";
+                return {
+                  entityId,
+                  data: node
+                };
+              }).filter((result) => result.entityId);
+              observer.next(results);
+            },
+            error: (error) => {
+              observer.error(error);
+            },
+            complete: () => {
+              observer.complete();
+            }
+          });
+          return () => {
+            streamSubscription.unsubscribe();
+          };
+        } catch (error) {
+          observer.error(error);
+        }
+      }
+    );
+  }
+  /**
+   * Initialize known entity list (for deletion detection)
+   */
+  async initializeLastKnownEntities(componentType, lastKnownEntities) {
+    try {
+      const connection = await this.graphqlClient.getAllTables(componentType, {
+        fields: ["updatedAt"]
+      });
+      connection.edges.forEach((edge) => {
+        const node = edge.node;
+        const entityId = node.nodeId || node.entityId || Object.values(node)[0];
+        if (entityId) {
+          lastKnownEntities.add(entityId);
+        }
+      });
+    } catch (error) {
+    }
+  }
+  /**
+   * Convert singular table name to plural form (using pluralize library for correctness)
+   */
+  getPluralTableName(tableName) {
+    const camelCaseName = this.toCamelCase(tableName);
+    return pluralize.plural(camelCaseName);
+  }
+  /**
+   * Convert snake_case to camelCase
+   */
+  toCamelCase(str) {
+    return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+  }
+  /**
+   * Extract entity ID from node (using component's primary key field information)
+   */
+  extractEntityId(node, componentType) {
+    if (!node || typeof node !== "object") {
+      return "";
+    }
+    const primaryKeyField = this.getComponentPrimaryKeyField(componentType);
+    if (node[primaryKeyField] && typeof node[primaryKeyField] === "string") {
+      return node[primaryKeyField];
+    }
+    if (primaryKeyField !== "entityId" && node.entityId && typeof node.entityId === "string") {
+      return node.entityId;
+    }
+    const values = Object.values(node);
+    for (const value of values) {
+      if (typeof value === "string" && value.length > 0) {
+        return value;
+      }
+    }
+    return "";
+  }
+  /**
+   * Unsubscribe all subscriptions
+   */
+  unsubscribeAll() {
+    this.subscriptions.forEach((subscription) => {
+      try {
+        subscription?.unsubscribe();
+      } catch (error) {
+      }
+    });
+    this.subscriptions.clear();
+    this.queryWatchers.forEach((watcher) => {
+      try {
+        watcher.dispose();
+      } catch (error) {
+      }
+    });
+    this.queryWatchers.clear();
+  }
+  /**
+   * Dispose resources
+   */
+  dispose() {
+    this.unsubscribeAll();
+  }
+};
+var QueryWatcherImpl = class {
+  constructor(graphqlClient, componentTypes, callback, options) {
+    this.subscriptions = [];
+    this.currentResults = [];
+    this.isInitialized = false;
+    this.graphqlClient = graphqlClient;
+    this.componentTypes = componentTypes;
+    this.callback = callback;
+    this.options = options;
+    this.initialize();
+  }
+  async initialize() {
+    try {
+      await this.updateCurrentResults();
+      this.componentTypes.forEach((componentType) => {
+        const observable = this.graphqlClient.subscribeToTableChanges(
+          componentType,
+          {
+            initialEvent: false,
+            onData: () => {
+              this.handleDataChange();
+            },
+            onError: (error) => {
+            }
+          }
+        );
+        const actualSubscription = observable.subscribe({});
+        this.subscriptions.push(actualSubscription);
+      });
+      this.isInitialized = true;
+      if (this.options?.initialEvent && this.currentResults.length > 0) {
+        this.callback({
+          added: this.currentResults,
+          removed: [],
+          current: this.currentResults
+        });
+      }
+    } catch (error) {
+    }
+  }
+  async handleDataChange() {
+    if (!this.isInitialized)
+      return;
+    try {
+      const oldResults = [...this.currentResults];
+      await this.updateCurrentResults();
+      const changes = calculateDelta(oldResults, this.currentResults);
+      if (changes.added.length > 0 || changes.removed.length > 0) {
+        const debouncedCallback = this.options?.debounceMs ? debounce(this.callback, this.options.debounceMs) : this.callback;
+        debouncedCallback(changes);
+      }
+    } catch (error) {
+    }
+  }
+  async updateCurrentResults() {
+    try {
+      if (this.componentTypes.length === 1) {
+        const connection = await this.graphqlClient.getAllTables(
+          this.componentTypes[0],
+          { fields: ["updatedAt"] }
+        );
+        this.currentResults = connection.edges.map((edge) => {
+          const node = edge.node;
+          return node.nodeId || node.entityId || Object.values(node)[0] || "";
+        }).filter(Boolean);
+      } else {
+        const queries = this.componentTypes.map((type) => ({
+          key: type,
+          tableName: type,
+          params: {
+            fields: ["updatedAt"],
+            filter: {}
+          }
+        }));
+        const batchResult = await this.graphqlClient.batchQuery(queries);
+        const entitySets = this.componentTypes.map((type) => {
+          const connection = batchResult[type];
+          return connection ? connection.edges.map((edge) => {
+            const node = edge.node;
+            return node.nodeId || node.entityId || Object.values(node)[0] || "";
+          }).filter(Boolean) : [];
+        });
+        this.currentResults = entitySets.reduce((intersection, currentSet) => {
+          const currentSetLookup = new Set(currentSet);
+          return intersection.filter((id) => currentSetLookup.has(id));
+        });
+      }
+    } catch (error) {
+      this.currentResults = [];
+    }
+  }
+  getCurrentResults() {
+    return [...this.currentResults];
+  }
+  dispose() {
+    this.subscriptions.forEach((subscription) => {
+      try {
+        subscription?.unsubscribe();
+      } catch (error) {
+      }
+    });
+    this.subscriptions = [];
+  }
+};
+
+// src/world.ts
+var ComponentDiscoverer = class {
+  constructor(graphqlClient, dubheMetadata) {
+    this.componentMetadataMap = /* @__PURE__ */ new Map();
+    this.componentTypes = [];
+    this.graphqlClient = graphqlClient;
+    this.dubheMetadata = dubheMetadata;
+    const components = [];
+    const errors = [];
+    this.parseFromDubheMetadata(components, errors);
+    const result = {
+      components,
+      discoveredAt: Date.now(),
+      errors: errors.length > 0 ? errors : void 0,
+      totalDiscovered: components.length,
+      fromDubheMetadata: true
+    };
+    this.discoveryResult = result;
+    this.componentTypes = components.map((comp) => comp.name);
+    components.forEach((comp) => {
+      this.componentMetadataMap.set(comp.name, comp);
+    });
+  }
+  /**
+   * Parse components from DubheMetadata JSON format
+   */
+  parseFromDubheMetadata(components, errors) {
+    if (!this.dubheMetadata?.components) {
+      return;
+    }
+    for (const componentRecord of this.dubheMetadata.components) {
+      for (const [componentName, componentConfig] of Object.entries(
+        componentRecord
+      )) {
+        const componentType = this.tableNameToComponentName(componentName);
+        try {
+          const fields = [];
+          const primaryKeys = [];
+          const enumFields = [];
+          if (componentConfig.fields && Array.isArray(componentConfig.fields)) {
+            for (const fieldRecord of componentConfig.fields) {
+              for (const [fieldName, fieldType] of Object.entries(
+                fieldRecord
+              )) {
+                const camelFieldName = this.snakeToCamel(fieldName);
+                const typeStr = String(fieldType);
+                const isCustomKey = componentConfig.keys && componentConfig.keys.includes(fieldName);
+                fields.push({
+                  name: camelFieldName,
+                  type: this.dubheTypeToGraphQLType(typeStr),
+                  nullable: !isCustomKey,
+                  isPrimaryKey: isCustomKey,
+                  isEnum: this.isEnumType(typeStr)
+                });
+                if (isCustomKey) {
+                  primaryKeys.push(camelFieldName);
+                }
+                if (this.isEnumType(typeStr)) {
+                  enumFields.push(camelFieldName);
+                }
+              }
+            }
+          }
+          if (primaryKeys.length === 0) {
+            fields.unshift({
+              name: "entityId",
+              type: "String",
+              nullable: false,
+              isPrimaryKey: true,
+              isEnum: false
+            });
+            primaryKeys.push("entityId");
+          }
+          fields.push(
+            {
+              name: "createdAt",
+              type: "String",
+              nullable: false,
+              isPrimaryKey: false,
+              isEnum: false
+            },
+            {
+              name: "updatedAt",
+              type: "String",
+              nullable: false,
+              isPrimaryKey: false,
+              isEnum: false
+            }
+          );
+          if (primaryKeys.length !== 1) {
+            continue;
+          }
+          const metadata = {
+            name: componentType,
+            tableName: componentName,
+            fields,
+            primaryKeys,
+            hasDefaultId: primaryKeys.includes("entityId"),
+            enumFields,
+            lastUpdated: Date.now(),
+            description: `Auto-discovered component: ${componentName}`
+          };
+          components.push(metadata);
+        } catch (error) {
+          const errorMsg = `Component ${componentType} validation failed: ${formatError(error)}`;
+          errors.push(errorMsg);
+        }
+      }
+    }
+  }
+  getComponentTypes() {
+    return this.componentTypes;
+  }
+  getComponentMetadata(componentType) {
+    return this.componentMetadataMap.get(componentType) || null;
+  }
+  snakeToCamel(str) {
+    return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+  }
+  dubheTypeToGraphQLType(dubheType) {
+    if (dubheType.startsWith("vector<") && dubheType.endsWith(">")) {
+      return "String";
+    }
+    switch (dubheType) {
+      case "u8":
+      case "u16":
+      case "u32":
+      case "u64":
+      case "u128":
+      case "i8":
+      case "i16":
+      case "i32":
+      case "i64":
+      case "i128":
+        return "Int";
+      case "address":
+      case "string":
+        return "String";
+      case "bool":
+        return "Boolean";
+      case "enum":
+        return "String";
+      default:
+        return "String";
+    }
+  }
+  componentNameToTableName(componentName) {
+    if (!componentName.endsWith("s")) {
+      return componentName + "s";
+    }
+    return componentName;
+  }
+  tableNameToComponentName(tableName) {
+    if (tableName.endsWith("s") && tableName.length > 1) {
+      return tableName.slice(0, -1);
+    }
+    return tableName;
+  }
+  isEnumType(typeStr) {
+    return this.dubheMetadata.enums.some(
+      (enumDef) => typeof enumDef === "object" && enumDef[typeStr]
+    );
+  }
+};
+var ResourceDiscoverer = class {
+  constructor(graphqlClient, dubheMetadata) {
+    this.resourceMetadataMap = /* @__PURE__ */ new Map();
+    this.resourceTypes = [];
+    this.graphqlClient = graphqlClient;
+    this.dubheMetadata = dubheMetadata;
+    const resources = [];
+    const errors = [];
+    this.parseFromDubheMetadata(resources, errors);
+    const result = {
+      resources,
+      discoveredAt: Date.now(),
+      errors: errors.length > 0 ? errors : void 0,
+      totalDiscovered: resources.length,
+      fromDubheMetadata: true
+    };
+    this.discoveryResult = result;
+    this.resourceTypes = resources.map((res) => res.name);
+    resources.forEach((res) => {
+      this.resourceMetadataMap.set(res.name, res);
+    });
+  }
+  /**
+   * Parse resources from DubheMetadata JSON format
+   */
+  parseFromDubheMetadata(resources, errors) {
+    if (!this.dubheMetadata?.resources) {
+      return;
+    }
+    for (const resourceRecord of this.dubheMetadata.resources) {
+      for (const [resourceName, resourceConfig] of Object.entries(
+        resourceRecord
+      )) {
+        try {
+          const fields = [];
+          const primaryKeys = [];
+          const enumFields = [];
+          if (resourceConfig.fields && Array.isArray(resourceConfig.fields)) {
+            for (const fieldRecord of resourceConfig.fields) {
+              for (const [fieldName, fieldType] of Object.entries(
+                fieldRecord
+              )) {
+                const camelFieldName = this.snakeToCamel(fieldName);
+                const typeStr = String(fieldType);
+                const isCustomKey = resourceConfig.keys && resourceConfig.keys.includes(fieldName);
+                fields.push({
+                  name: camelFieldName,
+                  type: this.dubheTypeToGraphQLType(typeStr),
+                  nullable: !isCustomKey,
+                  isPrimaryKey: isCustomKey,
+                  isEnum: this.isEnumType(typeStr)
+                });
+                if (isCustomKey) {
+                  primaryKeys.push(camelFieldName);
+                }
+                if (this.isEnumType(typeStr)) {
+                  enumFields.push(camelFieldName);
+                }
+              }
+            }
+          }
+          fields.push(
+            {
+              name: "createdAt",
+              type: "String",
+              nullable: false,
+              isPrimaryKey: false,
+              isEnum: false
+            },
+            {
+              name: "updatedAt",
+              type: "String",
+              nullable: false,
+              isPrimaryKey: false,
+              isEnum: false
+            }
+          );
+          const resourceType = resourceName;
+          const metadata = {
+            name: resourceType,
+            tableName: resourceName,
+            fields,
+            primaryKeys,
+            hasCompositeKeys: primaryKeys.length > 1,
+            hasNoKeys: primaryKeys.length === 0,
+            enumFields,
+            lastUpdated: Date.now(),
+            description: `Auto-discovered resource: ${resourceName}`
+          };
+          resources.push(metadata);
+        } catch (error) {
+          const errorMsg = `Resource ${resourceName} validation failed: ${formatError(error)}`;
+          errors.push(errorMsg);
+        }
+      }
+    }
+  }
+  getResourceTypes() {
+    return this.resourceTypes;
+  }
+  getResourceMetadata(resourceType) {
+    return this.resourceMetadataMap.get(resourceType) || null;
+  }
+  snakeToCamel(str) {
+    return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+  }
+  dubheTypeToGraphQLType(dubheType) {
+    if (dubheType.startsWith("vector<") && dubheType.endsWith(">")) {
+      return "String";
+    }
+    switch (dubheType) {
+      case "u8":
+      case "u16":
+      case "u32":
+      case "u64":
+      case "u128":
+      case "i8":
+      case "i16":
+      case "i32":
+      case "i64":
+      case "i128":
+        return "Int";
+      case "address":
+      case "string":
+        return "String";
+      case "bool":
+        return "Boolean";
+      case "enum":
+        return "String";
+      default:
+        return "String";
+    }
+  }
+  isEnumType(typeStr) {
+    return this.dubheMetadata.enums.some(
+      (enumDef) => typeof enumDef === "object" && enumDef[typeStr]
+    );
+  }
+};
+var DubheECSWorld = class {
+  constructor(graphqlClient, config) {
+    this.graphqlClient = graphqlClient;
+    this.config = {
+      queryConfig: {
+        defaultCacheTimeout: 5 * 60 * 1e3,
+        maxConcurrentQueries: 10,
+        enableBatchOptimization: true
+      },
+      subscriptionConfig: {
+        defaultDebounceMs: 100,
+        maxSubscriptions: 50,
+        reconnectOnError: true
+      },
+      ...config
+    };
+    let dubheMetadata = this.config.dubheMetadata;
+    if (!dubheMetadata) {
+      dubheMetadata = this.graphqlClient.getDubheMetadata();
+      if (!dubheMetadata) {
+        throw new Error(
+          "DubheMetadata is required for ECS World initialization. Please provide it either in ECSWorldConfig or in GraphQL client configuration."
+        );
+      }
+    }
+    this.dubheMetadata = dubheMetadata;
+    this.componentDiscoverer = new ComponentDiscoverer(
+      graphqlClient,
+      this.dubheMetadata
+    );
+    this.resourceDiscoverer = new ResourceDiscoverer(
+      graphqlClient,
+      this.dubheMetadata
+    );
+    this.querySystem = new ECSQuery(graphqlClient, this.componentDiscoverer);
+    this.subscriptionSystem = new ECSSubscription(
+      graphqlClient,
+      this.componentDiscoverer
+    );
+    this.initializeWithConfig();
+  }
+  initializeWithConfig() {
+    try {
+      const ecsComponents = this.componentDiscoverer.discoveryResult.components.filter((comp) => {
+        return comp.primaryKeys.length === 1;
+      });
+      const resources = this.resourceDiscoverer.discoveryResult.resources;
+      this.querySystem.setAvailableComponents(
+        ecsComponents.map((comp) => comp.name)
+      );
+      this.querySystem.initializeComponentMetadata(
+        ecsComponents.map((comp) => ({
+          name: comp.name,
+          primaryKeys: comp.primaryKeys
+        }))
+      );
+      this.subscriptionSystem.setAvailableComponents(
+        ecsComponents.map((comp) => comp.name)
+      );
+      this.subscriptionSystem.initializeComponentMetadata(
+        ecsComponents.map((comp) => ({
+          name: comp.name,
+          primaryKeys: comp.primaryKeys
+        }))
+      );
+      if (this.config.queryConfig) {
+      }
+      if (this.config.subscriptionConfig) {
+      }
+    } catch (error) {
+      throw new Error(`Failed to initialize ECS World: ${formatError(error)}`);
+    }
+  }
+  // ============ Configuration and Initialization ============
+  /**
+   * Configure ECS world
+   */
+  configure(config) {
+    this.config = { ...this.config, ...config };
+    if (config.dubheMetadata) {
+      this.dubheMetadata = config.dubheMetadata;
+      this.componentDiscoverer = new ComponentDiscoverer(
+        this.graphqlClient,
+        this.dubheMetadata
+      );
+      this.resourceDiscoverer = new ResourceDiscoverer(
+        this.graphqlClient,
+        this.dubheMetadata
+      );
+      this.querySystem.setComponentDiscoverer(this.componentDiscoverer);
+      this.subscriptionSystem.setComponentDiscoverer(this.componentDiscoverer);
+      this.initializeWithConfig();
+    }
+  }
+  // ============ Component Discovery and Information ============
+  /**
+   * Discover and return all available ECS component types
+   */
+  discoverComponents() {
+    return this.componentDiscoverer.getComponentTypes();
+  }
+  /**
+   * Get all available ECS component types (cached)
+   */
+  getAvailableComponents() {
+    return this.componentDiscoverer.getComponentTypes();
+  }
+  /**
+   * Get metadata for a specific ECS component
+   */
+  getComponentMetadata(componentType) {
+    return this.componentDiscoverer.getComponentMetadata(componentType);
+  }
+  // ============ Resource Discovery and Information ============
+  /**
+   * Get all available resource types
+   */
+  getAvailableResources() {
+    return this.resourceDiscoverer.getResourceTypes();
+  }
+  /**
+   * Get metadata for a specific resource
+   */
+  getResourceMetadata(resourceType) {
+    return this.resourceDiscoverer.getResourceMetadata(resourceType);
+  }
+  // ============ Entity Queries ============
+  /**
+   * Check if entity exists
+   */
+  async hasEntity(entityId) {
+    return this.querySystem.hasEntity(entityId);
+  }
+  /**
+   * Get all entity IDs
+   */
+  async getAllEntities() {
+    return this.querySystem.getAllEntities();
+  }
+  /**
+   * Get entity count
+   */
+  async getEntityCount() {
+    return this.querySystem.getEntityCount();
+  }
+  // ============ Standard ECS Interface (camelCase naming) ============
+  /**
+   * Get complete data of a single entity
+   * @param entityId Entity ID
+   * @returns Complete component data of the entity, or null if entity doesn't exist
+   */
+  async getEntity(entityId) {
+    try {
+      const exists = await this.hasEntity(entityId);
+      if (!exists) {
+        return null;
+      }
+      const componentTypes = await this.getComponents(entityId);
+      if (componentTypes.length === 0) {
+        return null;
+      }
+      const entityData = {
+        entityId,
+        components: {}
+      };
+      for (const componentType of componentTypes) {
+        const componentData = await this.getComponent(entityId, componentType);
+        if (componentData) {
+          entityData.components[componentType] = componentData;
+        }
+      }
+      return entityData;
+    } catch (error) {
+      console.error(`Failed to get entity ${entityId}:`, formatError(error));
+      return null;
+    }
+  }
+  /**
+   * Get all entity ID list
+   * @returns Array of all entity IDs
+   */
+  async getEntities() {
+    return this.getAllEntities();
+  }
+  /**
+   * Get all entities that have a specific component
+   * @param componentType Component type
+   * @returns Array of entity IDs that have this component
+   */
+  async getEntitiesByComponent(componentType) {
+    return this.queryWith(componentType);
+  }
+  // Note: getComponent, getComponents, hasComponent methods are defined below
+  // ============ Component Queries ============
+  /**
+   * Check if entity has specific component
+   */
+  async hasComponent(entityId, componentType) {
+    return this.querySystem.hasComponent(entityId, componentType);
+  }
+  /**
+   * Get specific component data of entity
+   */
+  async getComponent(entityId, componentType) {
+    return this.querySystem.getComponent(entityId, componentType);
+  }
+  /**
+   * Get all component types that entity has
+   */
+  async getComponents(entityId) {
+    return this.querySystem.getComponents(entityId);
+  }
+  // ============ World Queries ============
+  /**
+   * Query all entities that have a specific component
+   */
+  async queryWith(componentType, options) {
+    return this.querySystem.queryWith(componentType, options);
+  }
+  /**
+   * Query entities that have all specified components (intersection)
+   */
+  async queryWithAll(componentTypes, options) {
+    return this.querySystem.queryWithAll(componentTypes, options);
+  }
+  /**
+   * Query entities that have any of the specified components (union)
+   */
+  async queryWithAny(componentTypes, options) {
+    return this.querySystem.queryWithAny(componentTypes, options);
+  }
+  /**
+   * Query entities that have include components but not exclude components
+   */
+  async queryWithout(includeTypes, excludeTypes, options) {
+    return this.querySystem.queryWithout(includeTypes, excludeTypes, options);
+  }
+  // ============ Conditional Queries ============
+  /**
+   * Query components based on conditions
+   */
+  async queryWhere(componentType, predicate, options) {
+    return this.querySystem.queryWhere(componentType, predicate, options);
+  }
+  /**
+   * Range query
+   */
+  async queryRange(componentType, field, min, max, options) {
+    return this.querySystem.queryRange(componentType, field, min, max, options);
+  }
+  /**
+   * Paginated query
+   */
+  async queryPaged(componentTypes, page, pageSize) {
+    return this.querySystem.queryPaged(componentTypes, page, pageSize);
+  }
+  // ============ Query Builder ============
+  /**
+   * Create query builder
+   */
+  query() {
+    return this.querySystem.query();
+  }
+  // ============ Subscription System ============
+  /**
+   * Listen to component added events
+   */
+  onComponentAdded(componentType, options) {
+    return this.subscriptionSystem.onComponentAdded(componentType, options);
+  }
+  /**
+   * Listen to component removed events
+   */
+  onComponentRemoved(componentType, options) {
+    return this.subscriptionSystem.onComponentRemoved(
+      componentType,
+      options
+    );
+  }
+  /**
+   * Listen to component changed events
+   */
+  onComponentChanged(componentType, options) {
+    return this.subscriptionSystem.onComponentChanged(
+      componentType,
+      options
+    );
+  }
+  /**
+   * Listen to component changes with specific conditions
+   */
+  onComponentCondition(componentType, filter, options) {
+    return this.subscriptionSystem.onComponentCondition(
+      componentType,
+      filter,
+      options
+    );
+  }
+  /**
+   * Listen to query result changes
+   */
+  watchQuery(componentTypes, options) {
+    return this.subscriptionSystem.watchQuery(componentTypes, options);
+  }
+  /**
+   * Create real-time data stream
+   */
+  createRealTimeStream(componentType, initialFilter) {
+    return this.subscriptionSystem.createRealTimeStream(
+      componentType,
+      initialFilter
+    );
+  }
+  // ============ Convenience Methods ============
+  /**
+   * Query entity data with specific component (includes component data)
+   */
+  async queryWithComponentData(componentType, options) {
+    try {
+      const entityIds = await this.queryWith(componentType, options);
+      const results = [];
+      for (const entityId of entityIds) {
+        const componentData = await this.getComponent(
+          entityId,
+          componentType
+        );
+        if (componentData) {
+          results.push({ entityId, data: componentData });
+        }
+      }
+      return results;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Query multi-component entity data
+   */
+  async queryMultiComponentData(component1Type, component2Type, options) {
+    try {
+      const entityIds = await this.queryWithAll(
+        [component1Type, component2Type],
+        options
+      );
+      const results = [];
+      for (const entityId of entityIds) {
+        const [data1, data2] = await Promise.all([
+          this.getComponent(entityId, component1Type),
+          this.getComponent(entityId, component2Type)
+        ]);
+        if (data1 && data2) {
+          results.push({ entityId, data1, data2 });
+        }
+      }
+      return results;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get complete entity state (all component data)
+   */
+  async getEntityState(entityId) {
+    try {
+      const componentTypes = await this.getComponents(entityId);
+      if (componentTypes.length === 0)
+        return null;
+      const components = {};
+      for (const componentType of componentTypes) {
+        const componentData = await this.getComponent(entityId, componentType);
+        if (componentData) {
+          components[componentType] = componentData;
+        }
+      }
+      return { entityId, components };
+    } catch (error) {
+      return null;
+    }
+  }
+  // ============ Statistics and Analysis ============
+  /**
+   * Get component statistics
+   */
+  async getComponentStats() {
+    try {
+      const stats = {};
+      const componentTypes = await this.getAvailableComponents();
+      await Promise.all(
+        componentTypes.map(async (componentType) => {
+          try {
+            const entities = await this.queryWith(componentType);
+            stats[componentType] = entities.length;
+          } catch (error) {
+            stats[componentType] = 0;
+          }
+        })
+      );
+      return stats;
+    } catch (error) {
+      return {};
+    }
+  }
+  /**
+   * Find orphan entities (entities with only one component)
+   */
+  async findOrphanEntities() {
+    try {
+      const allEntities = await this.getAllEntities();
+      const orphanEntities = [];
+      for (const entityId of allEntities) {
+        const components = await this.getComponents(entityId);
+        if (components.length === 1) {
+          orphanEntities.push(entityId);
+        }
+      }
+      return orphanEntities;
+    } catch (error) {
+      return [];
+    }
+  }
+  // ============ Resource Management ============
+  /**
+   * Unsubscribe all subscriptions
+   */
+  unsubscribeAll() {
+    this.subscriptionSystem.unsubscribeAll();
+  }
+  /**
+   * Clear all caches
+   */
+  clearCache() {
+    this.querySystem.dispose();
+  }
+  /**
+   * Dispose resources
+   */
+  dispose() {
+    this.querySystem.dispose();
+    this.subscriptionSystem.dispose();
+  }
+  // ============ Get Underlying Clients ============
+  /**
+   * Get GraphQL client (for advanced operations)
+   */
+  getGraphQLClient() {
+    return this.graphqlClient;
+  }
+  /**
+   * Get query system (for advanced query operations)
+   */
+  getQuerySystem() {
+    return this.querySystem;
+  }
+  /**
+   * Get subscription system (for advanced subscription operations)
+   */
+  getSubscriptionSystem() {
+    return this.subscriptionSystem;
+  }
+  /**
+   * Get ECS world configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Get dubhe metadata info (JSON format)
+   */
+  getDubheMetadata() {
+    return this.dubheMetadata;
+  }
+  // ============ Resource Queries ============
+  /**
+   * Query resource by primary keys
+   */
+  async getResource(resourceType, keyValues, options) {
+    try {
+      const resourceMetadata = this.resourceDiscoverer.getResourceMetadata(resourceType);
+      if (!resourceMetadata) {
+        return null;
+      }
+      keyValues = keyValues || {};
+      const whereConditions = {};
+      for (const [key, value] of Object.entries(keyValues)) {
+        whereConditions[key] = { equalTo: value };
+      }
+      const result = await this.graphqlClient.getAllTables(resourceType, {
+        first: 1,
+        filter: whereConditions,
+        fields: options?.fields || resourceMetadata.fields.map((f) => f.name),
+        ...options
+      });
+      const record = result.edges[0]?.node;
+      return record ? record : null;
+    } catch (error) {
+      return null;
+    }
+  }
+  /**
+   * Query multiple resources
+   */
+  async getResources(resourceType, filters, options) {
+    try {
+      const resourceMetadata = this.resourceDiscoverer.getResourceMetadata(resourceType);
+      if (!resourceMetadata) {
+        return [];
+      }
+      const whereConditions = {};
+      if (filters) {
+        for (const [key, value] of Object.entries(filters)) {
+          if (typeof value === "object" && value !== null) {
+            whereConditions[key] = value;
+          } else {
+            whereConditions[key] = { equalTo: value };
+          }
+        }
+      }
+      const result = await this.graphqlClient.getAllTables(resourceType, {
+        filter: Object.keys(whereConditions).length > 0 ? whereConditions : void 0,
+        fields: options?.fields || resourceMetadata.fields.map((f) => f.name),
+        ...options
+      });
+      const records = result.edges.map((edge) => edge.node);
+      return records;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get all resources of a specific type
+   */
+  async getAllResources(resourceType, options) {
+    return this.getResources(resourceType, void 0, options);
+  }
+  /**
+   * Check if a resource exists
+   */
+  async hasResource(resourceType, keyValues) {
+    const resource = await this.getResource(resourceType, keyValues);
+    return resource !== null;
+  }
+  /**
+   * Get resource count
+   */
+  async getResourceCount(resourceType) {
+    try {
+      const result = await this.graphqlClient.getAllTables(resourceType, {
+        first: 1
+        // Only need count, not actual data
+      });
+      return result.totalCount || 0;
+    } catch (error) {
+      return 0;
+    }
+  }
+  /**
+   * Subscribe to resource changes
+   */
+  subscribeToResourceChanges(resourceType, options) {
+    const resourceMetadata = this.resourceDiscoverer.getResourceMetadata(resourceType);
+    if (!resourceMetadata) {
+      throw new Error(
+        `Unknown resource type: ${resourceType}. Available resources: [${this.getAvailableResources().join(", ")}]`
+      );
+    }
+    const subscriptionFields = options?.fields || resourceMetadata.fields.map((f) => f.name);
+    return this.graphqlClient.subscribeToFilteredTableChanges(
+      resourceType,
+      options?.filter,
+      {
+        ...options,
+        fields: subscriptionFields
+      }
+    );
+  }
+};
+function createECSWorld(graphqlClient, config) {
+  return new DubheECSWorld(graphqlClient, config);
+}
+export {
+  ComponentDiscoverer,
+  DubheECSWorld,
+  ECSQuery,
+  ECSSubscription,
+  ResourceDiscoverer,
+  calculateDelta,
+  createCacheKey,
+  createECSWorld,
+  createTimestamp,
+  debounce,
+  deepEqual,
+  DubheECSWorld as default,
+  extractEntityIds,
+  extractIntersectionFromBatchResult,
+  extractUnionFromBatchResult,
+  findEntityIntersection,
+  findEntityUnion,
+  formatError,
+  isValidComponentType,
+  isValidEntityId,
+  limitArray,
+  normalizeComponentType,
+  paginateArray,
+  safeJsonParse
+};
+//# sourceMappingURL=index.mjs.map