![\"Download](\"https://img.shields.io/npm/dt/validated-changeset.svg\")
\n![\"TravisCI](\"https://github.com/adopted-ember-addons/validated-changeset/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n![\"npm](\"https://badge.fury.io/js/validated-changeset.svg\"){kind=icon}
\n\n```\nnpm install validated-changeset --save\n```\n\n#### tl;dr\n\nThis library is the base class for functionality in [ember-changeset](https://github.com/adopted-ember-addons/ember-changeset) but could be used with any front end framework. Example uses in template assume handlebars.\n\n```js\nimport { Changeset } from 'validated-changeset';\n\nlet changeset = Changeset(user, validatorFn);\nuser.firstName; // \"Michael\"\nuser.lastName; // \"Bolton\"\n\nchangeset.set('firstName', 'Jim');\nchangeset.set('lastName', 'B');\nchangeset.get('isInvalid'); // true\nchangeset.get('errors'); // [{ key: 'lastName', validation: 'too short', value: 'B' }]\nchangeset.set('lastName', 'Bob');\nchangeset.get('isValid'); // true\n\nuser.firstName; // \"Michael\"\nuser.lastName; // \"Bolton\"\n\nchangeset.save(); // sets and saves valid changes on the user\nuser.firstName; // \"Jim\"\nuser.lastName; // \"Bob\"\n```\n\n## Usage\n\nFirst, create a new `Changeset` through JavaScript:\n\n```js\nimport { Changeset } from 'validated-changeset';\n\nexport default class FormComponent {\n constructor(...args) {\n let validatorFn = this.validate;\n this.changeset = Changeset(this.model, validatorFn);\n }\n}\n```\n\nThe helper receives any Object and an optional `validator` action. If a `validator` is passed into the helper, the changeset will attempt to call that function when a value changes.\n\nIn the above example, when the input changes, only the changeset's internal values are updated. When the submit button is clicked, the changes are only executed if *all changes* are valid.\n\nOn rollback, all changes are dropped and the underlying Object is left untouched.\n\n## Full API\n\n```js\nChangeset(model, lookupValidator(validationMap), validationMap, { skipValidate: boolean, initValidate: boolean, changesetKeys: string[] });\n```\n\n- `model` (required)\n\n- `validationFunc` (optional) - see [ember-changeset-validations](https://github.com/adopted-ember-addons/ember-changeset-validations#usage) for usage.\n\n- `validationMap` (optional) - see [ember-changeset-validations](https://github.com/adopted-ember-addons/ember-changeset-validations#usage) for usage.\n\n > note: `validationMap` might not be inclusive of all keys that can be set on an object.\n\n- `changesetKeys` (optional) - will ensure your changeset and related `isDirty` state is contained to a specific enum of keys. If a key that is not in `changesetKeys` is set on the changeset, it will not dirty the changeset.\n\n- `initValidate` (optional) - will run the validations and set the validation state when the changeset is created. This option does not support async validations.\n\n## Alternative Changeset\n\nWe now ship a ValidatedChangeset that is a proposed new API we would like to ship. The goal of this refactor is to remove confusing APIs and externalize validations.\n\n- ✂️ `save`\n- ✂️ `cast`\n- ✂️ `merge`\n- `errors` are required to be added to the Changeset manually after `validate`\n- `validate` takes a callback with the sum of changes. In user land you will call `changeset.validate((changes) => yupSchema.validate(changes))`\n\n\n```js\nimport { ValidationChangeset } from 'validated-changeset';\nimport { array, object, string, number, date } from 'yup';\n\nconst UserSchema = object({\n name: string().required(),\n age: number()\n .required()\n .positive()\n .integer(),\n email: string().email(),\n website: string()\n .url()\n .nullable(),\n createdOn: date().default(() => new Date())\n});\n\nexport default class FormComponent {\n constructor(...args) {\n this.changeset = ValidationChangeset(this.model);\n }\n\n onSubmit() {\n try {\n await this.changeset.validate(changes => UserSchema.validate(changes));\n this.changeset.removeError()\n } catch (e) {\n dummyChangeset.addError(e.path, { value: changeset.get(e.path), validation: e.message });\n }\n }\n}\n```\n\n## Examples\n\n- [`ember-changeset`](https://github.com/adopted-ember-addons/ember-changeset)\n- [`svelte example`](https://codesandbox.io/s/validated-svelte-xc5lp?fontsize=14&hidenavigation=1&theme=dark)\n\n## API\n\n* Properties\n + [`error`](#error)\n + [`change`](#change)\n + [`errors`](#errors)\n + [`changes`](#changes)\n + [`data`](#data)\n + [`isValid`](#isvalid)\n + [`isInvalid`](#isinvalid)\n + [`isPristine`](#ispristine)\n + [`isDirty`](#isdirty)\n* Methods\n + [`get`](#get)\n + [`set`](#set)\n + [`prepare`](#prepare)\n + [`execute`](#execute)\n + [`save`](#save)\n + [`merge`](#merge)\n + [`rollback`](#rollback)\n + [`rollbackInvalid`](#rollbackinvalid)\n + [`rollbackProperty`](#rollbackproperty)\n + [`validate`](#validate)\n + [`addError`](#adderror)\n + [`pushErrors`](#pusherrors)\n + [`removeError`](#removeerror)\n + [`removeErrors`](#removeerrors)\n + [`snapshot`](#snapshot)\n + [`restore`](#restore)\n + [`cast`](#cast)\n + [`isValidating`](#isvalidating)\n* Events\n + [`beforeValidation`](#beforevalidation)\n + [`afterValidation`](#aftervalidation)\n + [`afterRollback`](#afterrollback)\n\n#### `error`\n\nReturns the error object.\n\n```js\n{\n firstName: {\n value: 'Jim',\n validation: 'First name must be greater than 7 characters'\n }\n}\n```\n\nNote that keys can be arbitrarily nested:\n\n```js\n{\n address: {\n zipCode: {\n value: '123',\n validation: 'Zip code must have 5 digits'\n }\n }\n}\n```\n\nIf you have multiple validations, `validation` will be an array:\n\n```js\n{\n address: {\n zipCode: {\n value: '123',\n validation: ['Zip code must have 5 digits', 'too short']\n }\n }\n}\n```\n\nYou can use this property to locate a single error:\n\n```hbs\n{{#if changeset.error.firstName}}\n {{changeset.error.firstName.validation}}
\n{{/if}}\n\n{{#if changeset.error.address.zipCode}}\n{{changeset.error.address.zipCode.validation}}
\n{{/if}}\n```\n\n**[⬆️ back to top](#api)**\n\n#### `change`\n\nReturns the change object.\n\n```js\n{\n firstName: 'Jim'\n}\n```\n\nNote that keys can be arbitrarily nested:\n\n```js\n{\n address: {\n zipCode: '10001'\n }\n}\n```\n\nYou can use this property to locate a single change:\n\n```hbs\n{{changeset.change.firstName}}\n{{changeset.change.address.zipCode}}\n```\n\n**[⬆️ back to top](#api)**\n\n#### `errors`\n\nReturns an array of errors. If your `validate` function returns a non-boolean value, it is added here as the `validation` property.\n\n```js\n[\n {\n key: 'firstName',\n value: 'Jim',\n validation: 'First name must be greater than 7 characters'\n },\n {\n key: 'address.zipCode',\n value: '123',\n validation: 'Zip code must have 5 digits'\n }\n]\n```\n\nYou can use this property to render a list of errors:\n\n```hbs\n{{#if changeset.isInvalid}}\nThere were errors in your form:
\nGood job!
\n{{/if}}\n```\n\n**[⬆️ back to top](#api)**\n\n#### `isInvalid`\n\nReturns a Boolean value of the changeset's (in)validity.\n\n```js\nchangeset.get('isInvalid'); // true\n```\n\nYou can use this property in the template:\n\n```hbs\n{{#if changeset.isInvalid}}\nThere were one or more errors in your form
\n{{/if}}\n```\n\n**[⬆️ back to top](#api)**\n\n#### `isPristine`\n\nReturns a Boolean value of the changeset's state. A pristine changeset is one with no changes.\n\n```js\nchangeset.get('isPristine'); // true\n```\n\nIf changes present on the changeset are equal to the content's, this will return `true`. However, note that key/value pairs in the list of changes must all be present and equal on the content, but not necessarily vice versa:\n\n```js\nlet user = { name: 'Bobby', age: 21, address: { zipCode: '10001' } };\n\nchangeset.set('name', 'Bobby');\nchangeset.get('isPristine'); // true\n\nchangeset.set('address.zipCode', '10001');\nchangeset.get('isPristine'); // true\n\nchangeset.set('foo', 'bar');\nchangeset.get('isPristine'); // false\n```\n\n**[⬆️ back to top](#api)**\n\n#### `isDirty`\n\nReturns a Boolean value of the changeset's state. A dirty changeset is one with changes.\n\n```js\nchangeset.get('isDirty'); // true\n```\n\n**[⬆️ back to top](#api)**\n\n#### `get`\n\nExactly the same semantics as `Ember.get`. This proxies first to the error value, the changed value, and finally to the underlying Object.\n\n```js\nchangeset.get('firstName'); // \"Jim\"\nchangeset.set('firstName', 'Billy'); // \"Billy\"\nchangeset.get('firstName'); // \"Billy\"\n\nchangeset.get('address.zipCode'); // \"10001\"\nchangeset.set('address.zipCode', '94016'); // \"94016\"\nchangeset.get('address.zipCode'); // \"94016\"\n```\n\nYou can use and bind this property in the template:\n\n```hbs\n{{input value=changeset.firstName}}\n```\n\nNote that using `Ember.get` **will not necessarily work if you're expecting an Object**. On the other hand, using `changeset.get` will work just fine:\n\n```js\nget(changeset, 'momentObj').format('dddd'); // will error, format is undefined\nchangeset.get('momentObj').format('dddd'); // => \"Friday\"\n```\n\nThis is because `Changeset` wraps an Object with `Ember.ObjectProxy` internally, and overrides `Ember.Object.get` to hide this implementation detail.\n\nBecause an Object is wrapped with `Ember.ObjectProxy`, the following (although more verbose) will also work:\n\n```js\nget(changeset, 'momentObj.content').format('dddd'); // => \"Friday\"\n```\n\n**[⬆️ back to top](#api)**\n\n#### `set`\n\nExactly the same semantics as `Ember.set`. This stores the change on the changeset. It is recommended to use `changeset.set(...)` instead of `Ember.set(changeset, ...)`. `Ember.set` will set the property for nested keys on the underlying model.\n\n```js\nchangeset.set('firstName', 'Milton'); // \"Milton\"\nchangeset.set('address.zipCode', '10001'); // \"10001\"\n```\n\nYou can use and bind this property in the template:\n\n```hbs\n{{input value=changeset.firstName}}\n{{input value=changeset.address.country}}\n```\n\nAny updates on this value will only store the change on the changeset, even with 2 way binding.\n\n**[⬆️ back to top](#api)**\n\n#### `prepare`\n\nProvides a function to run before emitting changes to the model. The callback function must return a hash in the same shape:\n\n```js\nchangeset.prepare((changes) => {\n // changes = { firstName: \"Jim\", lastName: \"Bob\", 'address.zipCode': \"07030\" };\n let modified = {};\n\n for (let key in changes) {\n let newKey = key.split('.').map(underscore).join('.')\n modified[newKey] = changes[key];\n }\n\n // don't forget to return, the original changes object is not mutated\n // modified = { first_name: \"Jim\", last_name: \"Bob\", 'address.zip_code': \"07030\" };\n return modified;\n}); // returns changeset\n```\n\nThe callback function is **not validated** – if you modify a value, it is your responsibility to ensure that it is valid.\n\nReturns the changeset.\n\n**[⬆️ back to top](#api)**\n\n#### `execute`\n\nApplies the valid changes to the underlying Object.\n\n```js\nchangeset.execute(); // returns changeset\n```\n\nNote that executing the changeset will not remove the internal list of changes - instead, you should do so explicitly with `rollback` or `save` if that is desired.\n\nMoreover, if you need to perform additional work on `changeset.execute`, you can register a callback with a key 'execute' and we will ensure it is carried out whenever `changeset.execute` is called.\n\n```js\nfunction callback() {\n ...\n}\nchangeset.on('execute', callback);\n\n\nchangeset.execute();\n```\n\n#### `unexecute`\n\nUndo changes made to underlying Object for changeset. This is often useful if you want to remove changes from underlying Object if `save` fails.\n\n```js\nchangeset\n .save()\n .catch(() => {\n // save applies changes to the underlying Object via this.execute(). This may be undesired for your use case.\n dummyChangeset.unexecute();\n })\n```\n\n**[⬆️ back to top](#api)**\n\n#### `save`\n\nExecutes changes, then proxies to the underlying Object's `save` method, if one exists. If it does, the method can either return a `Promise` or a non-`Promise` value. Either way, the changeset's `save` method will return\na promise.\n\n```js\nchangeset.save(); // returns Promise\n```\n\nThe `save` method will also remove the internal list of changes if the `save` is successful.\n\n**[⬆️ back to top](#api)**\n\n#### `merge`\n\nMerges 2 changesets and returns a Changeset with the same underlying content and validator as the origin. Both changesets must point to the same underlying object. For example:\n\n```js\nlet changesetA = Changeset(user, validatorFn);\nlet changesetB = Changeset(user, validatorFn);\n\nchangesetA.set('firstName', 'Jim');\nchangesetA.set('address.zipCode', '94016');\n\nchangesetB.set('firstName', 'Jimmy');\nchangesetB.set('lastName', 'Fallon');\nchangesetB.set('address.zipCode', '10112');\n\nlet changesetC = changesetA.merge(changesetB);\nchangesetC.execute();\n\nuser.firstName; // \"Jimmy\"\nuser.lastName; // \"Fallon\"\nuser.address.zipCode; // \"10112\"\n```\n\nNote that both changesets `A` and `B` are not destroyed by the merge, so you might want to call `destroy()` on them to avoid memory leaks.\n\n**[⬆️ back to top](#api)**\n\n#### `rollback`\n\nRolls back all unsaved changes and resets all errors.\n\n```js\nchangeset.rollback(); // returns changeset\n```\n\n**[⬆️ back to top](#api)**\n\n#### `rollbackInvalid`\n\nRolls back all invalid unsaved changes and resets all errors. Valid changes will be kept on the changeset.\n\n```js\nchangeset.rollbackInvalid(); // returns changeset\n```\n\n**[⬆️ back to top](#api)**\n\n#### `rollbackProperty`\n\nRolls back unsaved changes for the specified property only. All other changes will be kept on the changeset.\n\n```js\n// user = { firstName: \"Jim\", lastName: \"Bob\" };\nlet changeset = Changeset(user);\nchangeset.set('firstName', 'Jimmy');\nchangeset.set('lastName', 'Fallon');\nchangeset.rollbackProperty('lastName'); // returns changeset\nchangeset.execute();\nuser.firstName; // \"Jimmy\"\nuser.lastName; // \"Bob\"\n```\n\n**[⬆️ back to top](#api)**\n\n#### `validate`\n\nValidates all, single or multiple fields on the changeset. This will also validate the property on the underlying object, and is a useful method if you require the changeset to validate immediately on render.\n\n**Note:** This method requires a validation map to be passed in when the changeset is first instantiated.\n\n```js\nuser.lastName = 'B';\nuser.address = {\n zipCode: '123'\n};\n\nlet validationMap = {\n lastName: validateLength({ min: 8 }),\n\n // specify nested keys with dot delimiters\n 'address.zipCode': validateLength({ is: 5 }),\n};\n\nlet changeset = Changeset(user, validatorFn, validationMap);\nchangeset.get('isValid'); // true\n\n// validate single field; returns Promise\nchangeset.validate('lastName');\nchangeset.validate('address.zipCode');\n// multiple keys\nchangeset.validate('lastName', 'address.zipCode');\n\n// validate all fields; returns Promise\nchangeset.validate().then(() => {\n changeset.get('isInvalid'); // true\n\n // [{ key: 'lastName', validation: 'too short', value: 'B' },\n // { key: 'address.zipCode', validation: 'too short', value: '123' }]\n changeset.get('errors');\n});\n```\n\n**[⬆️ back to top](#api)**\n\n#### `addError`\n\nManually add an error to the changeset.\n\n```js\nchangeset.addError('email', {\n value: 'jim@bob.com',\n validation: 'Email already taken'\n});\n\nchangeset.addError('address.zip', {\n value: '123',\n validation: 'Must be 5 digits'\n});\n\n// shortcut\nchangeset.addError('email', 'Email already taken');\nchangeset.addError('address.zip', 'Must be 5 digits');\n```\n\nAdding an error manually does not require any special setup. The error will be cleared if the value for the `key` is subsequently set to a valid value. Adding an error will overwrite any existing error or change for `key`.\n\nIf using the shortcut method, the value in the changeset will be used as the value for the error.\n\n**[⬆️ back to top](#api)**\n\n#### `pushErrors`\n\nManually push errors to the changeset.\n\n```js\nchangeset.pushErrors('age', 'Too short', 'Not a valid number', 'Must be greater than 18');\nchangeset.pushErrors('dogYears.age', 'Too short', 'Not a valid number', 'Must be greater than 2.5');\n```\n#### `removeError`\n\nManually remove an error from the changeset.\n\n```js\nchangeset.removeError('email');\n```\nRemoves an error without having to rollback the property.\n\n**[⬆️ back to top](#api)**\n\n#### `removeErrors`\n\nManually remove an error from the changeset.\n\n```js\nchangeset.removeErrors()\n```\nRemoves all the errors without having to rollback properties.\n\n**[⬆️ back to top](#api)**\n\n#### `snapshot`\n\nCreates a snapshot of the changeset's errors and changes. This can be used to `restore` the changeset at a later time.\n\n```js\nlet snapshot = changeset.snapshot(); // snapshot\n```\n\n**[⬆️ back to top](#api)**\n\n#### `restore`\n\nRestores a snapshot of changes and errors to the changeset. This overrides existing changes and errors.\n\n```js\nlet user = { name: 'Adam', address: { country: 'United States' } };\nlet changeset = Changeset(user, validatorFn);\n\nchangeset.set('name', 'Jim Bob');\nchangeset.set('address.country', 'North Korea');\nlet snapshot = changeset.snapshot();\n\nchangeset.set('name', 'Poteto');\nchangeset.set('address.country', 'Australia')\n\nchangeset.restore(snapshot);\nchangeset.get('name'); // \"Jim Bob\"\nchangeset.get('address.country'); // \"North Korea\"\n```\n\n**[⬆️ back to top](#api)**\n\n#### `cast`\n\nUnlike `Ecto.Changeset.cast`, `cast` will take an array of allowed keys and remove unwanted keys off of the changeset.\n\n```js\nlet allowed = ['name', 'password', 'address.country'];\nlet changeset = Changeset(user, validatorFn);\n\nchangeset.set('name', 'Jim Bob');\nchangeset.set('address.country', 'United States');\n\nchangeset.set('unwantedProp', 'foo');\nchangeset.set('address.unwantedProp', 123);\nchangeset.get('unwantedProp'); // \"foo\"\nchangeset.get('address.unwantedProp'); // 123\n\nchangeset.cast(allowed); // returns changeset\nchangeset.get('unwantedProp'); // undefined\nchangeset.get('address.country'); // \"United States\"\nchangeset.get('another.unwantedProp'); // undefined\n```\n\nFor example, this method can be used to only allow specified changes through prior to saving. This is especially useful if you also setup a `schema` object for your model (using Ember Data), which can then be exported and used as a list of allowed keys:\n\n```js\n// models/user.js\nexport const schema = {\n name: attr('string'),\n password: attr('string')\n};\n\nexport default Model.extend(schema);\n```\n\n```js\n// controllers/foo.js\nimport { schema } from '../models/user';\n\nexport default Controller.extend({\n // ...\n\n actions: {\n save(changeset) {\n return changeset\n .cast(Object.keys(schema))\n .save();\n }\n }\n});\n```\n\n**[⬆️ back to top](#api)**\n\n#### `isValidating`\n\nChecks to see if async validator for a given key has not resolved. If no key is provided it will check to see if any async validator is running.\n\n```js\nchangeset.set('lastName', 'Appleseed');\nchangeset.set('firstName', 'Johnny');\nchangeset.set('address.city', 'Anchorage');\nchangeset.validate();\n\nchangeset.isValidating(); // true if any async validation is still running\nchangeset.isValidating('lastName'); // true if lastName validation is async and still running\nchangeset.isValidating('address.city'); // true if address.city validation is async and still running\n\nchangeset.validate().then(() => {\n changeset.isValidating(); // false since validations are complete\n});\n```\n\n**[back to top](#api)**\n\n#### `beforeValidation`\n\nThis event is triggered after isValidating is set to true for a key, but before the validation is complete.\n\n```js\nchangeset.on('beforeValidation', key => {\n console.log(`${key} is validating...`);\n});\nchangeset.validate();\nchangeset.isValidating(); // true\n// console output: lastName is validating...\n// console output: address.city is validating...\n```\n\n**[⬆️ back to top](#api)**\n\n#### `afterValidation`\n\nThis event is triggered after async validations are complete and isValidating is set to false for a key.\n\n```js\nchangeset.on('afterValidation', key => {\n console.log(`${key} has completed validating`);\n});\nchangeset.validate().then(() => {\n changeset.isValidating(); // false\n // console output: lastName has completed validating\n // console output: address.city has completed validating\n});\n```\n\n**[⬆️ back to top](#api)**\n\n#### `afterRollback`\n\nThis event is triggered after a rollback of the changeset.\nThis can be used for [some advanced use cases](https://github.com/offirgolan/ember-changeset-cp-validations/issues/25#issuecomment-375855834)\nwhere it is necessary to separately track all changes that are made to the changeset.\n\n```js\nchangeset.on('afterRollback', () => {\n console.log(\"changeset has rolled back\");\n});\nchangeset.rollback();\n// console output: changeset has rolled back\n```\n\n**[⬆️ back to top](#api)**\n\n## Validation signature\n\nTo use with your favorite validation library, you should create a custom `validator` action to be passed into the changeset:\n\n```js\n// application/controller.js\nimport { action } from '@ember/object';\n\nexport default class FormController {\n @action\n validate({ key, newValue, oldValue, changes, content }) {\n // lookup a validator function on your favorite validation library\n // should return a Boolean\n }\n}\n```\n\n```hbs\n{{! application/template.hbs}}\n