@jwerre/vellum 1.2.0 → 1.3.0-next.2

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

@@ -8,6 +8,10 @@ export interface ValidationOptions {
     silent?: boolean;
     [key: string]: unknown;
 }
+export interface CloneOptions {
+    keepId?: boolean;
+    deep?: boolean;
+}
 /**
  * Abstract base class for creating model instances that interact with RESTful APIs.
  *
@@ -106,6 +110,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.
      *
@@ -374,6 +416,41 @@ export declare abstract class Model<T extends object> {
      * }
      */
     validate(attributes: Partial<T>, options?: ValidationOptions): string | undefined;
+    /**
+     * Creates a new instance of the model with identical attributes.
+     *
+     * This method returns a new model instance that is a clone of the current model,
+     * with all attributes copied to the new instance. The clone is a separate object
+     * with its own state, so modifications to the clone will not affect the original
+     * model and vice versa. By default, the ID is removed so the cloned instance is
+     * considered "new" (isNew() returns true).
+     *
+     * @param {CloneOptions} [options] - Configuration options for cloning
+     * @param {boolean} [options.keepId=false] - If true, preserves the ID in the clone
+     * @param {boolean} [options.deep=false] - If true, performs a deep clone of nested objects/arrays
+     * @returns {this} A new instance of the same model class with cloned attributes
+     *
+     * @example
+     * // Clone a user model (default - no ID)
+     * const user = new User({ id: 1, name: 'John', email: 'john@example.com' });
+     * const userCopy = user.clone();
+     * console.log(userCopy.isNew()); // true
+     * console.log(userCopy.get('id')); // undefined
+     *
+     * @example
+     * // Clone with ID preserved
+     * const userCopy = user.clone({ keepId: true });
+     * console.log(userCopy.isNew()); // false
+     * console.log(userCopy.get('id')); // 1
+     *
+     * @example
+     * // Deep clone for nested objects
+     * const user = new User({ id: 1, name: 'John', settings: { theme: 'dark' } });
+     * const userCopy = user.clone({ deep: true });
+     * userCopy.get('settings').theme = 'light';
+     * console.log(user.get('settings').theme); // 'dark' (unchanged)
+     */
+    clone(options?: CloneOptions): this;
     /**
      * Performs HTTP synchronization with the server for CRUD operations.
      *

package/dist/Model.svelte.js

@@ -46,12 +46,38 @@ import { escapeHTML } from './utils.js';
  * await user.destroy(); // Deletes user
  */
 export class Model {
+    /**
+     * Internal reactive storage for all model attributes.
+     *
+     * This private field uses Svelte's $state rune to create a reactive object that
+     * holds all the model's attribute data. When attributes are modified, this reactivity
+     * ensures that any Svelte components using the model will automatically re-render
+     * to reflect the changes.
+     *
+     * The attributes are initialized as an empty object cast to type T, and are populated
+     * during construction by merging default values with provided data. All attribute
+     * access and modification should go through the public API methods (get, set, has, etc.)
+     * rather than directly accessing this field.
+     *
+     * @private
+     * @type {T}
+     */
     #attributes = $state({});
     /**
      * Validation error property that gets set when validation fails.
      * 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 +118,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 +231,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;
     }
@@ -357,6 +438,53 @@ export class Model {
         // Default implementation - no validation
         return undefined;
     }
+    /**
+     * Creates a new instance of the model with identical attributes.
+     *
+     * This method returns a new model instance that is a clone of the current model,
+     * with all attributes copied to the new instance. The clone is a separate object
+     * with its own state, so modifications to the clone will not affect the original
+     * model and vice versa. By default, the ID is removed so the cloned instance is
+     * considered "new" (isNew() returns true).
+     *
+     * @param {CloneOptions} [options] - Configuration options for cloning
+     * @param {boolean} [options.keepId=false] - If true, preserves the ID in the clone
+     * @param {boolean} [options.deep=false] - If true, performs a deep clone of nested objects/arrays
+     * @returns {this} A new instance of the same model class with cloned attributes
+     *
+     * @example
+     * // Clone a user model (default - no ID)
+     * const user = new User({ id: 1, name: 'John', email: 'john@example.com' });
+     * const userCopy = user.clone();
+     * console.log(userCopy.isNew()); // true
+     * console.log(userCopy.get('id')); // undefined
+     *
+     * @example
+     * // Clone with ID preserved
+     * const userCopy = user.clone({ keepId: true });
+     * console.log(userCopy.isNew()); // false
+     * console.log(userCopy.get('id')); // 1
+     *
+     * @example
+     * // Deep clone for nested objects
+     * const user = new User({ id: 1, name: 'John', settings: { theme: 'dark' } });
+     * const userCopy = user.clone({ deep: true });
+     * userCopy.get('settings').theme = 'light';
+     * console.log(user.get('settings').theme); // 'dark' (unchanged)
+     */
+    clone(options) {
+        const Constructor = this.constructor;
+        let attrs = this.toJSON();
+        // Remove ID unless keepId is true
+        if (!options?.keepId) {
+            delete attrs[this.idAttribute];
+        }
+        // Perform deep clone if requested
+        if (options?.deep) {
+            attrs = structuredClone(attrs);
+        }
+        return new Constructor(attrs);
+    }
     /**
      * Performs HTTP synchronization with the server for CRUD operations.
      *

package/package.json

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