delectusnon 1.0.0

package/demos/vue/src/main.js

@@ -0,0 +1,92 @@
+// Import VueJS.
+import Vue from "vue";
+// Using the router to treat this like a single-page application.
+import Router from "vue-router";
+// Import the store plugin, Vuex.
+import Vuex from "vuex";
+// Import the arcgis-rest-auth bit required for deserializing local storage sessions.
+import { UserSession } from "@esri/arcgis-rest-auth";
+// Importing the main application.
+import App from "./components/App.vue";
+// Importing the authentication component that post-processes the OAuth response.
+import Authenticate from "./components/Authenticate.vue";
+
+// Tell Vue to use the vue-router plugin.
+Vue.use(Router);
+
+// Define the router.
+const router = new Router({
+  routes: [
+    // The root path will render the main application component.
+    { path: "/", component: App },
+    // At /authenticate, the authentication component will be rendered.
+    { path: "/authenticate", component: Authenticate }
+  ]
+});
+
+// Tell Vue to use the Vuex plugin.
+Vue.use(Vuex);
+
+// Define the application store.
+const store = new Vuex.Store({
+  state: {
+    session: null
+  },
+  mutations: {
+    setSession(state, data) {
+      state.session = data;
+    }
+  },
+  actions: {
+    updateSession({ commit }, session) {
+      // Apply the changes to the state's session.
+      commit("setSession", session);
+      // If the browser supports local storage, re-serialize it on change
+      // and update the local storage.
+      if (typeof Storage !== "undefined") {
+        if (session && session.serialize) {
+          localStorage.setItem(
+            "__ARCGIS_REST_USER_SESSION__",
+            session.serialize()
+          );
+        } else {
+          localStorage.removeItem("__ARCGIS_REST_USER_SESSION__");
+        }
+      }
+    }
+  }
+});
+
+// Define the main Vue instance.
+new Vue({
+  el: "#app",
+  router,
+  store,
+  data() {
+    return {};
+  },
+  created() {
+    // Load any previously serialized session.
+    this.loadSerializedSession();
+  },
+  methods: {
+    // Function to load any serialized session from local storage.
+    loadSerializedSession() {
+      if (typeof Storage !== "undefined") {
+        const serializedSession = localStorage.getItem(
+          "__ARCGIS_REST_USER_SESSION__"
+        );
+        if (serializedSession !== null && serializedSession !== "undefined") {
+          // If there is a serialized session, deserialize it into a new session object.
+          store.dispatch(
+            "updateSession",
+            UserSession.deserialize(serializedSession)
+          );
+        }
+      }
+    }
+  },
+  render(createElement) {
+    return createElement("router-view");
+  }
+});

package/docs/FAQ.md

@@ -0,0 +1,28 @@
+## Is this a _supported_ Esri product?
+
+It is not. We offer no guarantees, SLAs, nor a product lifecycle to support planning.
+
+This project is an open source collaboration between developers from a variety of teams at Esri that was initially developed to scratch an itch of our own. That said, we are actively recruiting outside contributors and fully expect that the tools here will be useful to a subset of our customers.
+
+## Comparison with the ArcGIS API for JavaScript
+
+The ArcGIS API for JavaScript is Esri's flagship product for building web applications to visualize, edit, map and analyze geospatial data. It is a feature complete client side API for working with the REST services based ArcGIS platform.
+The ArcGIS API for JavaScript includes significant client side functionality including smart mapping, 3D rendering, geometric analysis and feature editing as well as full support for working with web maps and web scenes.
+
+The goal of this project on the other hand is to provide a convenient binding to the underlying REST API for those who need to work directly with it from JavaScript. This project includes functional equivalents of the low-level request methods and identity management in the ArcGIS API for JavaScript, along with additional thin wrappers to assist developers in scripting against the ArcGIS REST API directly in Node.js and browser applications that do _not_ incorporate a map.
+
+We aim to make interacting with the platform as intuitive as possible, but the surface area of the project currently does not nearly encompass the entire ArcGIS REST API.
+
+## Comparison with the ArcGIS API for Python
+
+This project is similar to the ArcGIS API for Python in many ways. Like the ArcGIS API for Python, this library aims to be a scripting tool that simplifies interacting with the ArcGIS REST API, but where the ArcGIS API for Python highlights integration with dataframes and Jupyter Notebooks for visualization and sharing this project provides only generic tools for JavaScript applications running on a server, CLI, in a browser or as a script.
+
+## Why TypeScript
+
+Using TypeScript allows us to add type information to request params and response structures. This vastly simplifies development. TypeScript also has excellent support for newer `async`/`await` patterns and for generating API documentation with [TypeDoc](http://typedoc.org/).
+
+TypeScript compiles to JavaScript so you can use @esri/arcgis-rest-js in any JavaScript project. However if you use TypeScript you will get the benefits of type checking for free.
+
+We also _really_ like TypeScript because it supports exporting to both [ES 2015 modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) (use `import`/`export`) and [UMD](http://davidbcalhoun.com/2014/what-is-amd-commonjs-and-umd/) modules. This allows us to support a wide variety of module loaders and bundlers, including Browserify, Webpack, RequireJS, and Dojo 1 and 2.
+
+We include [`tslib`](https://www.npmjs.com/package/tslib) as a dependency of individual npm packages to make usage of `_extends` and `_assign` in our compiled code more concise.

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.
+* 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,223 @@
+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 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) => {
+    console.log(typedoc.packages, 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/umd/${package.name.replace("@esri/arcgis-rest-", "")}.umd`;
+  });
+
+  // <code> friendly script tag string
+  // future entry point for adding SRI hash
+  acetate.helper("scriptTag", function(context, package) {
+    return `&lt;script src="https://unpkg.com/${
+      package.name
+    }@${package.version}/dist/umd/${package.name.replace("@esri/arcgis-rest-", "")}.umd.min.js"&gt;&lt;/script&gt;`;
+  });
+
+  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(" ")}`;
+  });
+};