eth-graph-query 2.0.15 → 2.0.20

package/dist/query-builder.d.ts

@@ -1,51 +1,56 @@
 import { ElementType, GraphObject, InlineFragmentType, Metadata, QueryJson } from './type';
 export declare class QueryBuilder {
     /**
-     * Create a query string from a query with json format.
-     * @param {QueryJson} query the json format query
-     * @returns a query string respective with the json format query
+     * Converts a JSON query object into a GraphQL-compatible string.
+     * Handles nested objects and operator mapping (e.g., $gt -> _gt).
+     * @param query - The JSON filter object to build.
+     * @returns A string representing the GraphQL 'where' or 'block' filter.
      */
     static buildJsonQuery(query: QueryJson): string;
     /**
-     * Given a json format array as element input, returns the string array represent elements you want to query in the graph.
-     * @param {Array<ElementType>} elements A array with {@link ElementType} elements, each element in the array represent a element in the graph you want to query
-     * @returns {Array<string>} The string array represent the input array
+     * Builds the fields/elements part of a GraphQL query from an array of strings or objects.
+     * @param elements - An array of fields to query. Can include nested collections as GraphObject.
+     * @returns An array of strings representing the selected fields.
      */
     static buildElements(elements: Array<ElementType>): Array<string>;
     /**
-     * Given a instance of {@link Metadata}, returns the string represent the metadata you want to query
-     * @param {Metadata} metadata The instance represent all metadata you want to query
-     * @returns The string represent the metadata you want to query
+     * Builds the metadata (_meta) fragment of a GraphQL query.
+     * @param metadata - The metadata configuration.
+     * @returns A string representing the _meta query fragment.
      */
     static buildMetadata(metadata: Metadata): string;
+    /**
+     * Builds an inline fragment (... on Collection { ... }) for a query.
+     * @param fragment - The inline fragment configuration.
+     * @returns A string representing the inline fragment.
+     * @private
+     */
     private static _buildInlineFragment;
     /**
-     * Given a instance of Array<{@link InlineFragmentType}>, returns the string represent the inline fragments you want to query
-     * @param {Array<InlineFragmentType>} fragments The instance represent the inline fragments you want to query
-     * @returns The string represent the inline fragments you want to query
+     * Builds multiple inline fragments from an array of fragment configurations.
+     * @param fragments - An array of inline fragments.
+     * @returns A string containing all built inline fragments.
      */
     static buildInlineFragments(fragments: Array<InlineFragmentType>): string;
     /**
-     * Given json data, returns the string query. This function only can create a string query for a particular collection.
-     * @param {GraphObject} data An data for create query, contains two elements:
-     *   1. collection: string - collection name
-     *   2. params: GraphParams | undefined - If it is defined, it create a query to the collection
-     * @param {Metadata | undefined} metadata If it is defined, the query can get metadata that you defined
-     * @returns The string query
+     * Builds a complete GraphQL query for a single collection.
+     * @param data - The collection and parameters for the query.
+     * @param metadata - Optional metadata configuration.
+     * @returns A string containing the GraphQL query for the collection.
      */
     static buildQuery(data: GraphObject, metadata?: Metadata): string;
     /**
-     * Given a array contain many json data, return a query string represent a query to all collections that is in a array.
-     * @param {Array<GraphObject>} data An array contain data to query to many collections
-     * @param {Metadata | undefined} metadata If it is defined, the query can get metadata that you defined
-     * @returns The query string
+     * Builds a query that targets multiple collections simultaneously.
+     * @param data - An array of collection queries and their parameters.
+     * @param metadata - Optional metadata configuration that applies to the entire query.
+     * @returns A string containing the merged GraphQL query for multiple collections.
      */
     static buildMultipleQuery(data: Array<GraphObject>, metadata?: Metadata): string;
     /**
-     * Create complete query string, you can use directly this query to query to the graph
-     * @param {string} query The query string
-     * @param {string} queryName The query name(default query)
-     * @returns The complete query string
+     * Wraps a query fragment into a full GraphQL 'query' block.
+     * @param query - The query fragment to wrap.
+     * @param queryName - An optional name for the GraphQL query (defaults to 'query').
+     * @returns The full GraphQL query string.
      */
     static makeFullQuery(query: string, queryName?: string): string;
 }

