@jwerre/vellum 0.0.1 → 1.1.0

package/dist/Collection.svelte.d.ts

@@ -1,4 +1,9 @@
 import { Model } from './Model.svelte';
+import { type VellumConfig } from './config.svelte';
+export interface FetchOptions extends Partial<VellumConfig> {
+    endpoint?: string;
+    search?: Record<string, string | number | boolean>;
+}
 /**
  * Abstract base class for managing collections of Model instances.
  *
@@ -10,7 +15,6 @@ import { Model } from './Model.svelte';
  * @template T - The data object type that the models represent
  *
  * @example
- * ```typescript
  * class UserCollection extends Collection<UserModel, User> {
  *   model = UserModel;
  *   endpoint = () => '/api/users';
@@ -19,7 +23,6 @@ import { Model } from './Model.svelte';
  * const users = new UserCollection();
  * await users.fetch(); // Loads users from API
  * users.add({ name: 'John', email: 'john@example.com' }); // Adds new user
- * ```
  */
 export declare abstract class Collection<M extends Model<T>, T extends object> {
     /** Reactive array of model instances in the collection */
@@ -36,7 +39,6 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
      * @param models - Optional array of data objects to initialize the collection with
      *
      * @example
-     * ```typescript
      * // Create empty collection
      * const collection = new UserCollection();
      *
@@ -45,7 +47,6 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
      *   { id: 1, name: 'John' },
      *   { id: 2, name: 'Jane' }
      * ]);
-     * ```
      */
     constructor(models?: T[]);
     /** Gets the number of items in the collection */
@@ -57,14 +58,12 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
      * @returns The model instance that was added to the collection
      *
      * @example
-     * ```typescript
      * // Add raw data
      * const user = collection.add({ name: 'John', email: 'john@example.com' });
      *
      * // Add existing model instance
      * const existingUser = new UserModel({ name: 'Jane' });
      * collection.add(existingUser);
-     * ```
      */
     add(data: T | M): M;
     /**
@@ -73,13 +72,11 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
      * @param data - An array of raw data objects to populate the collection with
      *
      * @example
-     * ```typescript
      * // Reset collection with new user data
      * collection.reset([
      *   { id: 1, name: 'John', email: 'john@example.com' },
      *   { id: 2, name: 'Jane', email: 'jane@example.com' }
      * ]);
-     * ```
      */
     reset(data: T[]): void;
     /**
@@ -90,26 +87,24 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
      * @returns The first matching item, or undefined if no match is found.
      *
      * @example
-     * ```typescript
      * // Find a user by ID
      * const user = collection.find({ id: 123 });
      *
      * // Find by multiple properties
      * const activeAdmin = collection.find({ role: 'admin', status: 'active' });
-     * ```
      */
     find(query: Partial<T>): M | undefined;
     /**
      * Fetches data from the server and populates the collection.
      *
      * @param options - Configuration options for the fetch request
-     * @param options.search - Optional search parameters to include in the query string.
+     * @param [options.endpoint] - Optional endpoint to use if different than this.endpoint()
+     * @param [options.search] - Optional search parameters to include in the query string.
      *                        Keys and values will be converted to strings and URL-encoded.
      *
      * @throws {Error} Throws an error if the HTTP request fails or returns a non-ok status
      *
      * @example
-     * ```typescript
      * // Fetch all items
      * await collection.fetch();
      *
@@ -117,9 +112,6 @@ export declare abstract class Collection<M extends Model<T>, T extends object> {
      * await collection.fetch({
      *   search: { limit: 30, after: 29 }
      * });
-     * ```
      */
-    fetch(options?: {
-        search?: Record<string, string | number | boolean>;
-    }): Promise<void>;
+    fetch(options?: FetchOptions): Promise<void>;
 }

package/dist/Collection.svelte.js

@@ -12,7 +12,6 @@ import { vellumConfig } from './config.svelte';
  * @template T - The data object type that the models represent
  *
  * @example
