@ttoss/graphql-api 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# @ttoss/graphql-api
+
+This package provides an opinionated way to create an GraphQL API using ttoss ecosystem modules. The main goal of this package is to provide a resilient way to create a complex GraphQL API to meet the following goals:
+
+1. **Modular**: you can create your GraphQL API using modules, so you can reduce the complexity of a big GraphQL API.
+1. **Relay**: ttoss uses Relay as the main GraphQL client, so this package implements the [Relay Server Specification](https://relay.dev/docs/guides/graphql-server-specification/).
+1. **Build Schema**: 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`.
+1. **AppSync Support**: this package provides a way to create a GraphQL API that works with AWS AppSync, besides you can also create a local GraphQL API server.
+
+## Installation
+
+```bash
+pnpm add @ttoss/graphql-api graphql
+```
+
+## Getting Started
+
+This library uses [`graphql-compose`](https://graphql-compose.github.io/) to create the GraphQL schema. It re-export all the [`graphql-compose`](https://graphql-compose.github.io/) types and methods, so you can use it directly from this package.
+
+### Type Creation
+
+For more examples about how to create types, check the [`graphql-compose`](https://graphql-compose.github.io/docs/basics/understanding-types.html) documentation.
+
+```ts
+import { schemaComposer } from '@ttoss/graphql-api';
+
+const UserTC = schemaComposer.createObjectTC({
+  name: 'User',
+  fields: {
+    id: 'ID!',
+    name: 'String!',
+  },
+});
+```
+
+### Resolvers
+
+### Integrate All Modules
+
+Once you've created all your types and resolvers, you can integrate all the modules to create the GraphQL schema.
+
+```ts title="src/schemaComposer.ts"
+// scr/schemaComposer.ts
+import { schemaComposer } from '@ttoss/graphql-api';
+import './modules/Module1/composer';
+import './modules/Module3/composer';
+import './modules/User/composer';
+
+export { schemaComposer };
+```
+
+## Relay Server Specification
+
+As ttoss uses Relay as the main GraphQL client, this library implements the [Relay Server Specification](https://relay.dev/docs/guides/graphql-server-specification/).
+
+### Object Identification
+
+Method `composeWithRelay` will handle the object identification for your `ObjectTypeComposer`, it will return a globally unique ID among all types in the following format `base64(TypeName + ':' + recordId)`.
+
+Method `composeWithRelay` only works if `ObjectTypeComposer` meets the following requirements:
+
+1. Has defined `recordIdFn`: returns the id for the globalId construction. For example, if you use DynamoDB, you could create id from hash and range keys:
+
+   ```ts
+   UserTC.setRecordIdFn((source) => {
+     return `${source.hashKey}:${source.rangeKey}`;
+   });
+   ```
+
+2. Have `findById` resolver: this resolver will be used by `RootQuery.node` to resolve the object by globalId. For example:
+
+   ```ts
+   UserTC.addResolver({
+     name: 'findById',
+     type: UserTC,
+     args: {
+       id: 'String!',
+     },
+     resolve: ({ args }) => {
+       const { type, recordId } = fromGlobalId(args.id);
+       // find object
+     },
+   });
+   ```
+
+#### Example
+
+```ts
+import {
+  composeWithRelay,
+  schemaComposer,
+  fromGlobalId,
+} from '@ttoss/graphql-api';
+
+const UserTC = schemaComposer.createObjectTC({
+  name: 'User',
+  fields: {
+    id: 'ID!',
+    name: 'String!',
+  },
+});
+
+/**
+ * 1. Returns you id for the globalId construction.
+ */
+UserTC.setRecordIdFn((source) => {
+  /**
+   * If you use DynamoDB, you could create id from hash and range keys:
+   * return `${source.hashKey}:${source.rangeKey}`;
+   */
+  return source.id;
+});
+
+/**
+ * 2. Define `findById` resolver (that will be used by `RootQuery.node`).
+ */
+UserTC.addResolver({
+  name: 'findById',
+  type: UserTC,
+  args: {
+    id: 'String!',
+  },
+  resolve: ({ args }) => {
+    const { type, recordId } = fromGlobalId(args.id);
+    // find object
+  },
+});
+
+/**
+ * 3. This will add the `id` field and the `node` query.
+ */
+composeWithRelay(UserTC);
+```
+
+_We inspired ourselves on [graphql-compose-relay](https://graphql-compose.github.io/docs/plugins/plugin-relay.html) to create `composeWithRelay`._
+
+## Building Schema
+
+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`.
+
+```bash
+ttoss-graphl-api build-schema
+```
+
+## Server
+
+This package provides a Koa server to run your GraphQL API. You can use the `createServer` method to create the server.
+
+```ts
+import { createServer } from '@ttoss/graphql-api/server';
+
+const server = createServer({
+  schemaComposer,
+  graphiql: true,
+});
+
+server.listen(3000, () => {
+  console.log('Server listening on port 3000');
+});
+```

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli.js');

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export { }

package/dist/cli.js

@@ -0,0 +1,51 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+"use strict";
+
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+// If the importer is in node compatibility mode or this is not an ESM
+// file that has been converted to a CommonJS file using a Babel-
+// compatible transform (i.e. "__esModule" has not been set), then set
+// "default" to the CommonJS "module.exports" for node compatibility.
+isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+  value: mod,
+  enumerable: true
+}) : target, mod));
+
+// src/cli.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_ts_node = require("ts-node");
+var import_npmlog = __toESM(require("npmlog"));
+var import_yargs = __toESM(require("yargs"));
+var logPrefix = "graphql-api";
+(0, import_ts_node.register)({
+  transpileOnly: true
+});
+var argv = (0, import_yargs.default)(process.argv.slice(2)).argv;
+if (argv._.includes("build-schema")) {
+  import_npmlog.default.info(logPrefix, "Building schema...");
+  const {
+    schemaComposer
+  } = require(path.resolve(process.cwd(), "src", "schemaComposer.ts"));
+  const sdl = schemaComposer.toSDL();
+  fs.mkdirSync("schema", {
+    recursive: true
+  });
+  fs.writeFileSync("schema/schema.graphql", sdl);
+  import_npmlog.default.info(logPrefix, "Schema built.");
+}