package/dist/type.d.ts

@@ -1,66 +1,149 @@
-type BaseQueryType = Array<string | number | boolean> | string | number | boolean | null | undefined;
-export declare const OptionKeys: string[];
+/**
+ * Base types that can be used in query filters.
+ */
+export type BaseQueryType = string | number | boolean | Array<string | number | boolean> | null | undefined;
+/**
+ * Valid operator suffixes for The Graph queries (e.g., _gt, _in, _contains).
+ */
+export declare const OptionKeys: readonly ["contains", "contains_nocase", "ends_with", "end_with_nocase", "starts_with", "starts_with_nocase", "not_contains", "not_contains_nocase", "not_ends_with", "not_ends_with_nocase", "not_starts_with", "not_starts_with_nocase", "gt", "gte", "lt", "lte", "not", "in", "not_in"];
+/**
+ * Type representing the valid operator keys.
+ */
+export type OptionKey = (typeof OptionKeys)[number];
+/**
+ * Filter options for text-based fields.
+ */
 export type TextWhereOptions = {
+    /** Matches values containing the substring. */
     $contains?: BaseQueryType;
+    /** Case-insensitive contains. */
     $contains_nocase?: BaseQueryType;
+    /** Matches values ending with the substring. */
     $ends_with?: BaseQueryType;
+    /** Case-insensitive ends_with. */
     $end_with_nocase?: BaseQueryType;
+    /** Matches values starting with the substring. */
     $starts_with?: BaseQueryType;
+    /** Case-insensitive starts_with. */
     $starts_with_nocase?: BaseQueryType;
+    /** Matches values NOT containing the substring. */
     $not_contains?: BaseQueryType;
+    /** Case-insensitive not_contains. */
     $not_contains_nocase?: BaseQueryType;
+    /** Matches values NOT ending with the substring. */
     $not_ends_with?: BaseQueryType;
+    /** Case-insensitive not_ends_with. */
     $not_ends_with_nocase?: BaseQueryType;
+    /** Matches values NOT starting with the substring. */
     $not_starts_with?: BaseQueryType;
+    /** Case-insensitive not_starts_with. */
     $not_starts_with_nocase?: BaseQueryType;
 };
+/**
+ * Common filter options for all field types.
+ */
 export type CommonWhereOptions = {
+    /** Greater than. */
     $gt?: BaseQueryType;
+    /** Greater than or equal to. */
     $gte?: BaseQueryType;
+    /** Less than. */
     $lt?: BaseQueryType;
+    /** Less than or equal to. */
     $lte?: BaseQueryType;
+    /** Not equal to. */
     $not?: BaseQueryType;
+    /** Included in the provided array. */
     $in?: BaseQueryType;
+    /** Not included in the provided array. */
     $not_in?: BaseQueryType;
 };
+/**
+ * Combined filter options for a field.
+ */
 export type WhereOptions = TextWhereOptions & CommonWhereOptions;
+/**
+ * JSON structure representing the 'where' filter in a query.
+ * Keys are field names, and values can be primitive values or WhereOptions.
+ */
 export type QueryJson = {
     [key: string]: QueryJson | WhereOptions | BaseQueryType;
 };
+/**
+ * Filter for querying data at a specific block.
+ */
 export type BlockQuery = {
+    /** Filter by block hash. */
     hash?: string;
+    /** Filter by exact block number. */
     number?: number;
+    /** Filter by blocks with number greater than or equal to. */
     number_gte?: number;
 };
+/**
+ * Metadata fields to query from the subgraph (_meta).
+ */
 export type Metadata = {
+    /** Specific metadata elements to fetch. */
     elements?: Array<'deployment' | 'hasIndexingErrors' | 'hash' | 'number' | 'timestamp'>;
+    /** Query metadata for a specific block. */
     blockQuery?: BlockQuery;
 };
+/**
+ * Represents a field in a query. Can be a simple string (field name)
+ * or a GraphObject for nested collection queries.
+ */
 export type ElementType = string | GraphObject;
+/**
+ * Represents an inline fragment for polymorphic types.
+ */
 export type InlineFragmentType = {
+    /** The collection name for the fragment (e.g., 'User'). */
     collection: string;
+    /** Fields to select within the fragment. */
     params?: Pick<GraphParams, 'elements'>;
 };
