# object-context.js > A JavaScript object change tracking module. Latest version **1.0.10** (published 2017-01-31) · MIT license · 0 weekly downloads ## Install ```sh npm install object-context.js pnpm add object-context.js yarn add object-context.js bun add object-context.js ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.0.10 | | Published | 2017-01-31 | | First published | 2017-01-18 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 0 | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Author | Kieran Nichols | | Maintainers | discgolfer17 | | Keywords | JavaScript, ObjectContext, change, track | ## Links - npm: https://www.npmjs.com/package/object-context.js - Repository: https://github.com/DiscGolfer17/JavaScript-Object-Context - Homepage: https://github.com/DiscGolfer17/JavaScript-Object-Context#readme - Issues: https://github.com/DiscGolfer17/JavaScript-Object-Context/issues - npm.io page: https://npm.io/package/object-context.js ## Alternatives - [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads - [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads - [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads - [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads - [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads ## Recent versions - 1.0.10 (latest) — 2017-01-31 - 1.0.9 — 2017-01-31 - 1.0.8 — 2017-01-31 - 1.0.7 — 2017-01-31 - 1.0.6 — 2017-01-31 - 1.0.5 — 2017-01-31 - 1.0.4 — 2017-01-31 - 1.0.3 — 2017-01-18 - 1.0.2 — 2017-01-18 - 1.0.1 — 2017-01-18 - 1.0.0 — 2017-01-18 ## README JavaScript Object Context ======================================================== > **Version**: 1.0.2 A JavaScript object change tracking module. This module can be used as a standalone container to track JavaScript objects for changes. A sandbox demo Angular 1 app that uses the module can be found in [this plunker](http://plnkr.co/edit/YjvD9gb5iUvVVZC41g6s). ## Angular 2+ By using the ngDoCheck lifecycle hook in Angular 2+ you can have Angular automatically evaluate the context for changes. ## Angular 1.x To use with Angular 1.x you must include the 'ngObjectContext' module as a dependency and it will automatically evaluate the context for changes. * [API Documentation](#api-documentation) * [Development](#development) ## API Documentation * **`object` evaluate()** This is the change tracking engine. Checks if any of the property values in each of the tracked objects have any changes. Will recursively evaluate child properties that are arrays/objects themselves. - `returns` `object` A reference to `this` for chaining. * **`boolean` doesObjectExist(objectReference)** Checks to see if the provided object has already been added to the context. - `parameter` `object` `objectReference` The object to test for existence. - `returns` `boolean` if the objects exists already, `false` otherwise. * **`object` add(obj, [isStatusNew])** Adds an object to the context. Any changes to the properties on this object will trigger the context to have changes (after `evaluate()` is called) and notify any subscribers. This method wraps the passed in object in an object that it can work with. The passed in object will be copied so it can store its original state. If a meta property does not exist on the object then one will be added to it. Any changes that are made to this object can be seen by querying the `changeset` property. - `parameter` `object` `obj` The object to start tracking. - `parameter` `boolean` `isStatusNew` `[optional]` A boolean flag to indicate if this object is to be marked as 'New' or 'Unmodified'. Default value is falsy. - `returns` `object` A reference to `this` for chaining. * **`object` delete(obj, [hardDelete], [canRemoveMetadata])** Marks the provided object as 'Deleted'. If the object doesn't exist, an exception will be thrown. If `hardDelete` is true, then the object will be instantly removed from the context. Any children of this object will also be removed. Note: When 'hard-deleting' an object, the `_objectMeta` property is looked at and its status is reverted to its original value before deletion. - `parameter` `object` `obj` The object to delete. - `parameter` `boolean` `hardDelete` `[optional]` A boolean flag to determine if the object should be removed or just marked as 'Deleted'. The default value is falsy. - `parameter` `boolean` `canRemoveMetadata` `[optional]` A boolean flag to determine if an objects metadata property is to be removed before deleting. - `returns` `object` A reference to `this` for chaining. - `throws` Errorif the provided object doesn't exist. * **`boolean` hasChanges([obj])** Determines if any of the tracked objects in the context have any active changesets or are marked as 'New', 'Modified', or 'Deleted'. If an object is passed, then just that object will be tested for changes. - `parameter` `object` `obj` An existing context object to test for changes. - `returns` `boolean` True if changes exist, false otherwise. * **`boolean` hasChildChanges(obj)** Determines if the provided object has any children that are marked as being changed. - `parameter` `object` `obj` The object to check. - `returns` `boolean` True if the object has child changes, false otherwise. - `throws` Error if the provided object could not be found. * **`object` clear(canRemoveMetadata)** Removes all currently tracked objects, and resets the state of the context. This will usually be called when the state of the application is being destroyed, or if any object that are laoded into the context are no longer relevant. Note: When clearing the context, the `_objectMeta` property is looked at and its status is reverted to its original value before it is cleared. - `parameter` `boolean` `canRemoveMetadata` Whether or not the objects' metadata property is removed from itself before clear. - `returns` `object` A reference to `this` for chaining. * **`array` getObjects(returnMappedObjects)** Returns all objects in the context in their current state. - `parameter` `boolean` `returnMappedObjects` If true is passed, then the internal objects are returned, otherwise the objects as they were added are returned in their current state. - `returns` `array` An array of all existing objects. * **`array` getUnmodifiedObjects(parentsOnly)** Returns all objects that have status of 'Unmodified'. - `parameter` `boolean` `parentsOnly` Retrieve only parent objects if true, false will fetch all objects including children. - `returns` `array` An array of objects with a status of 'Unmodified'. * **`array` getModifiedObjects(parentsOnly)** Returns all objects that have status of 'Modified'. - `parameter` `boolean` `parentsOnly` Retrieve only parent objects if true, false will fetch all objects including children. - `returns` `array` An array of objects with a status of 'Modified'. * **`array` getNewObjects(parentsOnly)** Returns all objects that have status of 'New'. - `parameter` `boolean` `parentsOnly` Retrieve only parent objects if true, false will fetch all objects including children. - `returns` `array` An array of objects with a status of 'New'. * **`array` getDeletedObjects(parentsOnly)** Returns all objects that have status of 'Deleted'. - `parameter` `boolean` `parentsOnly` Retrieve only parent objects if true, false will fetch all objects including children. - `returns` `array` An array of objects with a status of 'Deleted'. * **`array` getObjectsByType(requestedType)** Attempts to find all objects in the context that have the `requestedType` noted in their metadata. If an object does not provide a type, its default type of 'Object' will be used. - `parameter` `string` `requestedType` The type of objects to fetch from the context. - `returns` `array` An array of objects found. * **`object` acceptChanges()** Applies all changes in currently modified objects. After this, all objects that previously had a status that was not equal to 'Unmodified', will now have an 'Unmodified' status. If the object has a status of deleted, then the object will be removed from the context. Objects that were unchanged are not touched. - `returns` `object` A reference to `this` for chaining. * **`array` getChangeset(obj, [includeChildren])** Returns the changeset for a specified object. If an object was not provided, then we return the changeset for all objects. If `includeChildren` is passed along with an object, then we fetch the changesets for all objects in the context, that have the provided object as a parent. - `parameter` `object` `obj` An object to search for. - `parameter` `boolean` `includeChildren` `[optional]` Include children of the provided (if possible) - `returns` `array` An array with the properties that have changed. - `throws` Error if the provided object could not be found. * **`object` getOriginal(objectReference)** Returns a copy of the original unchanged object in the state that it was in when it was either added or last saved. If the object is not found then `null` is returned. - `parameter` `object` `objectReference` The object to search for. - `returns` `object` A copy of the original object, or null if not found. * **`string` getObjectStatus(obj)** Gets an object status for the specified object reference. - `parameter` `object` `obj` The object to search for. - `returns` `string` The status of the requested object. - `throws` Error if `obj` could not be found. * **`object` rejectChanges([obj])** Rejects changes for an object that exist in the context by setting the values in the object back its original values. If a single object is passed, it will be tested for existance, and then that one object will be reverted. If no object is passed, then all objects will be reverted. - `parameter` `object` `obj` `[optional]` An existing context object to reject changes for. - `returns` `object` A reference to this for chaining. - `throws` Error if `obj` is provided and could not be found. * **`number` subscribeChangeListener(listener)** Subcribes the passed listener function that will be invoked when a change has occured. - `parameter` `function` `listener` A function to invoke when a change occurs to any objects in the context. - `returns` `number` The total number of subscribed listeners. - `throws` Error if `listener` is not a `function`. * **`number` unsubscribeChangeListener(listener)** Unsubscribes the provided change listener. - `parameter` `function` `listener` A function reference to unsubscribe. - `returns` `number` The total number of subscribed listeners. - `throws` Error if `listener` was not subscribed first. * **`void` log()** Output the state and all objects in the context to the console. - `returns` `object` A reference to this for chaining. * **`object` create()** Call this when creating a new object. The object will be flagged as 'New' and will automatically be added to the context. - `parameter` `string` `type` The type of object to create. - `parameter` `object` `obj` THe object structure to add. - `returns` `object` A reference to this for chaining. * **`array` query(type, [params])** Used for querying objects from the context by type. Query parameters are optional to filter the data further. - `parameter` `string` `type` The type of objects to query. - `parameter` `object` `params` `[optional]` An object containing properties and values to search for. - `returns` `array` An array of found objects. ## Development * Install karma (with the karma-coverage plugin): - npm install karma - npm install karma-coverage - npm install karma-jasmine - npm install jasmine-core - (Windows only) npm install -g karma-cli - karma init - karma start --- _Source: https://npm.io/package/object-context.js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._