@0xobelisk/ecs 1.2.0-pre.44 → 1.2.0-pre.46

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export type { EntityId, ComponentType, Unsubscribe, ComponentCallback, ComponentChangeCallback, EntityCallback, QueryChange, QueryChangeCallback, QueryWatcher, PagedResult, BatchQueryResult, ComponentChangeEvent, EntityChangeEvent, QueryOptions, SubscriptionOptions, ComponentMetadata, ComponentField, ComponentDiscoveryResult, ResourceMetadata, ResourceDiscoveryResult, ECSWorldConfig, DubheMetadata, } from './types';
+export type { EntityId, ComponentType, Unsubscribe, ComponentCallback, ComponentChangeCallback, EntityCallback, QueryChange, QueryChangeCallback, QueryWatcher, PagedResult, PagedQueryResult, BatchQueryResult, ComponentChangeEvent, EntityChangeEvent, QueryOptions, SubscriptionOptions, ComponentMetadata, ComponentField, ComponentDiscoveryResult, ResourceMetadata, ResourceDiscoveryResult, ECSWorldConfig, DubheMetadata, } from './types';
 export { DubheECSWorld } from './world';
 export { ComponentDiscoverer, ResourceDiscoverer } from './world';
 export { ECSQuery } from './query';
 export { ECSSubscription } from './subscription';
 export { createECSWorld } from './world';
-export { extractEntityIds, calculateDelta, findEntityIntersection, findEntityUnion, extractIntersectionFromBatchResult, extractUnionFromBatchResult, debounce, normalizeComponentType, createCacheKey, isValidEntityId, isValidComponentType, deepEqual, safeJsonParse, formatError, createTimestamp, limitArray, paginateArray, } from './utils';
+export { extractEntityIds, extractPagedQueryResult, calculateDelta, findEntityIntersection, findEntityUnion, extractIntersectionFromBatchResult, extractUnionFromBatchResult, debounce, normalizeComponentType, createCacheKey, isValidEntityId, isValidComponentType, deepEqual, safeJsonParse, formatError, createTimestamp, limitArray, paginateArray, } from './utils';
 export { DubheECSWorld as default } from './world';

package/dist/index.js

@@ -44,6 +44,7 @@ __export(src_exports, {
   default: () => DubheECSWorld,
   extractEntityIds: () => extractEntityIds,
   extractIntersectionFromBatchResult: () => extractIntersectionFromBatchResult,
+  extractPagedQueryResult: () => extractPagedQueryResult,
   extractUnionFromBatchResult: () => extractUnionFromBatchResult,
   findEntityIntersection: () => findEntityIntersection,
   findEntityUnion: () => findEntityUnion,
@@ -75,6 +76,21 @@ function extractEntityIds(connection, options) {
     }
   }).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);
