files.com 1.2.123 → 1.2.124

package/README.md

@@ -194,6 +194,113 @@ Files.configureNetwork({
 })
 ```
 
+## Sort and Filter
+
+Several of the Files.com API resources have list operations that return multiple instances of the resource.  The List operations
+can be sorted and filtered.
+
+### Sorting
+
+The returned data can be sorted by passing in the ```sort_by``` method argument.
+
+Each resource has a set of valid fields for sorting and can be sorted by one field at a time.
+
+The argument value is a Javascript object that has a property of the resource field name sort on and a value of either ```"asc"``` or ```"desc"``` to specify the sort order.
+
+### Filters
+
+Filters apply selection criteria to the underlying query that returns the results. Filters can be applied individually to select resource fields
+and/or in a combination with each other.  The results of applying filters and filter combinations can be sorted by a single field.
+
+The passed in argument value is a Javascript object that has a property of the resource field name to filter on and a passed in value to use in the filter comparison.
+
+Each resource has their own set of valid filters and fields, valid combinations of filters, and sortable fields.
+
+#### Types of Filters
+
+##### Exact Filter
+
+`filter` - find resources that have an exact field value match to a passed in value. (i.e., FIELD_VALUE = PASS_IN_VALUE).
+
+#### Range Filters
+
+`filter_gt` - find resources that have a field value that is greater than the passed in value.  (i.e., FIELD_VALUE > PASS_IN_VALUE).
+
+`filter_gte` - find resources that have a field value that is greater than or equal to the passed in value.  (i.e., FIELD_VALUE >=  PASS_IN_VALUE).
+
+`filter_lt` - find resources that have a field value that is less than the passed in value.  (i.e., FIELD_VALUE < PASS_IN_VALUE).
+
+`filter_lte` - find resources that have a field value that is less than or equal to the passed in value.  (i.e., FIELD_VALUE \<= PASS_IN_VALUE).
+
+##### Pattern Filter
+
+`filter_prefix` - find resources where the specified field is prefixed by the supplied value. This is applicable to values that are strings.
+
+```javascript title="Sort Example"
+// users sorted by username
+Files.setApiKey('my-key');
+var users = await User.list({
+    sort_by: { username: "asc"}
+  })
+
+for (var i = 0; i < users.length; i++) {
+    console.log(users[i].username);
+}
+```
+
+```javascript title="Exact Filter Example"
+// non admin users
+Files.setApiKey('my-key');
+var users = await User.list({
+    filter: { not_site_admin: true },
+    sort_by: { username: "asc"}
+  })
+
+for (var i = 0; i < users.length; i++) {
+    console.log(users[i].username);
+}
+```
+
+```javascript title="Range Filter Example"
+// users who haven't logged in since 2024-01-01
+Files.setApiKey('my-key');
+var users = await User.list({
+    filter_gte: { last_login_at: "2024-01-01" },
+    sort_by: { last_login_at: "asc"}
+  })
+
+for (var i = 0; i < users.length; i++) {
+    console.log(users[i].username);
+}
+```
+
+```javascript title="Pattern Filter Example"
+// users who usernames start with 'test'
+Files.setApiKey('my-key');
+var users = await User.list({
+    filter_prefix: { username: "test" },
+    sort_by: { last_login_at: "asc"}
+  })
+
+for (var i = 0; i < users.length; i++) {
+    console.log(users[i].username);
+}
+```
+
+```javascript title="Combined Filter Example"
+// users who usernames start with 'test' and are not admins
+Files.setApiKey('my-key');
+var users = await User.list({
+    filter_prefix: { username: "test" },
+    filter: { not_site_admin: true },
+    sort_by: { last_login_at: "asc"}
+  })
+
+for (var i = 0; i < users.length; i++) {
+    console.log(users[i].username);
+}
+```
+
 ## Errors
 
 The Files.com JavaScript SDK will return errors by raising exceptions. There are many exception classes defined in the Files SDK that correspond

package/_VERSION

@@ -1 +1 @@
-1.2.123
+1.2.124

package/lib/Files.js

@@ -11,7 +11,7 @@ var endpointPrefix = '/api/rest/v1';
 var apiKey;
 var baseUrl = 'https://app.files.com';
 var sessionId = null;
-var version = '1.2.123';
+var version = '1.2.124';
 var userAgent = "Files.com JavaScript SDK v".concat(version);
 var logLevel = _Logger.LogLevel.INFO;
 var debugRequest = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "files.com",
-  "version": "1.2.123",
+  "version": "1.2.124",
   "description": "Files.com SDK for JavaScript",
   "keywords": [
     "files.com",

package/src/Files.js

@@ -5,7 +5,7 @@ const endpointPrefix = '/api/rest/v1'
 let apiKey
 let baseUrl = 'https://app.files.com'
 let sessionId = null
-const version = '1.2.123'
+const version = '1.2.124'
 let userAgent = `Files.com JavaScript SDK v${version}`
 
 let logLevel = LogLevel.INFO