@ptolemy2002/immutability-utils 1.0.0

package/README.md

@@ -0,0 +1,164 @@
+# Immutability Utils
+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.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install @ptolemy2002/immutability-utils
+```
+
+## Requirements
+
+Your class must implement a `clone()` method that returns a deep copy of the instance.
+
+## Usage
+
+### Basic Example
+
+```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)
+```
+
+### How It Works
+
+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).
+
+### Advanced Features
+
+#### 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;
+```
+
+## API Reference
+
+### Types
+
+#### `Cloneable<T>`
+
+A type representing an object that can be cloned. It's essentially `T` with a `clone()` method that returns `Cloneable<T>`.
+
+```typescript
+type Cloneable<T=object> = Override<T, { clone(): Cloneable<T> }>;
+```
+
+#### `ImmutableRef<T>`
+
+A reference object containing the current immutable instance and an enabled flag.
+
+```typescript
+type ImmutableRef<T=object> = {
+    current: Cloneable<T>,  // The current instance
+    enabled: boolean         // Whether immutability is enabled
+};
+```
+
+### Functions
+
+#### `immutable<T>(obj: Cloneable<T>): ImmutableRef<T>`
+
+Creates an immutable reference wrapper around the provided object.
+
+**Parameters:**
+- `obj`: An object that implements the `clone()` method
+
+**Returns:**
+- An `ImmutableRef<T>` object containing:
+  - `current`: The proxied instance (initially the object you passed in)
+  - `enabled`: A boolean flag (initially `true`) that controls whether immutability is active
+
+**Example:**
+```typescript
+const ref = immutable(new MyClass());
+ref.current.mutate(); // Creates a new instance
+console.log(ref.enabled); // true
+```
+
+## How Mutations Are Handled
+
+1. **Property Setters**: When you set a property (e.g., `obj.prop = value`), the library:
+   - Clones the object
+   - Temporarily disables immutability during the setter execution
+   - Sets the property on the clone
+   - Re-enables immutability
+   - Updates `current` to point to the new clone
+
+2. **Method Calls**: When you call a method (except `clone()`), the library:
+   - Clones the object
+   - Temporarily disables immutability during method execution
+   - Calls the method on the clone
+   - Re-enables immutability
+   - Updates `current` to point to the new clone
+   - 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.
+
+## Peer Dependencies
+
+## Commands
+The following commands exist in the project:
+
+- `npm run uninstall` - Uninstalls all dependencies for the library
+- `npm run reinstall` - Uninstalls and then Reinstalls all dependencies for the library
+- `npm run example-uninstall` - Uninstalls all dependencies for the example app
+- `npm run example-install` - Installs all dependencies for the example app
+- `npm run example-reinstall` - Uninstalls and then Reinstalls all dependencies for the example app
+- `npm run example-start` - Starts the example app after building the library
+- `npm run build` - Builds the library
+- `npm run release` - Publishes the library to npm without changing the version
+- `npm run release-patch` - Publishes the library to npm with a patch version bump
+- `npm run release-minor` - Publishes the library to npm with a minor version bump
+- `npm run release-major` - Publishes the library to npm with a major version bump

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { Override } from '@ptolemy2002/ts-utils';
+export type Cloneable<T = object> = Override<T, {
+    clone(): Cloneable<T>;
+}>;
+export type ImmutableRef<T = object> = {
+    current: Cloneable<T>;
+    enabled: boolean;
+};
+export declare function immutable<T>(obj: Cloneable<T>): ImmutableRef<T>;

package/dist/index.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.immutable = immutable;
+const is_callable_1 = __importDefault(require("is-callable"));
+function immutable(obj) {
+    const imRef = { current: obj, enabled: true };
+    // Wrap in a Proxy to override mutations
+    function applyProxy(target) {
+        return new Proxy(target, {
+            get(o, prop, receiver) {
+                const value = Reflect.get(o, prop, receiver);
+                if (!imRef.enabled)
+                    return value;
+                const isFunction = (0, is_callable_1.default)(value);
+                if (isFunction && prop !== 'clone') {
+                    // The function could mutate the object, so we need to clone it first
+                    return function (...args) {
+                        const cloned = o.clone();
+                        // Disable for the duration of this call.
+                        // All mutations in this call will be treated
+                        // as one mutation.
+                        imRef.enabled = false;
+                        const result = cloned[prop](...args);
+                        imRef.enabled = true;
+                        // Sync the reference to the new cloned object
+                        // and reapply the proxy
+                        imRef.current = applyProxy(cloned);
+                        return result;
+                    };
+                }
+                return value;
+            },
+            set(o, prop, value, receiver) {
+                if (!imRef.enabled)
+                    return Reflect.set(o, prop, value, receiver);
+                // On any mutation, clone the object first.
+                const cloned = o.clone();
+                // Disable for the duration of this call (it could be a setter that triggers more mutations).
+                // All mutations in this call will be treated
+                // as one mutation.
+                imRef.enabled = false;
+                const result = Reflect.set(cloned, prop, value, cloned);
+                imRef.enabled = true;
+                // Sync the reference to the new cloned object
+                // and reapply the proxy
+                imRef.current = applyProxy(cloned);
+                return result;
+            }
+        });
+    }
+    imRef.current = applyProxy(imRef.current);
+    return imRef;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@ptolemy2002/immutability-utils",
+    "version": "1.0.0",
+    "private": false,
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "/dist"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Ptolemy2002/immutability-utils",
+        "directory": "lib"
+    },
+    "scripts": {
+        "prepare": "npx ts-patch install -s",
+        "build": "bash ./scripts/build.sh",
+        "_build": "tsc --project ./tsconfig.json",
+        "typecheck": "tsc --noEmit",
+        "postinstall": "npx typesync",
+        "uninstall": "bash ./scripts/uninstall.sh",
+        "reinstall": "bash ./scripts/reinstall.sh",
+        "example-uninstall": "bash ./scripts/example-uninstall.sh",
+        "example-install": "bash ./scripts/example-install.sh",
+        "example-reinstall": "bash ./scripts/example-reinstall.sh",
+        "example-start": "bash ./scripts/example-start.sh",
+        "release": "bash ./scripts/release.sh",
+        "release-patch": "bash ./scripts/release.sh patch",
+        "release-minor": "bash ./scripts/release.sh minor",
+        "release-major": "bash ./scripts/release.sh major"
+    },
+    "devDependencies": {
+        "ts-patch": "^3.3.0",
+        "tsconfig-paths": "^4.2.0",
+        "typescript-transform-paths": "^3.5.3"
+    },
+    "dependencies": {
+        "@ptolemy2002/ts-utils": "^3.2.1",
+        "@types/is-callable": "^1.1.2",
+        "is-callable": "^1.2.7"
+    }
+}