@jwerre/vellum 1.1.0 → 1.2.0

package/README.md

@@ -178,12 +178,10 @@ Vellum works seamlessly with Svelte 5 components.
 
 There is a working example of Vellum in the `routes` directory. To run it, clone the repository, install dependencies, and run the development server:
 
-```
-git clone https://github.com/jwerre/vellum.git
-cd vellum
-npm install
-npm run dev
-```
+    git clone https://github.com/jwerre/vellum.git
+    cd vellum
+    npm install
+    npm run dev
 
 ## API Documentation
 
@@ -198,58 +196,63 @@ npm run dev
 - [Model](#model)
   - [Parameters](#parameters-1)
   - [Examples](#examples-1)
-  - [validationError](#validationerror)
   - [idAttribute](#idattribute)
+    - [Examples](#examples-2)
+  - [validationError](#validationerror)
+  - [defaults](#defaults)
+    - [Examples](#examples-3)
   - [get](#get)
     - [Parameters](#parameters-2)
-    - [Examples](#examples-2)
+    - [Examples](#examples-4)
   - [has](#has)
     - [Parameters](#parameters-3)
-    - [Examples](#examples-3)
+    - [Examples](#examples-5)
   - [unset](#unset)
     - [Parameters](#parameters-4)
-    - [Examples](#examples-4)
+    - [Examples](#examples-6)
   - [clear](#clear)
-    - [Examples](#examples-5)
+    - [Examples](#examples-7)
   - [escape](#escape)
     - [Parameters](#parameters-5)
-    - [Examples](#examples-6)
+    - [Examples](#examples-8)
   - [isNew](#isnew)
   - [isValid](#isvalid)
     - [Parameters](#parameters-6)
-    - [Examples](#examples-7)
+    - [Examples](#examples-9)
   - [validate](#validate)
     - [Parameters](#parameters-7)
-    - [Examples](#examples-8)
+    - [Examples](#examples-10)
   - [sync](#sync)
     - [Parameters](#parameters-8)
-    - [Examples](#examples-9)
+    - [Examples](#examples-11)
   - [fetch](#fetch)
-    - [Examples](#examples-10)
+    - [Examples](#examples-12)
   - [save](#save)
     - [Parameters](#parameters-9)
-    - [Examples](#examples-11)
+    - [Examples](#examples-13)
   - [destroy](#destroy)
-    - [Examples](#examples-12)
+    - [Examples](#examples-14)
   - [toJSON](#tojson)
-    - [Examples](#examples-13)
+    - [Examples](#examples-15)
+- [validationError](#validationerror-1)
 - [Collection](#collection)
   - [Parameters](#parameters-10)
-  - [Examples](#examples-14)
+  - [Examples](#examples-16)
   - [items](#items)
   - [length](#length)
   - [add](#add)
     - [Parameters](#parameters-11)
-    - [Examples](#examples-15)
+    - [Examples](#examples-17)
+  - [sort](#sort)
   - [reset](#reset)
     - [Parameters](#parameters-12)
-    - [Examples](#examples-16)
+    - [Examples](#examples-18)
   - [find](#find)
     - [Parameters](#parameters-13)
-    - [Examples](#examples-17)
+    - [Examples](#examples-19)
   - [fetch](#fetch-1)
     - [Parameters](#parameters-14)
-    - [Examples](#examples-18)
+    - [Examples](#examples-20)
 
 ### vellumConfig
 
@@ -269,6 +272,7 @@ with existing headers rather than replaced entirely.
 - `config` **Partial\<VellumConfig>** Partial configuration object with properties to update
   - `config.origin` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** New origin URL to set
   - `config.headers` **Record<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>?** Headers to merge with existing headers
+  - `config.idAttribute` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The default unique identifier attribute for models (optional, default `"id"`)
 
 #### Examples
 
@@ -312,7 +316,6 @@ Key features:
 #### Parameters
 
 - `data` (optional, default `{}`)
-- `options` (optional, default `{}`)
 
 #### Examples
 
@@ -326,9 +329,12 @@ interface UserAttributes {
 }
 
 class User extends Model<UserAttributes> {
-  endpoint(): string {
+  endpoint() {
     return '/users';
   }
+  defaults() {
+    return { name: '', createdAt: new Date() };
+  }
 }
 
 // Create and use a model instance
@@ -336,40 +342,73 @@ const user = new User({ name: 'John Doe', email: 'john@example.com' });
 await user.save(); // Creates new user on server
 user.set('name', 'Jane Doe');
 await user.save(); // Updates existing user
+await user.destroy(); // Deletes user
 ```
 
-```javascript
-// Using custom ID attribute (e.g., MongoDB _id)
-interface MongoUserAttributes {
-  _id?: string;
-  username: string;
-  profile: {
-    firstName: string;
-    lastName: string;
-  };
-}
+#### idAttribute
 
-class MongoUser extends Model<MongoUserAttributes> {
-  constructor(data?: Partial<MongoUserAttributes>) {
-    super(data, { idAttribute: '_id' });
-  }
+The name of the attribute that serves as the unique identifier for this model instance.
 
-  endpoint(): string {
-    return '/api/users';
-  }
+This private field stores the attribute name that will be used to identify the model's
+primary key when performing operations like determining if the model is new, constructing
+URLs for API requests, and managing model identity. The default value is 'id', but it
+can be customized through the ModelOptions parameter in the constructor.
+
+Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
+
+##### Examples
+
+```javascript
+// Default behavior uses 'id' as the identifier
+const user = new User({ id: 1, name: 'John' });
+
+// Custom ID attribute can be specified in constructor options
+class User extends Model<UserSchema> {
+	idAttribute = '_id
+	endpoint(): string {
+		return '/users';
+	}
 }
+const user = new User({ _id: '507f1f77bcf86cd799439011', name: 'John' });
 ```
 
 #### validationError
 
-Validation error property that gets set when validation fails.
-This property contains the error returned by the validate method.
+Gets the latest validation error.
 
-#### idAttribute
+#### defaults
+
+Provides default attribute values for new model instances.
 
-Gets the current ID attribute name used by this model instance.
+This method is called during model construction to establish initial attribute
+values before applying any user-provided data. Subclasses can override this
+method to define default values for their specific attributes, ensuring that
+models always have sensible initial state.
 
-Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of the attribute used as the ID field
+The defaults are applied first, then any data passed to the constructor will
+override these default values. This allows for flexible model initialization
+where some attributes have fallback values while others can be explicitly set.
+
+##### Examples
+
+```javascript
+// Override in a User model subclass
+protected defaults(): Partial<UserAttributes> {
+  return {
+    role: 'user',
+    isActive: true,
+    createdAt: new Date()
+  };
+}
+```
+
+```javascript
+// Creating a model with defaults
+const user = new User({ name: 'John' });
+// Resulting attributes: { role: 'user', isActive: true, createdAt: Date, name: 'John' }
+```
+
+Returns **Partial\<T>** A partial object containing default attribute values
 
 #### get
 
@@ -766,6 +805,11 @@ const jsonString = JSON.stringify(user.toJSON());
 
 Returns **T** A plain object containing all of the model's attributes
 
+### validationError
+
+Validation error property that gets set when validation fails.
+This property contains the error returned by the validate method.
+
 ### Collection
 
 Abstract base class for managing collections of Model instances.
@@ -820,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/dist/Model.svelte.js

@@ -76,7 +76,7 @@ export class Model {
      *	}
      * const user = new User({ _id: '507f1f77bcf86cd799439011', name: 'John' });
      */
-    idAttribute = 'id';
+    idAttribute = vellumConfig.idAttribute;
     /**
      * Creates a new instance of Model.
      */

package/dist/config.svelte.d.ts

@@ -1,6 +1,7 @@
 export interface VellumConfig {
     origin: string;
     headers: Record<string, string>;
+    idAttribute: string;
 }
 /**
  * Global reactive state for Vellum configuration. Uses Svelte's $state rune to
@@ -8,6 +9,7 @@ export interface VellumConfig {
  *
  * @default origin - Empty string (must be configured before use)
  * @default headers - Contains 'Content-Type': 'application/json'
+ * @default idAttribute - The default unique identifier attribute for models
  */
 export declare const vellumConfig: VellumConfig;
 /**
@@ -20,6 +22,7 @@ export declare const vellumConfig: VellumConfig;
  * @param {Partial<VellumConfig>} config - Partial configuration object with properties to update
  * @param {string} [config.origin] - New origin URL to set
  * @param {Record<string, string>} [config.headers] - Headers to merge with existing headers
+ * @param {string} [config.idAttribute="id"] - The default unique identifier attribute for models
  *
  * @example
  * // Set the API origin

package/dist/config.svelte.js

@@ -4,12 +4,14 @@
  *
  * @default origin - Empty string (must be configured before use)
  * @default headers - Contains 'Content-Type': 'application/json'
+ * @default idAttribute - The default unique identifier attribute for models
  */
 export const vellumConfig = $state({
     origin: '',
     headers: {
         'Content-Type': 'application/json'
-    }
+    },
+    idAttribute: 'id'
 });
 /**
  * Helper function to update global Vellum configuration
@@ -21,6 +23,7 @@ export const vellumConfig = $state({
  * @param {Partial<VellumConfig>} config - Partial configuration object with properties to update
  * @param {string} [config.origin] - New origin URL to set
  * @param {Record<string, string>} [config.headers] - Headers to merge with existing headers
+ * @param {string} [config.idAttribute="id"] - The default unique identifier attribute for models
  *
  * @example
  * // Set the API origin
@@ -41,8 +44,12 @@ export const vellumConfig = $state({
  * });
  */
 export const configureVellum = (config) => {
-    if (config.origin)
+    if (config.origin?.length) {
         vellumConfig.origin = config.origin;
+    }
+    if (config.idAttribute?.length) {
+        vellumConfig.idAttribute = config.idAttribute;
+    }
     if (config.headers) {
         vellumConfig.headers = { ...vellumConfig.headers, ...config.headers };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jwerre/vellum",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Structural state management library for Svelte 5",
 	"repository": {
 		"type": "git",
@@ -32,7 +32,7 @@
 		"types:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"check": "npm audit --audit-level=moderate --omit=dev && npm run format && npm run lint && npm run spell && npm run types && npm test && npm run build && npm run release:dry",
 		"dev": "vite dev",
-		"docs": "npm run build && documentation readme dist/index.js --section=\"API Documentation\"",
+		"docs": "npm run build && documentation readme dist/index.js --section=\"API Documentation\" && prettier --write README.md",
 		"format": "prettier --check .",
 		"format:write": "prettier --write .",
 		"lint": "prettier --check . && eslint .",