@jwerre/vellum 0.0.1

package/README.md

@@ -0,0 +1,380 @@
+# Vellum
+
+Vellum is a lightweight, structural state management library for Svelte 5. Vellum provides a robust Model and Collection base powered by Svelte Runes.It bridges the gap between raw objects and complex state logic, offering a typed, class-based approach to managing data-heavy applications.
+
+## Features
+
+- **Rune-Powered**: Built from the ground up for Svelte 5 `$state` and `$derived`.
+- **TypeScript First**: Deeply integrated generics for strict type safety across models and collections.
+- **Class-Based**: Encapsulate data, validation, and API logic in clean JavaScript classes.
+- **Global Config**: Centralized management for base URLs and reactive headers.
+- **RESTful Persistence**: Built-in fetch, save, and destroy methods using node-fetch standards.
+- **Zero Boilerplate**: No more manual $store subscriptions; just access properties directly.
+
+## Why Vellum?
+
+Modern Svelte development often moves away from stores and toward raw $state objects. While flexible, this can lead to logic being scattered across components.
+
+### Vellum provides:
+
+- **Consistency**: A standard way to define data entities.
+- **API Integration**: A natural home for fetch, save, and delete logic.
+- **Encapsulation**: Keep your data transformations inside the class, not the UI.
+
+## Installation
+
+```bash
+npm install @jwerre/vellum
+```
+
+## Quick Start
+
+### Configuration
+
+Before using your models, you should configure Vellum globally. This is ideal for setting your API base URL and injecting authorization tokens. Because the configuration uses Svelte Runes, updating headers (like a bearer token) will reactively apply to all subsequent API calls.
+
+```ts
+import { configureVellum } from '@jwerre/vellum';
+
+configureVellum({
+	origin: 'https://api.example.com',
+	headers: {
+		Authorization: 'Bearer your-token-here'
+	}
+});
+```
+
+### Define a Model
+
+Extend the Model class to define your data structure and any derived state or business logic.
+
+```ts
+import { Model } from '@jwerre/vellum';
+interface UserSchema {
+	id: number;
+	firstName: string;
+	lastName: string;
+	role: 'admin' | 'user';
+}
+
+export class UserModel extends Model<UserSchema> {
+	endpoint() {
+		return `/v1/user`;
+	}
+
+	// Computed property using Svelte $derived
+	fullName = $derived(`${this.get('firstName')} ${this.get('lastName')}`);
+
+	isAdmin() {
+		return this.get('role') === 'admin';
+	}
+}
+
+const user = new UserModel({ firstName: 'John', lastName: 'Doe', role: 'user' });
+await user.sync();
+console.log(user.id); // 1
+console.log(user.fullName); // John Doe
+```
+
+### Define a Collection
+
+Manage groups of models with built-in reactivity.
+
+```ts
+import { Collection } from '@jwerre/vellum';
+import { UserModel } from './UserModel.svelte.js';
+
+export class UserCollection extends Collection<UserModel, UserSchema> {
+	model = UserModel;
+
+	endpoint() {
+		return `/v1/users`;
+	}
+
+	// Derived state for the entire collection
+	adminCount = $derived(this.items.filter((u) => u.isAdmin()).length);
+}
+```
+
+### Use in Svelte Components
+
+Vellum works seamlessly with Svelte 5 components.
+
+```svelte
+<script lang="ts">
+	import { UserCollection } from './UserCollection';
+
+	const users = new UserCollection([{ id: 1, firstName: 'Jane', lastName: 'Doe', role: 'admin' }]);
+
+	function addUser() {
+		users.add({ id: 2, firstName: 'John', lastName: 'Smith', role: 'user' });
+	}
+</script>
+
+<h1>Admins: {users.adminCount}</h1>
+
+<ul>
+	{#each users.items as user}
+		{#if user.isAdmin()}
+			<li>{user.fullName} ({user.get('email')})</li>
+		{/if}
+	{/each}
+</ul>
+
+<button onclick={addUser}>Add User</button>
+```
+
+## API Reference
+
+### `Model<T>`
+
+The `Model` class provides a base class for creating data models with built-in CRUD operations and server synchronization.
+
+#### Constructor
+
+```javascript
+new Model((data = {}));
+```
+
+Creates a new Model instance with optional initial attributes.
+
+**Parameters:**
+
+- `data` (Object) - Optional partial object of attributes to initialize the model
+
+#### Abstract Properties
+
+Must be implemented by subclasses:
+
+- `endpoint()` - Function that returns the base URL path for API endpoints (e.g., '/users')
+
+#### Methods
+
+##### get(key)
+
+Retrieves the value of a specific attribute from the model.
+
+**Parameters:**
+
+- `key` - The attribute key to retrieve
+
+**Returns:** The value associated with the specified key
+
+```javascript
+const user = new User({ id: 1, name: 'John Doe' });
+const name = user.get('name'); // Returns 'John Doe'
+```
+
+##### set(attrs)
+
+Updates multiple attributes on the model instance.
+
+**Parameters:**
+
+- `attrs` - Partial object containing attributes to update
+
+```javascript
+user.set({ name: 'Jane', email: 'jane@example.com' });
+```
+
+##### isNew()
+
+Determines whether this model instance is new (not yet persisted).
+
+**Returns:** `true` if the model has no ID, `false` otherwise
+
+```javascript
+const newUser = new User({ name: 'John' });
+console.log(newUser.isNew()); // true
+```
+
+##### sync(method, body, options)
+
+Performs HTTP synchronization with the server for CRUD operations.
+
+**Parameters:**
+
+- `method` - HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE'), defaults to 'GET'
+- `body` - Optional request body data
+- `options` - Optional configuration overrides
+
+**Returns:** Promise resolving to server response data or null
+
+```javascript
+// Fetch user data
+const userData = await user.sync();
+
+// Create new user
+const newUser = await user.sync('POST', { name: 'John' });
+
+// Update user
+const updated = await user.sync('PUT', user.toJSON());
+```
+
+##### fetch()
+
+Fetches data from the server and updates the model's attributes.
+
+**Returns:** Promise
+
+```javascript
+const user = new User({ id: 1 });
+await user.fetch(); // Model now contains full user data
+```
+
+##### save()
+
+Saves the model by creating (POST) or updating (PUT) the server resource.
+
+**Returns:** Promise
+
+```javascript
+// Create new user
+const newUser = new User({ name: 'John' });
+await newUser.save(); // POST request
+
+// Update existing user
+user.set({ name: 'Jane' });
+await user.save(); // PUT request
+```
+
+##### destroy()
+
+Deletes the model from the server.
+
+**Returns:** Promise
+
+```javascript
+await user.destroy(); // DELETE request to /users/1
+```
+
+##### toJSON()
+
+Returns a plain object representation of the model's attributes.
+
+**Returns:** Plain object containing all attributes
+
+```javascript
+const user = new User({ id: 1, name: 'John' });
+const userData = user.toJSON();
+// Returns: { id: 1, name: 'John' }
+```
+
+#### Example Usage
+
+```javascript
+class User extends Model {
+	endpoint() {
+		return '/users';
+	}
+}
+
+// Create and save new user
+const user = new User({ name: 'John', email: 'john@example.com' });
+await user.save();
+
+// Fetch existing user
+const existingUser = new User({ id: 1 });
+await existingUser.fetch();
+
+// Update user
+existingUser.set({ name: 'Jane' });
+await existingUser.save();
+
+// Delete user
+await existingUser.destroy();
+```
+
+### `Collection<M, T>`
+
+The `Collection` class provides a reactive container for managing groups of Model instances with automatic UI updates.
+
+#### Constructor
+
+```javascript
+new Collection((models = []));
+```
+
+Creates a new Collection instance with optional initial data.
+
+**Parameters:**
+
+- `models` (Array) - Optional array of data objects to initialize the collection
+
+#### Properties
+
+- `items` - Reactive array of model instances in the collection
+- `length` - Number of items in the collection (read-only)
+
+#### Abstract Properties
+
+These must be implemented by subclasses:
+
+- `model` - The Model class constructor for creating instances
+- `endpoint()` - Function that returns the API endpoint URL
+
+#### Methods
+
+##### add(data)
+
+Adds a new item to the collection.
+
+**Parameters:**
+
+- `data` - Raw data object or existing model instance
+
+**Returns:** The model instance that was added
+
+```javascript
+const user = collection.add({ name: 'John', email: 'john@example.com' });
+```
+
+##### reset(data)
+
+Replaces all items in the collection with new data.
+
+**Parameters:**
+
+- `data` - Array of raw data objects
+
+```javascript
+collection.reset([
+	{ id: 1, name: 'John' },
+	{ id: 2, name: 'Jane' }
+]);
+```
+
+##### find(query)
+
+Finds the first item matching the query object.
+
+**Parameters:**
+
+- `query` - Object with key-value pairs to match
+
+**Returns:** The first matching item or `undefined`
+
+```javascript
+const user = collection.find({ id: 123 });
+const activeAdmin = collection.find({ role: 'admin', status: 'active' });
+```
+
+##### fetch(options)
+
+Fetches data from the server and populates the collection.
+
+**Parameters:**
+
+- `options.search` - Optional search parameters for the query string
+
+**Returns:** Promise
+
+```javascript
+// Fetch all items
+await collection.fetch();
+
+// Fetch with search parameters
+await collection.fetch({
+	search: { limit: 30, after: 29 }
+});
+```

