README

Arcgoose

Let's face it, writing ArcGIS REST API validation, casting and business logic boilerplate is a drag. That's why we wrote Arcgoose.

const connection = await arcgoose.connect({ url });
const Cat = await arcgoose.model(connection.layers.Cats, { name: String });

const cat = await Cat.findOne({ name: 'Grumpy' }).exec();

Arcgoose provides a straight-forward, schema-based solution to model your application data. It includes built-in type casting, validation, query building, business logic hooks and more, out of the box.*

* Arcgoose is a work in progress.

* Arcgoose is loosely based on the Mongoose syntax.

Installing

$ npm install --save arcgoose

Then, just import to your service or module:

import arcgoose from 'arcgoose';

Instructions

Connecting to ArcGIS Feature Server

Using the feature server URL:

const connection = await arcgoose.connect({ url });

Using the hosted feature layer item id:

const connection = await arcgoose.connect({ portalUrl, portalItemId });

Structure of the connection JSON object:

{
  url,
  capabilities: { create, query, update, delete, editing },
  layers: {
    Cats: { id, url, fields, objectIdField },
    Dogs: { id, url, fields, objectIdField },
  },
  tables: {
    Rabbits: { id, url, fields, objectIdField },
  },
}

Schemas

Arcgoose uses schemas for validation and casting of types that are not Esri-supported (e.g., arrays, objects, ...). Arcgoose uses the JSON Schema standard, and uses the Ajv library for validation.

const catSchema = {
  type: 'object', // type should always be object
  required: ['GlobalID', 'name']
  properties: {
    GlobalID: {
      type: 'string',
    },
    name: {
      type: 'string',
      minLength: 3,
      maxLength: 100,
    },
    details: {
      type: 'object', // 'details' will be casted from a string to a javascript object
      properties: {
        color: {
          type: 'string',
          pattern: '^#(([0-9a-fA-F]{2}){3}|([0-9a-fA-F]){3})

, // reg exp to match HEX color code
        },
        age: {
          type: 'integer',
          minimum: 0,
        }
      }
    }
    friends: {
      type: 'array', // 'friends' will be casted from a string to a javascript array
      items: {
        type: 'string',
      }
    }
  }
};

Models

Models are fancy constructors compiled from Schema definitions. Instances of models are used to query and update layers and tables on the feature server.

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' }
  }
};

const Cat = await arcgoose.model(connection.layers.Cats, schema);

const cat = await Cat.findOne({ name: 'Grumpy' }).exec();

Queries

Queries can be executed using the find() or findOne() methods. You can pass one or more object fields to be matched.

const cat = await Cat
  .find({ name: 'Grumpy' })
  .exec();

Additional query methods can be chained after the find() method.

const cat = await Cat
  .find({ name: 'Grumpy' })
  .populate(['name', 'dateOfBirth'])
  .returnGeometry()
  .exec();

Here is a list of additional query methods:

.filter(additionalSQLWhereClause) // chain as many as you like

.populate(outFields) // otherwise all fields from the schema will be populated

.geometry(geometry, geometryType).intersects() // spatial query

.geometry(geometry, geometryType).contains()  // spatial query

.returnGeometry()

.returnCentroid()

.outSpatialReference(wkid)

.sort(sortOrder)

.offset(amount)

.limit(amount)

.offset(amount)

.outStatistics(outStatistics, groupByFieldsForStatistics)

If the query indicates, that the transfer limit was exceeded, more paged queries are executed until all the data has been received.

.ignoreServiceLimits()

.returnCountOnly()

Edits

Edits can be applied using the applyEdits() method.

const cat = await Cat
  .applyEdits()
  .add({ name: 'Grumpy' })
  .exec();

The following edits are possible:

.add(features)

.update(features)

.delete(idArray)

.useGlobalIds() // default

.useObjectIds()

Multi-layer Edits

You can also collect updates across multiple layers and execute them in a single REST call.

const schema = { name: String };
const Cat = await arcgoose.model(connection.layers.Cats, schema);
const Mouse = await arcgoose.model(connection.layers.Mice, schema);

const catHandle = Cat.applyEdits().add({ name: 'Tom' }).handle();
const mouseHandle = Mouse.applyEdits().add({ name: 'Jerry' }).handle();

arcgoose.execAll([catHandle, mouseHandle]);

Authentication

Arcgoose is compatible with @esri/arcgis-rest-auth.

import { UserSession } from '@esri/arcgis-rest-auth';

const session = new UserSession({
  username: "casey",
  password: "123456"
});

const connection = await arcgoose.connect({ url, authentication: session });
const Cat = await arcgoose.model(connection.layers.Cats, { name: String });

const cat = await Cat.findOne({ name: 'Grumpy' }).exec();

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Licensing

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's license.txt file.

Usage no npm install needed!