autnam 1.0.0

package/docs/build-typedoc.js

@@ -0,0 +1,434 @@
+const spawn = require("cross-spawn");
+const { join } = require("path");
+const { readFile, writeFile } = require("fs");
+const _ = require("lodash");
+const OUTPUT = join(process.cwd(), "docs", "src", `typedoc.json`);
+const { prettyifyUrl } = require("acetate/lib/utils.js");
+const slug = require("slug");
+const minimatch = require("minimatch");
+const cheerio = require("cheerio");
+const MarkdownIt = require("markdown-it");
+const md = new MarkdownIt();
+
+(function generateTypeDoc() {
+  return (
+    new Promise((resolve, reject) => {
+      const typedoc = spawn(
+        "typedoc",
+        [
+          "-json",
+          OUTPUT,
+          "--exclude",
+          "**/*test.ts",
+          "--tsconfig",
+          "./tsconfig.json",
+          "--excludePrivate"
+        ],
+        {
+          stdio: "inherit"
+        }
+      );
+
+      typedoc.on("close", (code) => {
+        if (code !== 0) {
+          reject(code);
+          return;
+        }
+
+        readFile(OUTPUT, (error, content) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+
+          resolve(JSON.parse(content.toString()));
+        });
+      });
+    })
+      .then((json) => {
+        /**
+         * `json.children` will be a list of all TypeScript files in our project.
+         * We dont care about the files, we just need all their children so we reduce
+         * to a single list of everything in the entire project.
+         */
+        return json.children.reduce(
+          (allChildren, fileChildren) => allChildren.concat(fileChildren),
+          []
+        );
+      })
+      .then((children) => {
+        /**
+         * We dont want TypeScript files that have been symlinked into `node_modules`
+         * folders by Lerna so ignore any child whose source file has `node_modules`
+         * in its `fileName`
+         */
+
+        return children.filter(
+          (c) => !minimatch(c.sources[0].fileName, "**/node_modules/**")
+        );
+      })
+      .then((children) => {
+        /**
+         * We now only want children that are actual source files, not tests, so
+         * filter out all children without `src` in their path.
+         */
+        return children.filter((c) =>
+          minimatch(c.sources[0].fileName, "**/src/**/*.ts")
+        );
+      })
+      .then((children) => {
+        /**
+         * Some children might be empty so there is nothing to document in them.
+         * For example most `index.ts` files don't have anything besides `import`
+         * or `export` so we can safely filter these children out.
+         */
+        return children.filter((c) => !!c.children);
+      })
+      .then((children) => {
+        /**
+         * The `name` of each child is wrapped in extra quote marks remove these
+         * quote marks and add `.ts` back to the end of the `name`,
+         */
+        return children.map((child) => {
+          child.name = child.name.replace(/"/g, "");
+          return child;
+        });
+      })
+      .then((children) => {
+        /**
+         * Now determine which `package` each of our children belongs to based on
+         * its name.
+         */
+        return children.map((child) => {
+          child.name = _.last(child.name.split("/"));
+          child.package = child.name;
+          return child;
+        });
+      })
+      // .then((children) => {
+      //   console.log(children);
+
+      //   /**
+      //    * `children` is currently a list of all TypeScript source files in
+      //    * `packages`. `children.children` is an array of all declarations in that
+      //    * source file. We need to concat all `children.children` arrays together
+      //    * into a giant array of all declarations in all packages.
+      //    */
+      //   return children.reduce((allChildren, child) => {
+      //     if (!child.children) {
+      //       return allChildren;
+      //     }
+      //     return allChildren.concat(
+      //       child.children.map((c) => {
+      //         c.package = child.package;
+      //         return c;
+      //       })
+      //     );
+      //   }, []);
+      // })
+      // .then((declarations) => {
+      //   /**
+      //    * Next we remove all children that are not exported out of their files.
+      //    */
+      //   return declarations.filter(
+      //     (declaration) => declaration.flags && declaration.flags.isExported
+      //   );
+      // })
+      // .then((declarations) => {
+      //   const blacklist = [
+      //     "genericSearch",
+      //     "appendCustomParams",
+      //     "requiresFormData",
+      //     "processParams",
+      //     "encodeParam",
+      //     "encodeQueryString",
+      //     "encodeFormData",
+      //     "warn",
+      //     "cleanUrl",
+      //     "checkForErrors",
+      //     "determineOwner",
+      //     "isItemOwner",
+      //     "isOrgAdmin"
+      //   ];
+      //   /**
+      //    * Next we remove any declarations we want to blacklist from the API ref
+      //    */
+      //   return declarations.filter(
+      //     (declaration) => !blacklist.includes(declaration.name)
+      //   );
+      // })
+      .then((declarations) => {
+        /**
+         * Now that we have a list of all declarations across the entire project
+         * we can begin to generate additional information about each declaration.
+         * For example we can now determine the `src` of the page that will
+         * be generated for this declaration. Each `declaration` will also have
+         * `children` which we can generate and define an `icon` property for. These
+         * additional properties, `src`, `pageUrl`, `icon` and `children` are then
+         * merged into the `declaration`. This also adds a `title`, `description`
+         * and `titleSegments` to each page which are used in the template for SEO.
+         */
+        return declarations.map((declaration) => {
+          const abbreviatedPackageName = declaration.package.replace(
+            "arcgis-rest-",
+            ""
+          );
+          const src = `arcgis-rest-js/api/${abbreviatedPackageName}/${declaration.name}.html`;
+          let children;
+
+          if (declaration.children) {
+            children = declaration.children.map((child) => {
+              child.icon = `tsd-kind-${slug(
+                child.kindString
+              ).toLowerCase()} tsd-parent-kind-${slug(
+                declaration.kindString
+              ).toLowerCase()}`;
+
+              if (child.flags.isPrivate) {
+                child.icon += ` tsd-is-private`;
+              }
+
+              if (child.flags.isProtected) {
+                child.icon += ` tsd-is-protected`;
+              }
+
+              if (child.flags.isStatic) {
+                child.icon += ` tsd-is-static`;
+              }
+
+              if (child.signatures) {
+                child.signatures = child.signatures.map((sig) => {
+                  sig.icon = child.icon;
+                  return sig;
+                });
+              }
+
+              return child;
+            });
+          }
+
+          declaration.title = declaration.name;
+          declaration.titleSegments = ["API Reference"];
+          declaration.description =
+            declaration.comment && declaration.comment.shortText
+              ? cheerio
+                  .load(md.render(declaration.comment.shortText))
+                  .text()
+                  .replace("\n", "")
+              : "API Reference documentation for ${child.name}, part of ${declaration.package}.";
+
+          return Object.assign(declaration, {
+            src,
+            pageUrl: prettyifyUrl(src),
+            icon: `tsd-kind-${slug(declaration.kindString).toLowerCase()}`,
+            children
+          });
+        });
+      })
+      .then((declarations) => {
+        /**
+         * We now have a list of `declarations` that will be used to generate the
+         * individual API reference pages, but we still need to generate a landing
+         * page for each `package`. Return a new object with our `declarations` and
+         * a new property `packages` which is an array of every `package` with a
+         * page `src`, a `pageUrl`, an `icon` and a list of `declarations`. This
+         * also adds a `title`, `description` and `titleSegments` to each page
+         * which are used in the template for SEO.
+         */
+        return {
+          declarations,
+          packages: _(declarations)
+            .map((d) => d.package)
+            .uniq()
+            .reduce((packages, package) => {
+              const abbreviatedPackageName = package.replace(
+                "arcgis-rest-",
+                ""
+              );
+              const src = `arcgis-rest-js/api/${abbreviatedPackageName}.html`;
+              const pkg = require(`${process.cwd()}/packages/${package}/package.json`);
+
+              packages.push({
+                package,
+                pkg,
+                title: package,
+                description: pkg.description,
+                titleSegments: ["API Reference"],
+                name: package,
+                declarations: declarations
+                  .filter((d) => d.package === package)
+                  .sort((da, db) => {
+                    const types = [
+                      "Class",
+                      "Function",
+                      "Object literal",
+                      "Variable",
+                      "Enumeration",
+                      "Type alias",
+                      "Interface"
+                    ];
+
+                    const aIndex = types.findIndex((t) => da.kindString === t);
+                    const bIndex = types.findIndex((t) => db.kindString === t);
+
+                    if (aIndex > bIndex) {
+                      return 1;
+                    } else if (aIndex < bIndex) {
+                      return -1;
+                    } else {
+                      return 0;
+                    }
+                  }),
+                icon: "tsd-kind-module",
+                src,
+                pageUrl: prettyifyUrl(src)
+              });
+              return packages;
+            }, [])
+        };
+      })
+      .then((api) => {
+        /**
+         * Since we generated the TypeDoc for the entire project at once each
+         * `declaration` has a unique numerical `id` property. We occasionally
+         * need to lookup a declaration by its `id` so we can prebuild an index of
+         * them here.
+         */
+        api.index = api.declarations.reduce((index, declaration) => {
+          index[declaration.id] = declaration;
+          return index;
+        }, {});
+
+        return api;
+      })
+      .then((api) => {
+        /**
+         * In order to power the API reference quick search we can build an array
+         * of all declarations and child items
+         */
+        api.quickSearchIndex = api.declarations.reduce(
+          (quickSearchIndex, declaration) => {
+            if (declaration.children) {
+              quickSearchIndex = quickSearchIndex.concat(
+                declaration.children.map((child) => {
+                  return {
+                    title: `${declaration.name}.${child.name}`,
+                    url: `${declaration.pageUrl}#${child.name}`,
+                    icon: child.icon
+                  };
+                })
+              );
+            }
+
+            return quickSearchIndex.concat([
+              {
+                title: declaration.name,
+                url: declaration.pageUrl,
+                icon: declaration.icon
+              }
+            ]);
+          },
+          []
+        );
+
+        return api;
+      })
+      .then((api) => {
+        /**
+         * Next we can sort the children of each declaration to sort by required/optional/inherited
+         */
+        api.declarations = api.declarations.map((declaration) => {
+          if (declaration.children) {
+            declaration.children.sort((ca, cb) => {
+              const aIndex = rankChild(ca);
+              const bIndex = rankChild(cb);
+
+              if (aIndex > bIndex) {
+                return 1; // sort a below b
+              } else if (aIndex < bIndex) {
+                return -1; // sort a above b
+              } else {
+                return 0;
+              }
+              // return 0;
+            });
+          }
+
+          if (declaration.groups) {
+            declaration.groups.forEach((group) => {
+              if (group.children) {
+                group.children.sort((ca, cb) => {
+                  const childA = declaration.children.find((c) => c.id === ca);
+                  const childB = declaration.children.find((c) => c.id === cb);
+
+                  const aIndex = rankChild(childA);
+                  const bIndex = rankChild(childB);
+
+                  if (aIndex > bIndex) {
+                    return 1;
+                  } else if (aIndex < bIndex) {
+                    return -1;
+                  } else {
+                    return 0;
+                  }
+                  // return 0;
+                });
+              }
+            });
+          }
+
+          return declaration;
+        });
+
+        return api;
+      })
+      .then((api) => {
+        /**
+         * Our final object looks like this:
+         *
+         * {
+         *   packages: [Array of packages.],
+         *   declarations: [Array of each exported declaration accross all source files.]
+         *   index: { Object mapping each declaration.id as a key with the declaration as its value}
+         * }
+         *
+         * We now export this to the Acetate source directory.
+         */
+        return new Promise((resolve, reject) => {
+          writeFile(OUTPUT, JSON.stringify(api, null, 2), (e) => {
+            if (e) {
+              reject(e);
+              return;
+            }
+
+            resolve(api);
+          });
+        });
+      })
+      .catch((e) => {
+        console.error(e);
+      })
+  );
+})();
+
+function rankChild(child) {
+  const { isPrivate, isOptional, isStatic } = child ? child.flags : {};
+
+  const isInherited = child.inheritedFrom ? true : false;
+
+  let score = 0;
+
+  if (isPrivate) {
+    score += 30;
+  }
+  if (isStatic) {
+    score -= 15;
+  }
+  if (!isInherited) {
+    score -= 5;
+  }
+  if (!isOptional) {
+    score -= 15;
+  }
+  return score;
+}

