docs: add jsdoc to functions & interfaces

Author: nodkz

src/astToSchema.ts

@@ -16,11 +16,41 @@ import { GraphQLObjectType } from 'graphql';
 import { FieldConfig, NamespaceConfig } from './typeDefs';
 
 export interface AstToSchemaOptions {
+  /**
+   * Pass here already existed SchemaComposer instance
+   * which already contains some types (eg with custom Scalars).
+   *
+   * Or new SchemaComposer instance will be created.
+   */
   schemaComposer?: SchemaComposer<any>;
   prefix?: string;
   suffix?: string;
 }
 
+/**
+ * Transform AST to GraphQL Schema.
+ *
+ * @example
+ *   // Scan some directory for getting Schema entrypoints as AST nodes.
+ *   const ast = directoryToAst(module);
+ *
+ *   // [Optional] Combining severals ast into source
+ *   // Useful if some sub-schemas are delivered via packages
+ *   // or created n separate directories.
+ *   const newAST = astMerge(ast, ast1, ast2, ...);
+ *
+ *   // [Optional] Some `ast` modifications
+ *   // Useful for writing some middlewares
+ *   // which transform FieldConfigs entrypoints.
+ *   astVisitor(newAST, visitorFns);
+ *
+ *   // Create SchemaComposer instance with all populated types & fields
+ *   // It provides declarative programmatic access to modify you schema
+ *   const schemaComposer = astToSchema(newAST, opts);
+ *
+ *   // Create GraphQLSchema instance which is ready for runtime.
+ *   const schema = schemaComposer.buildSchema();;
+ */
 export function astToSchema<TContext = any>(
   ast: AstRootNode,
   opts: AstToSchemaOptions = {}

src/astVisitor.ts

@@ -7,12 +7,12 @@ import {
 } from './directoryToAst';
 
 /**
- * Do not traverse children
+ * Do not traverse children, and go to next sibling.
  */
 export const VISITOR_SKIP_CHILDREN = false;
 
 /**
- * Means remove Node from Ast and do not traverse children
+ * Remove Node from AST and do not traverse children.
  */
 export const VISITOR_REMOVE_NODE = null;
 
@@ -22,23 +22,44 @@ export type VisitorEmptyResult =
   | typeof VISITOR_SKIP_CHILDREN;
 
 export type VisitKindFn<NodeKind> = (
+  /** Information about `node` obtained in `directoryToAst()` */
   node: NodeKind,
+  /** Information from visitor during traversing AST tree */
   info: VisitInfo
 ) => VisitorEmptyResult | NodeKind;
 
+/**
+ * Functions for every type of AST nodes which will be called by visitor.
+ */
 export type AstVisitor = {
   DIR?: VisitKindFn<AstDirNode>;
   FILE?: VisitKindFn<AstFileNode>;
   ROOT_TYPE?: VisitKindFn<AstRootTypeNode>;
 };
 
 export interface VisitInfo {
+  /** Brunch of schema under which is working visitor. Can be: query, mutation, subscription */
   operation: RootTypeNames;
+  /** Parent AST node from directoryToAst */
   parent: AstDirNode | AstRootTypeNode | AstRootNode;
+  /** Name of field for current FieldConfig */
   name: string;
+  /** List of parent names starting from root */
   path: string[];
 }
 
+/**
+ * Traverse AST for applying modifications to DIRs, FILEs & ROOT_TYPEs
+ * Useful for writing middlewares which transform FieldConfigs entrypoints.
+ *
+ * @example
+ *   const ast = directoryToAst(module);
+ *   astVisitor(ast, {
+ *     ROOT_TYPE: () => {}, // run for query, mutation, subscription
+ *     DIR: () => {}, // executes on visiting DIR node
+ *     FILE: () => {}, // executes on visiting FILE node
+ *   });
+ */
 export function astVisitor(ast: AstRootNode, visitor: AstVisitor): void {
   (Object.keys(ast.children) as Array<keyof typeof ast.children>).forEach((operation) => {
     const rootNode = ast.children[operation];

src/directoryToAst.ts

@@ -2,13 +2,6 @@ import fs from 'fs';
 import { join, resolve, dirname, basename } from 'path';
 import { FieldConfig, NamespaceConfig } from './typeDefs';
 
-export interface DirectoryToAstOptions {
-  relativePath?: string;
-  extensions?: string[];
-  include?: RegExp | ((path: string, kind: 'dir' | 'file', filename: string) => boolean);
-  exclude?: RegExp | ((path: string, kind: 'dir' | 'file', filename: string) => boolean);
-}
-
 export type AstNodeKinds = 'rootType' | 'dir' | 'file' | 'root';
 
 export interface AstBaseNode {
@@ -51,6 +44,23 @@ export const defaultOptions: DirectoryToAstOptions = {
   extensions: ['js', 'ts'],
 };
 
+export interface DirectoryToAstOptions {
+  /** Scan relative directory to `module` which was provided as a first arg to directoryToAst method. By default `.` */
+  relativePath?: string;
+  /** Which file extensions should be loaded. By default: .js, .ts */
+  extensions?: string[];
+  /** Regexp or custom function which determines should be loaded file/dir or not */
+  include?: RegExp | ((path: string, kind: 'dir' | 'file', filename: string) => boolean);
+  /** Regexp or custom function which determines should file/dir be skipped. It take precedence over `include` option. */
+  exclude?: RegExp | ((path: string, kind: 'dir' | 'file', filename: string) => boolean);
+}
+
+/**
+ * Traverses directories and construct AST for your graphql entrypoints.
+ *
+ * @param m – is a NodeJS Module which provides a way to load modules from scanned dir in the regular nodejs way
+ * @param options – set of options which helps to customize rules of what files/dirs should be loaded or not
+ */
 export function directoryToAst(
   m: NodeModule,
   options: DirectoryToAstOptions = defaultOptions

src/index.ts

@@ -5,10 +5,22 @@ import { GraphQLSchema } from 'graphql';
 
 export interface BuildOptions extends DirectoryToAstOptions, AstToSchemaOptions {}
 
+/**
+ * Traverses directories and return GraphQLSchema instance from `graphql-js`.
+ *
+ * @param m – is a NodeJS Module which provides a way to load modules from scanned dir in the regular nodejs way
+ * @param options – set of options which helps to customize rules of what files/dirs should be loaded or not
+ */
 export function buildSchema(module: NodeModule, opts: BuildOptions = {}): GraphQLSchema {
   return loadSchemaComposer(module, opts).buildSchema();
 }
 
+/**
+ * Traverses directories and return SchemaComposer instance from `graphql-compose`.
+ *
+ * @param m – is a NodeJS Module which provides a way to load modules from scanned dir in the regular nodejs way
+ * @param options – set of options which helps to customize rules of what files/dirs should be loaded or not
+ */
 export function loadSchemaComposer<TContext = any>(
   module: NodeModule,
   opts: BuildOptions

src/typeDefs.ts

@@ -1,11 +1,47 @@
 import { ObjectTypeComposerFieldConfigAsObjectDefinition } from 'graphql-compose';
 
+/**
+ * General type annotation for default export of your modules inside schema directory.
+ *
+ * @example schema/query/ping.ts
+ *   import { FieldConfig } from 'graphql-compose-modules';
+ *
+ *   export default {
+ *     type: 'String',
+ *     resolve: () => 'pong',
+ *   } as FieldConfig;
+ */
 export type FieldConfig<
   TContext = any,
   TArgs = any,
   TSource = any
 > = ObjectTypeComposerFieldConfigAsObjectDefinition<TSource, TContext, TArgs>;
 
+/**
+ * Specific type annotation for index.ts files in you folders.
+ * index.ts files have specific purpose to extend or override
+ * automatically generated ObjectType for directory.
+ *
+ * For example you have the following structure in `schema` folder:
+ *   query/
+ *     viewer/
+ *       index.ts  <--- will extend/override definition of `viewer/` type
+ *       articles.ts  <--- just add a field with name `articles` to `viewer/` type
+ *
+ * So the next code extends logic of `viewer/` type
+ *   - provide custom name for generated type (instead of `Viewer` will be `AuthorizedUser`)
+ *   - if `context.user` is empty then return error in runtime to the client
+ * @example query/viewer/index.ts
+ *   import { NamespaceConfig } from 'graphql-compose-modules';
+ *
+ *   export default {
+ *     type: 'AuthorizedUser',
+ *     resolve: (parent, args, context, info) => {
+ *       if (!context.user) throw new Error('You should be authenticated user to access `viewer` field');
+ *       return {};
+ *     },
+ *   } as NamespaceConfig;
+ */
 export type NamespaceConfig<TContext = any, TArgs = any, TSource = any> = Partial<
   ObjectTypeComposerFieldConfigAsObjectDefinition<TSource, TContext, TArgs>
 >;