+/**
+ * Parameters for a collection query.
+ */
 export interface GraphParams {
+    /** Fields to select from the collection. */
     elements?: Array<ElementType>;
+    /** Inline fragments for selecting fields on specific types. */
     inlineFragments?: Array<InlineFragmentType>;
+    /** Filter conditions for the query. */
     where?: QueryJson;
+    /** Filter by specific entity ID (shortcut for where: { id: ... }). */
     id?: string;
+    /** Number of items to return (max 1000). */
     first?: number;
+    /** Field to sort the results by. */
     orderBy?: string;
+    /** Direction of the sort (asc or desc). */
     orderDirection?: 'asc' | 'desc';
+    /** Number of items to skip (max 5000). */
     skip?: number;
+    /** Re-run the query even if the subgraph has indexing errors. */
     subgraphError?: 'allow' | 'deny';
+    /** Query the collection state at a specific block. */
     block?: BlockQuery;
 }
+/**
+ * Configuration for a query against a specific collection.
+ */
 export interface GraphObject {
+    /** The name of the collection to query (e.g., 'users'). */
     collection: string;
+    /** Optional parameters for filtering, sorting, and pagination. */
     params?: GraphParams;
 }
+/**
+ * Error structure returned by The Graph API.
+ */
 export type ErrorObject = {
+    /** List of errors encountered during query execution. */
     errors: Array<{
         message: string;
         locations: Array<unknown>;
     }>;
 };
-export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eth-graph-query",
-  "version": "2.0.15",
-  "description": "simple package for creating query to the GraphQL in ethereum",
+  "version": "2.0.20",
+  "description": "A lightweight and flexible library for building The Graph queries using simple JSON objects. Eliminate the need for complex string concatenation and maintain type-safe queries.",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -15,7 +15,8 @@
     "clear": "rm -rf dist",
     "test": "vitest run",
     "prepare": "npm run build && husky install",
-    "eslint": "eslint . --ext .ts",
+    "eslint": "eslint --config ./eslint.config.js --cache",
+    "format": "prettier --write .",
     "prepublishOnly": "npm run clear && npm run build && npm run test"
   },
   "repository": {
@@ -33,28 +34,28 @@
   },
   "homepage": "https://github.com/phamhongphuc1999/eth-graph-query#readme",
   "dependencies": {
-    "axios": "^1.6.8"
+    "axios": "^1.13.2"
   },
   "devDependencies": {
-    "@commitlint/cli": "^17.6.5",
-    "@commitlint/config-conventional": "^17.6.5",
+    "@commitlint/cli": "^19.4.0",
+    "@commitlint/config-conventional": "^19.2.2",
+    "@eslint/js": "^9.29.0",
     "@rollup/plugin-typescript": "^11.1.6",
     "@types/node": "^20.12.2",
-    "@typescript-eslint/eslint-plugin": "5.59.6",
-    "eslint": "^8.40.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-import-resolver-alias": "^1.1.2",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "husky": "^8.0.3",
-    "lint-staged": "^13.2.2",
+    "eslint": "^9.29.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.1",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "husky": "^9.1.6",
     "path": "^0.12.7",
-    "prettier": "^2.8.8",
     "rollup-plugin-typescript-paths": "^1.5.0",
     "tslib": "^2.6.2",
-    "typescript": "^5.2.2",
-    "vite": "^5.2.0",
-    "vitest": "^1.4.0"
+    "typescript": "5.5.3",
+    "typescript-eslint": "^8.34.1",
+    "vite": "^7.2.7",
+    "vitest": "^4.0.15"
   },
   "contributors": [
     {
@@ -64,18 +65,12 @@
     }
   ],
   "engines": {
-    "node": ">=16",
-    "npm": ">=7"
+    "node": ">=20",
+    "npm": ">=10"
   },
   "commitlint": {
     "extends": [
       "@commitlint/config-conventional"
     ]
-  },
-  "lint-staged": {
-    "*.{js,jsx,ts,tsx}": "eslint --config ./.eslintrc-staged.cjs --cache --fix",
-    "*.{json,yml,md}": [
-      "prettier --write"
-    ]
   }
 }