Ember-immer-changeset

ember-immer-changeset is an Ember addon that provides a robust changeset implementation using Immer. It allows you to easily manage, apply, and rollback changes in your data with immutability guarantees.

Key Features

• Immutable Data: Use Immer to manage immutable changes to data objects.
• Track Changes: Automatically track changes and patches made to your data.
• Validation: Integrate validation logic and manage errors easily.
• Revertible: Rollback changes or properties to previous states.
• Events: Hooks for listening to changes on specific properties.

Minimum Requirements

• Ember.js v4.4 or above
• Ember CLI v4.4 or above
• Node.js v16 or above

Installation

To install this addon, run:

ember install ember-immer-changeset

Documentation

For full API documentation and examples, visit the ember-immer-changeset documentation.

Example Usage

import ImmerChangeset from 'ember-immer-changeset';

// Define your data object
const userData = {
  id: 1,
  name: 'John Doe',
  email: '[email protected]',
  age: 30,
};

// Create a new changeset instance
const userChangeset = new ImmerChangeset(userData);

// Make changes
userChangeset.set('name', 'Jane Doe');
userChangeset.set('age', 31);

// Check if there are changes
console.log('Is Dirty:', userChangeset.isDirty); // true

// Get the changes made
console.log('Changes:', userChangeset.changes); // [{ key: 'name', value: 'Jane Doe' }, { key: 'age', value: 31 }]

// Validate changes
await userChangeset.validate((draftData) => {
  userChangeset.removeErrors();
  if (draftData.age < 18) {
    userChangeset.addError({
      originalValue: draftData.age,
      value: 18,
      key: 'age',
    });
  }
});

// If valid, apply and save changes
if (userChangeset.isValid) {
  userChangeset.execute();  // Apply changes
  console.log('Updated User Data:', userChangeset.data);  // Updated data
  
  userChangeset.save();  // Save changes permanently
  console.log('User Data after Saving:', userChangeset.data);
}

API Overview

ImmerChangeset<T>

This class represents a changeset for a given data object. It offers the following core methods:

• set(key: string, value: any): Apply a change to a property.
• get(key: string): Get the current value of a property.
• execute(): Apply all changes to the original data.
• rollback(): Revert changes back to the original state.
• rollbackProperty(key: string): Revert a specific property.
• addError(error: ValidationError): Add an error for a specific field.
• removeError(key: string): Remove an error for a specific field.
• validate(validationFunction): Validate the changeset with a custom validation function.
• onSet(callback): Register a callback that triggers on any set operation.

Event Hooks

You can register event listeners to trigger when changes are made:

const off = userChangeset.onSet((key, value) => {
  console.log(`Property ${key} set to ${value}`);
});

// To remove the event listener
off();

Additional Utilities

isChangeset

This utility function checks whether a given object is an instance of ImmerChangeset. It is useful when you want to ensure that an object is a valid changeset before interacting with it.

import { isChangeset } from 'ember-immer-changeset';
import ImmerChangeset from 'ember-immer-changeset';

const userChangeset = new ImmerChangeset(userData);

// Check if the object is a changeset
console.log(isChangeset(userChangeset)); // true

Function signature:

function isChangeset(obj?: InstanceType<any>): boolean;

• obj: The object to check.
• Returns: A boolean indicating if the object is an instance of ImmerChangeset or has a __changeset__ property.

changeset-get Helper

The changeset-get helper is an Ember template helper that retrieves the value of a specific property from an ImmerChangeset instance. This is particularly helpful when you want to access changeset properties within templates.

{{changeset-get this.userChangeset "name"}}

Function signature:

function changesetGet([changeset, key]: [ImmerChangeset | undefined, string]): any;

• changeset: The ImmerChangeset instance.
• key: The property name to retrieve from the changeset.
• Returns: The value of the specified property.

Usage in a template:

{{changeset-get this.userChangeset "email"}}

This helper allows easy access to the values of properties on the changeset directly within Ember templates.

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for details.