@0xobelisk/ecs 1.2.0-pre.100

package/dist/index.js

@@ -0,0 +1,2413 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ComponentDiscoverer: () => ComponentDiscoverer,
+  DubheECSWorld: () => DubheECSWorld,
+  ECSQuery: () => ECSQuery,
+  ECSSubscription: () => ECSSubscription,
+  ResourceDiscoverer: () => ResourceDiscoverer,
+  calculateDelta: () => calculateDelta,
+  createCacheKey: () => createCacheKey,
+  createECSWorld: () => createECSWorld,
+  createTimestamp: () => createTimestamp,
+  debounce: () => debounce,
+  deepEqual: () => deepEqual,
+  default: () => DubheECSWorld,
+  extractEntityIds: () => extractEntityIds,
+  extractIntersectionFromBatchResult: () => extractIntersectionFromBatchResult,
+  extractPagedQueryResult: () => extractPagedQueryResult,
+  extractUnionFromBatchResult: () => extractUnionFromBatchResult,
+  findEntityIntersection: () => findEntityIntersection,
+  findEntityUnion: () => findEntityUnion,
+  formatError: () => formatError,
+  isValidComponentType: () => isValidComponentType,
+  isValidEntityId: () => isValidEntityId,
+  limitArray: () => limitArray,
+  normalizeComponentType: () => normalizeComponentType,
+  paginateArray: () => paginateArray,
+  safeJsonParse: () => safeJsonParse
+});
+module.exports = __toCommonJS(src_exports);
+
+// 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 extractPagedQueryResult(connection, options) {
+  const entityIds = extractEntityIds(connection, options);
+  const items = connection.edges.map((edge) => edge.node);
+  return {
+    entityIds,
+    items,
+    pageInfo: {
+      hasNextPage: connection.pageInfo.hasNextPage,
+      hasPreviousPage: connection.pageInfo.hasPreviousPage,
+      startCursor: connection.pageInfo.startCursor,
+      endCursor: connection.pageInfo.endCursor
+    },
+    totalCount: connection.totalCount || 0
+  };
+}
+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;
+  }
+  buildPaginationParams(options) {
+    const params = {};
+    if (options?.first !== void 0) {
+      params.first = options.first;
+    } else if (options?.limit !== void 0) {
+      params.first = options.limit;
+      if (options?.offset !== void 0) {
+        console.warn(
+          "ECS Query: offset parameter is not supported with GraphQL cursor-based pagination. Use after/before instead."
+        );
+      }
+    }
+    if (options?.last !== void 0) {
+      params.last = options.last;
+    }
+    if (options?.after !== void 0) {
+      params.after = options.after;
+    }
+    if (options?.before !== void 0) {
+      params.before = options.before;
+    }
+    return params;
+  }
+  /**
+   * 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 with full pagination info
+   */
+  async queryWithFullPagination(componentType, options) {
+    const emptyResult = {
+      entityIds: [],
+      items: [],
+      pageInfo: {
+        hasNextPage: false,
+        hasPreviousPage: false
+      },
+      totalCount: 0
+    };
+    if (!isValidComponentType(componentType)) return emptyResult;
+    if (!this.isECSComponent(componentType)) {
+      return emptyResult;
+    }
+    try {
+      const queryFields = await this.getQueryFields(componentType, options?.fields);
+      const primaryKeys = await this.getComponentPrimaryKeys(componentType);
+      const paginationParams = this.buildPaginationParams(options);
+      const connection = await this.graphqlClient.getAllTables(componentType, {
+        ...paginationParams,
+        fields: queryFields,
+        orderBy: options?.orderBy
+      });
+      return extractPagedQueryResult(connection, {
+        idFields: options?.idFields || primaryKeys,
+        composite: options?.compositeId
+      });
+    } catch (_error) {
+      return emptyResult;
+    }
+  }
+  /**
+   * Query all entities that have a specific component
+   * Returns complete pagination information including entity IDs, actual data, and page info
+   */
+  async queryWith(componentType, options) {
+    return this.queryWithFullPagination(componentType, options);
+  }
+  /**
+   * Query entities that have all specified components (intersection)
+   */
+  async queryWithAll(componentTypes, options) {
+    if (componentTypes.length === 0) return [];
+    if (componentTypes.length === 1) {
+      const result = await this.queryWith(componentTypes[0], options);
+      return result.entityIds;
+    }
+    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 paginationParams = this.buildPaginationParams(options);
+      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,
+              ...paginationParams,
+              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) {
+      const result = await this.queryWith(componentTypes[0], options);
+      return result.entityIds;
+    }
+    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 paginationParams = this.buildPaginationParams(options);
+      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,
+              ...paginationParams,
+              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 with full pagination info
+   */
+  async queryWhereFullPagination(componentType, predicate, options) {
+    const emptyResult = {
+      entityIds: [],
+      items: [],
+      pageInfo: {
+        hasNextPage: false,
+        hasPreviousPage: false
+      },
+      totalCount: 0
+    };
+    if (!isValidComponentType(componentType)) return emptyResult;
+    if (!this.isECSComponent(componentType)) {
+      return emptyResult;
+    }
+    try {
+      const queryFields = await this.getQueryFields(componentType, options?.fields);
+      const primaryKeys = await this.getComponentPrimaryKeys(componentType);
+      const paginationParams = this.buildPaginationParams(options);
+      const connection = await this.graphqlClient.getAllTables(componentType, {
+        filter: predicate,
+        ...paginationParams,
+        fields: queryFields,
+        orderBy: options?.orderBy
+      });
+      return extractPagedQueryResult(connection, {
+        idFields: options?.idFields || primaryKeys,
+        composite: options?.compositeId
+      });
+    } catch (_error) {
+      return emptyResult;
+    }
+  }
+  /**
+   * Query components based on conditions
+   */
+  async queryWhere(componentType, predicate, options) {
+    const result = await this.queryWhereFullPagination(componentType, predicate, options);
+    return result.entityIds;
+  }
+  /**
+   * 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])).entityIds : 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
+var import_client = require("@apollo/client");
+var import_pluralize = __toESM(require("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 ["createdAtTimestampMs", "updatedAtTimestampMs", "isDeleted", "lastUpdateDigest"];
+  }
+  /**
+   * 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 import_client.Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    if (!this.isECSComponent(componentType)) {
+      return new import_client.Observable((observer) => {
+        observer.error(
+          new Error(`Component type ${componentType} is not ECS-compliant or not available`)
+        );
+      });
+    }
+    return new import_client.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 import_client.Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    if (!this.isECSComponent(componentType)) {
+      return new import_client.Observable((observer) => {
+        observer.error(
+          new Error(`Component type ${componentType} is not ECS-compliant or not available`)
+        );
+      });
+    }
+    return new import_client.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: ["updatedAtTimestampMs"],
+          // 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 import_client.Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    if (!this.isECSComponent(componentType)) {
+      return new import_client.Observable((observer) => {
+        observer.error(
+          new Error(`Component type ${componentType} is not ECS-compliant or not available`)
+        );
+      });
+    }
+    return new import_client.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
+   */
+  onEntityComponent(componentType, entityId, options) {
+    if (!isValidComponentType(componentType)) {
+      return new import_client.Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    if (!this.isECSComponent(componentType)) {
+      return new import_client.Observable((observer) => {
+        observer.error(
+          new Error(`Component type ${componentType} is not ECS-compliant or not available`)
+        );
+      });
+    }
+    return new import_client.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 primaryKeyField = this.getComponentPrimaryKeyField(componentType);
+        const entityFilter = {
+          [primaryKeyField]: { equalTo: entityId }
+        };
+        const observable = this.graphqlClient.subscribeToTableChanges(componentType, {
+          initialEvent: options?.initialEvent ?? false,
+          fields: subscriptionFields,
+          filter: entityFilter,
+          onData: (data) => {
+            try {
+              const pluralTableName = this.getPluralTableName(componentType);
+              const nodes = data?.listen?.query?.[pluralTableName]?.nodes || [];
+              nodes.forEach((node) => {
+                if (node) {
+                  const entityId2 = node.entityId || this.extractEntityId(node, componentType);
+                  if (entityId2) {
+                    const result = {
+                      entityId: entityId2,
+                      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 import_client.Observable((observer) => {
+        observer.error(new Error("No valid component types for query watching"));
+      });
+    }
+    return new import_client.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 import_client.Observable((observer) => {
+        observer.error(new Error(`Invalid component type: ${componentType}`));
+      });
+    }
+    return new import_client.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: ["updatedAtTimestampMs"]
+      });
+      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 import_pluralize.default.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: ["updatedAtTimestampMs"]
+        });
+        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: ["updatedAtTimestampMs"],
+            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.
+   *
+   * Two sources are scanned:
+   *  1. dubheMetadata.components – explicit ECS components (legacy / manual).
+   *  2. dubheMetadata.resources  – resources whose sole key is `entity_id` are
+   *     treated as ECS components because they follow the same 1-entity-1-record
+   *     semantics.  Resources with composite keys (entity_id + extra keys) have
+   *     N records per entity and remain pure resources.
+   */
+  parseFromDubheMetadata(components, errors) {
+    const entries = [];
+    if (this.dubheMetadata?.components) {
+      for (const record of this.dubheMetadata.components) {
+        entries.push(...Object.entries(record));
+      }
+    }
+    if (this.dubheMetadata?.resources) {
+      for (const record of this.dubheMetadata.resources) {
+        for (const [name, cfg] of Object.entries(record)) {
+          if (cfg.keys && cfg.keys.length === 1 && cfg.keys[0] === "entity_id") {
+            entries.push([name, cfg]);
+          }
+        }
+      }
+    }
+    for (const [componentName, componentConfig] of entries) {
+      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: "createdAtTimestampMs",
+            type: "BigInt",
+            nullable: false,
+            isPrimaryKey: false,
+            isEnum: false
+          },
+          {
+            name: "updatedAtTimestampMs",
+            type: "BigInt",
+            nullable: false,
+            isPrimaryKey: false,
+            isEnum: false
+          },
+          {
+            name: "isDeleted",
+            type: "Boolean",
+            nullable: false,
+            isPrimaryKey: false,
+            isEnum: false
+          },
+          {
+            name: "lastUpdateDigest",
+            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: "createdAtTimestampMs",
+              type: "BigInt",
+              nullable: false,
+              isPrimaryKey: false,
+              isEnum: false
+            },
+            {
+              name: "updatedAtTimestampMs",
+              type: "BigInt",
+              nullable: false,
+              isPrimaryKey: false,
+              isEnum: false
+            },
+            {
+              name: "isDeleted",
+              type: "Boolean",
+              nullable: false,
+              isPrimaryKey: false,
+              isEnum: false
+            },
+            {
+              name: "lastUpdateDigest",
+              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 (legacy version using page/pageSize)
+   */
+  async queryPaged(componentTypes, page, pageSize) {
+    return this.querySystem.queryPaged(componentTypes, page, pageSize);
+  }
+  /**
+   * Query with complete pagination info using GraphQL cursor-based pagination
+   */
+  async queryWithPagination(componentType, options) {
+    return this.querySystem.queryWith(componentType, options);
+  }
+  /**
+   * Query components with conditions and complete pagination info
+   */
+  async queryWherePagination(componentType, predicate, options) {
+    return this.querySystem.queryWhereFullPagination(componentType, predicate, options);
+  }
+  // ============ 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
+   */
+  onEntityComponent(componentType, entityId, options) {
+    return this.subscriptionSystem.onEntityComponent(componentType, entityId, 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 data = await this.queryWith(componentType, options);
+      const results = [];
+      for (const entityId of data.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.totalCount;
+          } 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 };
+  }
+  /**
+   * Update ECS World configuration dynamically
+   * @param config - Partial configuration to update (same type as constructor)
+   */
+  updateConfig(config) {
+    if (config.dubheMetadata !== void 0) {
+      this.dubheMetadata = config.dubheMetadata;
+      this.config.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();
+    }
+    if (config.queryConfig) {
+      this.config.queryConfig = {
+        ...this.config.queryConfig,
+        ...config.queryConfig
+      };
+      if (config.queryConfig.defaultCacheTimeout !== void 0) {
+        this.querySystem.cacheTimeout = config.queryConfig.defaultCacheTimeout;
+      }
+    }
+    if (config.subscriptionConfig) {
+      this.config.subscriptionConfig = {
+        ...this.config.subscriptionConfig,
+        ...config.subscriptionConfig
+      };
+    }
+  }
+  /**
+   * 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 paginationParams = {
+        first: options?.first ?? options?.limit ?? 1,
+        last: options?.last,
+        after: options?.after,
+        before: options?.before
+      };
+      const result = await this.graphqlClient.getAllTables(resourceType, {
+        ...paginationParams,
+        filter: whereConditions,
+        fields: options?.fields || resourceMetadata.fields.map((f) => f.name),
+        orderBy: options?.orderBy
+      });
+      const record = result.edges[0]?.node;
+      return record ? record : null;
+    } catch (_error) {
+      return null;
+    }
+  }
+  /**
+   * Query multiple resources with complete pagination info
+   */
+  async getResources(resourceType, options) {
+    try {
+      const resourceMetadata = this.resourceDiscoverer.getResourceMetadata(resourceType);
+      if (!resourceMetadata) {
+        return {
+          entityIds: [],
+          // Resources don't have entityIds, but include for compatibility
+          items: [],
+          pageInfo: {
+            hasNextPage: false,
+            hasPreviousPage: false
+          },
+          totalCount: 0
+        };
+      }
+      const whereConditions = {};
+      if (options?.filters) {
+        for (const [key, value] of Object.entries(options.filters)) {
+          if (typeof value === "object" && value !== null) {
+            whereConditions[key] = value;
+          } else {
+            whereConditions[key] = { equalTo: value };
+          }
+        }
+      }
+      const paginationParams = {
+        first: options?.first ?? options?.limit,
+        last: options?.last,
+        after: options?.after,
+        before: options?.before
+      };
+      const result = await this.graphqlClient.getAllTables(resourceType, {
+        ...paginationParams,
+        filter: Object.keys(whereConditions).length > 0 ? whereConditions : void 0,
+        fields: options?.fields || resourceMetadata.fields.map((f) => f.name),
+        orderBy: options?.orderBy
+      });
+      const items = result.edges.map((edge) => edge.node);
+      return {
+        entityIds: [],
+        // Resources don't have entityIds, but include for compatibility
+        items,
+        pageInfo: {
+          hasNextPage: result.pageInfo.hasNextPage,
+          hasPreviousPage: result.pageInfo.hasPreviousPage,
+          startCursor: result.pageInfo.startCursor,
+          endCursor: result.pageInfo.endCursor
+        },
+        totalCount: result.totalCount || 0
+      };
+    } catch (_error) {
+      return {
+        entityIds: [],
+        // Resources don't have entityIds, but include for compatibility
+        items: [],
+        pageInfo: {
+          hasNextPage: false,
+          hasPreviousPage: false
+        },
+        totalCount: 0
+      };
+    }
+  }
+  /**
+   * 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.subscribeToTableChanges(resourceType, {
+      ...options,
+      fields: subscriptionFields
+    });
+  }
+};
+function createECSWorld(graphqlClient, config) {
+  return new DubheECSWorld(graphqlClient, config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ComponentDiscoverer,
+  DubheECSWorld,
+  ECSQuery,
+  ECSSubscription,
+  ResourceDiscoverer,
+  calculateDelta,
+  createCacheKey,
+  createECSWorld,
+  createTimestamp,
+  debounce,
+  deepEqual,
+  extractEntityIds,
+  extractIntersectionFromBatchResult,
+  extractPagedQueryResult,
+  extractUnionFromBatchResult,
+  findEntityIntersection,
+  findEntityUnion,
+  formatError,
+  isValidComponentType,
+  isValidEntityId,
+  limitArray,
+  normalizeComponentType,
+  paginateArray,
+  safeJsonParse
+});
+//# sourceMappingURL=index.js.map