feat: add initial support for fragments (#81)

* Add fragment helper * Add barrels Signed-off-by: Lucas Santos <lhs.santoss@gmail.com> * Add warning Signed-off-by: Lucas Santos <lhs.santoss@gmail.com> * 2.0.6 * Add initial fragment support As requested by #55 this address a first approach to add the fragment support * Bump * Rollback * 2.0.7-alpha1.0 * Update readme * 2.1.1-alpha1.0 * chore: update packages * fix(runner): linting and build errors * fix(parser): linting and build errors * ci: update and clean workflows * ci: update minimum node version to 18 * chore: add jest globals * test(runner): fix tests after new version * docs: add fragment docs --------- Signed-off-by: Lucas Santos <lhs.santoss@gmail.com>
khaosdoctor · Dec 18, 2024 · bb1e416 · bb1e416
1 parent bc725cc
commit bb1e416
Show file tree

Hide file tree

Showing 15 changed files with 5,868 additions and 4,721 deletions.
diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml
@@ -1,13 +1,12 @@
-# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
 name: Tests and CI
 
 on:
   push:
-    branches-ignore: main
+    branches-ignore:
+      - main
   pull_request:
-    branches: main
+    branches:
+      - main
 
 jobs:
   build:
@@ -16,14 +15,14 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x, 18.x, 20.x]
+        node-version: [18.x, 20.x, 22.x, 23.x]
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: npm ci
-    - run: npm run build --if-present
-    - run: npm test
+      - uses: actions/checkout@v3
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm test
diff --git a/.github/workflows/npmpublish.yml b/.github/workflows/npmpublish.yml
@@ -1,6 +1,3 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
-
 name: Build and Publish
 
 on:
@@ -13,10 +10,10 @@ jobs:
     runs-on: ubuntu-latest
     if: "! contains(toJSON(github.event.commits.*.message), '[skip ci]')"
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
-          node-version: 20
+          node-version: 22
       - name: Install Dependencies
         run: npm ci
       - name: Test
@@ -26,10 +23,10 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
-          node-version: 14
+          node-version: 22
           registry-url: https://registry.npmjs.org/
       - name: Install Dependencies
         run: npm ci

diff --git a/README.md b/README.md
@@ -20,7 +20,6 @@
   </a>
 </h1>
 
-
 This is a better implementation of the [GraphQL](https://github.com/facebook/graphql) query API via NodeJS, created as a wrapper of [Got](http://github.com/sindresorhus/got). It works like a transpiler, with a built in HTTPRequest Client (Got), allowing you to write your GraphQL queries as Javascript Objects instead of strings.
 
 Built because manipulating strings is a real pain.
@@ -46,6 +45,7 @@ Built because manipulating strings is a real pain.
       - [Query with variables](#query-with-variables)
       - [Nested fields](#nested-fields)
       - [Enum args](#enum-args)
+    - [Fragment Support](#fragment-support)
   - [Contributing to this project](#contributing-to-this-project)
 
 <!-- /TOC -->
@@ -76,14 +76,15 @@ const query = {
 
 const options = {
   headers: {
-    "Authorization": "Bearer <token>"
+    Authorization: 'Bearer <token>'
   },
   debug: false,
   useHttp2: false
 }
 
-gotQL.query('mygraphqlendpoint.com.br/api', query, options)
-  .then(response => console.log(response.data))
+gotQL
+  .query('mygraphqlendpoint.com.br/api', query, options)
+  .then((response) => console.log(response.data))
   .catch(console.error)
 ```
 
@@ -119,7 +120,7 @@ const mutation = {
         id: variables.id
       }
     },
-    fields: [ 'uuid' ]
+    fields: ['uuid']
   }
 }
 ```
@@ -203,7 +204,7 @@ Both `gotql.query` and `gotql.mutation` accept an optional user option object wi
   - _useHttp2_: Boolean defining if the call should be made using HTTP2, defaults to `false` (see [release 11 of got](https://github.com/sindresorhus/got/releases/tag/v11.0.0))
     - Type: `boolean`
 
->**Note:** GotQL uses [`debug`](https://npmjs.com/package/debug) internally as default debugger, so you can set debug levels by setting the `DEBUG` environment variable. These are the current levels:
+> **Note:** GotQL uses [`debug`](https://npmjs.com/package/debug) internally as default debugger, so you can set debug levels by setting the `DEBUG` environment variable. These are the current levels:
 >
 > - `gotql:info`
 > - `gotql:info:parser`
@@ -287,7 +288,7 @@ const query = {
               - Example: `args { name: 'myName' }`
             - **_Detailed args_**: A tagged template. This will give more control over escaping (mostly to use enums). Argument name should be the key
               - Type: `tagged template`
-              - Examples: ```args: { status: literal`an_enum` }``` should output `operation (status: an_enum)...`
+              - Examples: `` args: { status: literal`an_enum` } `` should output `operation (status: an_enum)...`
         - _fields_: The field list to get back from the operation
           - Type: An `array` of `object` (to use nested fields) or `string`, or both.
           - Properties (for nested fields):
@@ -299,7 +300,9 @@ const query = {
                   - Example: `args { name: 'myName' }`
                 - **_Detailed args_**: A tagged template. This will give more control over escaping (mostly to use enums). Argument name should be the key
                   - Type: `tagged template`
-                  - Examples: ```args: { status: literal`an_enum` }``` should output `operation (status: an_enum)...`
+                  - Examples: `` args: { status: literal`an_enum` } `` should output `operation (status: an_enum)...`
+    - **_fragments_**: The fragments of the query, see [Fragments Support](#fragment-support) for more information
+      - Type: `string[]`
 
 ### Examples
 
@@ -466,7 +469,37 @@ If `literal` is omitted, or if `escape` is set to `true`, the output would be:
 query { users(type: "internal") { name age } }
 ```
 
-> **Note:** Variables such as described [here](#query-with-variables) will __not__ be recognized. If the arg object is not an `[argName]: value`, variables will not pass through the definition check (GotQL warns if a variable is not declared but used on operation).
+> **Note:** Variables such as described [here](#query-with-variables) will **not** be recognized. If the arg object is not an `[argName]: value`, variables will not pass through the definition check (GotQL warns if a variable is not declared but used on operation).
+
+### Fragment support
+
+Fragment support is in an alpha state (see #55), this means that, while the lib
+supports fragments, it's not as pretty or as tested as I'd like it to be, but
+PR's are welcome if you want to use it thoroughly.
+
+You can use fragments by adding a new key in the query JSON, besides
+`operation`, just like you do with variables. This key is called `fragments` and
+it's an array of strings that represent fragments in operations, for example:
+
+```js
+const query = {
+  operation: {
+    fields: ['f1']
+  },
+  fragments: [`fragment Test on Character { name id }`]
+}
+```
+
+You can then reference those fragments using the literal struct `fragment`:
+
+```js
+const query = {
+  operation: {
+    fields: [fragment`Test`]
+  },
+  fragments: [`fragment Test on Character { name id }`]
+}
+```
 
 ## Contributing to this project
 

diff --git a/jest.config.json b/jest.config.json
@@ -11,6 +11,7 @@
     "/coverage/",
     "/.devcontainer/",
     "/.nyc_output/",
-    "/.vscode/"
+    "/.vscode/",
+    "/src/helpers/index.ts"
   ]
 }