@jwerre/vellum 1.1.1 → 1.2.0

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,11 @@ 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.
+     * Called automatically when items are added to the collection.
+     */
+    private sort;
     /**
      * Resets the collection with new data, replacing all existing items.
      *

package/dist/Collection.svelte.js

@@ -65,8 +65,55 @@ 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.
+     * Called automatically when items are added to the collection.
+     */
+    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 +128,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/package.json

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