eth-graph-query 2.0.21 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phạm Hồng Phúc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,25 +1,26 @@
 # eth-graph-query
 
-A lightweight and flexible library for building [The Graph (GraphQL)](https://thegraph.com/) queries using simple JSON objects. Eliminate the need for complex string concatenation and maintain type-safe queries.
+A lightweight GraphQL query builder and client with first-class support for The Graph. Build queries using JSON, avoid string concatenation, and keep strong TypeScript types.
 
 [![npm version](https://img.shields.io/npm/v/eth-graph-query.svg)](https://www.npmjs.com/package/eth-graph-query)
 [![license](https://img.shields.io/npm/l/eth-graph-query.svg)](https://github.com/phamhongphuc1999/eth-graph-query/blob/main/LICENSE)
 
 ---
 
-## 🚀 Features
+## Features
 
-- **JSON to GraphQL**: Convert nested JSON structures into valid GraphQL query strings.
-- **Multiple Collections**: Query multiple collections in a single HTTP request.
-- **Deep Nesting**: Support for nested collection queries and entity relationships.
-- **Advanced Filtering**: Full support for The Graph's operators (`_gt`, `_in`, `_contains`, etc.) via `$` prefix.
-- **Inline Fragments**: Support for GraphQL inline fragments (`... on Type`).
-- **TypeScript First**: Full type definitions for parameters, filters, and metadata.
-- **Metadata Support**: Easily fetch subgraph metadata (`_meta`).
+- JSON to GraphQL: Convert nested JSON structures into valid GraphQL query strings.
+- Multiple collections: Query multiple collections in a single HTTP request.
+- Deep nesting: Support nested collection queries and entity relationships.
+- Advanced filtering: The Graph operators via `$` prefix (e.g., `$gt`, `$in`, `$contains`).
+- Inline fragments: Support GraphQL inline fragments (`... on Type`).
+- Generic GraphQL args: Pass schema-agnostic arguments via `params.args`.
+- TypeScript first: Full type definitions for parameters, filters, and metadata.
+- Metadata support: Fetch subgraph metadata (`_meta`) when using The Graph.
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```shell
 # npm
@@ -29,23 +30,28 @@ npm install eth-graph-query
 yarn add eth-graph-query
 
 # bun
-bun install eth-graph-query
+bun add eth-graph-query
 ```
 
 ---
 
-## 💡 Usage
-
-### 1. Initialize the Client
+## Quick Start
 
 ```typescript
 import { EthGraphQuery } from 'eth-graph-query';
 
 const rootUrl = 'https://api.thegraph.com/subgraphs/name/username/subgraph-name';
-const client = new EthGraphQuery(rootUrl);
+const client = new EthGraphQuery(rootUrl, {
+  headers: { Authorization: 'Bearer <token>' },
+  timeoutMs: 10_000,
+});
 ```
 
-### 2. Single Collection Query
+---
+
+## Usage
+
+### 1. Single Collection Query (The Graph)
 
 ```typescript
 const result = await client.query({
@@ -60,9 +66,7 @@ const result = await client.query({
 });
 ```
 
-### 3. Multiple Collections Query
-
-Fetch data from multiple collections in a single round-trip.
+### 2. Multiple Collections Query
 
 ```typescript
 const result = await client.multipleQuery([
@@ -77,9 +81,7 @@ const result = await client.multipleQuery([
 ]);
 ```
 
-### 4. Advanced Nested Query & Filters
-
-Build complex queries with nested collections and operators.
+### 3. Advanced Nested Query & Filters (The Graph)
 
 ```typescript
 const result = await client.query({
@@ -107,15 +109,42 @@ const result = await client.query({
 });
 ```
 
+### 4. Generic GraphQL Arguments (Schema-Agnostic)
+
+Use `params.args` to pass arbitrary GraphQL arguments for non-The-Graph schemas.
+
+```typescript
+const result = await client.query({
+  collection: 'users',
+  params: {
+    args: {
+      first: 20,
+      orderBy: 'name',
+      filter: { active: true },
+    },
+    elements: ['id', 'name'],
+  },
+});
+```
+
+---
+
+## API Reference
+
+Documentation for all functions and types can be found in the API docs:
+
+- [API Docs](https://github.com/phamhongphuc1999/eth-graph-query/blob/main/documents/api.md)
+
 ---
 
-## 📘 API Reference
+## Notes
 
-Documentation for all functions and types can be found in the [API Docs](https://github.com/phamhongphuc1999/eth-graph-query/blob/main/documents/api.md).
+- This library uses the native `fetch` API (Node 20+). No Axios dependency.
+- The Graph-specific features (`where`, `_meta`, `block`) remain supported.
 
 ---
 
-## 🛠 For Developers
+## For Developers
 
 ### Run Tests
 
@@ -125,11 +154,13 @@ npm run test
 
 ---
 
-## 📜 License
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+---
 
-## 🔗 References
+## References
 
 - [The Graph Documentation](https://thegraph.com/docs/)
 - [GraphQL Specification](https://spec.graphql.org)

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const y=require("axios"),f={Accept:"application/json","Content-Type":"application/json"};function d(h){return h.data}class b{root;config;constructor(t,e={}){this.root=t,this.config={...e,headers:{...f,...e.headers||{}}}}async request(t,e,r,s){const n=`${this.root}${e}`,i={...this.config,...s},c=await(t==="get"||t==="delete"?y[t](n,i):y[t](n,r,i));return d(c)}async get(t,e){return this.request("get",t,void 0,e)}async post(t,e,r){return this.request("post",t,e,r)}async put(t,e,r){return this.request("put",t,e,r)}async del(t,e){return this.request("delete",t,void 0,e)}}const p=["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"],$=1e3,g=5e3;class a{static buildJsonQuery(t){const e=[];for(const r in t){const s=t[r];if(s!==void 0)if(s===null)e.push(`${r}: null`);else if(Array.isArray(s)){const n=s;e.push(`${r}: [${n.map(i=>typeof i=="string"?`"${i}"`:i).join(", ")}]`)}else if(typeof s=="string")e.push(`${r}: "${s}"`);else if(typeof s=="object"){const n={},i={},c=s;for(const l in c){const u=c[l];if(l.startsWith("$")){const o=l.slice(1);p.includes(o)?i[`${r}_${o}`]=u:n[l]=u}else n[l]=u}Object.keys(n).length>0&&e.push(`${r}: {${this.buildJsonQuery(n)}}`),Object.keys(i).length>0&&e.push(this.buildJsonQuery(i))}else e.push(`${r}: ${s}`)}return e.join(", ")}static buildElements(t){return t.map(e=>{if(typeof e=="string")return e;const r=e;return this.buildQuery({collection:r.collection,params:r.params})})}static buildMetadata(t){let e="";const r=[];t.blockQuery&&(t.blockQuery.hash&&r.push(`hash: "${t.blockQuery.hash}"`),t.blockQuery.number!==void 0&&r.push(`number: ${t.blockQuery.number}`),t.blockQuery.number_gte!==void 0&&r.push(`number_gte: ${t.blockQuery.number_gte}`));const s=r.join(", ");s.length>0&&(e+=`(block: {${s}})`);const n=[],i=[];if(t.elements){for(const u of t.elements)u==="deployment"||u==="hasIndexingErrors"?n.includes(u)||n.push(u):i.includes(u)||i.push(u);const c=i.join(" ");c.length>0&&n.push(`block{${c}}`);const l=n.join(" ");l.length>0&&(e+=`{${l}}`)}return e.length>0?`_meta${e}`:""}static _buildInlineFragment(t){const e=t.params?.elements?.length?this.buildElements(t.params.elements):["id"];return`... on ${t.collection}{${e.join(" ")}}`}static buildInlineFragments(t){return t.map(e=>this._buildInlineFragment(e)).join(" ")}static buildQuery(t,e){const{collection:r,params:s}=t,n=[];if(s?.id!==void 0&&n.push(`id: ${s.id}`),s?.orderBy&&n.push(`orderBy: ${s.orderBy}`),s?.orderDirection&&n.push(`orderDirection: ${s.orderDirection}`),s?.first!==void 0){const o=Math.max(0,Math.min(s.first,$));n.push(`first: ${o}`)}if(s?.skip!==void 0){const o=Math.max(0,Math.min(s.skip,g));n.push(`skip: ${o}`)}if(s?.where){const o=this.buildJsonQuery(s.where);o.length>0&&n.push(`where: {${o}}`)}if(s?.block){const o=this.buildJsonQuery(s.block);o.length>0&&n.push(`block: {${o}}`)}const i=n.length>0?`(${n.join(", ")})`:"";let c=["id"];s?.elements&&s.elements.length>0&&(c=this.buildElements(s.elements));let l="";s?.inlineFragments&&s.inlineFragments.length>0&&(l=` ${this.buildInlineFragments(s.inlineFragments)}`);const u=`${r}${i} {${c.join(" ")}${l}}`;if(e){const o=this.buildMetadata(e);return o?`${o} ${u}`:u}return u}static buildMultipleQuery(t,e){const s=t.map(n=>this.buildQuery({collection:n.collection,params:n.params})).join(" ");if(e){const n=this.buildMetadata(e);return n?`${n} ${s}`:s}return s}static makeFullQuery(t,e="query"){return`query ${e} {${t}}`}}class Q extends b{queryName;constructor(t,e){super(t,e),this.queryName="query"}async stringQuery(t){const e=await this.post("",{query:t});if(e&&typeof e=="object"&&"errors"in e){const s=e.errors.map(n=>n.message).join("; ");throw new Error(`GraphQL Error: ${s}`)}return e.data}async query(t,e){const r=a.buildQuery(t,e);return this.stringQuery(a.makeFullQuery(r,this.queryName))}async multipleQuery(t,e){const r=a.buildMultipleQuery(t,e);return this.stringQuery(a.makeFullQuery(r,this.queryName))}}exports.EthGraphQuery=Q;exports.OptionKeys=p;exports.QueryBuilder=a;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const y={Accept:"application/json","Content-Type":"application/json"};class f{root;config;constructor(e,t={}){this.root=e,this.config={...t,headers:{...y,...t.headers||{}}}}async request(e,t,s,r){const i=`${this.root}${t}`,o={...this.config,...r,headers:{...this.config.headers||{},...r?.headers||{}}},c=new AbortController,l=o.timeoutMs,u=typeof l=="number"&&l>0?setTimeout(()=>c.abort(),l):void 0;try{const n=await fetch(i,{method:e.toUpperCase(),headers:o.headers,body:e==="get"||e==="delete"?void 0:JSON.stringify(s??{}),signal:o.signal??c.signal});if(!n.ok)throw new Error(`HTTP Error: ${n.status} ${n.statusText}`);return await n.json()}finally{u&&clearTimeout(u)}}async get(e,t){return this.request("get",e,void 0,t)}async post(e,t,s){return this.request("post",e,t,s)}async put(e,t,s){return this.request("put",e,t,s)}async del(e,t){return this.request("delete",e,void 0,t)}}const p=["contains","contains_nocase","ends_with","ends_with_nocase","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"],d=1e3,b=5e3,g=new Set(p);class a{static escapeGraphqlString(e){return e.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}static serializeValue(e){return e===null?"null":typeof e=="string"?`"${this.escapeGraphqlString(e)}"`:`${e}`}static serializeArgValue(e){return e===null||e===void 0?"null":typeof e=="string"?this.serializeValue(e):typeof e=="number"||typeof e=="boolean"?`${e}`:Array.isArray(e)?`[${e.map(s=>this.serializeArgValue(s)).join(", ")}]`:`{${this.buildArgs(e).join(", ")}}`}static buildArgs(e){const t=[];for(const s in e){if(!Object.prototype.hasOwnProperty.call(e,s))continue;const r=e[s];r!==void 0&&t.push(`${s}: ${this.serializeArgValue(r)}`)}return t}static buildJsonQuery(e){const t=[];for(const s in e){if(!Object.prototype.hasOwnProperty.call(e,s))continue;const r=e[s];if(r!==void 0)if(r===null)t.push(`${s}: null`);else if(Array.isArray(r)){const i=r;t.push(`${s}: [${i.map(o=>typeof o=="string"?this.serializeValue(o):o).join(", ")}]`)}else if(typeof r=="string")t.push(`${s}: ${this.serializeValue(r)}`);else if(typeof r=="object"){const i={},o={},c=r;for(const l in c){if(!Object.prototype.hasOwnProperty.call(c,l))continue;const u=c[l];if(l.startsWith("$")){let n=l.slice(1);n==="end_with_nocase"&&(n="ends_with_nocase"),g.has(n)?o[`${s}_${n}`]=u:i[l]=u}else i[l]=u}Object.keys(i).length>0&&t.push(`${s}: {${this.buildJsonQuery(i)}}`),Object.keys(o).length>0&&t.push(this.buildJsonQuery(o))}else t.push(`${s}: ${r}`)}return t.join(", ")}static buildElements(e){return e.map(t=>{if(typeof t=="string")return t;const s=t;return this.buildQuery({collection:s.collection,params:s.params})})}static buildMetadata(e){let t="";const s=[];e.blockQuery&&(e.blockQuery.hash&&s.push(`hash: "${e.blockQuery.hash}"`),e.blockQuery.number!==void 0&&s.push(`number: ${e.blockQuery.number}`),e.blockQuery.number_gte!==void 0&&s.push(`number_gte: ${e.blockQuery.number_gte}`));const r=s.join(", ");r.length>0&&(t+=`(block: {${r}})`);const i=new Set,o=new Set;if(e.elements){for(const u of e.elements)u==="deployment"||u==="hasIndexingErrors"?i.add(u):o.add(u);const c=Array.from(o).join(" ");c.length>0&&i.add(`block{${c}}`);const l=Array.from(i).join(" ");l.length>0&&(t+=`{${l}}`)}return t.length>0?`_meta${t}`:""}static _buildInlineFragment(e){const t=e.params?.elements?.length?this.buildElements(e.params.elements):["id"];return`... on ${e.collection}{${t.join(" ")}}`}static buildInlineFragments(e){return e.map(t=>this._buildInlineFragment(t)).join(" ")}static buildQuery(e,t){const{collection:s,params:r}=e,i=[];if(r?.id!==void 0&&i.push(`id: ${this.serializeValue(r.id)}`),r?.orderBy&&i.push(`orderBy: ${r.orderBy}`),r?.orderDirection&&i.push(`orderDirection: ${r.orderDirection}`),r?.subgraphError&&i.push(`subgraphError: ${r.subgraphError}`),r?.args){const n=this.buildArgs(r.args);n.length>0&&i.push(...n)}if(r?.first!==void 0){const n=Math.max(0,Math.min(r.first,d));i.push(`first: ${n}`)}if(r?.skip!==void 0){const n=Math.max(0,Math.min(r.skip,b));i.push(`skip: ${n}`)}if(r?.where){const n=this.buildJsonQuery(r.where);n.length>0&&i.push(`where: {${n}}`)}if(r?.block){const n=this.buildJsonQuery(r.block);n.length>0&&i.push(`block: {${n}}`)}const o=i.length>0?`(${i.join(", ")})`:"";let c=["id"];r?.elements&&r.elements.length>0&&(c=this.buildElements(r.elements));let l="";r?.inlineFragments&&r.inlineFragments.length>0&&(l=` ${this.buildInlineFragments(r.inlineFragments)}`);const u=`${s}${o} {${c.join(" ")}${l}}`;if(t){const n=this.buildMetadata(t);return n?`${n} ${u}`:u}return u}static buildMultipleQuery(e,t){const r=e.map(i=>this.buildQuery({collection:i.collection,params:i.params})).join(" ");if(t){const i=this.buildMetadata(t);return i?`${i} ${r}`:r}return r}static makeFullQuery(e,t="query"){return`query ${t} {${e}}`}}class $ extends f{queryName;constructor(e,t){super(e,t),this.queryName="query"}async stringQuery(e){const t=await this.post("",{query:e});if(t&&typeof t=="object"&&"errors"in t){const r=t.errors.map(i=>i.message).join("; ");throw new Error(`GraphQL Error: ${r}`)}return t.data}async query(e,t){const s=a.buildQuery(e,t);return this.stringQuery(a.makeFullQuery(s,this.queryName))}async multipleQuery(e,t){const s=a.buildMultipleQuery(e,t);return this.stringQuery(a.makeFullQuery(s,this.queryName))}}exports.EthGraphQuery=$;exports.OptionKeys=p;exports.QueryBuilder=a;

package/dist/index.d.ts

@@ -1,27 +1,25 @@
-import { AxiosRequestConfig } from 'axios';
-
 /**
- * Base class for handling API requests using axios.
+ * Base class for handling API requests using fetch.
  * Provides protected methods for common HTTP verbs.
  */
 declare class ApiQuery {
     /** The root URL for all API requests. */
     root: string;
-    /** Axios configuration used for all requests. */
-    config: AxiosRequestConfig;
+    /** Request options used for all requests. */
+    config: RequestOptions;
     /**
      * Initializes a new instance of the ApiQuery class.
      * @param rootUrl - The base URL for the API.
-     * @param config - Optional axios configuration.
+     * @param config - Optional request configuration.
      */
-    constructor(rootUrl: string, config?: AxiosRequestConfig);
+    constructor(rootUrl: string, config?: RequestOptions);
     /**
      * Performs an API request.
      * @template T - The expected response type.
      * @param method - The HTTP method to use.
      * @param url - The relative URL for the request.
      * @param data - The request payload (for POST, PUT).
-     * @param config - Optional axios configuration to override defaults.
+     * @param config - Optional request configuration to override defaults.
      * @returns A promise that resolves to the response data.
      */
     private request;
@@ -29,38 +27,38 @@ declare class ApiQuery {
      * Performs a GET request.
      * @template T - The expected response type.
      * @param url - The relative URL for the request.
-     * @param config - Optional axios configuration to override defaults.
+     * @param config - Optional request configuration to override defaults.
      * @returns A promise that resolves to the response data.
      */
-    protected get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    protected get<T = any>(url: string, config?: RequestOptions): Promise<T>;
     /**
      * Performs a POST request.
      * @template B - The request body type.
      * @template T - The expected response type.
      * @param url - The relative URL for the request.
      * @param data - The request payload.
-     * @param config - Optional axios configuration to override defaults.
+     * @param config - Optional request configuration to override defaults.
      * @returns A promise that resolves to the response data.
      */
-    protected post<B = any, T = any>(url: string, data?: B, config?: AxiosRequestConfig): Promise<T>;
+    protected post<B = any, T = any>(url: string, data?: B, config?: RequestOptions): Promise<T>;
     /**
      * Performs a PUT request.
      * @template B - The request body type.
      * @template T - The expected response type.
      * @param url - The relative URL for the request.
      * @param data - The request payload.
-     * @param config - Optional axios configuration to override defaults.
+     * @param config - Optional request configuration to override defaults.
      * @returns A promise that resolves to the response data.
      */
-    protected put<B = any, T = any>(url: string, data?: B, config?: AxiosRequestConfig): Promise<T>;
+    protected put<B = any, T = any>(url: string, data?: B, config?: RequestOptions): Promise<T>;
     /**
      * Performs a DELETE request.
      * @template T - The expected response type.
      * @param url - The relative URL for the request.
-     * @param config - Optional axios configuration to override defaults.
+     * @param config - Optional request configuration to override defaults.
      * @returns A promise that resolves to the response data.
      */
-    protected del<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    protected del<T = any>(url: string, config?: RequestOptions): Promise<T>;
 }
 
 /**
@@ -76,8 +74,6 @@ export declare type BlockQuery = {
     hash?: string;
     /** Filter by exact block number. */
     number?: number;
-    /** Filter by blocks with number greater than or equal to. */
-    number_gte?: number;
 };
 
 /**
@@ -127,9 +123,9 @@ export declare class EthGraphQuery extends ApiQuery {
     /**
      * Initializes a new EthGraphQuery instance.
      * @param rootUrl - The endpoint URL of the subgraph.
-     * @param config - Optional axios configuration for custom headers or timeouts.
+     * @param config - Optional request configuration for custom headers or timeouts.
      */
-    constructor(rootUrl: string, config?: AxiosRequestConfig);
+    constructor(rootUrl: string, config?: RequestOptions);
     /**
      * Executes a raw GraphQL query string.
      * @template T - The expected return type of the data.
@@ -174,24 +170,35 @@ export declare interface GraphParams {
     elements?: Array<ElementType>;
     /** Inline fragments for selecting fields on specific types. */
     inlineFragments?: Array<InlineFragmentType>;
-    /** Filter conditions for the query. */
+    /** Generic GraphQL arguments (schema-agnostic). */
+    args?: {
+        [key: string]: GraphQLArgValue;
+    };
+    /** The Graph-specific 'where' filter conditions. */
     where?: QueryJson;
     /** Filter by specific entity ID (shortcut for where: { id: ... }). */
     id?: string;
-    /** Number of items to return (max 1000). */
+    /** Number of items to return. */
     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). */
+    /** Number of items to skip. */
     skip?: number;
     /** Re-run the query even if the subgraph has indexing errors. */
     subgraphError?: 'allow' | 'deny';
-    /** Query the collection state at a specific block. */
+    /** Query the collection state at a specific block (The Graph). */
     block?: BlockQuery;
 }
 
+/**
+ * Generic GraphQL argument value for schema-agnostic queries.
+ */
+export declare type GraphQLArgValue = string | number | boolean | null | undefined | Array<GraphQLArgValue> | {
+    [key: string]: GraphQLArgValue;
+};
+
 /**
  * Represents an inline fragment for polymorphic types.
  */
@@ -199,7 +206,9 @@ export declare type InlineFragmentType = {
     /** The collection name for the fragment (e.g., 'User'). */
     collection: string;
     /** Fields to select within the fragment. */
-    params?: Pick<GraphParams, 'elements'>;
+    params?: {
+        elements?: Array<ElementType>;
+    };
 };
 
 /**
@@ -209,7 +218,19 @@ export declare type Metadata = {
     /** Specific metadata elements to fetch. */
     elements?: Array<'deployment' | 'hasIndexingErrors' | 'hash' | 'number' | 'timestamp'>;
     /** Query metadata for a specific block. */
-    blockQuery?: BlockQuery;
+    blockQuery?: MetadataBlockQuery;
+};
+
+/**
+ * Metadata block query supports number_gte in The Graph _meta.
+ */
+export declare type MetadataBlockQuery = {
+    /** 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;
 };
 
 /**
@@ -220,9 +241,13 @@ export declare type OptionKey = (typeof OptionKeys)[number];
 /**
  * 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"];
+export declare const OptionKeys: readonly ["contains", "contains_nocase", "ends_with", "ends_with_nocase", "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"];
 
 export declare class QueryBuilder {
+    private static escapeGraphqlString;
+    static serializeValue(value: string | number | boolean | null): string;
+    private static serializeArgValue;
+    private static buildArgs;
     /**
      * Converts a JSON query object into a GraphQL-compatible string.
      * Handles nested objects and operator mapping (e.g., $gt -> _gt).
@@ -286,6 +311,12 @@ export declare type QueryJson = {
     [key: string]: QueryJson | WhereOptions | BaseQueryType;
 };
 
+declare type RequestOptions = {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+
 /**
  * Filter options for text-based fields.
  */

package/dist/index.js

@@ -1,25 +1,18 @@
-import y from "axios";
 const p = { Accept: "application/json", "Content-Type": "application/json" };
-function f(a) {
-  return a.data;
-}
-class d {
+class y {
   /** The root URL for all API requests. */
   root;
-  /** Axios configuration used for all requests. */
+  /** Request options used for all requests. */
   config;
   /**
    * Initializes a new instance of the ApiQuery class.
    * @param rootUrl - The base URL for the API.
-   * @param config - Optional axios configuration.
+   * @param config - Optional request configuration.
    */
-  constructor(t, e = {}) {
-    this.root = t, this.config = {
-      ...e,
-      headers: {
-        ...p,
-        ...e.headers || {}
-      }
+  constructor(e, t = {}) {
+    this.root = e, this.config = {
+      ...t,
+      headers: { ...p, ...t.headers || {} }
     };
   }
   /**
@@ -28,22 +21,38 @@ class d {
    * @param method - The HTTP method to use.
    * @param url - The relative URL for the request.
    * @param data - The request payload (for POST, PUT).
-   * @param config - Optional axios configuration to override defaults.
+   * @param config - Optional request configuration to override defaults.
    * @returns A promise that resolves to the response data.
    */
-  async request(t, e, r, s) {
-    const n = `${this.root}${e}`, i = { ...this.config, ...s }, c = await (t === "get" || t === "delete" ? y[t](n, i) : y[t](n, r, i));
-    return f(c);
+  async request(e, t, s, r) {
+    const i = `${this.root}${t}`, o = {
+      ...this.config,
+      ...r,
+      headers: { ...this.config.headers || {}, ...r?.headers || {} }
+    }, c = new AbortController(), l = o.timeoutMs, u = typeof l == "number" && l > 0 ? setTimeout(() => c.abort(), l) : void 0;
+    try {
+      const n = await fetch(i, {
+        method: e.toUpperCase(),
+        headers: o.headers,
+        body: e === "get" || e === "delete" ? void 0 : JSON.stringify(s ?? {}),
+        signal: o.signal ?? c.signal
+      });
+      if (!n.ok)
+        throw new Error(`HTTP Error: ${n.status} ${n.statusText}`);
+      return await n.json();
+    } finally {
+      u && clearTimeout(u);
+    }
   }
   /**
    * Performs a GET request.
    * @template T - The expected response type.
    * @param url - The relative URL for the request.
-   * @param config - Optional axios configuration to override defaults.
+   * @param config - Optional request configuration to override defaults.
    * @returns A promise that resolves to the response data.
    */
-  async get(t, e) {
-    return this.request("get", t, void 0, e);
+  async get(e, t) {
+    return this.request("get", e, void 0, t);
   }
   /**
    * Performs a POST request.
@@ -51,11 +60,11 @@ class d {
    * @template T - The expected response type.
    * @param url - The relative URL for the request.
    * @param data - The request payload.
-   * @param config - Optional axios configuration to override defaults.
+   * @param config - Optional request configuration to override defaults.
    * @returns A promise that resolves to the response data.
    */
-  async post(t, e, r) {
-    return this.request("post", t, e, r);
+  async post(e, t, s) {
+    return this.request("post", e, t, s);
   }
   /**
    * Performs a PUT request.
@@ -63,27 +72,28 @@ class d {
    * @template T - The expected response type.
    * @param url - The relative URL for the request.
    * @param data - The request payload.
-   * @param config - Optional axios configuration to override defaults.
+   * @param config - Optional request configuration to override defaults.
    * @returns A promise that resolves to the response data.
    */
-  async put(t, e, r) {
-    return this.request("put", t, e, r);
+  async put(e, t, s) {
+    return this.request("put", e, t, s);
   }
   /**
    * Performs a DELETE request.
    * @template T - The expected response type.
    * @param url - The relative URL for the request.
-   * @param config - Optional axios configuration to override defaults.
+   * @param config - Optional request configuration to override defaults.
    * @returns A promise that resolves to the response data.
    */
-  async del(t, e) {
-    return this.request("delete", t, void 0, e);
+  async del(e, t) {
+    return this.request("delete", e, void 0, t);
   }
 }
-const b = [
+const f = [
   "contains",
   "contains_nocase",
   "ends_with",
+  "ends_with_nocase",
   "end_with_nocase",
   "starts_with",
   "starts_with_nocase",
@@ -100,54 +110,70 @@ const b = [
   "not",
   "in",
   "not_in"
-], $ = 1e3, g = 5e3;
-class h {
+], d = 1e3, b = 5e3, g = new Set(f);
+class a {
+  static escapeGraphqlString(e) {
+    return e.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  }
+  static serializeValue(e) {
+    return e === null ? "null" : typeof e == "string" ? `"${this.escapeGraphqlString(e)}"` : `${e}`;
+  }
+  static serializeArgValue(e) {
+    return e === null || e === void 0 ? "null" : typeof e == "string" ? this.serializeValue(e) : typeof e == "number" || typeof e == "boolean" ? `${e}` : Array.isArray(e) ? `[${e.map((s) => this.serializeArgValue(s)).join(", ")}]` : `{${this.buildArgs(e).join(", ")}}`;
+  }
+  static buildArgs(e) {
+    const t = [];
+    for (const s in e) {
+      if (!Object.prototype.hasOwnProperty.call(e, s)) continue;
+      const r = e[s];
+      r !== void 0 && t.push(`${s}: ${this.serializeArgValue(r)}`);
+    }
+    return t;
+  }
   /**
    * 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(t) {
-    const e = [];
-    for (const r in t) {
-      const s = t[r];
-      if (s !== void 0)
-        if (s === null)
-          e.push(`${r}: null`);
-        else if (Array.isArray(s)) {
-          const n = s;
-          e.push(
-            `${r}: [${n.map((i) => typeof i == "string" ? `"${i}"` : i).join(", ")}]`
+  static buildJsonQuery(e) {
+    const t = [];
+    for (const s in e) {
+      if (!Object.prototype.hasOwnProperty.call(e, s)) continue;
+      const r = e[s];
+      if (r !== void 0)
+        if (r === null) t.push(`${s}: null`);
+        else if (Array.isArray(r)) {
+          const i = r;
+          t.push(
+            `${s}: [${i.map((o) => typeof o == "string" ? this.serializeValue(o) : o).join(", ")}]`
           );
-        } else if (typeof s == "string")
-          e.push(`${r}: "${s}"`);
-        else if (typeof s == "object") {
-          const n = {}, i = {}, c = s;
+        } else if (typeof r == "string") t.push(`${s}: ${this.serializeValue(r)}`);
+        else if (typeof r == "object") {
+          const i = {}, o = {}, c = r;
           for (const l in c) {
+            if (!Object.prototype.hasOwnProperty.call(c, l)) continue;
             const u = c[l];
             if (l.startsWith("$")) {
-              const o = l.slice(1);
-              b.includes(o) ? i[`${r}_${o}`] = u : n[l] = u;
-            } else
-              n[l] = u;
+              let n = l.slice(1);
+              n === "end_with_nocase" && (n = "ends_with_nocase"), g.has(n) ? o[`${s}_${n}`] = u : i[l] = u;
+            } else i[l] = u;
           }
-          Object.keys(n).length > 0 && e.push(`${r}: {${this.buildJsonQuery(n)}}`), Object.keys(i).length > 0 && e.push(this.buildJsonQuery(i));
-        } else
-          e.push(`${r}: ${s}`);
+          Object.keys(i).length > 0 && t.push(`${s}: {${this.buildJsonQuery(i)}}`), Object.keys(o).length > 0 && t.push(this.buildJsonQuery(o));
+        } else t.push(`${s}: ${r}`);
     }
-    return e.join(", ");
+    return t.join(", ");
   }
   /**
    * 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(t) {
-    return t.map((e) => {
-      if (typeof e == "string") return e;
-      const r = e;
-      return this.buildQuery({ collection: r.collection, params: r.params });
+  static buildElements(e) {
+    return e.map((t) => {
+      if (typeof t == "string") return t;
+      const s = t;
+      return this.buildQuery({ collection: s.collection, params: s.params });
     });
   }
   /**
@@ -155,22 +181,22 @@ class h {
    * @param metadata - The metadata configuration.
    * @returns A string representing the _meta query fragment.
    */
-  static buildMetadata(t) {
-    let e = "";
-    const r = [];
-    t.blockQuery && (t.blockQuery.hash && r.push(`hash: "${t.blockQuery.hash}"`), t.blockQuery.number !== void 0 && r.push(`number: ${t.blockQuery.number}`), t.blockQuery.number_gte !== void 0 && r.push(`number_gte: ${t.blockQuery.number_gte}`));
-    const s = r.join(", ");
-    s.length > 0 && (e += `(block: {${s}})`);
-    const n = [], i = [];
-    if (t.elements) {
-      for (const u of t.elements)
-        u === "deployment" || u === "hasIndexingErrors" ? n.includes(u) || n.push(u) : i.includes(u) || i.push(u);
-      const c = i.join(" ");
-      c.length > 0 && n.push(`block{${c}}`);
-      const l = n.join(" ");
-      l.length > 0 && (e += `{${l}}`);
+  static buildMetadata(e) {
+    let t = "";
+    const s = [];
+    e.blockQuery && (e.blockQuery.hash && s.push(`hash: "${e.blockQuery.hash}"`), e.blockQuery.number !== void 0 && s.push(`number: ${e.blockQuery.number}`), e.blockQuery.number_gte !== void 0 && s.push(`number_gte: ${e.blockQuery.number_gte}`));
+    const r = s.join(", ");
+    r.length > 0 && (t += `(block: {${r}})`);
+    const i = /* @__PURE__ */ new Set(), o = /* @__PURE__ */ new Set();
+    if (e.elements) {
+      for (const u of e.elements)
+        u === "deployment" || u === "hasIndexingErrors" ? i.add(u) : o.add(u);
+      const c = Array.from(o).join(" ");
+      c.length > 0 && i.add(`block{${c}}`);
+      const l = Array.from(i).join(" ");
+      l.length > 0 && (t += `{${l}}`);
     }
-    return e.length > 0 ? `_meta${e}` : "";
+    return t.length > 0 ? `_meta${t}` : "";
   }
   /**
    * Builds an inline fragment (... on Collection { ... }) for a query.
@@ -178,17 +204,17 @@ class h {
    * @returns A string representing the inline fragment.
    * @private
    */
-  static _buildInlineFragment(t) {
-    const e = t.params?.elements?.length ? this.buildElements(t.params.elements) : ["id"];
-    return `... on ${t.collection}{${e.join(" ")}}`;
+  static _buildInlineFragment(e) {
+    const t = e.params?.elements?.length ? this.buildElements(e.params.elements) : ["id"];
+    return `... on ${e.collection}{${t.join(" ")}}`;
   }
   /**
    * 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(t) {
-    return t.map((e) => this._buildInlineFragment(e)).join(" ");
+  static buildInlineFragments(e) {
+    return e.map((t) => this._buildInlineFragment(t)).join(" ");
   }
   /**
    * Builds a complete GraphQL query for a single collection.
@@ -196,33 +222,37 @@ class h {
    * @param metadata - Optional metadata configuration.
    * @returns A string containing the GraphQL query for the collection.
    */
-  static buildQuery(t, e) {
-    const { collection: r, params: s } = t, n = [];
-    if (s?.id !== void 0 && n.push(`id: ${s.id}`), s?.orderBy && n.push(`orderBy: ${s.orderBy}`), s?.orderDirection && n.push(`orderDirection: ${s.orderDirection}`), s?.first !== void 0) {
-      const o = Math.max(0, Math.min(s.first, $));
-      n.push(`first: ${o}`);
+  static buildQuery(e, t) {
+    const { collection: s, params: r } = e, i = [];
+    if (r?.id !== void 0 && i.push(`id: ${this.serializeValue(r.id)}`), r?.orderBy && i.push(`orderBy: ${r.orderBy}`), r?.orderDirection && i.push(`orderDirection: ${r.orderDirection}`), r?.subgraphError && i.push(`subgraphError: ${r.subgraphError}`), r?.args) {
+      const n = this.buildArgs(r.args);
+      n.length > 0 && i.push(...n);
+    }
+    if (r?.first !== void 0) {
+      const n = Math.max(0, Math.min(r.first, d));
+      i.push(`first: ${n}`);
     }
-    if (s?.skip !== void 0) {
-      const o = Math.max(0, Math.min(s.skip, g));
-      n.push(`skip: ${o}`);
+    if (r?.skip !== void 0) {
+      const n = Math.max(0, Math.min(r.skip, b));
+      i.push(`skip: ${n}`);
     }
-    if (s?.where) {
-      const o = this.buildJsonQuery(s.where);
-      o.length > 0 && n.push(`where: {${o}}`);
+    if (r?.where) {
+      const n = this.buildJsonQuery(r.where);
+      n.length > 0 && i.push(`where: {${n}}`);
     }
-    if (s?.block) {
-      const o = this.buildJsonQuery(s.block);
-      o.length > 0 && n.push(`block: {${o}}`);
+    if (r?.block) {
+      const n = this.buildJsonQuery(r.block);
+      n.length > 0 && i.push(`block: {${n}}`);
     }
-    const i = n.length > 0 ? `(${n.join(", ")})` : "";
+    const o = i.length > 0 ? `(${i.join(", ")})` : "";
     let c = ["id"];
-    s?.elements && s.elements.length > 0 && (c = this.buildElements(s.elements));
+    r?.elements && r.elements.length > 0 && (c = this.buildElements(r.elements));
     let l = "";
-    s?.inlineFragments && s.inlineFragments.length > 0 && (l = ` ${this.buildInlineFragments(s.inlineFragments)}`);
-    const u = `${r}${i} {${c.join(" ")}${l}}`;
-    if (e) {
-      const o = this.buildMetadata(e);
-      return o ? `${o} ${u}` : u;
+    r?.inlineFragments && r.inlineFragments.length > 0 && (l = ` ${this.buildInlineFragments(r.inlineFragments)}`);
+    const u = `${s}${o} {${c.join(" ")}${l}}`;
+    if (t) {
+      const n = this.buildMetadata(t);
+      return n ? `${n} ${u}` : u;
     }
     return u;
   }
@@ -232,15 +262,15 @@ class h {
    * @param metadata - Optional metadata configuration that applies to the entire query.
    * @returns A string containing the merged GraphQL query for multiple collections.
    */
-  static buildMultipleQuery(t, e) {
-    const s = t.map(
-      (n) => this.buildQuery({ collection: n.collection, params: n.params })
+  static buildMultipleQuery(e, t) {
+    const r = e.map(
+      (i) => this.buildQuery({ collection: i.collection, params: i.params })
     ).join(" ");
-    if (e) {
-      const n = this.buildMetadata(e);
-      return n ? `${n} ${s}` : s;
+    if (t) {
+      const i = this.buildMetadata(t);
+      return i ? `${i} ${r}` : r;
     }
-    return s;
+    return r;
   }
   /**
    * Wraps a query fragment into a full GraphQL 'query' block.
@@ -248,20 +278,20 @@ class h {
    * @param queryName - An optional name for the GraphQL query (defaults to 'query').
    * @returns The full GraphQL query string.
    */
-  static makeFullQuery(t, e = "query") {
-    return `query ${e} {${t}}`;
+  static makeFullQuery(e, t = "query") {
+    return `query ${t} {${e}}`;
   }
 }
-class Q extends d {
+class $ extends y {
   /** The name of the GraphQL query, used in makeFullQuery. */
   queryName;
   /**
    * Initializes a new EthGraphQuery instance.
    * @param rootUrl - The endpoint URL of the subgraph.
-   * @param config - Optional axios configuration for custom headers or timeouts.
+   * @param config - Optional request configuration for custom headers or timeouts.
    */
-  constructor(t, e) {
-    super(t, e), this.queryName = "query";
+  constructor(e, t) {
+    super(e, t), this.queryName = "query";
   }
   /**
    * Executes a raw GraphQL query string.
@@ -270,13 +300,13 @@ class Q extends d {
    * @returns A promise resolving to the query result.
    * @throws Error if the response contains any GraphQL errors.
    */
-  async stringQuery(t) {
-    const e = await this.post("", { query: t });
-    if (e && typeof e == "object" && "errors" in e) {
-      const s = e.errors.map((n) => n.message).join("; ");
-      throw new Error(`GraphQL Error: ${s}`);
+  async stringQuery(e) {
+    const t = await this.post("", { query: e });
+    if (t && typeof t == "object" && "errors" in t) {
+      const r = t.errors.map((i) => i.message).join("; ");
+      throw new Error(`GraphQL Error: ${r}`);
     }
-    return e.data;
+    return t.data;
   }
   /**
    * Executes a single collection query using a JSON configuration.
@@ -285,9 +315,9 @@ class Q extends d {
    * @param metadata - Optional metadata fields to include in the query.
    * @returns A promise resolving to the fetched data.
    */
-  async query(t, e) {
-    const r = h.buildQuery(t, e);
-    return this.stringQuery(h.makeFullQuery(r, this.queryName));
+  async query(e, t) {
+    const s = a.buildQuery(e, t);
+    return this.stringQuery(a.makeFullQuery(s, this.queryName));
   }
   /**
    * Executes multiple collection queries in a single request using JSON configurations.
@@ -296,13 +326,13 @@ class Q extends d {
    * @param metadata - Optional metadata fields to include in the query.
    * @returns A promise resolving to the merged results of all queries.
    */
-  async multipleQuery(t, e) {
-    const r = h.buildMultipleQuery(t, e);
-    return this.stringQuery(h.makeFullQuery(r, this.queryName));
+  async multipleQuery(e, t) {
+    const s = a.buildMultipleQuery(e, t);
+    return this.stringQuery(a.makeFullQuery(s, this.queryName));
   }
 }
 export {
-  Q as EthGraphQuery,
-  b as OptionKeys,
-  h as QueryBuilder
+  $ as EthGraphQuery,
+  f as OptionKeys,
+  a as QueryBuilder
 };

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "eth-graph-query",
-  "version": "2.0.21",
-  "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.",
+  "version": "3.0.0",
+  "description": "A lightweight GraphQL query builder and client with first-class support for The Graph. Build queries using JSON, avoid string concatenation, and keep strong TypeScript types.",
   "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "typings": "dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
   "files": [
     "dist"
   ],
-  "sideEffects": false,
   "scripts": {
     "build": "bun run clear && tsc && vite build",
     "preview": "vite preview",
@@ -34,19 +41,16 @@
     "url": "https://github.com/phamhongphuc1999/eth-graph-query/issues"
   },
   "homepage": "https://github.com/phamhongphuc1999/eth-graph-query#readme",
-  "peerDependencies": {
-    "axios": "^1.13.2"
-  },
   "devDependencies": {
     "@commitlint/cli": "^19.4.0",
     "@commitlint/config-conventional": "^19.2.2",
     "@eslint/js": "^9.29.0",
     "@types/node": "^20.12.2",
-    "axios": "^1.13.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": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.20",
     "husky": "^9.1.6",

package/dist/.vite/manifest.json

@@ -1,8 +0,0 @@
-{
-  "src/index.ts": {
-    "file": "index.cjs",
-    "name": "index",
-    "src": "src/index.ts",
-    "isEntry": true
-  }
-}