package/docs/generate-srihashes.js

@@ -0,0 +1,61 @@
+/**
+ * Generate a JSON file containing hash of packages and sha384 hashes of minified umd dist files.
+ */
+const { join, dirname, resolve } = require("path");
+const { readFile, writeFile } = require("fs/promises");
+const { generate } = require("sri-toolbox");
+const OUTPUT = join(process.cwd(), "docs", "src", `srihashes.json`);
+const version = require(join(process.cwd(), "lerna.json")).version;
+const { promisify } = require("util");
+
+const glob = promisify(require("glob"));
+
+const promises = [];
+
+glob("packages/*/package.json")
+  .then((packages) => {
+    return Promise.all(
+      packages.map((pkgPath) => {
+        return readFile(pkgPath).then((pkg) => {
+          return JSON.parse(pkg);
+        });
+      })
+    );
+  })
+  .then((packageJsons) => {
+    return Promise.all(
+      packageJsons
+        .filter((p) => !!p.unpkg)
+        .map((pkg) => {
+          return readFile(
+            resolve(join("packages", pkg.name.replace("@esri/", "")), pkg.unpkg)
+          ).then((data) => {
+            return {
+              pkg,
+              hash: generate(
+                {
+                  algorithms: ["sha384"],
+                },
+                data
+              ),
+            };
+          });
+        })
+    );
+  })
+  .then((res) => {
+    const json = {
+      version,
+      packages: {},
+    };
+    res.forEach((r) => {
+      if (r.hash) json.packages[r.pkg.name] = r.hash;
+    });
+    writeFile(OUTPUT, JSON.stringify(json, null, "  "), "utf8", (err) => {
+      if (err) throw err;
+    });
+  })
+  .catch((err) => {
+    console.log(err);
+    // make node happy to see `catch()`
+  });

