@ttoss/graphql-api 0.4.2 → 0.4.4

package/README.md

@@ -142,6 +142,14 @@ This packages provides the method `composeWithConnection` to create a connection
 ```typescript
 import { composeWithConnection } from '@ttoss/appsync-api';
 
+AuthorTC.addResolver({
+  name: 'findMany',
+  type: AuthorTC,
+  resolve: async ({ args }) => {
+    // find many
+  },
+});
+
 composeWithConnection(AuthorTC, {
   findManyResolver: AuthorTC.getResolver('findMany'),
   countResolver: AuthorTC.getResolver('count'),
@@ -160,10 +168,167 @@ composeWithConnection(AuthorTC, {
         rawQuery.id.$gt = cursorData.id;
       },
     },
+    DESC: {
+      value: {
+        scanIndexForward: false,
+      },
+      cursorFields: ['id'],
+      beforeCursorQuery: (rawQuery, cursorData, resolveParams) => {
+        if (!rawQuery.id) rawQuery.id = {};
+        rawQuery.id.$gt = cursorData.id;
+      },
+      afterCursorQuery: (rawQuery, cursorData, resolveParams) => {
+        if (!rawQuery.id) rawQuery.id = {};
+        rawQuery.id.$lt = cursorData.id;
+      },
+    },
   },
 });
+
+schemaComposer.Query.addFields({
+  authors: Authors.getResolver('connection'),
+});
+```
+
+When you `composeWithConnection` a type, it will add the resolver `connection` to the type, so you can add to `Query` or any other type:
+
+```ts
+schemaComposer.Query.addFields({
+  authors: Authors.getResolver('connection'),
+});
 ```
 
