impeditmaiores 1.0.0

package/demos/webmap-checker-sapper/src/server.js

@@ -0,0 +1,101 @@
+require('cross-fetch/polyfill');
+import "isomorphic-form-data";
+import sirv from "sirv";
+import express from "express";
+import session from "express-session";
+import compression from "compression";
+import * as sapper from "../__sapper__/server.js";
+import SessionFileStore from "session-file-store";
+
+import { UserSession } from "@esri/arcgis-rest-auth";
+import { Store } from "svelte/store.js";
+import { userInfoMiddleware } from "./userInfoMiddleware";
+
+// setup file storeage for user sessions
+const FileStore = SessionFileStore(session);
+
+// load and setup our config variables from out .env file
+require("dotenv").config();
+const { PORT, NODE_ENV, ENCRYPTION_KEY, SESSION_SECRET } = process.env;
+const dev = NODE_ENV === "development";
+
+// start express
+express()
+  // configure express middleware
+  .use(
+    // compress responses
+    compression({ threshold: 0 }),
+
+    // serve static assets like images, css ect...
+    sirv("static", { dev }),
+
+    // setup sessions, express will set a cookie on the client
+    // to keep track of a session id and rehydrate the
+    // correstponding session on the server.
+    session({
+      name: "webmap-checker-session",
+      secret: SESSION_SECRET,
+      resave: false,
+      saveUninitialized: false,
+      cookie: {
+        maxAge: 2592000000 // 30 days in milliseconds
+      },
+
+      // store session data in a secure, encrypted file
+      // sessions will be loaded from these files and decrypted
+      // at the end of every request the state of `request.session`
+      // will be saved back to disk.
+      store: new FileStore({
+        ttl: 2592000000 / 1000, // 30 days in seconds
+        retries: 1,
+        secret: ENCRYPTION_KEY,
+
+        // custom encoding and decoding for sessions means we can
+        // initalize a single `UserSession` object for use with rest js
+        encoder: sessionObj => {
+          sessionObj.userSession = sessionObj.userSession.serialize();
+          return JSON.stringify(sessionObj);
+        },
+        decoder: sessionContents => {
+          const sessionObj = JSON.parse(sessionContents);
+          sessionObj.userSession = UserSession.deserialize(
+            sessionObj.userSession
+          );
+          return sessionObj;
+        }
+      })
+    }),
+
+    // next check for a session and if we have one fetch additional information
+    // the rest api for use in our app.
+    userInfoMiddleware,
+
+    // finally we can setup sapper by creating a Store that will syncronize
+    // server side data with the client
+    sapper.middleware({
+      store: request => {
+        let userSession;
+
+        // since the store is shared between the client and server
+        // we dont want to put refresh tokens in it. The store also needs to be
+        // in a serializable format so sapper and send it to the client.
+        if (request.session && request.session.userSession) {
+          userSession = request.session.userSession.toJSON();
+          delete userSession.refreshToken;
+          delete userSession.refreshTokenExpires;
+        }
+
+        // now we can initalize the store with our session (from the encrypted
+        // file) and the org and user info which userInfoMiddleware attached to
+        // the request object.
+        return new Store({
+          session: userSession,
+          user: request.session ? request.session.userInfo : undefined,
+          org: request.session ? request.session.orgInfo : undefined
+        });
+      }
+    })
+  )
+  .listen(PORT, err => {
+    if (err) console.log("error", err);
+  });

package/demos/webmap-checker-sapper/src/service-worker.js

