Merge pull request #3128 from jspsych/docs-add-utils-reference

Document the `utils` module and reference it in the randomization docs

docs/reference/jspsych-randomization.md

@@ -89,7 +89,7 @@ output:
 full_design = {
 	stimulus: ['a.jpg','b.jpg','b.jpg','a.jpg'],
 	ms_delay: [200, 100, 200, 100]
-]
+}
 */
 ```
 
@@ -182,6 +182,8 @@ This method takes an array of values and generates a new random order of the arr
 
 If the array elements are objects with the same set of properties, then this method can optionally return a single object where each property is a randomized order of the properties defined in the original set of objects. This is useful for randomizing sets of parameters that are used to define a jsPsych block.
 
+This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy).
+
 ### Examples
 
 #### Shuffle an array, no repeats
@@ -414,6 +416,8 @@ An array containing the sample.
 
 This method returns a sample drawn at random from a set of values with replacement. The relative probability of drawing each item can be controlled by specifying the `weights`.
 
+This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy).
+
 ### Examples
 
 #### Sample with equal probability
@@ -455,6 +459,8 @@ An array containing the sample.
 
 This method returns a sample drawn at random from a set of values without replacement. The sample size must be less than or equal to the length of the array.
 
+This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy).
+
 ### Examples
 
 #### Sample without replacement
@@ -532,6 +538,8 @@ Returns an array with the same elements as the input array in a random order.
 
 A simple method for shuffling the order of an array.
 
+This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy).
+
 ### Examples
 
 #### Shuffle an array
@@ -565,6 +573,8 @@ Returns an array with the same elements as the input array in a random order, wi
 
 Shuffle an array, ensuring that neighboring elements in the array are different.
 
+This returns a shallow copy of the array, i.e. modifications to arrays/objects within this array will affect the original. If this is not desired, consider taking a [`deepCopy`](./jspsych-utils.md#jspsychutilsdeepcopy).
+
 *Warning: if you provide an array that has very few valid permutations with no neighboring elements, then this method will fail and cause the browser to hang.*
 
 ### Examples

docs/reference/jspsych-utils.md

@@ -0,0 +1,93 @@
+# jsPsych.utils
+
+The jsPsych.utils module contains utility functions that might turn out useful at one place or the other.
+
+---
+
+## jsPsych.utils.unique
+
+```javascript
+jsPsych.utils.unique(array)
+```
+
+### Parameters
+
+| Parameter | Type  | Description                    |
+| --------- | ----- | ------------------------------ |
+| array     | Array | An array of arbitrary elements |
+
+### Return value
+
+An array containing all elements from the input array, but without duplicate elements
+
+### Description
+
+This function takes an array and returns a copy of that array with all duplicate elements removed.
+
+### Example
+
+```javascript
+jsPsych.utils.unique(["a", "b", "b", 1, 1, 2]) // returns ["a", "b", 1, 2]
+```
+
+---
+
+## jsPsych.utils.deepCopy
+
+```javascript
+jsPsych.utils.deepCopy(object);
+```
+
+### Parameters
+
+| Parameter | Type            | Description                  |
+| --------- | --------------- | ---------------------------- |
+| object    | Object or Array | An arbitrary object or array |
+
+### Return value
+
+A deep copy of the provided object or array
+
+### Description
+
+This function takes an arbitrary object or array and returns a deep copy of it, i.e. all child objects or arrays are recursively copied too.
+
+### Example
+
+```javascript
+var myObject = { nested: ["array", "of", "elements"] };
+var deepCopy = jsPsych.utils.deepCopy(myObject);
+deepCopy.nested[2] = "thingies";
+console.log(myObject.nested[2]) // still logs "elements"
+```
+
+---
+
+## jsPsych.utils.deepMerge
+
+```javascript
+jsPsych.utils.deepMerge(object1, object2);
+```
+
+### Parameters
+
+| Parameter | Type   | Description     |
+| --------- | ------ | --------------- |
+| object1   | Object | Object to merge |
+| object2   | Object | Object to merge |
+
+### Return value
+
+A deep copy of `object1` with all the (nested) properties from `object2` filled in
+
+### Description
+
+This function takes two objects and recursively merges them into a new object. If both objects define the same (nested) property, the property value from `object2` takes precedence.
+
+### Example
+
+```javascript
+var object1 = { a: 1, b: { c: 1, d: 2 } };
+var object2 = { b: { c: 2 }, e: 3 };
+jsPsych.utils.deepMerge(object1, object2); // returns { a: 1, b: { c: 2, d: 2 }, e: 3 }
+```

mkdocs.yml

@@ -71,6 +71,7 @@ nav:
   - 'jsPsych.data': 'reference/jspsych-data.md'
   - 'jsPsych.randomization': 'reference/jspsych-randomization.md'
   - 'jsPsych.turk': 'reference/jspsych-turk.md'
+  - 'jsPsych.utils': 'reference/jspsych-utils.md'
   - 'jsPsych.pluginAPI': 'reference/jspsych-pluginAPI.md'
 - Plugins:
   - 'List of Plugins': 'plugins/list-of-plugins.md'