+The resolver `connection` has the following arguments based on the [Relay Connection Specification](https://facebook.github.io/relay/graphql/connections.htm):
+
+- `first`: the number of nodes to return.
+- `after`: the cursor to start the query.
+- `last`: the number of nodes to return.
+- `before`: the cursor to start the query.
+- `sort`: the sort option to use. It's the keys of the `sort` object. In our example, it's `ASC` and `DESC`.
+- `filter`: the filter to use. It'll exist if you add the `filter` to `findManyResolver` for example, the implementation below will add the `filter` argument with the `name` and `book` fields:
+
+  ```ts
+  AuthorTC.addResolver({
+    name: 'findMany',
+    type: AuthorTC,
+    args: {
+      filter: {
+        name: 'String',
+        book: 'String',
+      },
+    },
+    resolve: async ({ args }) => {
+      // find many
+    },
+  });
+  ```
+
+To configure `composeWithConnection`, you need to provide the following options:
+
+#### `findManyResolver`
+
+The resolver that will be used to find the nodes. It receives the following arguments:
+
+- `args`: the `args` object from the resolver. Example:
+
+  ```ts
+  AuthorTC.addResolver({
+    name: 'findMany',
+    type: AuthorTC,
+    args: {
+      filter: {
+        name: 'String',
+        book: 'String',
+      },
+    },
+    resolve: async ({
+      args,
+    }: {
+      args: {
+        first?: number;
+        after?: string;
+        last?: number;
+        before?: string;
+        /**
+         * The `filter` argument, if provided on the query.
+         */
+        filter: {
+          name: string;
+          book: string;
+        };
+        /**
+         * The `sort` argument, if provided on the query as
+         * they keys of the `sort` object. In our example
+         * above, it's `ASC` and `DESC`. `scanIndexForward`
+         * is the value of the `value` property on the sort
+         * object. In our example above, it's `true` for
+         * `ASC` and `false` for `DESC`.
+         */
+        sort: {
+          scanIndexForward: boolean;
+        };
+      };
+    }) => {
+      //
+    },
+  });
+  ```
+
+- `rawQuery`: an object created by `beforeCursorQuery` or `afterCursorQuery` methods from [sort](#sort) option.
+
+#### `countResolver`
+
+#### `sort`
+
+It's an object that defines the sort options. Each key is the sort name and the value is an object with the following properties:
+
+- `value`: and object that the resolver will receive as the `sort` argument.
+- `cursorFields`: an array of fields that will be used to create the cursor.
+- `beforeCursorQuery` and `afterCursorQuery`: methods that will be used to create the `rawQuery` object for the `findManyResolver`. They receive the following arguments:
+
+  - `rawQuery`: the `rawQuery` object that will be used to find the nodes.
+  - `cursorData`: the data from the cursor define on `cursorFields`. For example, if you define `cursorFields` as `['id', 'name']`, the `cursorData` will an object with the `id` and `name` properties.
+  - `resolveParams`: the `resolveParams` object from the resolver. You can access `args`, `context` and `info` and other GraphQL properties from this object.
+
+  Example:
+
+  ```ts
+  composeWithConnection(AuthorTC, {
+    // ...
+    sort: {
+      ASC: {
+        // ...
+        cursorFields: ['id', 'name'],
+        // Called when `before` cursor is provided.
+        beforeCursorQuery: (rawQuery, cursorData, resolveParams) => {
+          if (!rawQuery.id) rawQuery.id = {};
+          rawQuery.id.$lt = cursorData.id;
+          rawQuery.name.$lt = cursorData.name;
+        },
+        // Called when `after` cursor is provided.
+        afterCursorQuery: (rawQuery, cursorData, resolveParams) => {
+          if (!rawQuery.id) rawQuery.id = {};
+          rawQuery.id.$gt = cursorData.id;
+          rawQuery.name.$gt = cursorData.name;
+        },
+      },
+    },
+  });
+  ```
+
+  In the example above, the `findManyResolver` will receive the following `rawQuery` object when `before` cursor is provided:
+
+  ```json
+  {
+    "id": {
+      "$lt": "id-from-cursor"
+    },
+    "name": {
+      "$lt": "name-from-cursor"
+    }
+  }
+  ```
+
 ### Middlewares
 
 This package provides a way to add middlewares to your final schema. You can add middlewares compatible with [`graphql-middleware`](https://github.com/dimatill/graphql-middleware) by passing them to the `middlewares` option on `buildSchema` method. For example, you can use [GraphQL Shield](https://the-guild.dev/graphql/shield) to add authorization to your API:
@@ -210,7 +375,7 @@ This package re-exports the all methods from [GraphQL Shield](https://the-guild.
 import { allow, deny, shield } from '@ttoss/graphql-api/shield';
 ```
 
-## Building Schema
+## Building Schema and Types
 
 As Relay needs an introspection query to work, this package provides a way to build the GraphQL schema by running `ttoss-graphl-api build-schema`. It build the schema using the `schemaComposer` from `src/schemaComposer.ts` file and save the schema in `schema/schema.graphql` file and TypeScript types in `schema/types.ts` file.
 

package/dist/index.d.mts

@@ -27,4 +27,4 @@ type BuildSchemaInput<TContext = any> = {
 };
 declare const buildSchema: ({ schemaComposer, middlewares, }: BuildSchemaInput) => GraphQLSchema;
 
-export { BuildSchemaInput, buildSchema, composeWithRelay, fromGlobalId, toGlobalId };
+export { type BuildSchemaInput, buildSchema, composeWithRelay, fromGlobalId, toGlobalId };

package/dist/index.d.ts

@@ -27,4 +27,4 @@ type BuildSchemaInput<TContext = any> = {
 };
 declare const buildSchema: ({ schemaComposer, middlewares, }: BuildSchemaInput) => GraphQLSchema;
 
-export { BuildSchemaInput, buildSchema, composeWithRelay, fromGlobalId, toGlobalId };
+export { type BuildSchemaInput, buildSchema, composeWithRelay, fromGlobalId, toGlobalId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/graphql-api",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "A library for building GraphQL APIs using ttoss ecosystem.",
   "author": "ttoss",
   "contributors": [
@@ -47,11 +47,11 @@
     "graphql": "^16.6.0"
   },
   "devDependencies": {
-    "@types/yargs": "^17.0.24",
+    "@types/yargs": "^17.0.32",
     "graphql": "^16.8.1",
-    "jest": "^29.6.2",
-    "tsup": "^7.1.0",
-    "@ttoss/config": "^1.30.6"
+    "jest": "^29.7.0",
+    "tsup": "^8.0.1",
+    "@ttoss/config": "^1.31.1"
   },
   "keywords": [
     "api",