https://github.com/esri/arcgoose
Mongoose-style bindings for the ArcGIS REST API
https://github.com/esri/arcgoose
arcgis-rest-api rest-api schemas web
Last synced: 4 months ago
JSON representation
Mongoose-style bindings for the ArcGIS REST API
- Host: GitHub
- URL: https://github.com/esri/arcgoose
- Owner: Esri
- License: apache-2.0
- Created: 2018-10-18T13:23:59.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-07-08T12:40:03.000Z (over 2 years ago)
- Last Synced: 2025-06-09T17:09:44.847Z (4 months ago)
- Topics: arcgis-rest-api, rest-api, schemas, web
- Language: JavaScript
- Size: 1.69 MB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
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.
```javascript
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](https://mongoosejs.com) syntax.
## Installing
```
$ npm install --save arcgoose
```
Then, just import to your service or module:
```jsx
import arcgoose from 'arcgoose';
```
## Instructions
### Connecting to ArcGIS Feature Server
Using the feature server URL:
```javascript
const connection = await arcgoose.connect({ url });
```
Using the hosted feature layer item id:
```javascript
const connection = await arcgoose.connect({ portalUrl, portalItemId });
```
Structure of the `connection` JSON object:
```javascript
{
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](https://github.com/epoberezkin/ajv#api) library for validation.
```javascript
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.
```javascript
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.
```javascript
const cat = await Cat
.find({ name: 'Grumpy' })
.exec();
```
Additional query methods can be chained after the `find()` method.
```javascript
const cat = await Cat
.find({ name: 'Grumpy' })
.populate(['name', 'dateOfBirth'])
.returnGeometry()
.exec();
```
Here is a list of additional query methods:
```javascript
.filter(additionalSQLWhereClause) // chain as many as you like
```
```javascript
.populate(outFields) // otherwise all fields from the schema will be populated
```
```javascript
.geometry(geometry, geometryType).intersects() // spatial query
```
```javascript
.geometry(geometry, geometryType).contains() // spatial query
```
```javascript
.returnGeometry()
```
```javascript
.returnCentroid()
```
```javascript
.outSpatialReference(wkid)
```
```javascript
.sort(sortOrder)
```
```javascript
.offset(amount)
```
```javascript
.limit(amount)
```
```javascript
.offset(amount)
```
```javascript
.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.
```javascript
.ignoreServiceLimits()
```
```javascript
.returnCountOnly()
```
### Edits
Edits can be applied using the `applyEdits()` method.
```javascript
const cat = await Cat
.applyEdits()
.add({ name: 'Grumpy' })
.exec();
```
The following edits are possible:
```javascript
.add(features)
```
```javascript
.update(features)
```
```javascript
.delete(idArray)
```
```javascript
.useGlobalIds() // default
```
```javascript
.useObjectIds()
```
### Multi-layer Edits
You can also collect updates across multiple layers and execute them in a single REST call.
```javascript
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](https://github.com/Esri/arcgis-rest-js/blob/master/packages/arcgis-rest-auth).
```javascript
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](https://github.com/esri/contributing).
## Licensing
Copyright 2018 Esri
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](/license.txt) file.