@graphitation/supermassive - npm Package Compare versions

Comparing version 0.2.0 to 0.3.0

bin/supermassive.js

 #!/usr/bin/env node
 
 (function () {
-  require("../lib/bin/supermassive").supermassive().parseAsync(process.argv);
+  require("../lib/cjs/bin/supermassive")
+    .supermassive()
+    .parseAsync(process.argv);
 })();

CHANGELOG.md

 # Change Log - @graphitation/supermassive
 
-This log was last generated on Fri, 26 Nov 2021 15:43:24 GMT and should not be manually modified.
+This log was last generated on Tue, 14 Dec 2021 10:06:07 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 0.3.0
+
+Tue, 14 Dec 2021 10:06:07 GMT
+
+### Minor changes
+
+- Support ESM in distro packages ([e-mail])
+
 ## 0.2.0
 
-Fri, 26 Nov 2021 15:43:24 GMT
+Fri, 26 Nov 2021 15:43:37 GMT
 
@@ -11,0 +19,0 @@ ### Minor changes

lib/executeWithSchema.js

@@ -43,6 +43,6 @@ var __create = Object.create;
 var import_graphql = __toModule(require("graphql"));
-var import__ = __toModule(require("."));
+var import_index = __toModule(require("./index"));
 function executeWithSchema({
   typeDefs,
-  resolvers: resolvers2,
+  resolvers,
   document: rawDocument,
@@ -56,6 +56,6 @@ rootValue,
 }) {
-  const schema = (0, import_schema.makeExecutableSchema)({typeDefs, resolvers: resolvers2});
+  const schema = (0, import_schema.makeExecutableSchema)({typeDefs, resolvers});
   let extractedResolvers = {};
   const getTypeByName = (name) => {
-    const type = import__.specifiedScalars[name] || extractedResolvers[name];
+    const type = import_index.specifiedScalars[name] || extractedResolvers[name];
     if ((0, import_graphql.isInputType)(type)) {
@@ -67,6 +67,6 @@ return type;
   };
-  extractedResolvers = (0, import__.extractImplicitTypes)(typeDefs, getTypeByName);
-  const fullResolvers = __objSpread(__objSpread({}, extractedResolvers), resolvers2);
-  const document = (0, import__.addTypesToRequestDocument)(schema, rawDocument);
-  return (0, import__.executeWithoutSchema)({
+  extractedResolvers = (0, import_index.extractImplicitTypes)(typeDefs, getTypeByName);
+  const fullResolvers = __objSpread(__objSpread({}, extractedResolvers), resolvers);
+  const document = (0, import_index.addTypesToRequestDocument)(schema, rawDocument);
+  return (0, import_index.executeWithoutSchema)({
     document,
@@ -73,0 +73,0 @@ resolvers: fullResolvers,

lib/index.d.ts

 export { executeWithoutSchema } from "./executeWithoutSchema";
 export { executeWithSchema } from "./executeWithSchema";
-export { Resolvers } from "./types";
+export type { Resolvers } from "./types";
 export { addTypesToRequestDocument } from "./ast/addTypesToRequestDocument";
@@ -5,0 +5,0 @@ export { extractImplicitTypes } from "./extractImplicitTypesRuntime";

lib/index.js

@@ -25,3 +25,2 @@ var __create = Object.create;
 __export(exports, {
-  Resolvers: () => import_types.Resolvers,
   addTypesToRequestDocument: () => import_addTypesToRequestDocument.addTypesToRequestDocument,
@@ -36,3 +35,2 @@ annotateDocumentGraphQLTransform: () => import_annotateDocumentGraphQLTransform.annotateDocumentGraphQLTransform,
 var import_executeWithSchema = __toModule(require("./executeWithSchema"));
-var import_types = __toModule(require("./types"));
 var import_addTypesToRequestDocument = __toModule(require("./ast/addTypesToRequestDocument"));
@@ -39,0 +37,0 @@ var import_extractImplicitTypesRuntime = __toModule(require("./extractImplicitTypesRuntime"));

package.json

 {
   "name": "@graphitation/supermassive",
   "license": "MIT",
-  "version": "0.2.0",
-  "main": "./lib/index",
+  "version": "0.3.0",
+  "bin": {
+    "supermassive": "./bin/supermassive.js"
+  },
+  "main": "./lib/index.js",
   "scripts": {
@@ -35,3 +38,10 @@ "build": "monorepo-scripts build",
   },
-  "types": "./lib/index.d.ts"
+  "types": "./lib/index.d.ts",
+  "module": "./lib/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./lib/index.mjs",
+      "require": "./lib/index.js"
+    }
+  }
 }

README.md

 # @graphitation/supermassive
 
-_Pack more performance into smaller space_
+_[Pack more performance into smaller space](https://en.wikipedia.org/wiki/Supermassive_black_hole)_
 
-Supermassive is lightweight schema-less GraphQL executor and query build-time compiler.
+Supermassive is a lightweight schema-less GraphQL executor and query build-time compiler.
 
-Running GraphQL executor on client can be expensive. Schema is a heavy object, typedefs, queries - it all can add up both in bundle size and performance. Supermassive aims to reduce that cost by removing the need to have a schema to run queries. It removes all runtime validation and accepts resolvers (like makeExecutableSchema resolvers) object. In addition it annotates GraphQL Documents to containt annotated type information. After that it proceeds to execute the queries without requiring actual schema. In future the plan is that GraphQL Documents are also eliminated and a inline functions are generated instead.
+## What
 
-There are 3 main parts of supermassive - the executor, query annotator and implicit resolver extractor. Executor is the part that actually runs the queries. It takes resolvers object instead of schema and annotated documents instead of normal documents. Query annotator processes query to include type information inside them. It can be ran as part of query extraction stage in Relay Compiler or eg in `@graphitation/graphql-js-tag`. Implicit resolver extractor writes out resolvers for types that are only implicitly defined in GraphQL SDL, like Unions or Input Objects. It generates typescript file with extracted object that can be merged with the rest of the resolvers.
+Supermassive's goals are to provide a solution with the following optimizations for when all GraphQL operations (queries, mutations, subscriptions) needed by the user-experiences are statically known at build-time:
 
+- Bundle size of production targets needs to be as small as possible.
+- Performance is favored over runtime validation.
+
+Such is the case in our scenarios, where our schema lives entirely in the client application and some of these applications have very little to no GraphQL needs [yet] other than to suffice the needs of a single or few components.
+
+## Why
+
+Running a GraphQL executor can be an expensive exercise. The JavaScript community has the good fortune of having the official reference implementation of the GraphQL specification being implemented in JavaScript, namely [graphql-js](http://github.com/graphql/graphql-js). Inevitably this means that most general purpose GraphQL libraries in the JavaScript ecosystem end up wrapping it or otherwise rely on it. However, graphql-js' goal is specifically to be an _all-encompassing_ implementation used for reference needs, _not_ to be an optimized solution for specific use-cases.
+
+## How
+
+Consider a GraphQL schema. It is typically a sizeable chunk of data, both in terms of type/field definition metadata as well as associated field-resolvers and _their_ code dependencies. Statically knowing all GraphQL operations allows us to reduce the bundle size to a minimum by [tree-shaking](https://en.wikipedia.org/wiki/Tree_shaking) all the definition metadata not required by any of the given operations. A JavaScript code bundler can in turn ensure only that code which is needed by the remaining field-resolvers is included in the production bundle. This means that the process is entirely dependency driven by needs expressed by the user-experiences, rather than requiring blunt manual configuration.
+
+Similarly, the GraphQL operations themselves, described using e.g. [GraphQL SDL](https://graphql.org/learn/schema/) or [`graphql-js` AST](https://github.com/graphql/graphql-js/blob/main/src/language/ast.ts), can incur quite some overhead as operations and number of operations grow. Eliminating these from the bundles can save size as well as runtime processing.
+
+## Roadmap
+
+### Phase 1
+
+In this initial phase, we will achieve the goal of tree-shaking the schema definitions. We do this by inlining required metadata into the documents that describe the operations, after which they can be executed with the need of the entire schema. This means overall bundle size will be decreased when only a subset of the schema is actually used, which pays off significantly when a host application introduces its first component(s) leveraging GraphQL.
+
+Consider a GraphQL operation like the following:
+
+```graphql
+query CurrentUserNameQuery {
+  me {
+    name
+  }
+}
+```
+
+This would lead to the following [conceptual] tree-shaking after compilation of the schema:
+
+```diff
+ type Query {
+   me: User!
+ }
+
+ type User {
+   name: String!
+-  presence: Presence!
+ }
+
+-type Presence {
+-  availability: PresenceAvailability!
+-}
+-
+-enum PresenceAvailability {
+-  AVAILABLE
+-  BUSY
+-  OFFLINE
+-}
+```
+
+...and the field-resolver map:
+
+```diff
+ import { getUser } from "user-service";
+-import { getUserPresence } from "presence-service";
+
+ const resolvers = {
+   Query: {
+     me: async (_source, _args, context) => getUser(context.currentUserId),
+   },
+   User: {
+     name: (source) => source.name,
+-    presence: async (source) => getUserPresence(source.id),
+   },
+ };
+```
+
+### Phase 2
+
+In this phase, we will expand on the previous phase by ahead-of-time compiling the resolution of the operations, their field-resolvers, and invocation thereof into JavaScript code. This essentially does away with any need for AST of the operation during execution. This means execution will be faster as no more generic lookups and checks need to be performed.
+
+Consider the GraphQL operation shown in the previous phase, typical generic execution (as [described in the specification](https://spec.graphql.org/June2018/#sec-Execution)) would look something like the following recursive pseudo-code:
+
+```ts
+function visitSelectionSet(parentType, selectionSet, parentSource) {
+  const result = {};
+  for (const selection of selectionSet.selections) {
+    switch (selection.kind) {
+      case "Field": {
+        const type = getType(selection.type.name);
+        if (isScalarType(type)) {
+          result[selection.name] = parentType.invokeFieldResolver(
+            selection.name,
+            parentSource
+          );
+        } else if (isObjectType(type)) {
+          const source = parentType.invokeFieldResolver(
+            selection.name,
+            parentSource
+          );
+          result[selection.name] = visitSelectionSet(
+            type,
+            selection.selectionSet,
+            source
+          );
+        } else {
+          // ...
+        }
+      }
+      // ...
+    }
+  }
+  return result;
+}
+
+function execute(query, rootSource = {}) {
+  return visitSelectionSet(getType("Query"), query.selectionSet, rootSource);
+}
+
+execute(
+  parse(`
+    query CurrentUserNameQuery {
+      me {
+        name
+      }
+    }
+  `)
+);
+```
+
+Whereas a compiled version of the specific operation would look something like the following:
+
+```ts
+function CurrentUserNameQuery(rootSource = {}) {
+  const meSource = QueryType.fieldResolvers["me"](rootSource);
+  const result = {
+    me: {
+      name: UserType.fieldResolvers["name"](meSource),
+    },
+  };
+  return result;
+}
+
+CurrentUserNameQuery();
+```
+
+### Phase 3
+
+In this final phase, we will make it possible to replace the operations at runtime using a simple identifier, thus allowing GraphQL clients to execute their operations using these identifiers that they obtain through a concept known as ["persisted queries"](https://relay.dev/docs/guides/persisted-queries/). This means that GraphQL clients that do not require graphql-js AST _themselves_ to operate, such as Relay, will be able to greatly reduce the size of the User-Experience bundles by entirely eliminating the document in favour of a short identifier.
+
+Again, considering the above GraphQL operation, a React component needing that data would include the GraphQL document in its bundle and look something like the following:
+
+```tsx
+function CurrentUser() {
+  const data = useQuery({
+    document: `
+      query CurrentUserNameQuery {
+        me {
+          name
+        }
+      }
+    `,
+  });
+  return <div>User: {data.me.name}</div>;
+}
+```
+
+However, now that we can compile the operation to code ahead-of-time, and no longer need the operation AST during execution, we can eliminate the document entirely and compile the component to refer to the compiled version of the document instead:
+
+```tsx
+function CurrentUser() {
+  const data = useQuery({
+    persistedDocumentId: "CurrentUserNameQuery",
+  });
+  return <div>User: {data.me.name}</div>;
+}
+```
+
 ## Usage
 
+There are 3 main parts of Supermassive - the executor, query annotator and implicit resolver extractor. Executor is the part that actually runs the queries. It takes resolvers object instead of schema and annotated documents instead of normal documents. Query annotator processes query to include type information inside them. It can be ran as part of query extraction stage in Relay Compiler or eg in `@graphitation/graphql-js-tag`. Implicit resolver extractor writes out resolvers for types that are only implicitly defined in GraphQL SDL, like Unions or Input Objects. It generates typescript file with extracted object that can be merged with the rest of the resolvers.
+
 ### Executor
@@ -43,3 +217,3 @@
 
-`addTypesToRequestDocument` converts untyped graphql-js AST node into a supermassive typed one.
+`addTypesToRequestDocument` converts untyped graphql-js AST node into a Supermassive typed one.
 
@@ -46,0 +220,0 @@ ```js

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 3 instances in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

268

increased by185.11%

Number of low supply chain risk alerts

7

decreased by-22.22%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Total package byte prevSize

262353

decreased by-84.08%

Number of package files

182

decreased by-7.61%

Lines of code

5565

decreased by-20.84%

No dependency changes