@@ -0,0 +1,82 @@
+import { timestamp, files, shell, routes } from '../__sapper__/service-worker.js';
+
+const ASSETS = `cache${timestamp}`;
+
+// `shell` is an array of all the files generated by the bundler,
+// `files` is an array of everything in the `static` directory
+const to_cache = shell.concat(files);
+const cached = new Set(to_cache);
+
+self.addEventListener('install', event => {
+	event.waitUntil(
+		caches
+			.open(ASSETS)
+			.then(cache => cache.addAll(to_cache))
+			.then(() => {
+				self.skipWaiting();
+			})
+	);
+});
+
+self.addEventListener('activate', event => {
+	event.waitUntil(
+		caches.keys().then(async keys => {
+			// delete old caches
+			for (const key of keys) {
+				if (key !== ASSETS) await caches.delete(key);
+			}
+
+			self.clients.claim();
+		})
+	);
+});
+
+self.addEventListener('fetch', event => {
+	if (event.request.method !== 'GET' || event.request.headers.has('range')) return;
+
+	const url = new URL(event.request.url);
+
+	// don't try to handle e.g. data: URIs
+	if (!url.protocol.startsWith('http')) return;
+
+	// ignore dev server requests
+	if (url.hostname === self.location.hostname && url.port !== self.location.port) return;
+
+	// always serve static files and bundler-generated assets from cache
+	if (url.host === self.location.host && cached.has(url.pathname)) {
+		event.respondWith(caches.match(event.request));
+		return;
+	}
+
+	// for pages, you might want to serve a shell `index.html` file,
+	// which Sapper has generated for you. It's not right for every
+	// app, but if it's right for yours then uncomment this section
+	/*
+	if (url.origin === self.origin && routes.find(route => route.pattern.test(url.pathname))) {
+		event.respondWith(caches.match('/index.html'));
+		return;
+	}
+	*/
+
+	if (event.request.cache === 'only-if-cached') return;
+
+	// for everything else, try the network first, falling back to
+	// cache if the user is offline. (If the pages never change, you
+	// might prefer a cache-first approach to a network-first one.)
+	event.respondWith(
+		caches
+			.open(`offline${timestamp}`)
+			.then(async cache => {
+				try {
+					const response = await fetch(event.request);
+					cache.put(event.request, response.clone());
+					return response;
+				} catch(err) {
+					const response = await cache.match(event.request);
+					if (response) return response;
+
+					throw err;
+				}
+			})
+	);
+});

package/demos/webmap-checker-sapper/src/template.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html>
+<head>
+	<meta charset='utf-8'>
+	<meta name='viewport' content='width=device-width'>
+	<meta name='theme-color' content='#aa1e1e'>
+
+	%sapper.base%
+
+	<link rel='stylesheet' href='global.css'>
+	<link rel='manifest' href='manifest.json'>
+	<link rel='icon' type='image/png' href='favicon.png'>
+
+	<!-- Sapper generates a <style> tag containing critical CSS
+	     for the current page. CSS for the rest of the app is
+	     lazily loaded when it precaches secondary pages -->
+	%sapper.styles%
+
+	<!-- This contains the contents of the <svelte:head> component, if
+	     the current page has one -->
+	%sapper.head%
+</head>
+<body>
+	<!-- The application will be rendered inside this element,
+	     because `app/client.js` references it -->
+	<div id='app'>%sapper.html%</div>
+
+	<!-- Sapper creates a <script> tag containing `app/client.js`
+	     and anything else it needs to hydrate the app and
+	     initialise the router -->
+	%sapper.scripts%
+</body>
+</html>

package/demos/webmap-checker-sapper/src/userInfoMiddleware.js

@@ -0,0 +1,21 @@
+// we could use UserSession.getUser() instead
+import { getSelf, getUser } from "@esri/arcgis-rest-portal";
+
+// this middleware checks for a session and if we find a session add
+// additional info to that session from the getUser and getSelf calls
+// request here is the incoming request in express.
+export function userInfoMiddleware(incomingRequest, outgoingResponse, next) {
+  if (incomingRequest.session && incomingRequest.session.userSession) {
+    Promise.all([
+      getUser({ authentication: incomingRequest.session.userSession }),
+      getSelf({ authentication: incomingRequest.session.userSession })
+    ]).then(([userInfo, orgInfo]) => {
+      // add information to the request so the next middleware can access it
+      incomingRequest.session.userInfo = userInfo;
+      incomingRequest.session.orgInfo = orgInfo;
+      next(); // run the next middleware
+    });
+  } else {
+    next(); // run the next middleware
+  }
+}

package/demos/webmap-checker-sapper/src/utils.js

