@jwerre/vellum 1.1.1 → 1.3.0-next.1

package/README.md

@@ -243,6 +243,7 @@ There is a working example of Vellum in the `routes` directory. To run it, clone
   - [add](#add)
     - [Parameters](#parameters-11)
     - [Examples](#examples-17)
+  - [sort](#sort)
   - [reset](#reset)
     - [Parameters](#parameters-12)
     - [Examples](#examples-18)
@@ -863,6 +864,11 @@ collection.add(existingUser);
 
 Returns **any** The model instance that was added to the collection
 
+#### sort
+
+Sorts the collection using the comparator if one is defined.
+Called automatically when items are added to the collection.
+
 #### reset
 
 Resets the collection with new data, replacing all existing items.

package/dist/Collection.svelte.d.ts

@@ -33,6 +33,46 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
     };
     /** Returns the API endpoint URL for this collection */
     abstract endpoint(): string;
+    /**
+     * Optional comparator for sorting the collection.
+     *
+     * By default, there is no comparator for a collection. If you define a comparator,
+     * it will be used to sort the collection any time a model is added.
+     *
+     * A comparator can be defined in three ways:
+     *
+     * 1. **sortBy** - Pass a function that takes a single model argument and returns
+     *    a numeric or string value by which the model should be ordered relative to others.
+     *
+     * 2. **sort** - Pass a comparator function that takes two model arguments and returns
+     *    -1 if the first model should come before the second, 0 if they are of the same
+     *    rank, and 1 if the first model should come after.
+     *
+     * 3. **attribute name** - Pass a string indicating the attribute to sort by.
+     *
+     * Note: The implementation depends on the arity of your comparator function to
+     * determine between sortBy (1 argument) and sort (2 arguments) styles, so be
+     * careful if your comparator function is bound.
+     *
+     * @returns A comparator function, string attribute name, or undefined for no sorting
+     *
+     * @example
+     * // Sort by attribute name
+     * comparator = () => 'createdAt';
+     *
+     * @example
+     * // Sort using sortBy (single argument)
+     * comparator = () => (model: UserModel) => model.get('age');
+     *
+     * @example
+     * // Sort using sort comparator (two arguments)
+     * comparator = () => (a: UserModel, b: UserModel) => {
+     *   if (a.get('priority') < b.get('priority')) return -1;
+     *   if (a.get('priority') > b.get('priority')) return 1;
+     *   return 0;
+     * };
+     */
+    comparator?(): string | ((model: M) => string | number) | ((a: M, b: M) => number) | undefined;
     /**
      * Creates a new Collection instance.
      *
@@ -66,6 +106,26 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
      * collection.add(existingUser);
      */
     add(data: T | M): M;
+    /**
+     * Sorts the collection using the comparator if one is defined.
+     *
+     * 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(): void;
     /**
      * Resets the collection with new data, replacing all existing items.
      *

package/dist/Collection.svelte.js

@@ -65,8 +65,70 @@ export class Collection {
     add(data) {
         const instance = data instanceof Model ? data : new this.model(data);
         this.items.push(instance);
+        this.sort();
         return instance;
     }
+    /**
+     * Sorts the collection using the comparator if one is defined.
+     *
+     * 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) {
+            return;
+        }
+        const comparator = this.comparator();
+        if (!comparator) {
+            return;
+        }
+        // String attribute name
+        if (typeof comparator === 'string') {
+            const attr = comparator;
+            this.items.sort((a, b) => {
+                const aVal = a.get(attr);
+                const bVal = b.get(attr);
+                if (aVal < bVal)
+                    return -1;
+                if (aVal > bVal)
+                    return 1;
+                return 0;
+            });
+            return;
+        }
+        // Function comparator - check arity
+        if (comparator.length === 1) {
+            // sortBy function (single argument)
+            const sortByFn = comparator;
+            this.items.sort((a, b) => {
+                const aVal = sortByFn(a);
+                const bVal = sortByFn(b);
+                if (aVal < bVal)
+                    return -1;
+                if (aVal > bVal)
+                    return 1;
+                return 0;
+            });
+        }
+        else {
+            // sort function (two arguments)
+            const sortFn = comparator;
+            this.items.sort(sortFn);
+        }
+    }
     /**
      * Resets the collection with new data, replacing all existing items.
      *
@@ -81,6 +143,7 @@ export class Collection {
      */
     reset(data) {
         this.items = data.map((attrs) => new this.model(attrs));
+        this.sort();
     }
     /**
      * Finds the first item in the collection that matches the given query.

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.1.1",
+	"version": "1.3.0-next.1",
 	"description": "Structural state management library for Svelte 5",
 	"repository": {
 		"type": "git",