Update docs for new documentationjs version (#12615)

packages/gatsby/src/redux/actions.js

@@ -1173,14 +1173,16 @@ actions.addThirdPartySchema = (
   }
 }
 
+import type GatsbyGraphQLType from "../schema/types/type-builders"
 /**
  * Add type definitions to the GraphQL schema.
  *
- * @param {TypeDefinitions} types Type definitions, where `type TypeDefinitions = string | GraphQLOutputType | string[] | GraphQLOutputType[] | GatsbyGraphQLType`
+ * @param {string | GraphQLOutputType | GatsbyGraphQLType | string[] | GraphQLOutputType[] | GatsbyGraphQLType[]} types Type definitions
  *
  * Type definitions can be provided either as
  * [`graphql-js` types](https://graphql.org/graphql-js/), in
- * [GraphQL schema definition language (SDL)](https://graphql.org/learn/) or using Gatsby Type Builders.
+ * [GraphQL schema definition language (SDL)](https://graphql.org/learn/)
+ * or using Gatsby Type Builders available on the `schema` API argument.
  *
  * Things to note:
  * * needs to be called *before* schema generation. It is recommended to use
@@ -1193,7 +1195,7 @@ actions.addThirdPartySchema = (
  *   with inferred field types, and default field resolvers for `Date` (which
  *   adds formatting options) and `File` (which resolves the field value as
  *   a `relativePath` foreign-key field) are added. This behavior can be
- *   customised with `@infer` and `dontInfer` directives, and their
+ *   customised with `@infer` and `@dontInfer` directives, and their
  *   `noDefaultResolvers` argument.
  *
  * @example
@@ -1230,7 +1232,7 @@ actions.addThirdPartySchema = (
  *   createTypes(typeDefs)
  * }
  *
- * // using type builder API
+ * // using Gatsby Type Builder API
  * exports.sourceNodes = ({ actions, schema }) => {
  *   const { createTypes } = actions
  *   const typeDefs = [
@@ -1260,7 +1262,11 @@ actions.addThirdPartySchema = (
  * }
  */
 actions.createTypes = (
-  types: string | GraphQLOutputType | Array<string | GraphQLOutputType>,
+  types:
+    | string
+    | GraphQLOutputType
+    | GatsbyGraphQLType
+    | Array<string | GraphQLOutputType | GatsbyGraphQLType>,
   plugin: Plugin,
   traceId?: string
 ) => {

packages/gatsby/src/schema/node-model.js

@@ -11,22 +11,41 @@ const invariant = require(`invariant`)
 type IDOrNode = string | { id: string }
 type TypeOrTypeName = string | GraphQLOutputType
 
-interface ConnectionArgs {
+/**
+ * Optional page dependency information.
+ *
+ * @typedef {Object} PageDependencies
+ * @property {string} path The path of the page that depends on the retrieved nodes' data
+ * @property {string} [connectionType] Mark this dependency as a connection
+ */
+interface PageDependencies {
   path: string;
   connectionType?: string;
 }
 
+interface QueryArguments {
+  type: TypeOrTypeName;
+  query: { filter: Object, sort?: Object, skip?: number, limit?: number };
+  firstOnly?: boolean;
+}
+
 export interface NodeModel {
   getNodeById(
     { id: IDOrNode, type?: TypeOrTypeName },
-    ConnectionArgs
+    pageDependencies?: PageDependencies
   ): any | null;
   getNodesByIds(
     { ids: Array<IDOrNode>, type?: TypeOrTypeName },
-    ConnectionArgs
+    pageDependencies?: PageDependencies
+  ): Array<any>;
+  getAllNodes(
+    { type?: TypeOrTypeName },
+    pageDependencies?: PageDependencies
   ): Array<any>;
-  getAllNodes({ type?: TypeOrTypeName }, ConnectionArgs): Array<any>;
-  runQuery(args: any): Promise<any>;
+  runQuery(
+    args: QueryArguments,
+    pageDependencies?: PageDependencies
+  ): Promise<any>;
   getTypes(): Array<string>;
 }
 
@@ -38,14 +57,6 @@ class LocalNodeModel {
     this.path = path
   }
 
-  /**
-   * Optional page dependency information.
-   *
-   * @typedef {Object} PageDependencies
-   * @property {string} path
-   * @property {string} [connectionType]
-   */
-
   /**
    * Get a node from the store by ID and optional type.
    *
@@ -83,7 +94,7 @@ class LocalNodeModel {
    * @param {Object} args
    * @param {string[]} args.ids IDs of the requested nodes
    * @param {(string|GraphQLOutputType)} [args.type] Optional type of the nodes
-   * @param {PageDependencies} [pageDependencies]   *
+   * @param {PageDependencies} [pageDependencies]
    * @returns {Node[]}
    */
   getNodesByIds(args, pageDependencies) {
@@ -113,7 +124,7 @@ class LocalNodeModel {
    *
    * @param {Object} args
    * @param {(string|GraphQLOutputType)} [args.type] Optional type of the nodes
-   * @param {PageDependencies} [pageDependencies]   *
+   * @param {PageDependencies} [pageDependencies]
    * @returns {Node[]}
    */
   getAllNodes(args, pageDependencies) {
@@ -142,10 +153,10 @@ class LocalNodeModel {
    * Get nodes of a type matching the specified query.
    *
    * @param {Object} args
-   * @param {Object} args.query Query arguments
+   * @param {Object} args.query Query arguments (`filter`, `sort`, `limit`, `skip`)
    * @param {(string|GraphQLOutputType)} args.type Type
    * @param {boolean} [args.firstOnly] If true, return only first match
-   * @param {PageDependencies} [pageDependencies]   *
+   * @param {PageDependencies} [pageDependencies]
    * @returns {Promise<Node[]>}
    */
   async runQuery(args, pageDependencies) {
@@ -206,12 +217,12 @@ class LocalNodeModel {
    * Get the root ancestor node for an object's parent node, or its first
    * ancestor matching a specified condition.
    *
-   * @param {Object} obj The object you want to retrieve an ancestor node for
+   * @param {(Object|Array)} obj An object belonging to a Node, or a Node object
    * @param {Function} [predicate] Optional condition to match
    * @returns {(Node|null)}
    */
-  findRootNodeAncestor(...args) {
-    return this.nodeStore.findRootNodeAncestor(...args)
+  findRootNodeAncestor(obj, predicate) {
+    return this.nodeStore.findRootNodeAncestor(obj, predicate)
   }
 }
 

packages/gatsby/src/utils/api-node-docs.js

@@ -250,7 +250,7 @@ exports.setFieldsOnGraphQLNodeType = true
  *         resolve: (source, args, context, info) => {
  *           const posts = context.nodeModel.getAllNodes({ type: `BlogPost` })
  *           const recentPosts = posts.filter(
- *             post => post.publishedAt > Date.UTC(2018, 0 , 1)
+ *             post => post.publishedAt > Date.UTC(2018, 0, 1)
  *           )
  *           return recentPosts
  *         }

www/src/pages/docs/node-model.js

@@ -3,8 +3,9 @@ import { graphql } from "gatsby"
 import { Helmet } from "react-helmet"
 import sortBy from "lodash/sortBy"
 
-import Functions from "../../components/function-list"
-import { rhythm, scale } from "../../utils/typography"
+import APIReference from "../../components/api-reference"
+import { rhythm } from "../../utils/typography"
+import { space } from "../../utils/presets"
 import Layout from "../../components/layout"
 import Container from "../../components/container"
 import { itemListDocs } from "../../utils/sidebar/item-list"
@@ -14,7 +15,7 @@ class NodeModelDocs extends React.Component {
     const funcs = sortBy(
       this.props.data.file.childrenDocumentationJs,
       func => func.name
-    )
+    ).filter(func => !func.type) // Filter out @typedef
     return (
       <Layout location={this.props.location} itemList={itemListDocs}>
         <Container>
@@ -28,19 +29,43 @@ class NodeModelDocs extends React.Component {
             Gatsby exposes its internal data store and query capabilities to
             GraphQL field resolvers on <code>context.nodeModel</code>.
           </p>
+          <div className="gatsby-code-title">Example usage</div>
+          <div className="gatsby-highlight">
+            <pre
+              className="language-javascript"
+              dangerouslySetInnerHTML={{
+                __html:
+                  `<code class="language-javascript">\n` +
+                  `<span class="token function">createResolvers</span><span class="token punctuation">(</span><span class="token punctuation">{</span>\n` +
+                  `  Query<span class="token punctuation">:</span> <span class="token punctuation">{</span>\n` +
+                  `    mood<span class="token punctuation">:</span> <span class="token punctuation">{</span>\n` +
+                  `      type<span class="token punctuation">:</span> <span class="token template-string"><span class="token string">\`String\`</span></span><span class="token punctuation">,</span>\n` +
+                  `      <span class="token function">resolve</span><span class="token punctuation">(</span><span class="token parameter">source<span class="token punctuation">,</span> args<span class="token punctuation">,</span> context<span class="token punctuation">,</span> info</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>\n` +
+                  `        <span class="token keyword">const</span> coffee <span class="token operator">=</span> context<span class="token punctuation">.</span>nodeModel<span class="token punctuation">.</span><span class="token function">getAllNodes</span><span class="token punctuation">(</span><span class="token punctuation">{</span> type<span class="token punctuation">:</span> <span class="token template-string"><span class="token string">\`Coffee\`</span></span> <span class="token punctuation">}</span><span class="token punctuation">)</span>\n` +
+                  `        <span class="token keyword">if</span> <span class="token punctuation">(</span><span class="token operator">!</span>coffee<span class="token punctuation">.</span>length<span class="token punctuation">)</span> <span class="token punctuation">{</span>\n` +
+                  `          <span class="token keyword">return</span> 😞\n` +
+                  `        <span class="token punctuation">}</span>\n` +
+                  `        <span class="token keyword">return</span> 😊\n` +
+                  `      <span class="token punctuation">}</span><span class="token punctuation">,</span>\n` +
+                  `    <span class="token punctuation">}</span><span class="token punctuation">,</span>\n` +
+                  `  <span class="token punctuation">}</span><span class="token punctuation">,</span>\n` +
+                  `<span class="token punctuation">}</span><span class="token punctuation">)</span>\n` +
+                  `</code>`,
+              }}
+            />
+          </div>
           <hr />
-          <h2 css={{ marginBottom: rhythm(1 / 2) }}>Methods</h2>
-          <ul css={{ ...scale(-1 / 5) }}>
+          <h2 css={{ marginBottom: rhythm(space[3]) }}>Methods</h2>
+          <ul>
             {funcs.map((node, i) => (
               <li key={`function list ${node.name}`}>
                 <a href={`#${node.name}`}>{node.name}</a>
               </li>
             ))}
           </ul>
-          <br />
           <hr />
           <h2>Reference</h2>
-          <Functions functions={funcs} />
+          <APIReference docs={funcs} />
         </Container>
       </Layout>
     )
@@ -51,10 +76,10 @@ export default NodeModelDocs
 
 export const pageQuery = graphql`
   query {
-    file(relativePath: { regex: "/src.*node-model.js/" }) {
+    file(relativePath: { eq: "gatsby/src/schema/node-model.js" }) {
       childrenDocumentationJs {
         name
-        ...FunctionList
+        ...DocumentationFragment
       }
     }
   }