@jwerre/vellum 1.0.1 → 1.1.0

package/dist/Model.svelte.js

@@ -1,20 +1,129 @@
 import { vellumConfig } from './config.svelte';
+import { ValidationError } from './errors/validation_error.js';
+import { escapeHTML } from './utils.js';
+/**
+ * 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 class Model {
     #attributes = $state({});
+    /**
+     * Validation error property that gets set when validation fails.
+     * This property contains the error returned by the validate method.
+     */
+    #validationError = $state();
+    /**
+     * 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' });
+     */
+    idAttribute = 'id';
+    /**
+     * Creates a new instance of Model.
+     */
     constructor(data = {}) {
-        this.#attributes = { ...data };
+        // Initialize model attributes with provided data, ensuring type safety
+        this.#attributes = { ...this.defaults(), ...data };
     }
     /**
-     * Internal helper to find the ID
+     * Gets the latest validation error.
+     *
+     * @returns {ValidationError || undefined} An instance of ValidationError if validation failed, otherwise undefined
      */
-    #getId() {
-        // Cast to Record<string, unknown> to allow string indexing
-        const attrs = this.#attributes;
-        const id = attrs['id'] ?? attrs['_id'];
-        if (typeof id === 'string' || typeof id === 'number') {
-            return id;
-        }
-        return undefined;
+    get validationError() {
+        return this.#validationError;
+    }
+    /**
+     * 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' }
+     */
+    defaults() {
+        return {};
     }
     /**
      * Retrieves the value of a specific attribute from the model.
@@ -35,30 +144,140 @@ export class Model {
     get(key) {
         return this.#attributes[key];
     }
+    set(keyOrAttrs, valueOrOptions, options) {
+        let attrs = {};
+        let opts;
+        if (typeof keyOrAttrs === 'object') {
+            attrs = keyOrAttrs;
+            opts = valueOrOptions;
+        }
+        else {
+            attrs[keyOrAttrs] = valueOrOptions;
+            opts = options;
+        }
+        if (opts?.validate && !this.#doValidation({ ...this.#attributes, ...attrs }, opts)) {
+            return false;
+        }
+        Object.assign(this.#attributes, attrs);
+        return true;
+    }
+    /**
+     * 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(key) {
+        const value = this.#attributes[key];
+        return value !== null && value !== undefined;
+    }
     /**
-     * Sets multiple attributes on the model instance.
+     * Removes a specific attribute from the model by deleting it from the internal attributes hash.
      *
-     * This method allows for bulk updating of model attributes by merging the provided
-     * partial attributes object with the existing attributes. The method performs a
-     * shallow merge, meaning that only the top-level properties specified in the attrs
-     * parameter will be updated, while other existing attributes remain unchanged.
+     * 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.
      *
-     * @param {Partial<T>} attrs - A partial object containing the attributes to update
+     * @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(key) {
+        // Cast to Record to allow delete operation
+        const attrs = this.#attributes;
+        delete attrs[key];
+    }
+    /**
+     * 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() {
+        this.#attributes = {};
+    }
+    /**
+     * 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) {
-        Object.assign(this.#attributes, attrs);
+    escape(key) {
+        const val = this.#attributes[key];
+        if (val === undefined || val === null)
+            return '';
+        return escapeHTML(val.toString());
     }
     /**
      * Determines whether this model instance is new (not yet persisted).
@@ -69,6 +288,75 @@ export class Model {
     isNew() {
         return !this.#getId();
     }
+    /**
+     * 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) {
+        return this.#doValidation(this.#attributes, { ...options, validate: true });
+    }
+    /**
+     * 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
+     * }
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    validate(attributes, options) {
+        // Default implementation - no validation
+        return undefined;
+    }
     /**
      * Performs HTTP synchronization with the server for CRUD operations.
      *
@@ -167,7 +455,13 @@ export class Model {
      * 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
@@ -178,14 +472,28 @@ export class Model {
      * // 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' }
+     * });
      */
