autnam 1.0.0

package/docs/HISTORY.md

@@ -0,0 +1,62 @@
+## Origins
+
+The idea for this library originated in a slack conversation between @patrickarlt and @ajturner when he was looking for a library to automate the creation of Feature Layers in ArcGIS Online for the Hub project.
+
+## Key Collaborators
+
+This list includes people who contributed to the original conversation and those who have contributed to similar projects.
+
+- @ajturner - ArcGIS Hub
+- @dbouwman - ArcGIS Hub
+- @tomwayson - ArcGIS Hub
+- @patricakrlt - ArcGIS for Developers
+- @noahmulfinger - ArcGIS for Developers
+- @araedavis - ArcGIS for Developers
+- @nixta - Developer Outreach
+- @jgravois - Developer Outreach
+
+## Use Cases and Target Audience
+
+This API intends to simplify interactions with the ArcGIS REST API, enabling the creation of powerful scripting tools in both Node.js and the browser that currently require deep knowledge of the REST API, and coordinating chained calls with a variety of complex parameters. This library also enables downstream projects like the ArcGIS for Developers website and ArcGIS Hub to achieve identity management.
+
+The tools proposed here are intended to be useful in internal projects such as ArcGIS for Developers and ArcGIS Hub, but they also strongly target outside developers who need to script and automate the platform but do not know or are not willing to integrate the ArcGIS API for Python into their projects. Hopefully, this project will also have appeal to enterprise developers who have existing Node.js systems and want to integrate with ArcGIS.
+
+## Functionality Roadmap
+
+- Manage feature layers
+  - Create new feature layers
+  - Add/Remove/Update fields in feature layers
+  - Query and edit features
+  - Get statistics
+- Make interacting with premium ArcGIS Online services intuitive
+  - Geocoding
+  - Routing
+  - Geoenrichment
+  - Spatial Analysis
+  - Elevation Analysis
+- Managing groups and users
+  - Create/invite new users
+  - Create/edit/delete/share with groups
+- Manage content
+  - Create, edit and delete items, maps and scenes
+- Handle authentication and identity
+- Compatible with Node 6+ and the 2 latest releases of every browser and IE 11.
+
+## Prior Projects
+
+- [node-arcgis](https://github.com/Esri/node-arcgis) - Originally started by Nik Wise and currently maintained by John Gravois this library wraps a large amount of functionality for ArcGIS Online into a single API. However this library lacks much key functionality and does not handle authentication at all leaving it to the user to obtain and manage tokens. This library also lacks a significant test suite.
+- [geoservices.js](https://github.com/Esri/geoservices-js) - Originally created by Jerry Seivert to wrap the [Geoservices](https://geoservices.github.io/) specification it is currently maintained by John Gravois. However this library does not fully implement the specification, handle authentication with ArcGIS or work in browsers.
+- ArcGIS for Developers - The developers website has a large amount of internal tooling for working with Portal APIs and publishing feature services, we have plans to add additional features that would require either creating our own implementations or writing a common implementation in this project.
+- Koop
+- ArcGIS Hub
+
+## Project Architecture
+
+As with any new JavaScript project there are numerous decisions to make regarding which technologies to use. We decided to go with the options below, but all these choices are up for debate.
+
+- ~Implemented as a [monorepo managed with Lerna](https://lernajs.io/). The monorepo approach allows us to manage distinct packages like `arcgis-rest-geocoding` and separate functionality while sharing build, test and documentation tooling.~ Switched to NPM workspaces.
+- Author the library in [TypeScript](https://www.typescriptlang.org/). Using TypeScript will allow us to add type information to request params and response structures which vastly simplifies development. TypeScript also has excellent support for newer `async`/`await` patterns with miminal code overhead and can publish to any module format we might need to support. Additionally TypeScript has excellent support for generating API documentation with [TypeDoc](http://typedoc.org/). TypeScript also has better internal adoption since Dojo 2 is using it as well as the JSAPI, Insights and the ArcGIS for Developers site.
+- ~Would recommend using a Node/browser HTTP library like [Axios](https://github.com/mzabriskie/axios) which also has support for mocking in tests via [axios-mock-adapter](https://github.com/ctimmerm/axios-mock-adapter).~ We have decided to use the new [fetch](https://fetch.spec.whatwg.org/) standard.
+- Testing is a concern. I initially thought that we could simply use Karma to test all the code. However Karma can only be used to test browser based code. We could however use the `jasmine` command line tool it would just mean we would have to compile the TypeScript source first and then run the Jasmine CLI tools. Karma would use the `karma-typescript` plugin and run the browser tests. ~An alternative to this might be to use [The Intern](https://theintern.github.io/) setup according to this [blog post about testing with TypeScript](https://www.sitepen.com/blog/2015/03/24/testing-typescript-with-intern/). However the Intern doesn't have super great support for TypeScript currently though these issues should be solved in this Falls Intern 4 release.~ We have decided to use Jasmine and the Jasmine CLI for Node tests and Karma with Jasmine for browser tests.
+
+It is worth noting that a TypeScript/Intern approach aligns perfectly with the direction of the JavaScript API team.

package/docs/acetate.config.js

@@ -0,0 +1,262 @@
+const path = require("path");
+const fs = require("fs");
+const { inspect } = require("util");
+const _ = require("lodash");
+
+const IS_DEV = process.env.ENV !== "prod";
+
+module.exports = function (acetate) {
+  /**
+   * Load SRI hashes.
+   */
+  let srihashes;
+  fs.readFile("docs/src/srihashes.json", (err, data) => {
+    srihashes = err
+      ? {
+          packages: {}
+        }
+      : JSON.parse(data);
+  });
+
+  /**
+   * Load all .html and markdown pages in the `src` folder, assigning them a
+   * default layout.
+   */
+  acetate.load("**/*.+(html|md)", {
+    basePath: "arcgis-rest-js",
+    metadata: {
+      layout: "_layout:main"
+    }
+  });
+
+  acetate.metadata("**/*", {
+    isDev: IS_DEV
+  });
+
+  /**
+   * Add a different layout for guides. Add an array of `titleSegments` to go
+   * inbetween the page title and the "Esri REST JS" title suffix.
+   */
+  acetate.metadata("guides/**/*", {
+    layout: "guides/_layout:content",
+    titleSegments: ["Guide"]
+  });
+
+  /**
+   * Now we need to make a new query called `guides` that will be used to render
+   * the guide navigation.
+   */
+  acetate.query(
+    /**
+     * results will be accessible as `queries.guides` in templates
+     */
+    "guides",
+    /**
+     * start by getting all markdown pages in the `guides` folder
+     */
+    "guides/**/*.md",
+    /**
+     * Now map over each page extracting values from it into a new array.
+     */
+    (page) => {
+      return {
+        title: page.navTitle || page.title,
+        order: page.order,
+        group: page.group,
+        url: page.url
+      };
+    },
+    /**
+     * Now reduce our array from the previous step sorting the items into sections
+     * based on their `group` property.
+     */
+    (sections, item) => {
+      if (!item.group) {
+        return sections;
+      }
+
+      // does this items `section` already have a `section` in `sections`?
+      const idx = _.findIndex(sections, (section) => section.id === item.group);
+
+      if (idx >= 0) {
+        // if it does push this item into it.
+        sections[idx].items.push(item);
+      } else {
+        // if it does not push a new `section` into `sections`.
+        sections.push({
+          name: _.startCase(item.group.replace(/\d-/, "")),
+          id: item.group,
+          items: [item]
+        });
+      }
+
+      /**
+       * sort our sections by their `id` (which starts with a number) an sort
+       * each sections items by their `order` property
+       */
+      return _(sections)
+        .sortBy("id")
+        .map((section) => {
+          section.items = _.sortBy(section.items, "order");
+          return section;
+        })
+        .value();
+    },
+    /**
+     * The initial value for the above reduce function.
+     */
+    []
+  );
+
+  /**
+   * Load the typedoc.json file as a page in Acetate. This makes the watcher
+   * start looking for changes and we can listen for the events later.
+   */
+  acetate.load("typedoc.json", {
+    basePath: "arcgis-rest-js",
+    metadata: {
+      layout: false,
+      prettyUrl: false
+    }
+  });
+
+  /**
+   * Use Acetates generate helper to generate a page for each `declaration`
+   * and `package` in the typedoc.json and generate the search index file
+   */
+  acetate.generate((createPage, callback) => {
+    fs.readFile(
+      path.join(acetate.root, "src", "typedoc.json"),
+      (e, contents) => {
+        const typedoc = JSON.parse(contents.toString());
+
+        const declarationPages = typedoc.declarations.map((declaration) => {
+          return createPage.fromTemplate(
+            declaration.src,
+            path.join(acetate.sourceDir, "api", "_declaration.html"),
+            Object.assign({}, declaration, {
+              layout: "api/_layout:content"
+            })
+          );
+        });
+
+        const packagePages = typedoc.packages.map((package) => {
+          return createPage.fromTemplate(
+            package.src,
+            path.join(acetate.sourceDir, "api", "_package.html"),
+            Object.assign({}, package, {
+              layout: "api/_layout:content"
+            })
+          );
+        });
+
+        const searchIndex = createPage.fromTemplateString(
+          "arcgis-rest-js/js/index.js",
+          `const ESRI_REST_API_REF_INDEX = ${JSON.stringify(
+            typedoc.quickSearchIndex
+          )}`,
+          path.join(acetate.sourceDir, "js", "index.js"),
+          { layout: false, prettyUrl: false }
+        );
+
+        // once all the pages have been generated provide them to Acetate.
+        Promise.all(declarationPages.concat(packagePages)).then((pages) => {
+          callback(null, pages.concat(searchIndex));
+        });
+      }
+    );
+  });
+
+  /**
+   * Also register typedoc.json as a global data object called `typedoc`.
+   */
+  acetate.data("typedoc", "typedoc.json");
+
+  /**
+   * Register some tools for working with the typedoc output.
+   */
+  acetate.global("API_TOOLS", {
+    findById: function (typedoc, id) {
+      return typedoc.index[id];
+    },
+    findByName: function (typedoc, name) {
+      return typedoc.declarations.find((c) => c.name === name);
+    },
+    findChildById: function (id, children) {
+      return children.find((c) => c.id === id);
+    }
+  });
+
+  acetate.filter("findPackage", (typedoc, name) => {
+    return typedoc.packages.find((p) => p.pkg.name === name).pkg;
+  });
+
+  /**
+   * Listen for changes, if we see a change in typedoc.json we know we need to
+   * regenerate all the dymanically generated pages so reload this config file.
+   */
+  acetate.on("watcher:change", (page) => {
+    if (page.src === "typedoc.json") {
+      acetate.reloadConfig();
+    }
+  });
+
+  /**
+   * Template helper for safely inspecting objects with circular references.
+   */
+  acetate.filter("inspect", function (obj) {
+    return inspect(obj, { depth: 3 });
+  });
+
+  // without the '.js' on the end, for the benefit of the AMD sample
+  acetate.helper("cdnUrl", function (context, package) {
+    return `https://unpkg.com/${
+      package.name
+    }@${package.version}/dist/bundled/${package.name.replace("@esri/arcgis-rest-", "")}.umd`;
+  });
+
+  // <code> friendly script tag string
+  acetate.helper("scriptTag", function (context, package) {
+    return acetate.nunjucks.renderString(
+      `{% highlight "html" %}<script src="https://unpkg.com/${package.name}@${
+        package.version
+      }/dist/bundled/${package.name.replace(
+        "@esri/arcgis-rest-",
+        ""
+      )}.umd.min.js"></script>{% endhighlight %}`
+    );
+  });
+
+  // CDN with SRI only if hash exists
+  acetate.helper("scriptTagSRI", function (context, package) {
+    const hash = srihashes.packages[package.name];
+    if (hash) {
+      return acetate.nunjucks.renderString(`
+        {%highlight "html" %}
+        <script src="https://unpkg.com/${package.name}@${
+        package.version
+      }/dist/bundled/${package.name.replace(
+        "@esri/arcgis-rest-",
+        ""
+      )}.umd.min.js" integrity="${hash}" crossorigin="anonymous"></script>{% endhighlight %}`);
+    } else {
+      return "";
+    }
+  });
+
+  acetate.helper("npmInstallCmd", function (context, package) {
+    const peers = package.peerDependencies
+      ? Object.keys(package.peerDependencies).map(
+          (pkg) => `${pkg}@${package.peerDependencies[pkg]} `
+        )
+      : [];
+    return `npm install ${package.name} ${peers.join(" ")}`;
+  });
+
+  acetate.filter("stripThisFromParams", function (params) {
+    if (!params || !params.length) {
+      return [];
+    }
+    return params.filter((p) => p.name !== "this");
+  });
+};