A TypeScript library that wraps mutable classes and makes them immutable using proxies and cloning. This library allows you to work with classes designed with a mutable API while automatically maintaining immutability through copy-on-write semantics.
npm install @ptolemy2002/immutability-utils- Automatic Copy-on-Write: Any mutation (property assignment or method call) automatically creates a clone of the object
- Proxy-Based: Uses JavaScript Proxies to intercept and handle mutations transparently
- Zero Refactoring: Works with existing mutable classes without requiring changes to the class implementation
- Type-Safe: Full TypeScript support with proper type inference
- Efficient: Groups multiple mutations within a single method call into one clone operation
- Toggle Support: Can temporarily disable immutability when needed
- Clone Listeners: Register callbacks that execute whenever a clone operation occurs
``bash`
npm install @ptolemy2002/immutability-utils
Your class must implement a clone() method that returns a deep copy of the instance.
`typescript
import { immutable, ImmutableRef } from '@ptolemy2002/immutability-utils';
class Counter {
value: number;
constructor(value: number) {
this.value = value;
}
increment(amount: number): Counter {
this.value += amount;
return this;
}
clone(): Counter {
return new Counter(this.value);
}
}
// Create an immutable reference
const counterRef = immutable(new Counter(0));
// This creates a new instance with value = 5
counterRef.current.increment(5);
console.log(counterRef.current.value); // 5
// The old instance is preserved
const oldCounter = counterRef.current;
counterRef.current.increment(3);
console.log(oldCounter.value); // 5 (unchanged)
console.log(counterRef.current.value); // 8 (new instance)
`
1. Method Calls: When you call a method that might mutate the object, the library first clones the object, then calls the method on the clone, and finally updates the reference to point to the new clone.
2. Property Assignments: When you set a property, the library clones the object first, applies the change to the clone, and updates the reference.
3. Read Operations: Getters and property reads do not trigger cloning.
4. Chained Calls: Multiple mutations within a single method call are treated as one mutation (only one clone is created).
#### Temporarily Disable Immutability
`typescript
const dataRef = immutable(new MyClass());
// Disable immutability temporarily
dataRef.enabled = false;
dataRef.current.someProperty = "mutated in place"; // No clone created
dataRef.enabled = true;
`
#### Clone Listeners
You can register listeners that will be called whenever a clone operation occurs. This is useful for tracking changes, updating UI, or triggering side effects.
`typescript
const counterRef = immutable(new Counter(0));
// Add a listener that logs whenever a clone occurs
counterRef.cloneListeners.push((imRef) => {
console.log('Clone occurred! New value:', imRef.current.value);
});
// This will trigger the listener
counterRef.current.increment(5); // Logs: "Clone occurred! New value: 5"
counterRef.current.increment(3); // Logs: "Clone occurred! New value: 8"
`
Use Cases for Clone Listeners:
- Triggering React state updates when working with immutable data structures
- Logging or debugging mutation operations
- Synchronizing changes to external systems
- Implementing undo/redo functionality
#### Cloneable
A type representing an object that can be cloned. It's essentially T with a clone() method that returns Cloneable.
`typescript`
type Cloneable
#### ImmutableRef
A reference object containing the current immutable instance and an enabled flag.
`typescript`
type ImmutableRef
current: Cloneable
enabled: boolean, // Whether immutability is enabled
cloneListeners: Array<(imRef: ImmutableRef
};
#### immutable
Creates an immutable reference wrapper around the provided object.
Parameters:
- obj: An object that implements the clone() method
Returns:
- An ImmutableRef object containing:current
- : The proxied instance (initially the object you passed in)enabled
- : A boolean flag (initially true) that controls whether immutability is activecloneListeners
- : An empty array (initially []) where you can register listener callbacks
Example:
`typescript`
const ref = immutable(new MyClass());
ref.current.mutate(); // Creates a new instance
console.log(ref.enabled); // true
1. Property Setters: When you set a property (e.g., obj.prop = value), the library:current
- Clones the object
- Temporarily disables immutability during the setter execution
- Sets the property on the clone
- Re-enables immutability
- Updates to point to the new clone
- Invokes all registered clone listeners
2. Method Calls: When you call a method (except clone()), the library:current
- Clones the object
- Temporarily disables immutability during method execution
- Calls the method on the clone
- Re-enables immutability
- Updates to point to the new clone
- Invokes all registered clone listeners
- Returns the method's result
3. Read Operations: Property reads and getters do not trigger cloning and return the value directly.
4. The clone() Method: Calling clone() explicitly does not trigger the immutability mechanism and returns a clone directly.
- npm run uninstall - Uninstalls all dependencies for the librarynpm run reinstall
- - Uninstalls and then Reinstalls all dependencies for the librarynpm run example-uninstall
- - Uninstalls all dependencies for the example appnpm run example-install
- - Installs all dependencies for the example appnpm run example-reinstall
- - Uninstalls and then Reinstalls all dependencies for the example appnpm run example-start
- - Starts the example app after building the librarynpm run build
- - Builds the librarynpm run release
- - Publishes the library to npm without changing the versionnpm run release-patch
- - Publishes the library to npm with a patch version bumpnpm run release-minor
- - Publishes the library to npm with a minor version bumpnpm run release-major` - Publishes the library to npm with a major version bump
-