- * ```typescript
  * class UserCollection extends Collection<UserModel, User> {
  *   model = UserModel;
  *   endpoint = () => '/api/users';
@@ -21,7 +20,6 @@ import { vellumConfig } from './config.svelte';
  * const users = new UserCollection();
  * await users.fetch(); // Loads users from API
  * users.add({ name: 'John', email: 'john@example.com' }); // Adds new user
- * ```
  */
 export class Collection {
     /** Reactive array of model instances in the collection */
@@ -32,7 +30,6 @@ export class Collection {
      * @param models - Optional array of data objects to initialize the collection with
      *
      * @example
-     * ```typescript
      * // Create empty collection
      * const collection = new UserCollection();
      *
@@ -41,7 +38,6 @@ export class Collection {
      *   { id: 1, name: 'John' },
      *   { id: 2, name: 'Jane' }
      * ]);
-     * ```
      */
     constructor(models = []) {
         if (models.length > 0) {
@@ -59,14 +55,12 @@ export class Collection {
      * @returns The model instance that was added to the collection
      *
      * @example
-     * ```typescript
      * // Add raw data
      * const user = collection.add({ name: 'John', email: 'john@example.com' });
      *
      * // Add existing model instance
      * const existingUser = new UserModel({ name: 'Jane' });
      * collection.add(existingUser);
-     * ```
      */
     add(data) {
         const instance = data instanceof Model ? data : new this.model(data);
@@ -79,13 +73,11 @@ export class Collection {
      * @param data - An array of raw data objects to populate the collection with
      *
      * @example
-     * ```typescript
      * // Reset collection with new user data
      * collection.reset([
      *   { id: 1, name: 'John', email: 'john@example.com' },
      *   { id: 2, name: 'Jane', email: 'jane@example.com' }
      * ]);
-     * ```
      */
     reset(data) {
         this.items = data.map((attrs) => new this.model(attrs));
@@ -98,13 +90,11 @@ export class Collection {
      * @returns The first matching item, or undefined if no match is found.
      *
      * @example
-     * ```typescript
      * // Find a user by ID
      * const user = collection.find({ id: 123 });
      *
      * // Find by multiple properties
      * const activeAdmin = collection.find({ role: 'admin', status: 'active' });
-     * ```
      */
     find(query) {
         return this.items.find((item) => {
@@ -117,13 +107,13 @@ export class Collection {
      * Fetches data from the server and populates the collection.
      *
      * @param options - Configuration options for the fetch request
-     * @param options.search - Optional search parameters to include in the query string.
+     * @param [options.endpoint] - Optional endpoint to use if different than this.endpoint()
+     * @param [options.search] - Optional search parameters to include in the query string.
      *                        Keys and values will be converted to strings and URL-encoded.
      *
      * @throws {Error} Throws an error if the HTTP request fails or returns a non-ok status
      *
      * @example
-     * ```typescript
      * // Fetch all items
      * await collection.fetch();
      *
@@ -131,7 +121,6 @@ export class Collection {
      * await collection.fetch({
      *   search: { limit: 30, after: 29 }
      * });
-     * ```
      */
     async fetch(options = {}) {
         let query = '';
@@ -142,7 +131,8 @@ export class Collection {
             }
             query = `?${params.toString()}`;
         }
-        const fullUrl = `${vellumConfig.origin}${this.endpoint()}${query}`;
+        const endpoint = options?.endpoint?.length ? options.endpoint : this.endpoint();
+        const fullUrl = `${vellumConfig.origin}${endpoint}${query}`;
         const response = await fetch(fullUrl, {
             headers: { ...vellumConfig.headers }
         });

package/dist/Model.svelte.d.ts

@@ -1,4 +1,57 @@
 import { type VellumConfig } from './config.svelte';
+import { ValidationError } from './errors/validation_error.js';
+export interface SyncOptions extends Partial<VellumConfig> {
+    endpoint?: string;
+}
+export interface ValidationOptions {
+    validate?: boolean;
+    silent?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Abstract base class for creating model instances that interact with RESTful APIs.
+ *
+ * The Model class provides a structured way to manage data objects with full CRUD
+ * (Create, Read, Update, Delete) capabilities. It includes built-in HTTP synchronization,
+ * attribute management, and data validation features. This class is designed to work
+ * with Svelte's reactivity system using the `$state` rune for automatic UI updates.
+ *
+ * Key features:
+ * - Type-safe attribute access and manipulation
+ * - Automatic HTTP synchronization with RESTful APIs
+ * - Built-in HTML escaping for XSS prevention
+ * - Configurable ID attributes for different database schemas
+ * - Reactive attributes that integrate with Svelte's state management
+ * - Support for both single attribute and bulk attribute operations
+ *
+ * @template T - The type definition for the model's attributes, must extend object
+ * @abstract This class must be extended by concrete model implementations
+ *
+ * @example
+ * // Define a User model
+ * interface UserAttributes {
+ *   id?: number;
+ *   name: string;
+ *   email: string;
+ *   createdAt?: Date;
+ * }
+ *
+ * class User extends Model<UserAttributes> {
+ *   endpoint() {
+ *     return '/users';
+ *   }
+ *   defaults() {
+ *     return { name: '', createdAt: new Date() };
+ *   }
+ * }
+ *
+ * // Create and use a model instance
+ * 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
+ */
 export declare abstract class Model<T extends object> {
     #private;
     /**
@@ -17,8 +70,73 @@ export declare abstract class Model<T extends object> {
      *   return '/users';
      * }
      */
-    abstract endpoint(): string;
+    protected abstract endpoint(): string;
+    /**
+     * The name of the attribute that serves as the unique identifier for this model instance.
+     *
+     * 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.
+     *
+     * @protected
+     * @type {string}
+     * @default 'id'
+     * @example
+     * // 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' });
+     */
+    protected idAttribute: string;
+    /**
+     * Creates a new instance of Model.
+     */
     constructor(data?: Partial<T>);
+    /**
+     * Gets the latest validation error.
+     *
+     * @returns {ValidationError || undefined} An instance of ValidationError if validation failed, otherwise undefined
+     */
+    get validationError(): ValidationError | undefined;
+    /**
+     * Provides default attribute values for new model instances.
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * @protected
+     * @returns {Partial<T>} A partial object containing default attribute values
+     *
+     * @example
+     * // Override in a User model subclass
+     * protected defaults(): Partial<UserAttributes> {
+     *   return {
+     *     role: 'user',
+     *     isActive: true,
+     *     createdAt: new Date()
+     *   };
+     * }
+     *
+     * @example
+     * // Creating a model with defaults
+     * const user = new User({ name: 'John' });
+     * // Resulting attributes: { role: 'user', isActive: true, createdAt: Date, name: 'John' }
+     */
+    protected defaults(): Partial<T>;
     /**
      * Retrieves the value of a specific attribute from the model.
      *
@@ -44,21 +162,148 @@ export declare abstract class Model<T extends object> {
      * shallow merge, meaning that only the top-level properties specified in the attrs
      * parameter will be updated, while other existing attributes remain unchanged.
      *
+     * The method supports optional validation through the ValidationOptions parameter.
+     * If validation is enabled and fails, the attributes will not be updated and the
+     * method will return false. The validationError property will be set with details
+     * about the validation failure.
+     *
+     * @overload
+     * @param {K} key - The attribute key to set
+     * @param {T[K]} value - The value to set for the specified key
+     * @param {ValidationOptions} [options] - Optional validation and behavior settings
+     * @param {boolean} [options.validate] - If true, validates attributes before setting them
+     * @param {boolean} [options.silent] - If true, suppresses validation error setting
+     * @returns {boolean} True if attributes were set successfully, false if validation failed
+     *
+     * @overload
      * @param {Partial<T>} attrs - A partial object containing the attributes to update
+     * @param {ValidationOptions} [options] - Optional validation and behavior settings
+     * @param {boolean} [options.validate] - If true, validates attributes before setting them
+     * @param {boolean} [options.silent] - If true, suppresses validation error setting
+     * @returns {boolean} True if attributes were set successfully, false if validation failed
+     *
+     * @example
+     * // Set a single attribute
+     * user.set('name', 'Jane');
+     *
+     * // Set multiple attributes
+     * user.set({ name: 'Jane', email: 'jane@example.com' });
+     *
+     * // Set with validation enabled
+     * const success = user.set({ email: 'invalid-email' }, { validate: true });
+     * if (!success) {
+     *   console.log('Validation failed:', user.validationError);
+     * }
+     *
+     * // Set attributes silently without validation errors
+     * user.set({ name: '' }, { validate: true, silent: true });
+     */
+    set<K extends keyof T>(key: K, value: T[K], options?: ValidationOptions): boolean;
+    set(attrs: Partial<T>, options?: ValidationOptions): boolean;
+    /**
+     * Checks whether a specific attribute has a non-null, non-undefined value.
+     *
+     * This method provides a way to determine if an attribute exists and has a
+     * meaningful value. It returns true if the attribute is set to any value
+     * other than null or undefined, including falsy values like false, 0, or
+     * empty strings, which are considered valid values.
+     *
+     * @template K - The key type, constrained to keys of T
+     * @param {K} key - The attribute key to check
+     * @returns {boolean} True if the attribute has a non-null, non-undefined value
+     * @example
+     * // Assuming a User model with attributes { id: number, name: string, email?: string }
+     * const user = new User({ id: 1, name: 'John', email: null });
+     *
+     * user.has('id');    // Returns true (value is 1)
+     * user.has('name');  // Returns true (value is 'John')
+     * user.has('email'); // Returns false (value is null)
+     *
+     * // Even falsy values are considered "set"
+     * user.set({ name: '' });
+     * user.has('name');  // Returns true (empty string is a valid value)
+     */
+    has<K extends keyof T>(key: K): boolean;
+    /**
+     * Removes a specific attribute from the model by deleting it from the internal attributes hash.
+     *
+     * This method permanently removes an attribute from the model instance. Once unset,
+     * the attribute will no longer exist on the model and subsequent calls to get() for
+     * that key will return undefined. This is different from setting an attribute to
+     * null or undefined, as the property is completely removed from the attributes object.
+     *
+     * @template K - The key type, constrained to keys of T
+     * @param {K} key - The attribute key to remove from the model
      * @returns {void}
      * @example
      * // Assuming a User model with attributes { id: number, name: string, email: string }
      * const user = new User({ id: 1, name: 'John', email: 'john@example.com' });
      *
-     * // Update multiple attributes at once
+     * user.has('email'); // Returns true
+     * user.unset('email'); // Remove the email attribute
+     * user.has('email'); // Returns false
+     * user.get('email'); // Returns undefined
+     *
+     * // The attribute is completely removed, not just set to undefined
+     * const userData = user.toJSON(); // { id: 1, name: 'John' }
+     */
+    unset<K extends keyof T>(key: K): void;
+    /**
+     * Removes all attributes from the model, including the id attribute.
+     *
+     * This method completely clears the model instance by removing all stored attributes,
+     * effectively resetting it to an empty state. After calling clear(), the model will
+     * behave as if it were newly instantiated with no data. This includes removing the
+     * ID attribute, which means the model will be considered "new" after clearing.
+     *
+     * This is useful when you want to reuse a model instance for different data or
+     * reset a model to its initial state without creating a new instance.
+     *
+     * @returns {void}
+     * @example
+     * // Clear all data from a user model
+     * const user = new User({ id: 1, name: 'John', email: 'john@example.com' });
+     * user.clear();
+     *
+     * user.has('id');    // Returns false
+     * user.has('name');  // Returns false
+     * user.isNew();      // Returns true
+     * user.toJSON();     // Returns {}
+     *
+     * // Model can be reused with new data
      * user.set({ name: 'Jane', email: 'jane@example.com' });
-     * // Now user has { id: 1, name: 'Jane', email: 'jane@example.com' }
+     */
+    clear(): void;
+    /**
+     * Retrieves and escapes the HTML content of a specific attribute from the model.
+     *
+     * This method provides a safe way to access model attributes that may contain
+     * user-generated content or data that will be rendered in HTML contexts. It
+     * automatically applies HTML escaping to prevent XSS attacks and ensure safe
+     * rendering of potentially dangerous content.
+     *
+     * The method uses the escapeHTML utility function to convert special HTML
+     * characters (such as <, >, &, ", and ') into their corresponding HTML entities,
+     * making the content safe for direct insertion into HTML templates.
      *
-     * // Update a single attribute
-     * user.set({ name: 'Bob' });
-     * // Now user has { id: 1, name: 'Bob', email: 'jane@example.com' }
+     * @template K - The key type, constrained to keys of T
+     * @param {K} key - The attribute key to retrieve and escape the value for
+     * @returns {T[K]} The HTML-escaped value associated with the specified key
+     * @example
+     * // Assuming a Post model with attributes { id: number, title: string, content: string }
+     * const post = new Post({
+     *   id: 1,
+     *   title: 'Hello <script>alert("XSS")</script>',
+     *   content: 'This is "safe" & secure content'
+     * });
+     *
+     * const safeTitle = post.escape('title');
+     * // Returns: 'Hello &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
+     *
+     * const safeContent = post.escape('content');
+     * // Returns: 'This is &quot;safe&quot; &amp; secure content'
      */
-    set(attrs: Partial<T>): void;
+    escape<K extends keyof T>(key: K): string;
     /**
      * Determines whether this model instance is new (not yet persisted).
      * A model is considered new if it doesn't have an 'id' or '_id' attribute.
@@ -66,6 +311,69 @@ export declare abstract class Model<T extends object> {
      * @returns {boolean} true if the model is new, false if it has been persisted
      */
     isNew(): boolean;
+    /**
+     * Validates the current model instance and returns whether it passes validation.
+     *
+     * This method performs validation on the model's current attributes using the
+     * validate() method defined by the subclass. It's a convenience method that
+     * allows you to check if a model is valid without having to manually call
+     * the validation logic.
+     *
+     * If validation fails, the validationError property will be set with details
+     * about what went wrong. If validation passes, validationError will be cleared.
+     *
+     * @param {ValidationOptions} [options] - Optional validation configuration
+     * @param {boolean} [options.silent] - If true, suppresses validation error setting
+     * @returns {boolean} True if the model passes validation, false otherwise
+     *
+     * @example
+     * // Check if a user model is valid
+     * const user = new User({ name: '', email: 'invalid-email' });
+     *
+     * if (!user.isValid()) {
+     *   console.log('Validation failed:', user.validationError);
+     *   // Handle validation errors
+     * } else {
+     *   // Proceed with saving or other operations
+     *   await user.save();
+     * }
+     *
+     * @example
+     * // Validate silently without setting validationError
+     * const isValid = user.isValid({ silent: true });
+     * // user.validationError remains unchanged
+     */
+    isValid(options?: ValidationOptions): boolean;
+    /**
+     * Validates the model's attributes using custom validation logic.
+     *
+     * This method is intended to be overridden by subclasses to implement custom
+     * validation rules. By default, it returns undefined (no validation errors).
+     * If validation fails, this method should return an error - either a simple
+     * string message or a complete error object.
+     *
+     * The validate method is automatically called by save() before persisting data,
+     * and can also be explicitly called by set() when the {validate: true} option
+     * is passed. If validation fails, the save operation is aborted and model
+     * attributes are not modified.
+     *
+     * @param {Partial<T>} attributes - The attributes to validate
+     * @param {any} [options] - Additional options passed from set() or save()
+     * @returns {any} Returns undefined if valid, or an error (string/object) if invalid
+     *
+     * @example
+     * // Override in a User model subclass
+     * validate(attributes: Partial<UserAttributes>) {
+     *   if (!attributes.email) {
+     *     return 'Email is required';
+     *   }
+     *   if (!attributes.email.includes('@')) {
+     *     return { email: 'Invalid email format' };
+     *   }
+     *   // Return undefined if validation passes
+     * }
+     */
+    validate(attributes: Partial<T>, options?: ValidationOptions): string | undefined;
     /**
      * Performs HTTP synchronization with the server for CRUD operations.
      *
@@ -97,7 +405,7 @@ export declare abstract class Model<T extends object> {
      * // Delete a user (DELETE request)
      * await user.sync('DELETE'); // Returns null for 204 responses
      */
-    sync<R = T>(method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', body?: Record<string, unknown> | T, options?: VellumConfig): Promise<R | null>;
+    sync<R = T>(method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', body?: Record<string, unknown> | T, options?: SyncOptions): Promise<R | null>;
     /**
      * Fetches data from the server and updates the model's attributes.
      *
@@ -135,7 +443,13 @@ export declare abstract class Model<T extends object> {
      * generates additional fields (like timestamps, computed values, or normalized data)
      * during the save process.
      *
-     * @returns {Promise<void>} A promise that resolves when the save operation completes
+     * @param {ValidationOptions & SyncOptions} [options] - Optional configuration for save behavior
+     * @param {boolean} [options.validate] - Whether to validate before saving (defaults to true)
+     * @param {boolean} [options.silent] - If true, suppresses validation error setting
+     * @param {string} [options.endpoint] - Override the default endpoint for this save operation
+     * @param {Record<string, string>} [options.headers] - Additional headers to include in the request
+     * @param {string} [options.origin] - Override the base URL origin for this request
+     * @returns {Promise<boolean>} A promise that resolves to true if save succeeds, false if validation fails
      * @throws {Error} Throws an error if the HTTP request fails or server returns an error
      *
      * @example
@@ -146,8 +460,17 @@ export declare abstract class Model<T extends object> {
      * // Update an existing user
      * existingUser.set({ name: 'Jane' });
      * await existingUser.save(); // PUT request with updated data
+     *
+     * // Save without validation
+     * await user.save({ validate: false });
+     *
+     * // Save with custom endpoint and headers
+     * await user.save({
+     *   endpoint: '/api/v2/users',
+     *   headers: { 'Custom-Header': 'value' }
+     * });
      */
-    save(): Promise<void>;
+    save(options?: ValidationOptions & SyncOptions): Promise<boolean>;
     /**
      * Deletes the model from the server.
      *