@jwerre/vellum 1.2.0 → 1.3.0-next.1

package/dist/Collection.svelte.d.ts

@@ -108,9 +108,24 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
     add(data: T | M): M;
     /**
      * Sorts the collection using the comparator if one is defined.
-     * Called automatically when items are added to the collection.
+     *
+     * This method is called automatically when items are added to the collection via `add()` or `reset()`.
+     * You can also call it manually to re-sort the collection after modifying model attributes.
+     *
+     * The sorting behavior depends on the type of comparator defined:
+     *
+     * - **String attribute**: Sorts by the specified model attribute in ascending order
+     * - **sortBy function** (1 argument): Sorts by the return value of the function in ascending order
+     * - **sort function** (2 arguments): Uses a custom comparator that returns -1, 0, or 1
+     *
+     * If no comparator is defined or the comparator returns undefined, no sorting is performed.
+     *
+     * @example
+     * // Manual sorting after updating a model
+     * user.set('priority', 5);
+     * collection.sort();
      */
-    private sort;
+    sort(): void;
     /**
      * Resets the collection with new data, replacing all existing items.
      *

package/dist/Collection.svelte.js

@@ -70,7 +70,22 @@ export class Collection {
     }
     /**
      * Sorts the collection using the comparator if one is defined.
-     * Called automatically when items are added to the collection.
+     *
+     * This method is called automatically when items are added to the collection via `add()` or `reset()`.
+     * You can also call it manually to re-sort the collection after modifying model attributes.
+     *
+     * The sorting behavior depends on the type of comparator defined:
+     *
+     * - **String attribute**: Sorts by the specified model attribute in ascending order
+     * - **sortBy function** (1 argument): Sorts by the return value of the function in ascending order
+     * - **sort function** (2 arguments): Uses a custom comparator that returns -1, 0, or 1
+     *
+     * If no comparator is defined or the comparator returns undefined, no sorting is performed.
+     *
+     * @example
+     * // Manual sorting after updating a model
+     * user.set('priority', 5);
+     * collection.sort();
      */
     sort() {
         if (!this.comparator) {

package/dist/Model.svelte.d.ts

@@ -106,6 +106,44 @@ export declare abstract class Model<T extends object> {
      * @returns {ValidationError || undefined} An instance of ValidationError if validation failed, otherwise undefined
      */
     get validationError(): ValidationError | undefined;
+    /**
+     * Gets the hash of attributes that have changed since the last set call.
+     * This is a readonly accessor - the changed object cannot be modified directly.
+     *
+     * @returns {Partial<T>} An object containing all attributes that have changed
+     */
+    get changed(): Partial<T>;
+    /**
+     * Gets the hash of previous attribute values before they were changed.
+     * This is a readonly accessor - the previous object cannot be modified directly.
+     *
+     * @returns {Partial<T>} An object containing the previous values of changed attributes
+     */
+    get previous(): Partial<T>;
+    /**
+     * Determines if attributes have changed since the last set call.
+     *
+     * This method checks whether any attributes were modified in the most recent
+     * set operation. When called without arguments, it returns true if any attributes
+     * have changed. When called with a specific attribute key, it returns true only
+     * if that particular attribute was changed.
+     *
+     * @param {keyof T} [attr] - Optional attribute key to check for changes
+     * @returns {boolean} True if attributes have changed, false otherwise
+     *
+     * @example
+     * // Check if any attributes changed
+     * const user = new User({ name: 'John', email: 'john@example.com' });
+     * user.set('name', 'Jane');
+     * user.hasChanged(); // Returns true
+     *
+     * @example
+     * // Check if a specific attribute changed
+     * user.set('name', 'Jane');
+     * user.hasChanged('name'); // Returns true
+     * user.hasChanged('email'); // Returns false
+     */
+    hasChanged(attr?: keyof T): boolean;
     /**
      * Provides default attribute values for new model instances.
      *

package/dist/Model.svelte.js

@@ -52,6 +52,16 @@ export class Model {
      * This property contains the error returned by the validate method.
      */
     #validationError = $state();
+    /**
+     * Internal hash containing all attributes that have changed since the last set call.
+     * This property tracks which attributes have been modified and their new values.
+     */
+    #changed = {};
+    /**
+     * Internal hash containing the previous values of attributes before they were changed.
+     * This property stores the original values of attributes from before the last set call.
+     */
+    #previous = {};
     /**
      * The name of the attribute that serves as the unique identifier for this model instance.
      *
@@ -92,6 +102,53 @@ export class Model {
     get validationError() {
         return this.#validationError;
     }
+    /**
+     * Gets the hash of attributes that have changed since the last set call.
+     * This is a readonly accessor - the changed object cannot be modified directly.
+     *
+     * @returns {Partial<T>} An object containing all attributes that have changed
+     */
+    get changed() {
+        return this.#changed;
+    }
+    /**
+     * Gets the hash of previous attribute values before they were changed.
+     * This is a readonly accessor - the previous object cannot be modified directly.
+     *
+     * @returns {Partial<T>} An object containing the previous values of changed attributes
+     */
+    get previous() {
+        return this.#previous;
+    }
+    /**
+     * Determines if attributes have changed since the last set call.
+     *
+     * This method checks whether any attributes were modified in the most recent
+     * set operation. When called without arguments, it returns true if any attributes
+     * have changed. When called with a specific attribute key, it returns true only
+     * if that particular attribute was changed.
+     *
+     * @param {keyof T} [attr] - Optional attribute key to check for changes
+     * @returns {boolean} True if attributes have changed, false otherwise
+     *
+     * @example
+     * // Check if any attributes changed
+     * const user = new User({ name: 'John', email: 'john@example.com' });
+     * user.set('name', 'Jane');
+     * user.hasChanged(); // Returns true
+     *
+     * @example
+     * // Check if a specific attribute changed
+     * user.set('name', 'Jane');
+     * user.hasChanged('name'); // Returns true
+     * user.hasChanged('email'); // Returns false
+     */
+    hasChanged(attr) {
+        if (attr !== undefined) {
+            return attr in this.#changed;
+        }
+        return Object.keys(this.#changed).length > 0;
+    }
     /**
      * Provides default attribute values for new model instances.
      *
@@ -158,6 +215,14 @@ export class Model {
         if (opts?.validate && !this.#doValidation({ ...this.#attributes, ...attrs }, opts)) {
             return false;
         }
+        // Store previous values and record new changes
+        this.#previous = {};
+        for (const key in attrs) {
+            if (key in this.#attributes) {
+                this.#previous[key] = this.#attributes[key];
+            }
+        }
+        this.#changed = attrs;
         Object.assign(this.#attributes, attrs);
         return true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jwerre/vellum",
-	"version": "1.2.0",
+	"version": "1.3.0-next.1",
 	"description": "Structural state management library for Svelte 5",
 	"repository": {
 		"type": "git",