package/dist/esm/chunk-SAO2ACBY.js

@@ -0,0 +1,8 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+var __require = /* @__PURE__ */(x => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function (x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw new Error('Dynamic require of "' + x + '" is not supported');
+});
+export { __require };

package/dist/esm/cli.js

@@ -0,0 +1,26 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { __require } from "./chunk-SAO2ACBY.js";
+
+// src/cli.ts
+import * as fs from "fs";
+import * as path from "path";
+import { register } from "ts-node";
+import log from "npmlog";
+import yargs from "yargs";
+var logPrefix = "graphql-api";
+register({
+  transpileOnly: true
+});
+var argv = yargs(process.argv.slice(2)).argv;
+if (argv._.includes("build-schema")) {
+  log.info(logPrefix, "Building schema...");
+  const {
+    schemaComposer
+  } = __require(path.resolve(process.cwd(), "src", "schemaComposer.ts"));
+  const sdl = schemaComposer.toSDL();
+  fs.mkdirSync("schema", {
+    recursive: true
+  });
+  fs.writeFileSync("schema/schema.graphql", sdl);
+  log.info(logPrefix, "Schema built.");
+}

package/dist/esm/index.js

@@ -0,0 +1,156 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import "./chunk-SAO2ACBY.js";
+
+// src/composeWithRelay/composeWithRelay.ts
+import { ObjectTypeComposer } from "graphql-compose";
+
+// src/composeWithRelay/nodeFieldConfig.ts
+import { getProjectionFromAST } from "graphql-compose";
+
+// src/composeWithRelay/globalId.ts
+var base64 = i => {
+  return Buffer.from(i, "ascii").toString("base64");
+};
+var unbase64 = i => {
+  return Buffer.from(i, "base64").toString("ascii");
+};
+var toGlobalId = (type, recordId) => {
+  return base64([type, recordId].join(":"));
+};
+var fromGlobalId = globalId => {
+  const unbasedGlobalId = unbase64(globalId);
+  const [type, recordId] = unbasedGlobalId.split(":");
+  return {
+    type,
+    recordId
+  };
+};
+
+// src/composeWithRelay/nodeFieldConfig.ts
+var getNodeFieldConfig = (typeMapForRelayNode, nodeInterface) => {
+  return {
+    description: "Fetches an object that has globally unique ID among all types",
+    type: nodeInterface,
+    args: {
+      id: {
+        type: "ID!",
+        description: "The globally unique ID among all types"
+      }
+    },
+    resolve: (source, args, context, info) => {
+      if (!args.id || !(typeof args.id === "string")) {
+        return null;
+      }
+      const {
+        type
+      } = fromGlobalId(args.id);
+      if (!typeMapForRelayNode[type]) {
+        return null;
+      }
+      const {
+        tc,
+        resolver: findById
+      } = typeMapForRelayNode[type];
+      if (findById && findById.resolve && tc) {
+        const graphqlType = tc.getType();
+        let projection;
+        if (info) {
+          projection = getProjectionFromAST({
+            ...info,
+            returnType: graphqlType
+          });
+        } else {
+          projection = {};
+        }
+        const idArgName = Object.keys(findById.args)[0];
+        return findById.resolve({
+          source,
+          args: {
+            [idArgName]: args.id
+          },
+          // eg. mongoose has _id fieldname, so should map
+          context,
+          info,
+          projection
+        }).then(res => {
+          if (!res) return res;
+          res.__nodeType = graphqlType;
+          return res;
+        });
+      }
+      return null;
+    }
+  };
+};
+
+// src/composeWithRelay/nodeInterface.ts
+import { InterfaceTypeComposer } from "graphql-compose";
+var NodeTC = InterfaceTypeComposer.createTemp({
+  name: "Node",
+  description: "An object, that can be fetched by the globally unique ID among all types.",
+  fields: {
+    id: {
+      type: "ID!",
+      description: "The globally unique ID among all types."
+    }
+  },
+  resolveType: payload => {
+    return payload.__nodeType.name ? payload.__nodeType.name : null;
+  }
+});
+var NodeInterface = NodeTC.getType();
+var getNodeInterface = sc => {
+  if (sc.hasInstance("Node", InterfaceTypeComposer)) {
+    return sc.get("Node");
+  }
+  sc.set("Node", NodeTC);
+  return NodeTC;
+};
+
+// src/composeWithRelay/composeWithRelay.ts
+var TypeMapForRelayNode = {};
+var composeWithRelay = tc => {
+  if (!(tc instanceof ObjectTypeComposer)) {
+    throw new Error("You should provide ObjectTypeComposer instance to composeWithRelay method");
+  }
+  const nodeInterface = getNodeInterface(tc.schemaComposer);
+  const nodeFieldConfig = getNodeFieldConfig(TypeMapForRelayNode, nodeInterface);
+  if (tc.getTypeName() === "Query" || tc.getTypeName() === "RootQuery") {
+    tc.setField("node", nodeFieldConfig);
+    return tc;
+  }
+  if (tc.getTypeName() === "Mutation" || tc.getTypeName() === "RootMutation") {
+    return tc;
+  }
+  if (!tc.hasRecordIdFn()) {
+    throw new Error(`ObjectTypeComposer(${tc.getTypeName()}) should have recordIdFn. This function returns ID from provided object.`);
+  }
+  const findById = tc.getResolver("findById");
+  if (!findById) {
+    throw new Error(`ObjectTypeComposer(${tc.getTypeName()}) provided to composeWithRelay should have findById resolver.`);
+  }
+  TypeMapForRelayNode[tc.getTypeName()] = {
+    resolver: findById,
+    tc
+  };
+  tc.addFields({
+    id: {
+      type: "ID!",
+      description: "The globally unique ID among all types",
+      resolve: source => {
+        return toGlobalId(tc.getTypeName(), tc.getRecordId(source));
+      }
+    }
+  });
+  tc.addInterface(nodeInterface);
+  return tc;
+};
+
+// src/composeWithRelay/index.ts
+import { schemaComposer } from "graphql-compose";
+composeWithRelay(schemaComposer.Query);
+
+// src/index.ts
+import { default as default2 } from "graphql-compose-connection";
+export * from "graphql-compose";
+export { default2 as composeWithConnection, composeWithRelay, fromGlobalId, toGlobalId };