package/dist/Collection.svelte.d.ts

@@ -0,0 +1,125 @@
+import { Model } from './Model.svelte';
+/**
+ * Abstract base class for managing collections of Model instances.
+ *
+ * Provides a reactive collection that can be populated with data, fetched from a server,
+ * and manipulated with type-safe operations. The collection is backed by Svelte's reactivity
+ * system for automatic UI updates.
+ *
+ * @template M - The Model type that extends Model<T>
+ * @template T - The data object type that the models represent
+ *
+ * @example
+ * ```typescript
+ * class UserCollection extends Collection<UserModel, User> {
+ *   model = UserModel;
+ *   endpoint = () => '/api/users';
+ * }
+ *
+ * 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 */
+    items: M[];
+    /** The Model class constructor used to create new instances */
+    abstract model: {
+        new (data: Partial<T>): M;
+    };
+    /** Returns the API endpoint URL for this collection */
+    abstract endpoint(): string;
+    /**
+     * Creates a new Collection instance.
+     *
+     * @param models - Optional array of data objects to initialize the collection with
+     *
+     * @example
+     * ```typescript
+     * // Create empty collection
+     * const collection = new UserCollection();
+     *
+     * // Create collection with initial data
+     * const collection = new UserCollection([
+     *   { id: 1, name: 'John' },
+     *   { id: 2, name: 'Jane' }
+     * ]);
+     * ```
+     */
+    constructor(models?: T[]);
+    /** Gets the number of items in the collection */
+    get length(): number;
+    /**
+     * Adds a new item to the collection.
+     *
+     * @param data - Either raw data of type T or an existing model instance of type M
+     * @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;
+    /**
+     * Resets the collection with new data, replacing all existing items.
+     *
+     * @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;
+    /**
+     * Finds the first item in the collection that matches the given query.
+     *
+     * @param query - An object containing key-value pairs to match against items in the collection.
+     *                Only items that match all specified properties will be returned.
+     * @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.
+     *                        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();
+     *
+     * // Fetch with search parameters
+     * await collection.fetch({
+     *   search: { limit: 30, after: 29 }
+     * });
+     * ```
+     */
+    fetch(options?: {
+        search?: Record<string, string | number | boolean>;
+    }): Promise<void>;
+}