@@ -0,0 +1,33 @@
+import { UserSession } from "@esri/arcgis-rest-auth";
+import { loadModules } from "esri-loader";
+
+export function retryWithNewSession(error, fetch) {
+  if (error.name === "ArcGISAuthError") {
+    return fetch("/auth/exchange-token")
+      .then(exchangeTokenResponse => {
+        return exchangeTokenResponse.json();
+      })
+      .then(sessionInfo => {
+        console.log(sessionInfo);
+        const newSession = new UserSession(session);
+
+        // if we are in a browser (client side) we are working with an instance
+        // of `UserSession` otherwise (server side) we are working with a JSON
+        // representation of a session.
+        if (process.browser) {
+          this.store.set({ session: newSession });
+
+          // if we are in a browser we should also update IdentityManager
+          loadModules(["esri/identity/IdentityManager"]).then(([esriId]) => {
+            esriId.registerToken(session.toCredential());
+          });
+        } else {
+          this.store.set({ session: sessionInfo });
+        }
+
+        return error.retry(newSession, 1);
+      });
+  }
+
+  throw error;
+}

package/demos/webmap-checker-sapper/static/global.css

@@ -0,0 +1,36 @@
+body {
+	margin: 0;
+	font-family: Roboto, -apple-system, BlinkMacSystemFont, Segoe UI, Oxygen, Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
+	font-size: 14px;
+	line-height: 1.5;
+	color: #333;
+}
+
+h1, h2, h3, h4, h5, h6 {
+	margin: 0 0 0.5em 0;
+	font-weight: 400;
+	line-height: 1.2;
+}
+
+h1 {
+	font-size: 2em;
+}
+
+a {
+	color: inherit;
+}
+
+code {
+	font-family: menlo, inconsolata, monospace;
+	font-size: calc(1em - 2px);
+	color: #555;
+	background-color: #f0f0f0;
+	padding: 0.2em 0.4em;
+	border-radius: 2px;
+}
+
+@media (min-width: 400px) {
+	body {
+		font-size: 16px;
+	}
+}

package/demos/webmap-checker-sapper/static/manifest.json

@@ -0,0 +1,20 @@
+{
+	"background_color": "#ffffff",
+	"theme_color": "#aa1e1e",
+	"name": "TODO",
+	"short_name": "TODO",
+	"display": "minimal-ui",
+	"start_url": "/",
+	"icons": [
+		{
+			"src": "svelte-logo-192.png",
+			"sizes": "192x192",
+			"type": "image/png"
+		},
+		{
+			"src": "svelte-logo-512.png",
+			"sizes": "512x512",
+			"type": "image/png"
+		}
+	]
+}

package/docs/FAQ.md

@@ -0,0 +1,48 @@
+## 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.
+
+## Who is using these packages?
+
+REST JS is trusted in ArcGIS applications serving **many** thousands of users.
+
+* ArcGIS [Hub](https://hub.arcgis.com)
+* ArcGIS for [Developers](https://developers.arcgis.com)
+* ArcGIS [Storymaps](https://storymaps.arcgis.com/en/)
+* ArcGIS [Solutions](https://solutions.arcgis.com/)
+* ArcGIS Enterprise
+* ArcGIS [Urban](https://www.esri.com/en-us/landing-page/product/2018/arcgis-urban)
+* ArcGIS [Analytics for IoT](https://www.esri.com/en-us/landing-page/product/2018/arcgis-analytics-for-iot)
+
+And since its on GitHub, Esri developers are _far_ from the only ones using ArcGIS REST JS. Besides the usual culprits, we've seen the library running in:
+
+* [Chrome Extensions](https://chrome.google.com/webstore/detail/echo-for-arcgis/mkeckgendkgcofhhenfkknonnkoboobm?hl=en-US)
+* [Lambda Functions](https://medium.com/@adamjpfister/know-your-apis-6dc6ea3d084c)
+* [Web Components](https://github.com/esridc/hub-components)
+* [React Components](https://twitter.com/oppoudel/status/1022209378378805249)
+* [Observable](https://observablehq.com/@jgravois/introduction-to-esri-arcgis-rest-js)
+
+## 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.