package/docs/package.json

@@ -0,0 +1,3 @@
+{
+  "types": "module"
+}

package/docs/src/_layout.html

@@ -0,0 +1,86 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta content="IE=edge" http-equiv="X-UA-Compatible">
+    <meta name="viewport" content="width=device-width, user-scalable=no">
+    <title>{{title if title}}{{" | " + titleSegments | join(" |") if titleSegments}}{{" | " if title}}ArcGIS REST JS</title>
+    {% if description %}
+    <meta name="description" content="A modular, high quality toolkit for working with the ArcGIS REST API.">
+    {% endif %}
+    <link rel="stylesheet" href="https://s3-us-west-1.amazonaws.com/patterns.esri.com/files/calcite-web/1.2.5/css/calcite-web.min.css">
+    <link rel="stylesheet" href="/arcgis-rest-js/css/style.css">
+    {% block css %}{% endblock %}
+  </head>
+  <body>
+  <!-- Drawer -->
+    <div class="drawer drawer-left js-drawer" data-drawer="top-nav" tabindex="0">
+      <nav class="drawer-nav" role="navigation">
+        <aside class="side-nav">
+          <h2 class="side-nav-title">ArcGIS REST JS</h2>
+          {% link "/arcgis-rest-js/guides/", "Guides", class="side-nav-link" %}
+          {% link "/arcgis-rest-js/api/", "API Reference", class="side-nav-link"%}
+          {% link "https://github.com/Esri/arcgis-rest-js", "GitHub", class="side-nav-link" %}
+        </aside>
+      </nav>
+    </div>
+
+    <div id="page" class="wrapper">
+      <!-- Sample HTML -->
+      <header class="top-nav">
+        <div class="grid-container">
+          <div class="column-24">
+            <!-- desktop sized navigation -->
+            <div class="tablet-hide">
+              <!-- logo / home -->
+              <a href="/arcgis-rest-js/" class="top-nav-title">ArcGIS REST JS</a>
+              <!-- primary navigation sections -->
+              <nav class="top-nav-list" role="navigation" aria-labelledby="topnav">
+                {% link "/arcgis-rest-js/guides/", "Guides", class="top-nav-link" %}
+                {% link "/arcgis-rest-js/api/", "API Reference", class="top-nav-link"%}
+                {% link "https://github.com/Esri/arcgis-rest-js", "GitHub", class="top-nav-link" %}
+              </nav>
+            </div>
+
+            <!-- tablet and mobile sized navigation -->
+            <div class="tablet-show top-nav-flex">
+              <!-- open primary navigation drawer -->
+              <nav class="top-nav-flex-list" role="navigation" aria-labelledby="topnav">
+                <a href="/arcgis-rest-js/" class="icon-ui-menu top-nav-link js-drawer-toggle" data-drawer="top-nav"><span class="phone-hide">Menu</span></a>
+              </nav>
+              <!-- logo / home -->
+              <header class="top-nav-flex-title">
+                <a href="/arcgis-rest-js/" class="top-nav-link">ArcGIS REST API JavaScript Client</a>
+              </header>
+            </div>
+          </div>
+
+        </div>
+      </header>
+
+
+      <main id="#skip-to-content">
+        {% block main %}{% endblock %}
+      </main>
+    </div>
+
+    <footer class="footer">
+      {% block footer %}{% endblock %}
+      <div class="panel panel-white">
+        <div class="grid-container">
+          <div class="column-24">
+            <a href="https://github.com/Esri/arcgis-rest-js" class="font-size--2">Fork this project</a>
+          </div>
+        </div>
+      </div>
+    </footer>
+
+    <script src="https://s3-us-west-1.amazonaws.com/patterns.esri.com/files/calcite-web/1.2.5/js/calcite-web.min.js"></script>
+
+    <script>
+       calcite.init()
+    </script>
+
+    {% block scripts %}{% endblock %}
+  </body>
+</html>