package/dist/Collection.svelte.js

@@ -0,0 +1,155 @@
+import { SvelteURLSearchParams } from 'svelte/reactivity';
+import { Model } from './Model.svelte';
+import { vellumConfig } from './config.svelte';
+/**
+ * Abstract base class for managing collections of Model instances.
+ *
+ * Provides a reactive collection that can be populated with data, fetched from a server,
+ * and manipulated with type-safe operations. The collection is backed by Svelte's reactivity
+ * system for automatic UI updates.
+ *
+ * @template M - The Model type that extends Model<T>
+ * @template T - The data object type that the models represent
+ *
+ * @example
+ * ```typescript
+ * class UserCollection extends Collection<UserModel, User> {
+ *   model = UserModel;
+ *   endpoint = () => '/api/users';
+ * }
+ *
+ * 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 */
+    items = $state([]);
+    /**
+     * Creates a new Collection instance.
+     *
+     * @param models - Optional array of data objects to initialize the collection with
+     *
+     * @example
+     * ```typescript
+     * // Create empty collection
+     * const collection = new UserCollection();
+     *
+     * // Create collection with initial data
+     * const collection = new UserCollection([
+     *   { id: 1, name: 'John' },
+     *   { id: 2, name: 'Jane' }
+     * ]);
+     * ```
+     */
+    constructor(models = []) {
+        if (models.length > 0) {
+            this.reset(models);
+        }
+    }
+    /** Gets the number of items in the collection */
+    get length() {
+        return this.items.length;
+    }
+    /**
+     * Adds a new item to the collection.
+     *
+     * @param data - Either raw data of type T or an existing model instance of type M
+     * @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);
+        this.items.push(instance);
+        return instance;
+    }
+    /**
+     * Resets the collection with new data, replacing all existing items.
+     *
+     * @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));
+    }
+    /**
+     * Finds the first item in the collection that matches the given query.
+     *
+     * @param query - An object containing key-value pairs to match against items in the collection.
+     *                Only items that match all specified properties will be returned.
+     * @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) => {
+            return Object.entries(query).every(([key, value]) => {
+                return item.get(key) === value;
+            });
+        });
+    }
+    /**
+     * 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.
+     *                        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();
+     *
+     * // Fetch with search parameters
+     * await collection.fetch({
+     *   search: { limit: 30, after: 29 }
+     * });
+     * ```
+     */
+    async fetch(options = {}) {
+        let query = '';
+        if (options.search) {
+            const params = new SvelteURLSearchParams();
+            for (const [key, value] of Object.entries(options.search)) {
+                params.append(key, String(value));
+            }
+            query = `?${params.toString()}`;
+        }
+        const fullUrl = `${vellumConfig.origin}${this.endpoint()}${query}`;
+        const response = await fetch(fullUrl, {
+            headers: { ...vellumConfig.headers }
+        });
+        if (!response.ok) {
+            throw new Error(`Vellum Collection Error: ${response.statusText}`);
+        }
+        const data = (await response.json());
+        this.reset(data);
+    }
+}

