Issue #224: Deprecate the mustEqualStrict constraint

The constraint is to be removed in the next major release.

Author: OldSneerJaw

CHANGELOG.md

@@ -2,6 +2,10 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [1.11.0] - 2018-02-11
+### Deprecated
+- `mustEqualStrict` constraint
+
 ## [1.10.0] - 2018-01-24
 ### Added
 - [#146](https://github.com/Kashoo/synctos/issues/146): Underscore.js support
@@ -15,22 +19,27 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - [#118](https://github.com/Kashoo/synctos/issues/118): Embed indent.js as a static dependency
 - [#174](https://github.com/Kashoo/synctos/issues/174): Reorganize project source structure
 
-## [1.9.4] - 2018-01-04
+### Deprecated
+- `etc/test-helper.js` module
+- `etc/validation-error-message-formatter.js` module
 
+## [1.9.4] - 2018-01-04
 ### Changed
 - [#157](https://github.com/Kashoo/synctos/issues/157): Swap in Chai as the assertion library used in specs throughout the project
 - [#163](https://github.com/Kashoo/synctos/issues/163): Embed simple-mock as a static development dependency
 
 ### Fixed
-- [#156](https://github.com/Kashoo/synctos/issues/156): Users with a replace role may erroneously gain the privilege of removing a document under certain conditions
 - [#160](https://github.com/Kashoo/synctos/issues/160): Unable to import document if it was deleted via Couchbase SDK
 
+### Security
+- [#156](https://github.com/Kashoo/synctos/issues/156): Users with a replace role may erroneously gain the privilege of removing a document under certain conditions
+
 ## [1.9.3] - 2017-10-23
 ### Fixed
 - [#152](https://github.com/Kashoo/synctos/issues/152): Cannot append a new object with immutable properties to an array
 
 ## [1.9.2] - 2017-10-02
-### Fixed
+### Security
 - [#149](https://github.com/Kashoo/synctos/issues/149): Permissions for add operations sometimes applied to other operation types
 
 ## [1.9.1] - 2017-05-01
@@ -112,7 +121,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [1.0.0] - 2016-07-12
 First public release
 
-[Unreleased]: https://github.com/Kashoo/synctos/compare/v1.10.0...HEAD
+[Unreleased]: https://github.com/Kashoo/synctos/compare/v1.11.0...HEAD
+[1.11.0]: https://github.com/Kashoo/synctos/compare/v1.10.0...v1.11.0
 [1.10.0]: https://github.com/Kashoo/synctos/compare/v1.9.4...v1.10.0
 [1.9.4]: https://github.com/Kashoo/synctos/compare/v1.9.3...v1.9.4
 [1.9.3]: https://github.com/Kashoo/synctos/compare/v1.9.2...v1.9.3

README.md

@@ -433,7 +433,7 @@ Validation for all simple and complex data types support the following additiona
 * `immutableWhenSet`: As with the `immutable` property, the item cannot be changed from its existing value if the document is being replaced. However, it differs in that it only prevents modification if the item is neither `null` nor missing/`undefined`. The constraint is applied recursively so that, even if a value that is nested an arbitrary number of levels deep within an immutable complex type is modified, the document change will be rejected. Does not apply when creating a new document or deleting an existing document. Defaults to `false`.
 * `immutableWhenSetStrict`: As with the `immutableWhenSet` property, the item cannot be changed if it already has a value. However, it differs in that modification is allowed only when the existing value is missing/`undefined`; otherwise, if the existing value is `null` or any other value, it cannot be changed. The constraint is applied recursively so that, even if a value that is nested an arbitrary number of levels deep within an immutable complex type is modified, the document change will be rejected. Does not apply when creating a new document or deleting an existing document. Defaults to `false`. **WARNING:** This constraint exists for advanced users only. Generally the `immutableWhenSet` constraint should be favoured because many programming languages are incapable of distinguishing between `null` and missing values, potentially leading to a situation in which a client application cannot satisfy this constraint depending on the JSON serialization strategy it uses.
 * `mustEqual`: The value of the property or element must be equal to the specified value. Useful in cases where the item's value should be computed from other properties of the document (e.g. a reference ID that is encoded into the document's ID or a number that is the result of some calculation performed on other properties in the document). For that reason, this constraint is perhaps most useful when specified as a dynamic constraint (e.g. `mustEqual: function(doc, oldDoc, value, oldValue) { ... }`) rather than as a static value (e.g. `mustEqual: 'foobar'`). If this constraint is set to `null`, then only values of `null` or missing/`undefined` will be accepted for the corresponding property or element. No constraint by default.
-* `mustEqualStrict`: The value of the property or element must be equal to the specified value. Differs from `mustEqual` in that a value of `null` is treated as different from missing/`undefined`. In other words, if this constraint is set to `null`, then only values of `null` will be accepted for the corresponding property or element. No constraint by default. **WARNING:** This constraint exists for advanced users only. Generally the `mustEqual` constraint should be favoured because many programming languages are incapable of distinguishing between `null` and missing values, potentially leading to a situation in which a client application cannot satisfy this constraint depending on the JSON serialization strategy it uses.
+* `mustEqualStrict`: (**DEPRECATED**) The value of the property or element must be equal to the specified value. Differs from `mustEqual` in that a value of `null` is treated as different from missing/`undefined`. In other words, if this constraint is set to `null`, then only values of `null` will be accepted for the corresponding property or element. No constraint by default. **WARNING:** This constraint exists for advanced users only. Generally the `mustEqual` constraint should be favoured because many programming languages are incapable of distinguishing between `null` and missing values, potentially leading to a situation in which a client application cannot satisfy this constraint depending on the JSON serialization strategy it uses.
 * `customValidation`: A function that accepts as parameters (1) the new document, (2) the old document that is being replaced/deleted (if any), (3) an object that contains metadata about the current item to validate and (4) a stack of the items (e.g. object properties, array elements, hashtable element values) that have gone through validation, where the last/top element contains metadata for the direct parent of the item currently being validated and the first/bottom element is metadata for the root (i.e. the document). In cases where the document is in the process of being deleted, the first parameter's `_deleted` property will be `true`, so be sure to account for such cases. If the document does not yet exist, the second parameter will be null or undefined. And, in some cases where the document previously existed (i.e. it was deleted), the second parameter _may_ be non-null and its `_deleted` property will be `true`. Generally, custom validation should not throw exceptions; it's recommended to return an array/list of error descriptions so the sync function can compile a list of all validation errors that were encountered once full validation is complete. A return value of `null`, `undefined` or an empty array indicate there were no validation errors. An example:
 
 ```

src/document-definitions-loader.js

@@ -29,5 +29,11 @@ function loadFromFile(docDefinitionsFile) {
   var docDefinitionsDir = path.dirname(docDefinitionsFile);
 
   // Automatically replace instances of the "importDocumentDefinitionFragment" macro with the contents of the file that is specified by each
-  return fileFragmentLoader.load(docDefinitionsDir, 'importDocumentDefinitionFragment', docDefinitions);
+  var result = fileFragmentLoader.load(docDefinitionsDir, 'importDocumentDefinitionFragment', docDefinitions);
+
+  if (result.match(/\bmustEqualStrict\b/)) {
+    console.log('WARNING: The "mustEqualStrict" constraint has been deprecated');
+  }
+
+  return result;
 }