@@ -243,6 +259,29 @@ var ECSQuery = class {
   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
    */
@@ -453,47 +492,60 @@ var ECSQuery = class {
     return validComponents;
   }
   /**
-   * Query all entities that have a specific component
+   * Query all entities that have a specific component with full pagination info
    */
-  async queryWith(componentType, options) {
+  async queryWithFullPagination(componentType, options) {
+    const emptyResult = {
+      entityIds: [],
+      items: [],
+      pageInfo: {
+        hasNextPage: false,
+        hasPreviousPage: false
+      },
+      totalCount: 0
+    };
     if (!isValidComponentType(componentType))
-      return [];
+      return emptyResult;
     if (!this.isECSComponent(componentType)) {
-      return [];
+      return emptyResult;
     }
-    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 paginationParams = this.buildPaginationParams(options);
       const connection = await this.graphqlClient.getAllTables(componentType, {
-        first: options?.limit,
+        ...paginationParams,
         fields: queryFields,
         orderBy: options?.orderBy
       });
-      const result = extractEntityIds(connection, {
+      return extractPagedQueryResult(connection, {
         idFields: options?.idFields || primaryKeys,
         composite: options?.compositeId
       });
-      this.setCachedResult(cacheKey, result);
-      return result;
     } catch (error) {
-      return [];
+      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)
-      return this.queryWith(componentTypes[0], options);
+    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 [];
@@ -502,6 +554,7 @@ var ECSQuery = class {
     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);
@@ -510,7 +563,7 @@ var ECSQuery = class {
             tableName: type,
             params: {
               fields: queryFields,
-              first: options?.limit,
+              ...paginationParams,
               orderBy: options?.orderBy
             }
           };
@@ -544,8 +597,10 @@ var ECSQuery = class {
   async queryWithAny(componentTypes, options) {
     if (componentTypes.length === 0)
       return [];
-    if (componentTypes.length === 1)
-      return this.queryWith(componentTypes[0], options);
+    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 [];
@@ -554,6 +609,7 @@ var ECSQuery = class {
     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);
@@ -562,7 +618,7 @@ var ECSQuery = class {
             tableName: type,
             params: {
               fields: queryFields,
-              first: options?.limit,
+              ...paginationParams,
               orderBy: options?.orderBy
             }
           };
@@ -611,13 +667,22 @@ var ECSQuery = class {
     }
   }
   /**
-   * Query components based on conditions
+   * Query components based on conditions with full pagination info
    */
-  async queryWhere(componentType, predicate, options) {
+  async queryWhereFullPagination(componentType, predicate, options) {
+    const emptyResult = {
+      entityIds: [],
+      items: [],
+      pageInfo: {
+        hasNextPage: false,
+        hasPreviousPage: false
+      },
+      totalCount: 0
+    };
     if (!isValidComponentType(componentType))
-      return [];
+      return emptyResult;
     if (!this.isECSComponent(componentType)) {
-      return [];
+      return emptyResult;
     }
     try {
       const queryFields = await this.getQueryFields(
@@ -625,20 +690,32 @@ var ECSQuery = class {
         options?.fields
       );
       const primaryKeys = await this.getComponentPrimaryKeys(componentType);
+      const paginationParams = this.buildPaginationParams(options);
       const connection = await this.graphqlClient.getAllTables(componentType, {
         filter: predicate,
-        first: options?.limit,
+        ...paginationParams,
         fields: queryFields,
         orderBy: options?.orderBy
       });
-      return extractEntityIds(connection, {
+      return extractPagedQueryResult(connection, {
         idFields: options?.idFields || primaryKeys,
         composite: options?.compositeId
       });
     } catch (error) {
-      return [];
+      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
    */
@@ -661,7 +738,7 @@ var ECSQuery = class {
    */
   async queryPaged(componentTypes, page, pageSize) {
     try {
-      const allResults = componentTypes.length === 1 ? await this.queryWith(componentTypes[0]) : await this.queryWithAll(componentTypes);
+      const allResults = componentTypes.length === 1 ? (await this.queryWith(componentTypes[0])).entityIds : await this.queryWithAll(componentTypes);
       return paginateArray(allResults, page, pageSize);
     } catch (error) {
       return {
@@ -1989,11 +2066,27 @@ var DubheECSWorld = class {
     return this.querySystem.queryRange(componentType, field, min, max, options);
   }
   /**
-   * Paginated query
+   * 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
@@ -2057,9 +2150,9 @@ var DubheECSWorld = class {
    */
   async queryWithComponentData(componentType, options) {
     try {
-      const entityIds = await this.queryWith(componentType, options);
+      const data = await this.queryWith(componentType, options);
       const results = [];
-      for (const entityId of entityIds) {
+      for (const entityId of data.entityIds) {
         const componentData = await this.getComponent(
           entityId,
           componentType
@@ -2129,7 +2222,7 @@ var DubheECSWorld = class {
         componentTypes.map(async (componentType) => {
           try {
             const entities = await this.queryWith(componentType);
-            stats[componentType] = entities.length;
+            stats[componentType] = entities.totalCount;
           } catch (error) {
             stats[componentType] = 0;
           }
@@ -2224,11 +2317,17 @@ var DubheECSWorld = class {
       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, {
-        first: 1,
+        ...paginationParams,
         filter: whereConditions,
         fields: options?.fields || resourceMetadata.fields.map((f) => f.name),
-        ...options
+        orderBy: options?.orderBy
       });
       const record = result.edges[0]?.node;
       return record ? record : null;
@@ -2237,17 +2336,26 @@ var DubheECSWorld = class {
     }
   }
   /**
-   * Query multiple resources
+   * Query multiple resources with complete pagination info
    */
-  async getResources(resourceType, filters, options) {
+  async getResources(resourceType, options) {
     try {
       const resourceMetadata = this.resourceDiscoverer.getResourceMetadata(resourceType);
       if (!resourceMetadata) {
-        return [];
+        return {
+          entityIds: [],
+          // Resources don't have entityIds, but include for compatibility
+          items: [],
+          pageInfo: {
+            hasNextPage: false,
+            hasPreviousPage: false
+          },
+          totalCount: 0
+        };
       }
       const whereConditions = {};
-      if (filters) {
-        for (const [key, value] of Object.entries(filters)) {
+      if (options?.filters) {
+        for (const [key, value] of Object.entries(options.filters)) {
           if (typeof value === "object" && value !== null) {
             whereConditions[key] = value;
           } else {
@@ -2255,23 +2363,44 @@ var DubheECSWorld = class {
           }
         }
       }
+      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),
-        ...options
+        orderBy: options?.orderBy
       });
-      const records = result.edges.map((edge) => edge.node);
-      return records;
+      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 [];
+      return {
+        entityIds: [],
+        // Resources don't have entityIds, but include for compatibility
+        items: [],
+        pageInfo: {
+          hasNextPage: false,
+          hasPreviousPage: false
+        },
+        totalCount: 0
+      };
     }
   }
-  /**
-   * Get all resources of a specific type
-   */
-  async getAllResources(resourceType, options) {
-    return this.getResources(resourceType, void 0, options);
-  }
   /**
    * Check if a resource exists
    */
@@ -2332,6 +2461,7 @@ function createECSWorld(graphqlClient, config) {
   deepEqual,
   extractEntityIds,
   extractIntersectionFromBatchResult,
+  extractPagedQueryResult,
   extractUnionFromBatchResult,
   findEntityIntersection,
   findEntityUnion,