package/dist/Model.svelte.d.ts

@@ -0,0 +1,200 @@
+import { type VellumConfig } from './config.svelte';
+export declare abstract class Model<T extends object> {
+    #private;
+    /**
+     * Abstract method that must be implemented by subclasses to define the base URL path
+     * for API endpoints related to this model.
+     *
+     * This method returns the root URL segment that will be appended to the base API URL
+     * to form complete endpoints for CRUD operations. For example, if endpoint() returns
+     * '/users', the full URL for API calls would be `${baseUrl}/users` for collections
+     * or `${baseUrl}/users/{id}` for individual resources.
+     *
+     * @returns {string} The root URL path for this model's API endpoints (e.g., '/users', '/posts')
+     * @example
+     * // In a User model subclass:
+     * endpoint(): string {
+     *   return '/users';
+     * }
+     */
+    abstract endpoint(): string;
+    constructor(data?: Partial<T>);
+    /**
+     * Retrieves the value of a specific attribute from the model.
+     *
+     * This method provides type-safe access to model attributes, ensuring that the
+     * returned value matches the expected type for the given key. It acts as a
+     * getter for the internal attributes stored in the model instance.
+     *
+     * @template K - The key type, constrained to keys of T
+     * @param {K} key - The attribute key to retrieve the value for
+     * @returns {T[K]} The value associated with the specified key
+     * @example
+     * // Assuming a User model with attributes { id: number, name: string }
+     * const user = new User({ id: 1, name: 'John Doe' });
+     * const name = user.get('name'); // Returns 'John Doe' (string)
+     * const id = user.get('id');     // Returns 1 (number)
+     */
+    get<K extends keyof T>(key: K): T[K];
+    /**
+     * Sets multiple attributes on the model instance.
+     *
+     * 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.
+     *
+     * @param {Partial<T>} attrs - A partial object containing the attributes to update
+     * @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.set({ name: 'Jane', email: 'jane@example.com' });
+     * // Now user has { id: 1, name: 'Jane', email: 'jane@example.com' }
+     *
+     * // Update a single attribute
+     * user.set({ name: 'Bob' });
+     * // Now user has { id: 1, name: 'Bob', email: 'jane@example.com' }
+     */
+    set(attrs: Partial<T>): void;
+    /**
+     * 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.
+     *
+     * @returns {boolean} true if the model is new, false if it has been persisted
+     */
+    isNew(): boolean;
+    /**
+     * Performs HTTP synchronization with the server for CRUD operations.
+     *
+     * This method handles all HTTP communication between the model and the server,
+     * automatically constructing the appropriate URL based on the model's ID and
+     * endpoint(). It supports all standard REST operations and provides type-safe
+     * response handling.
+     *
+     * The URL construction follows REST conventions:
+     * - For new models (no ID): uses collection endpoint `${baseUrl}${endpoint()}`
+     * - For existing models (with ID): uses resource endpoint `${baseUrl}${endpoint()}/${id}`
+     *
+     * @template R - The expected response type, defaults to T (the model's attribute type)
+     * @param {('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE')} [method='GET'] - The HTTP method to use (defaults to 'GET')
+     * @param {Record<string, unknown> | T} [body] - Optional request body data to send
+     * @returns {Promise<R | null>} The server response data, or null for 204 No Content responses
+     * @throws {Error} Throws an error if the HTTP response is not successful
+     *
+     * @example
+     * // Fetch a user by ID (default 'GET' request)
+     * const userData = await user.sync();
+     *
+     * // Create a new user (POST request)
+     * const newUser = await user.sync('POST', { name: 'John', email: 'john@example.com' });
+     *
+     * // Update an existing user (PUT request)
+     * const updatedUser = await user.sync('PUT', user.toJSON());
+     *
+     * // 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>;
+    /**
+     * Fetches data from the server and updates the model's attributes.
+     *
+     * This method performs a GET request to retrieve the latest data for this model
+     * instance from the server. If the model has an ID, it will fetch the specific
+     * resource; if it's a new model without an ID, it will make a request to the
+     * collection endpoint.
+     *
+     * Upon successful retrieval, the model's attributes are automatically updated
+     * with the server response data. This method is useful for refreshing a model's
+     * state or loading data after creating a model instance with just an ID.
+     *
+     * @returns {Promise<void>} A promise that resolves when the fetch operation completes
+     * @throws {Error} Throws an error if the HTTP request fails or server returns an error
+     *
+     * @example
+     * // Fetch data for an existing user
+     * const user = new User({ id: 1 });
+     * await user.fetch(); // Model now contains full user data from server
+     *
+     * // Refresh a model's data
+     * await existingUser.fetch(); // Updates with latest server data
+     */
+    fetch(): Promise<void>;
+    /**
+     * Saves the model to the server by creating a new resource or updating an existing one.
+     *
+     * This method automatically determines whether to create or update based on the model's
+     * state. If the model is new (has no ID), it performs a POST request to create a new
+     * resource. If the model already exists (has an ID), it performs a PUT request to
+     * update the existing resource.
+     *
+     * After a successful save operation, the model's attributes are updated with any
+     * data returned from the server. This is particularly useful when the server
+     * 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
+     * @throws {Error} Throws an error if the HTTP request fails or server returns an error
+     *
+     * @example
+     * // Create a new user
+     * const newUser = new User({ name: 'John', email: 'john@example.com' });
+     * await newUser.save(); // POST request, user now has ID from server
+     *
+     * // Update an existing user
+     * existingUser.set({ name: 'Jane' });
+     * await existingUser.save(); // PUT request with updated data
+     */
+    save(): Promise<void>;
+    /**
+     * Deletes the model from the server.
+     *
+     * This method performs a DELETE request to remove the model's corresponding resource
+     * from the server. The method only executes if the model has an ID (i.e., it exists
+     * on the server). If the model is new and has no ID, the method will return without
+     * performing any operation.
+     *
+     * The DELETE request is sent to the model's specific resource endpoint using the
+     * pattern `${baseUrl}${endpoint()}/${id}`. After successful deletion, the model
+     * instance remains in memory but the corresponding server resource is removed.
+     *
+     * @returns {Promise<void>} A promise that resolves when the delete operation completes
+     * @throws {Error} Throws an error if the HTTP request fails or server returns an error
+     *
+     * @example
+     * // Delete an existing user
+     * const user = new User({ id: 1, name: 'John' });
+     * await user.destroy(); // DELETE request to /users/1
+     *
+     * // Attempting to destroy a new model (no operation performed)
+     * const newUser = new User({ name: 'Jane' }); // No ID
+     * await newUser.destroy(); // Returns immediately, no HTTP request
+     */
+    destroy(): Promise<void>;
+    /**
+     * Returns a plain JavaScript object representation of the model's attributes.
+     *
+     * This method creates a shallow copy of the model's internal attributes, returning
+     * them as a plain object. This is useful for serialization, debugging, or when you
+     * need to pass the model's data to functions that expect plain objects rather than
+     * model instances.
+     *
+     * The returned object is a copy, so modifications to it will not affect the original
+     * model's attributes. This method is commonly used internally by other model methods
+     * (like save()) when preparing data for HTTP requests.
+     *
+     * @returns {T} A plain object containing all of the model's attributes
+     *
+     * @example
+     * // Get plain object representation
+     * const user = new User({ id: 1, name: 'John', email: 'john@example.com' });
+     * const userData = user.toJSON();
+     * // Returns: { id: 1, name: 'John', email: 'john@example.com' }
+     *
+     * // Useful for serialization
+     * const jsonString = JSON.stringify(user.toJSON());
+     */
+    toJSON(): T;
+}

