Add API documentation in JSDoc format.

API.md

@@ -0,0 +1,150 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### Table of Contents
+
+-   [Constants.SCIM_BULK_REQUEST_MESSAGE_URN](#constantsscim_bulk_request_message_urn)
+-   [Constants.SCIM_BULK_RESPONSE_MESSAGE_URN](#constantsscim_bulk_response_message_urn)
+-   [Constants.SCIM_ERROR_MESSAGE_URN](#constantsscim_error_message_urn)
+-   [Constants.SCIM_LIST_RESPONSE_URN](#constantsscim_list_response_urn)
+-   [Constants.SCIM_MEDIA_TYPE](#constantsscim_media_type)
+-   [Constants.SCIM_PATCH_MESSAGE_URN](#constantsscim_patch_message_urn)
+-   [Constants.SCIM_SEARCH_REQUEST_URN](#constantsscim_search_request_urn)
+-   [Patch.addOperation](#patchaddoperation)
+-   [Patch.patchRequest](#patchpatchrequest)
+-   [Patch.removeOperation](#patchremoveoperation)
+-   [Patch.replaceOperation](#patchreplaceoperation)
+-   [Resource](#resource)
+    -   [get](#get)
+    -   [id](#id)
+    -   [meta](#meta)
+    -   [schemas](#schemas)
+    -   [set](#set)
+    -   [toJSON](#tojson)
+    -   [fromJSON](#fromjson)
+
+## Constants.SCIM_BULK_REQUEST_MESSAGE_URN
+
+The SCIM 2 bulk request URN.
+
+## Constants.SCIM_BULK_RESPONSE_MESSAGE_URN
+
+The SCIM 2 bulk response URN.
+
+## Constants.SCIM_ERROR_MESSAGE_URN
+
+The SCIM 2 error message URN.
+
+## Constants.SCIM_LIST_RESPONSE_URN
+
+The SCIM 2 list response URN.
+
+## Constants.SCIM_MEDIA_TYPE
+
+The media type for SCIM 2 messages.
+
+## Constants.SCIM_PATCH_MESSAGE_URN
+
+The SCIM 2 patch request URN.
+
+## Constants.SCIM_SEARCH_REQUEST_URN
+
+The SCIM 2 search request URN.
+
+## Patch.addOperation
+
+Create an 'add' patch operation.
+
+**Parameters**
+
+-   `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A SCIM attribute path.
+-   `value` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** The value to add.
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** An 'add' patch operation object.
+
+## Patch.patchRequest
+
+Create a PATCH request from the provided patch operations.
+
+**Parameters**
+
+-   `operations` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** One or more patch operations.
+
+Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A PATCH request as a JSON string.
+
+## Patch.removeOperation
+
+Create a 'remove' patch operation.
+
+**Parameters**
+
+-   `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A SCIM attribute path.
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** A 'remove' patch operation object.
+
+## Patch.replaceOperation
+
+Create a 'replace' patch operation.
+
+**Parameters**
+
+-   `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A SCIM attribute path.
+-   `value` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** The new value to set.
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** A 'replace' patch operation object.
+
+## Resource
+
+A class representing a generic SCIM resource, such as a user.
+
+### get
+
+Get the attribute value at the specified path.
+
+**Parameters**
+
+-   `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A SCIM attribute path.
+
+Returns **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** The value at the
+specified path, or undefined if the path does not exist.
+
+### id
+
+Get the SCIM resource id.
+
+Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The SCIM resource id.
+
+### meta
+
+Get the SCIM resource's metadata. This might include the
+resource's location and created/updated timestamps.
+
+Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The SCIM resource's metadata.
+
+### schemas
+
+Get the SCIM resource's schemas.
+
+Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** An array of SCIM schema URNs.
+
+### set
+
+Set an attribute value at the specified path.
+
+**Parameters**
+
+-   `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A SCIM attribute path.
+-   `value` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** The value to set.
+
+### toJSON
+
+Get the SCIM resource as a JSON string.
+
+### fromJSON
+
+Create a new {Resource} instance from a JSON string.
+
+**Parameters**
+
+-   `json` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A SCIM resource in JSON format.
+
+Returns **[Resource](#resource)** A SCIM resource object.

README.md

@@ -27,6 +27,10 @@ Or
 yarn add @braveulysses/scim2-js
 ```
 
+## API
+
+See the generated [API docs](API.md).
+
 ## Example
 
 ```javascript
@@ -74,6 +78,8 @@ fetch(url, {
 });
 ```
 
+## API
+
 ## License
 
 This is licensed under the Apache License 2.0.

package.json

@@ -5,6 +5,7 @@
   "main": "./dist/index.js",
   "scripts": {
     "build": "babel src --presets babel-preset-es2015 --out-dir dist",
+    "build-docs": "documentation build 'src/**' --shallow --sort-order alpha --format md --output API.md",
     "prepublish": "npm run build",
     "test": "jest",
     "test-watch": "jest --watch",
@@ -29,6 +30,7 @@
     "babel-cli": "6",
     "babel-jest": "^18.0.0",
     "babel-preset-es2015": "6",
+    "documentation": "^4.0.0-beta.18",
     "jest": "^18.1.0"
   },
   "dependencies": {

src/Constants.js

@@ -1,9 +1,64 @@
 module.exports = {
+  /**
+   * The media type for SCIM 2 messages.
+   * @name Constants.SCIM_MEDIA_TYPE
+   * @constant
+   * @type {string}
+   * @default
+   */
   SCIM_MEDIA_TYPE: 'application/scim+json',
+
+  /**
+   * The SCIM 2 search request URN.
+   * @name Constants.SCIM_SEARCH_REQUEST_URN
+   * @constant
+   * @type {string}
+   * @default
+   */
   SCIM_SEARCH_REQUEST_URN: 'urn:ietf:params:scim:api:messages:2.0:SearchRequest',
+
+  /**
+   * The SCIM 2 list response URN.
+   * @name Constants.SCIM_LIST_RESPONSE_URN
+   * @constant
+   * @type {string}
+   * @default
+   */
   SCIM_LIST_RESPONSE_URN: 'urn:ietf:params:scim:api:messages:2.0:ListResponse',
+
+  /**
+   * The SCIM 2 patch request URN.
+   * @name Constants.SCIM_PATCH_MESSAGE_URN
+   * @constant
+   * @type {string}
+   * @default
+   */
   SCIM_PATCH_MESSAGE_URN: 'urn:ietf:params:scim:api:messages:2.0:PatchOp',
+
+  /**
+   * The SCIM 2 bulk request URN.
+   * @name Constants.SCIM_BULK_REQUEST_MESSAGE_URN
+   * @constant
+   * @type {string}
+   * @default
+   */
   SCIM_BULK_REQUEST_MESSAGE_URN: 'urn:ietf:params:scim:api:messages:2.0:BulkRequest',
+
+  /**
+   * The SCIM 2 bulk response URN.
+   * @name Constants.SCIM_BULK_RESPONSE_MESSAGE_URN
+   * @constant
+   * @type {string}
+   * @default
+   */
   SCIM_BULK_RESPONSE_MESSAGE_URN: 'urn:ietf:params:scim:api:messages:2.0:BulkResponse',
+
+  /**
+   * The SCIM 2 error message URN.
+   * @name Constants.SCIM_ERROR_MESSAGE_URN
+   * @constant
+   * @type {string}
+   * @default
+   */
   SCIM_ERROR_MESSAGE_URN: 'urn:ietf:params:scim:api:messages:2.0:Error'
 };

src/Filter.js

@@ -4,8 +4,8 @@ const OPERATORS = [
   'eq', 'ne', 'co', 'sw', 'ew', 'pr', 'gt', 'ge', 'lt', 'le'
 ];
 
-/**
- * Simple SCIM 2 filter parser. It currently does not support filters
+/*
+ * A simple SCIM 2 filter parser. It currently does not support filters
  * containing multiple expressions (i.e., filters with 'and' or 'or').
  */
 class Filter {

src/Patch.js

@@ -1,5 +1,12 @@
 import { SCIM_PATCH_MESSAGE_URN } from './Constants';
 
+/**
+ * Create a PATCH request from the provided patch operations.
+ * @name Patch.patchRequest
+ * @function
+ * @param {Object} operations - One or more patch operations.
+ * @return {string} A PATCH request as a JSON string.
+ */
 export function patchRequest(...operations) {
   const request = {
     schemas: [
@@ -23,14 +30,37 @@ function _request(op, path, value) {
   return request;
 }
 
+/**
+ * Create an 'add' patch operation.
+ * @name Patch.addOperation
+ * @function
+ * @param {string} path - A SCIM attribute path.
+ * @param {(string|number|boolean|Object)} value - The value to add.
+ * @returns {Object} An 'add' patch operation object.
+ */
 export function addOperation(path, value) {
   return _request('add', path, value);
 }
 
+/**
+ * Create a 'remove' patch operation.
+ * @name Patch.removeOperation
+ * @function
+ * @param {string} path - A SCIM attribute path.
+ * @returns {Object} A 'remove' patch operation object.
+ */
 export function removeOperation(path) {
   return _request('remove', path, null);
 }
 
+/**
+ * Create a 'replace' patch operation.
+ * @name Patch.replaceOperation
+ * @function
+ * @param {string} path - A SCIM attribute path.
+ * @param {(string|number|boolean|Object)} value - The new value to set.
+ * @returns {Object} A 'replace' patch operation object.
+ */
 export function replaceOperation(path, value) {
   return _request('replace', path, value);
 }

src/Resource.js

@@ -1,12 +1,22 @@
 import objectPath from 'object-path';
 import Filter from './Filter';
 
+/**
+ * A class representing a generic SCIM resource, such as a user.
+ */
 class Resource {
   constructor(data) {
     this.data = data;
     this._resolveSchema = this._resolveSchema.bind(this);
   }
 
+  /**
+   * Create a new {Resource} instance from a JSON string.
+   *
+   * @param {string} json - A SCIM resource in JSON format.
+   * @returns {Resource} A SCIM resource object.
+   * @static
+   */
   static fromJSON(json) {
     return new Resource(JSON.parse(json));
   }
@@ -106,18 +116,37 @@ class Resource {
     }
   }
 
+  /**
+   * Get the SCIM resource id.
+   * @returns {string} The SCIM resource id.
+   */
   id() {
     return this.get('id');
   }
 
+  /**
+   * Get the SCIM resource's metadata. This might include the
+   * resource's location and created/updated timestamps.
+   * @returns {string} The SCIM resource's metadata.
+   */
   meta() {
     return this.get('meta');
   }
 
+  /**
+   * Get the SCIM resource's schemas.
+   * @returns {Array} An array of SCIM schema URNs.
+   */
   schemas() {
     return this.get('schemas');
   }
 
+  /**
+   * Get the attribute value at the specified path.
+   * @param {string} path - A SCIM attribute path.
+   * @returns {(string|number|boolean|Object)} The value at the
+   * specified path, or undefined if the path does not exist.
+   */
   get(path) {
     const { attributePath, data } = this._resolveSchema(path);
     const parsedPath = Resource._parseValueFilter(attributePath);
@@ -137,6 +166,11 @@ class Resource {
     return objectPath.get(data, attributePath);
   }
 
+  /**
+   * Set an attribute value at the specified path.
+   * @param {string} path - A SCIM attribute path.
+   * @param {(string|number|boolean|Object)} value - The value to set.
+   */
   set(path, value) {
     const { attributePath, data } = this._resolveSchema(path);
     const parsedPath = Resource._parseValueFilter(attributePath);
@@ -146,6 +180,9 @@ class Resource {
     objectPath.set(data, attributePath, value);
   }
 
+  /**
+   * Get the SCIM resource as a JSON string.
+   */
   toJSON() {
     return JSON.stringify(this.data);
   }