package/dist/esm/server.js

@@ -0,0 +1,46 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import "./chunk-SAO2ACBY.js";
+
+// src/server.ts
+import { getGraphQLParameters, processRequest, renderGraphiQL, sendResult, shouldRenderGraphiQL } from "graphql-helix";
+import Koa from "koa";
+import Router from "@koa/router";
+import bodyParser from "koa-bodyparser";
+var createServer = ({
+  schemaComposer,
+  graphiql = false
+}) => {
+  const server = new Koa();
+  const router = new Router();
+  server.use(bodyParser());
+  router.all("/graphql", async ctx => {
+    const request = {
+      body: ctx.request.body,
+      headers: ctx.headers,
+      method: ctx.method,
+      query: ctx.request.query
+    };
+    if (shouldRenderGraphiQL(request)) {
+      if (graphiql) {
+        ctx.body = renderGraphiQL({});
+      }
+      return;
+    }
+    const {
+      operationName,
+      query,
+      variables
+    } = getGraphQLParameters(request);
+    const result = await processRequest({
+      operationName,
+      query,
+      variables,
+      request,
+      schema: schemaComposer.buildSchema()
+    });
+    sendResult(result, ctx.res);
+  });
+  server.use(router.routes()).use(router.allowedMethods());
+  return server;
+};
+export { Router, createServer };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { ObjectTypeComposer } from 'graphql-compose';
+export * from 'graphql-compose';
+export { default as composeWithConnection } from 'graphql-compose-connection';
+
+declare const composeWithRelay: <TContext>(tc: ObjectTypeComposer<any, TContext>) => ObjectTypeComposer<any, TContext>;
+
+type ResolvedGlobalId = {
+    type: string;
+    recordId: string;
+};
+/**
+ * Takes a type name and an ID specific to that type name, and returns a
+ * "global ID" that is unique among all types.
+ */
+declare const toGlobalId: (type: string, recordId: string | number) => string;
+/**
+ * Takes the "global ID" created by toGlobalID, and returns the type name and ID
+ * used to create it.
+ */
+declare const fromGlobalId: (globalId: string) => ResolvedGlobalId;
+
+export { composeWithRelay, fromGlobalId, toGlobalId };