package/dist/Model.svelte.js

@@ -0,0 +1,245 @@
+import { vellumConfig } from './config.svelte';
+export class Model {
+    #attributes = $state({});
+    constructor(data = {}) {
+        this.#attributes = { ...data };
+    }
+    /**
+     * Internal helper to find the ID
+     */
+    #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;
+    }
+    /**
+     * Retrieves the value of a specific attribute from the model.
+     *
+     * This method provides type-safe access to model attributes, ensuring that the
+     * returned value matches the expected type for the given key. It acts as a
+     * getter for the internal attributes stored in the model instance.
+     *
+     * @template K - The key type, constrained to keys of T
+     * @param {K} key - The attribute key to retrieve the value for
+     * @returns {T[K]} The value associated with the specified key
+     * @example
+     * // Assuming a User model with attributes { id: number, name: string }
+     * const user = new User({ id: 1, name: 'John Doe' });
+     * const name = user.get('name'); // Returns 'John Doe' (string)
+     * const id = user.get('id');     // Returns 1 (number)
+     */
+    get(key) {
+        return this.#attributes[key];
+    }
+    /**
+     * Sets multiple attributes on the model instance.
+     *
+     * 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.
+     *
+     * @param {Partial<T>} attrs - A partial object containing the attributes to update
+     * @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.set({ name: 'Jane', email: 'jane@example.com' });
+     * // Now user has { id: 1, name: 'Jane', email: 'jane@example.com' }
+     *
+     * // Update a single attribute
+     * user.set({ name: 'Bob' });
+     * // Now user has { id: 1, name: 'Bob', email: 'jane@example.com' }
+     */
+    set(attrs) {
+        Object.assign(this.#attributes, attrs);
+    }
+    /**
+     * 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.
+     *
+     * @returns {boolean} true if the model is new, false if it has been persisted
+     */
+    isNew() {
+        return !this.#getId();
+    }
+    /**
+     * Performs HTTP synchronization with the server for CRUD operations.
+     *
+     * This method handles all HTTP communication between the model and the server,
+     * automatically constructing the appropriate URL based on the model's ID and
+     * endpoint(). It supports all standard REST operations and provides type-safe
+     * response handling.
+     *
+     * The URL construction follows REST conventions:
+     * - For new models (no ID): uses collection endpoint `${baseUrl}${endpoint()}`
+     * - For existing models (with ID): uses resource endpoint `${baseUrl}${endpoint()}/${id}`
+     *
+     * @template R - The expected response type, defaults to T (the model's attribute type)
+     * @param {('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE')} [method='GET'] - The HTTP method to use (defaults to 'GET')
+     * @param {Record<string, unknown> | T} [body] - Optional request body data to send
+     * @returns {Promise<R | null>} The server response data, or null for 204 No Content responses
+     * @throws {Error} Throws an error if the HTTP response is not successful
+     *
+     * @example
+     * // Fetch a user by ID (default 'GET' request)
+     * const userData = await user.sync();
+     *
+     * // Create a new user (POST request)
+     * const newUser = await user.sync('POST', { name: 'John', email: 'john@example.com' });
+     *
+     * // Update an existing user (PUT request)
+     * const updatedUser = await user.sync('PUT', user.toJSON());
+     *
+     * // Delete a user (DELETE request)
+     * await user.sync('DELETE'); // Returns null for 204 responses
+     */
+    async sync(method = 'GET', body, options) {
+        const id = this.#getId();
+        const fullUrl = `${vellumConfig.origin}${this.endpoint()}`;
+        const url = id ? `${fullUrl}/${id}` : fullUrl;
+        const fetchOpts = {
+            method,
+            headers: {
+                ...vellumConfig.headers,
+                ...options?.headers
+            },
+            body: body ? JSON.stringify(body) : undefined
+        };
+        // console.log('Model::sync()', url, fetchOpts);
+        const response = await fetch(url, fetchOpts);
+        if (!response.ok) {
+            throw new Error(`Vellum Sync Error: ${response.statusText}`);
+        }
+        // Handle 204 No Content safely
+        if (response.status === 204) {
+            return null;
+        }
+        const data = await response.json();
+        return data;
+    }
+    /**
+     * Fetches data from the server and updates the model's attributes.
+     *
+     * This method performs a GET request to retrieve the latest data for this model
+     * instance from the server. If the model has an ID, it will fetch the specific
+     * resource; if it's a new model without an ID, it will make a request to the
+     * collection endpoint.
+     *
+     * Upon successful retrieval, the model's attributes are automatically updated
+     * with the server response data. This method is useful for refreshing a model's
+     * state or loading data after creating a model instance with just an ID.
+     *
+     * @returns {Promise<void>} A promise that resolves when the fetch operation completes
+     * @throws {Error} Throws an error if the HTTP request fails or server returns an error
+     *
+     * @example
+     * // Fetch data for an existing user
+     * const user = new User({ id: 1 });
+     * await user.fetch(); // Model now contains full user data from server
+     *
+     * // Refresh a model's data
+     * await existingUser.fetch(); // Updates with latest server data
+     */
+    async fetch() {
+        const data = await this.sync('GET');
+        if (data && typeof data === 'object') {
+            this.set(data);
+        }
+    }
+    /**
+     * Saves the model to the server by creating a new resource or updating an existing one.
+     *
+     * This method automatically determines whether to create or update based on the model's
+     * state. If the model is new (has no ID), it performs a POST request to create a new
+     * resource. If the model already exists (has an ID), it performs a PUT request to
+     * update the existing resource.
+     *
+     * After a successful save operation, the model's attributes are updated with any
+     * data returned from the server. This is particularly useful when the server
+     * 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
+     * @throws {Error} Throws an error if the HTTP request fails or server returns an error
+     *
+     * @example
+     * // Create a new user
+     * const newUser = new User({ name: 'John', email: 'john@example.com' });
+     * await newUser.save(); // POST request, user now has ID from server
+     *
+     * // Update an existing user
+     * existingUser.set({ name: 'Jane' });
+     * await existingUser.save(); // PUT request with updated data
+     */
+    async save() {
+        const id = this.#getId();
+        const method = id ? 'PUT' : 'POST';
+        const data = await this.sync(method, this.toJSON());
+        if (data && typeof data === 'object') {
+            this.set(data);
+        }
+    }
+    /**
+     * Deletes the model from the server.
+     *
+     * This method performs a DELETE request to remove the model's corresponding resource
+     * from the server. The method only executes if the model has an ID (i.e., it exists
+     * on the server). If the model is new and has no ID, the method will return without
+     * performing any operation.
+     *
+     * The DELETE request is sent to the model's specific resource endpoint using the
+     * pattern `${baseUrl}${endpoint()}/${id}`. After successful deletion, the model
+     * instance remains in memory but the corresponding server resource is removed.
+     *
+     * @returns {Promise<void>} A promise that resolves when the delete operation completes
+     * @throws {Error} Throws an error if the HTTP request fails or server returns an error
+     *
+     * @example
+     * // Delete an existing user
+     * const user = new User({ id: 1, name: 'John' });
+     * await user.destroy(); // DELETE request to /users/1
+     *
+     * // Attempting to destroy a new model (no operation performed)
+     * const newUser = new User({ name: 'Jane' }); // No ID
+     * await newUser.destroy(); // Returns immediately, no HTTP request
+     */
+    async destroy() {
+        const id = this.#getId();
+        if (id) {
+            await this.sync('DELETE');
+        }
+    }
+    /**
+     * Returns a plain JavaScript object representation of the model's attributes.
+     *
+     * This method creates a shallow copy of the model's internal attributes, returning
+     * them as a plain object. This is useful for serialization, debugging, or when you
+     * need to pass the model's data to functions that expect plain objects rather than
+     * model instances.
+     *
+     * The returned object is a copy, so modifications to it will not affect the original
+     * model's attributes. This method is commonly used internally by other model methods
+     * (like save()) when preparing data for HTTP requests.
+     *
+     * @returns {T} A plain object containing all of the model's attributes
+     *
+     * @example
+     * // Get plain object representation
+     * const user = new User({ id: 1, name: 'John', email: 'john@example.com' });
+     * const userData = user.toJSON();
+     * // Returns: { id: 1, name: 'John', email: 'john@example.com' }
+     *
+     * // Useful for serialization
+     * const jsonString = JSON.stringify(user.toJSON());
+     */
+    toJSON() {
+        return { ...this.#attributes };
+    }
+}

package/dist/config.svelte.d.ts

@@ -0,0 +1,9 @@
+export interface VellumConfig {
+    origin: string;
+    headers: Record<string, string>;
+}
+export declare const vellumConfig: VellumConfig;
+/**
+ * Helper to update global configuration
+ */
+export declare const configureVellum: (config: Partial<VellumConfig>) => void;

package/dist/config.svelte.js

@@ -0,0 +1,16 @@
+export const vellumConfig = $state({
+    origin: '',
+    headers: {
+        'Content-Type': 'application/json'
+    }
+});
+/**
+ * Helper to update global configuration
+ */
+export const configureVellum = (config) => {
+    if (config.origin)
+        vellumConfig.origin = config.origin;
+    if (config.headers) {
+        vellumConfig.headers = { ...vellumConfig.headers, ...config.headers };
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { vellumConfig, configureVellum } from './config.svelte.js';
+export { Model } from './Model.svelte.js';
+export { Collection } from './Collection.svelte.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+// Reexport your entry components here
+export { vellumConfig, configureVellum } from './config.svelte.js';
+export { Model } from './Model.svelte.js';
+export { Collection } from './Collection.svelte.js';

package/package.json

@@ -0,0 +1,93 @@
+{
+	"name": "@jwerre/vellum",
+	"version": "0.0.1",
+	"description": "Structural state management library for Svelte 5",
+	"repository": {
+		"type": "git",
+		"url": "git@github.com:jwerre/vellum.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"svelte",
+		"svelte5",
+		"runes",
+		"vellum",
+		"model",
+		"collection",
+		"state-management",
+		"typescript",
+		"rest",
+		"active-record",
+		"orm",
+		"reactive",
+		"data-modeling"
+	],
+	"author": "Jonah Werre <jonahwerre@gmail.com>",
+	"scripts": {
+		"build": "svelte-kit sync && svelte-package",
+		"prepack": "publint",
+		"types": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"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",
+		"format": "prettier --check .",
+		"format:write": "prettier --write .",
+		"lint": "prettier --check . && eslint .",
+		"prepare": "svelte-kit sync || echo ''",
+		"preview": "vite preview",
+		"release": "semantic-release",
+		"release:dry": "semantic-release --dry-run",
+		"spell": "cspell .",
+		"test": "vitest --run",
+		"test:watch": "vitest"
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"sideEffects": false,
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"svelte": "^5.0.0"
+	},
+	"devDependencies": {
+		"@eslint/compat": "^1.4.0",
+		"@eslint/js": "^9.39.1",
+		"@semantic-release/changelog": "^6.0.3",
+		"@semantic-release/commit-analyzer": "^13.0.1",
+		"@semantic-release/github": "^12.0.2",
+		"@semantic-release/npm": "^13.1.3",
+		"@semantic-release/release-notes-generator": "^14.1.0",
+		"@sveltejs/adapter-auto": "^7.0.0",
+		"@sveltejs/kit": "^2.49.1",
+		"@sveltejs/package": "^2.5.7",
+		"@sveltejs/vite-plugin-svelte": "^6.2.1",
+		"@types/node": "^24",
+		"cspell": "^9.4.0",
+		"eslint": "^9.39.1",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-svelte": "^3.13.1",
+		"globals": "^16.5.0",
+		"prettier": "^3.7.4",
+		"prettier-plugin-svelte": "^3.4.0",
+		"publint": "^0.3.15",
+		"semantic-release": "^25.0.2",
+		"svelte": "^5.45.6",
+		"svelte-check": "^4.3.4",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.48.1",
+		"vite": "^7.2.6",
+		"vitest": "^4.0.15"
+	}
+}