-    async save() {
+    async save(options) {
+        // Always validates before saving unless {validate: false}
+        if (options?.validate !== false && !this.#doValidation(this.#attributes, options)) {
+            return false;
+        }
         const id = this.#getId();
         const method = id ? 'PUT' : 'POST';
-        const data = await this.sync(method, this.toJSON());
+        const data = await this.sync(method, this.toJSON(), options);
         if (data && typeof data === 'object') {
-            this.set(data);
+            this.set(data, { silent: true });
         }
+        return true;
     }
     /**
      * Deletes the model from the server.
@@ -243,4 +551,26 @@ export class Model {
     toJSON() {
         return { ...this.#attributes };
     }
+    // --------------- PRIVATE METHODS --------------- //
+    #getId() {
+        const id = this.#attributes[this.idAttribute];
+        if (typeof id === 'number' || (typeof id === 'string' && id.length > 0)) {
+            return id;
+        }
+        return undefined;
+    }
+    #doValidation(attrs, options) {
+        if (options?.silent || !this.validate || typeof this.validate !== 'function') {
+            this.#validationError = undefined;
+            return true;
+        }
+        const errMsg = this.validate(attrs, options);
+        // console.log(errMsg);
+        if (errMsg && errMsg.length > 0) {
+            this.#validationError = new ValidationError(errMsg);
+            return false;
+        }
+        this.#validationError = undefined;
+        return true;
+    }
 }

package/dist/config.svelte.d.ts

@@ -2,8 +2,41 @@ export interface VellumConfig {
     origin: string;
     headers: Record<string, string>;
 }
+/**
+ * Global reactive state for Vellum configuration. Uses Svelte's $state rune to
+ * create a reactive configuration object that automatically triggers updates when modified.
+ *
+ * @default origin - Empty string (must be configured before use)
+ * @default headers - Contains 'Content-Type': 'application/json'
+ */
 export declare const vellumConfig: VellumConfig;
 /**
- * Helper to update global configuration
+ * Helper function to update global Vellum configuration
+ *
+ * Allows partial updates to the global configuration state. Only provided
+ * properties will be updated, leaving others unchanged. Headers are merged
+ * with existing headers rather than replaced entirely.
+ *
+ * @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
+ *
+ * @example
+ * // Set the API origin
+ * configureVellum({ origin: 'https://api.vellum.ai' });
+ *
+ * // Add custom headers
+ * configureVellum({
+ *   headers: {
+ *     'Authorization': 'Bearer token123',
+ *     'X-Custom-Header': 'value'
+ *   }
+ * });
+ *
+ * // Update both origin and headers
+ * configureVellum({
+ *   origin: 'https://api.vellum.ai',
+ *   headers: { 'Authorization': 'Bearer token123' }
+ * });
  */
 export declare const configureVellum: (config: Partial<VellumConfig>) => void;

package/dist/config.svelte.js

@@ -1,3 +1,10 @@
+/**
+ * Global reactive state for Vellum configuration. Uses Svelte's $state rune to
+ * create a reactive configuration object that automatically triggers updates when modified.
+ *
+ * @default origin - Empty string (must be configured before use)
+ * @default headers - Contains 'Content-Type': 'application/json'
+ */
 export const vellumConfig = $state({
     origin: '',
     headers: {
@@ -5,7 +12,33 @@ export const vellumConfig = $state({
     }
 });
 /**
- * Helper to update global configuration
+ * Helper function to update global Vellum configuration
+ *
+ * Allows partial updates to the global configuration state. Only provided
+ * properties will be updated, leaving others unchanged. Headers are merged
+ * with existing headers rather than replaced entirely.
+ *
+ * @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
+ *
+ * @example
+ * // Set the API origin
+ * configureVellum({ origin: 'https://api.vellum.ai' });
+ *
+ * // Add custom headers
+ * configureVellum({
+ *   headers: {
+ *     'Authorization': 'Bearer token123',
+ *     'X-Custom-Header': 'value'
+ *   }
+ * });
+ *
+ * // Update both origin and headers
+ * configureVellum({
+ *   origin: 'https://api.vellum.ai',
+ *   headers: { 'Authorization': 'Bearer token123' }
+ * });
  */
 export const configureVellum = (config) => {
     if (config.origin)

package/dist/errors/validation_error.d.ts

@@ -0,0 +1,8 @@
+export interface ValidationDetails {
+    [key: string]: string | string[];
+}
+export declare class ValidationError extends Error {
+    details: ValidationDetails;
+    status: number;
+    constructor(message: string, details?: ValidationDetails);
+}

package/dist/errors/validation_error.js

@@ -0,0 +1,9 @@
+export class ValidationError extends Error {
+    details;
+    status = 400;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = 'ValidationError';
+        this.details = details;
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { vellumConfig, configureVellum } from './config.svelte.js';
-export { Model } from './Model.svelte.js';
-export { Collection } from './Collection.svelte.js';
+export { type ValidationDetails, ValidationError } from './errors/validation_error.js';
+export { type SyncOptions, type ValidationOptions, Model } from './Model.svelte.js';
+export { type FetchOptions, Collection } from './Collection.svelte.js';
+export * as utils from './utils.js';

package/dist/index.js

@@ -1,4 +1,5 @@
-// Reexport your entry components here
 export { vellumConfig, configureVellum } from './config.svelte.js';
+export { ValidationError } from './errors/validation_error.js';
 export { Model } from './Model.svelte.js';
 export { Collection } from './Collection.svelte.js';
+export * as utils from './utils.js';

package/dist/utils.d.ts

@@ -0,0 +1 @@
+export declare const escapeHTML: (text: string) => string;

package/dist/utils.js

@@ -0,0 +1,10 @@
+export const escapeHTML = (text) => {
+    const lookup = {
+        '&': '&',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;'
+    };
+    return text.replace(/[&<>"']/g, (char) => lookup[char]);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jwerre/vellum",
-	"version": "1.0.1",
+	"version": "1.1.0",
 	"description": "Structural state management library for Svelte 5",
 	"repository": {
 		"type": "git",
@@ -32,6 +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\"",
 		"format": "prettier --check .",
 		"format:write": "prettier --write .",
 		"lint": "prettier --check . && eslint .",
@@ -75,6 +76,7 @@
 		"@sveltejs/vite-plugin-svelte": "^6.2.1",
 		"@types/node": "^24",
 		"cspell": "^9.4.0",
+		"documentation": "^14.0.3",
 		"eslint": "^9.39.1",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-svelte": "^3.13.1",