package/dist/index.js

@@ -0,0 +1,207 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+"use strict";
+
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, {
+    get: all[name],
+    enumerable: true
+  });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+// If the importer is in node compatibility mode or this is not an ESM
+// file that has been converted to a CommonJS file using a Babel-
+// compatible transform (i.e. "__esModule" has not been set), then set
+// "default" to the CommonJS "module.exports" for node compatibility.
+isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+  value: mod,
+  enumerable: true
+}) : target, mod));
+var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
+  value: true
+}), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  composeWithConnection: () => import_graphql_compose_connection.default,
+  composeWithRelay: () => composeWithRelay,
+  fromGlobalId: () => fromGlobalId,
+  toGlobalId: () => toGlobalId
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/composeWithRelay/composeWithRelay.ts
+var import_graphql_compose3 = require("graphql-compose");
+
+// src/composeWithRelay/nodeFieldConfig.ts
+var import_graphql_compose = require("graphql-compose");
+
+// src/composeWithRelay/globalId.ts
+var base64 = i => {
+  return Buffer.from(i, "ascii").toString("base64");
+};
+var unbase64 = i => {
+  return Buffer.from(i, "base64").toString("ascii");
+};
+var toGlobalId = (type, recordId) => {
+  return base64([type, recordId].join(":"));
+};
+var fromGlobalId = globalId => {
+  const unbasedGlobalId = unbase64(globalId);
+  const [type, recordId] = unbasedGlobalId.split(":");
+  return {
+    type,
+    recordId
+  };
+};
+
+// src/composeWithRelay/nodeFieldConfig.ts
+var getNodeFieldConfig = (typeMapForRelayNode, nodeInterface) => {
+  return {
+    description: "Fetches an object that has globally unique ID among all types",
+    type: nodeInterface,
+    args: {
+      id: {
+        type: "ID!",
+        description: "The globally unique ID among all types"
+      }
+    },
+    resolve: (source, args, context, info) => {
+      if (!args.id || !(typeof args.id === "string")) {
+        return null;
+      }
+      const {
+        type
+      } = fromGlobalId(args.id);
+      if (!typeMapForRelayNode[type]) {
+        return null;
+      }
+      const {
+        tc,
+        resolver: findById
+      } = typeMapForRelayNode[type];
+      if (findById && findById.resolve && tc) {
+        const graphqlType = tc.getType();
+        let projection;
+        if (info) {
+          projection = (0, import_graphql_compose.getProjectionFromAST)({
+            ...info,
+            returnType: graphqlType
+          });
+        } else {
+          projection = {};
+        }
+        const idArgName = Object.keys(findById.args)[0];
+        return findById.resolve({
+          source,
+          args: {
+            [idArgName]: args.id
+          },
+          // eg. mongoose has _id fieldname, so should map
+          context,
+          info,
+          projection
+        }).then(res => {
+          if (!res) return res;
+          res.__nodeType = graphqlType;
+          return res;
+        });
+      }
+      return null;
+    }
+  };
+};
+
+// src/composeWithRelay/nodeInterface.ts
+var import_graphql_compose2 = require("graphql-compose");
+var NodeTC = import_graphql_compose2.InterfaceTypeComposer.createTemp({
+  name: "Node",
+  description: "An object, that can be fetched by the globally unique ID among all types.",
+  fields: {
+    id: {
+      type: "ID!",
+      description: "The globally unique ID among all types."
+    }
+  },
+  resolveType: payload => {
+    return payload.__nodeType.name ? payload.__nodeType.name : null;
+  }
+});
+var NodeInterface = NodeTC.getType();
+var getNodeInterface = sc => {
+  if (sc.hasInstance("Node", import_graphql_compose2.InterfaceTypeComposer)) {
+    return sc.get("Node");
+  }
+  sc.set("Node", NodeTC);
+  return NodeTC;
+};
+
+// src/composeWithRelay/composeWithRelay.ts
+var TypeMapForRelayNode = {};
+var composeWithRelay = tc => {
+  if (!(tc instanceof import_graphql_compose3.ObjectTypeComposer)) {
+    throw new Error("You should provide ObjectTypeComposer instance to composeWithRelay method");
+  }
+  const nodeInterface = getNodeInterface(tc.schemaComposer);
+  const nodeFieldConfig = getNodeFieldConfig(TypeMapForRelayNode, nodeInterface);
+  if (tc.getTypeName() === "Query" || tc.getTypeName() === "RootQuery") {
+    tc.setField("node", nodeFieldConfig);
+    return tc;
+  }
+  if (tc.getTypeName() === "Mutation" || tc.getTypeName() === "RootMutation") {
+    return tc;
+  }
+  if (!tc.hasRecordIdFn()) {
+    throw new Error(`ObjectTypeComposer(${tc.getTypeName()}) should have recordIdFn. This function returns ID from provided object.`);
+  }
+  const findById = tc.getResolver("findById");
+  if (!findById) {
+    throw new Error(`ObjectTypeComposer(${tc.getTypeName()}) provided to composeWithRelay should have findById resolver.`);
+  }
+  TypeMapForRelayNode[tc.getTypeName()] = {
+    resolver: findById,
+    tc
+  };
+  tc.addFields({
+    id: {
+      type: "ID!",
+      description: "The globally unique ID among all types",
+      resolve: source => {
+        return toGlobalId(tc.getTypeName(), tc.getRecordId(source));
+      }
+    }
+  });
+  tc.addInterface(nodeInterface);
+  return tc;
+};
+
+// src/composeWithRelay/index.ts
+var import_graphql_compose4 = require("graphql-compose");
+composeWithRelay(import_graphql_compose4.schemaComposer.Query);
+
+// src/index.ts
+var import_graphql_compose_connection = __toESM(require("graphql-compose-connection"));
+__reExport(src_exports, require("graphql-compose"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  composeWithConnection,
+  composeWithRelay,
+  fromGlobalId,
+  toGlobalId
+});