svelte-specma 1.1.6 → 2.0.0

package/README.md

@@ -1,298 +1,968 @@
 # Svelte-Specma
 
-Svelte-Specma is a Svelte store used to do client-side validation using the very powerful [Specma](https://www.npmjs.com/package/specma) library.
-
-- Collection specs defined with the exact **same shape as the value**!
-- Based on **predicate functions** of type `true || "reason"`
-- **Composable specs** with intuitive `and`/`or` operators
-- Easy **cross-validation** between multiple fields
-- User defined **customized invalid reasons**
-- **Async validation** out of the box
-- Very **small footprint**
-
-# Design considerations
+Svelte-Specma connects Specma predicate specs to Svelte stores to provide small, composable, and predictable client-side validation for forms and arbitrary state. It supports nested/collection shapes, synchronous and asynchronous predicates, custom error messages and easy binding to HTML inputs.
+
+Goals
+
+- Minimal API that maps Specma specs to reactive Svelte stores
+- Compose nested validators for objects, arrays and Maps
+- Allow cross-field and async validation via Specma
+- Small, framework-friendly building blocks (stores + a Svelte action)
+- **Share validation specs between client and server** — define once, use everywhere
+
+## Table of Contents
+
+- [Svelte-Specma](#svelte-specma)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Quick setup](#quick-setup)
+  - [Concepts in two lines](#concepts-in-two-lines)
+  - [Create a store (convenience)](#create-a-store-convenience)
+    - [Primitive example (single field)](#primitive-example-single-field)
+    - [Collection example (form with nested list)](#collection-example-form-with-nested-list)
+  - [Svelte input binding (register)](#svelte-input-binding-register)
+  - [Shared Specs (Client \& Server)](#shared-specs-client--server)
+    - [Basic Pattern](#basic-pattern)
+    - [Client-Side Usage (Svelte)](#client-side-usage-svelte)
+    - [Server-Side Usage (Node.js/SvelteKit)](#server-side-usage-nodejssveltekit)
+    - [Complex Nested Specs](#complex-nested-specs)
+    - [Benefits of Shared Specs](#benefits-of-shared-specs)
+  - [API summary](#api-summary)
+  - [Real-world patterns](#real-world-patterns)
+  - [Tips \& best practices](#tips--best-practices)
+  - [Comprehensive Examples](#comprehensive-examples)
+    - [Example 1: Simple Login Form with Email and Password Validation](#example-1-simple-login-form-with-email-and-password-validation)
+    - [Example 2: User Profile Form with Nested Validation](#example-2-user-profile-form-with-nested-validation)
+    - [Example 3: Dynamic List Management (Shopping Cart)](#example-3-dynamic-list-management-shopping-cart)
+    - [Example 4: Async Validation (Username Availability Check)](#example-4-async-validation-username-availability-check)
+    - [Example 5: Shared Validation (Full Stack)](#example-5-shared-validation-full-stack)
+
+## Installation
+
+```bash
+npm install svelte-specma
+# or
+yarn add svelte-specma
+```
 
-## Spec design
+## Quick setup
 
-You should first get familiar with the Specma way of [defining a spec](https://davidsavoie1.github.io/specma/#/gettingStarted?id=predicate-spec). All valid Specma specs will work fine with Svelte-Specma, including async validation, spec composition and cross-fields validation with `getFrom` function as second predicate argument. Specs can hence be reused in a variety of contexts without redefining them all the time.
+Svelte-Specma delegates predicate operations to a Specma-compatible implementation. Configure the library once at app startup:
 
-Simple composition with possibily nested `and` and `or` allows adding advanced constraints on a base spec, such as calling a remote endpoint asynchronously to check a value availability.
+```js
+import * as specma from "specma"; // or another Specma-compatible lib
+import { configure } from "svelte-specma";
 
-## Requiredness
+configure(specma);
+```
 
-By design, as in Specma, the requiredness of certain fields is not defined in the spec itself. It is rather is defined at store creation time by passing in a `required` object of the same shape as the value. This allows reusing the same spec in different forms, where only the required fields change, not the predicates themselves.
+This must run before creating any specable stores.
 
-Values that are `undefined` won't be validated against their spec unless they are specified as required. Also, because Svelte-Specma is mainly used in forms, `null` and `""` are considered as missing when a value is required.
+## Concepts in two lines
 
-## Svelte integration
+- `predSpecable`: single-value store that validates a primitive/non-collection value.
+- `collSpecable`: collection-aware store (object / array / Map) that composes child specable stores.
 
-Svelte-Specma uses Svelte stores to manage state and validation. It is not tied to any particular component, although it might make sense for you to eventually design components to reduce boilerplate code (updating store value, activating on input blur, displaying loading or error messages, etc.).
+## Create a store (convenience)
 
-# `configure` - Before using!
+Use `specable()` — it chooses `predSpecable` or `collSpecable` automatically.
 
-Since Specma relies on some Javascript Symbols to define specs, Svelte-Specma must use the same instance of the Spec library. **It must hence be configured once prior to usage**.
+### Primitive example (single field)
 
 ```js
-import * as specma from "specma";
-import { configure } from "svelte-specma";
-
-configure(specma);
-```
+import { specable } from "svelte-specma";
 
-# `specable`
+const age = specable(0, {
+  id: "age",
+  required: true,
+  spec: (v) =>
+    typeof v === "number" && v >= 0 ? true : "must be a non-negative number",
+});
 
-Main entry point and **preferred way for defining a specable store**. Will dispatch to `collSpecable` or `predSpecable` based on its arguments (based on spec's shape first, then initial value's shape) to eventually produce a deeply nested store.
+// subscribe for UI binding:
+age.subscribe((s) => {
+  // s.value, s.valid, s.validating, s.error, s.changed, s.active, s.promise, ...
+  console.log(s);
+});
+```
 
-## Inputs
+### Collection example (form with nested list)
 
 ```js
-const store = specable(initialValue, { spec, ...rest });
-```
+import { specable } from "svelte-specma";
+import { spread } from "specma"; // example usage of Specma helpers
 
-- `initialValue`: Any. The initial value to validate against the spec.
+const productSpec = {
+  name: (v = "") => (v.length ? true : "required"),
+  price: (v) => (typeof v === "number" && v >= 0 ? true : "invalid price"),
+};
+
+const catalog = specable(
+  { title: "My shop", items: [{ id: "1", name: "Pen", price: 1.5 }] },
+  {
+    spec: { title: (v) => true, items: spread(productSpec) },
+    getId: { items: (item) => item.id }, // id strategy for collection children
+    required: { title: 1, items: spread({ name: 1 }) },
+  }
+);
 
-- `spec`: Any. The Specma spec to validate against.
+// add an item programmatically:
+catalog.add([{ id: "2", name: "", price: null }]);
+```
 
-- `...rest`: Object. See `collSpecable` and `predSpecable` details below.
+## Svelte input binding (register)
 
-## Output
+Use the `register` action to bind a `predSpecable` to an input with optional converters:
 
-Either a [`collSpecable`](#collSpecable) or [`predSpecable`](#predSpecable) store (see below).
+Basic usage:
 
-# `predSpecable`
+```svelte
+<script>
+  import { specable, register } from "svelte-specma";
+  const name = specable("", { id: "name", spec: (v) => v ? true : "required" });
+</script>
 
-A Svelte store used to validate a value against the predicate function part of a Specma spec.
+<input use:register="{name}" />
+```
 
-```js
-/* Will create a `predSpecable` store, since initial value is not a collection */
-const store = specable(
-  30, // Initial value
-  {
-    spec: (v) => v === 42 || "is not the answer",
-    required: false,
-    id: "someId",
-  }
-);
+With converters (e.g. numeric input):
 
-/* Static properties and methods */
-const { id, isRequired, spec, activate, reset, set, subscribe } = store;
+```svelte
+<script>
+  const age = specable(0, { id: "age", spec: v => typeof v === 'number' || "must be a number" });
+  const conv = { toInput: (v) => v == null ? "" : String(v), toValue: (s) => s === "" ? undefined : Number(s) };
+</script>
 
-/* Subscription state values */
-$: ({ value, active, changed, valid, validating, error, promise, id } = $store);
+<input use:register="{[age, conv]}" inputmode="numeric" />
 ```
 
-## Inputs
+## Shared Specs (Client & Server)
 
-- `initialValue`: Any. The initial value to validate, saved in internal state
-- `spec`: Any. The Specma spec. Only the predicate function part of the spec is used in a `predSpecable`, so a compound value (object, array, etc.) won't validate its children spec. To do so, use a `collSpecable` instead.
-- `required`: Boolean. If a value is required, must be different than `undefined`, `null` or `""`; will return the Specma `isRequired` message otherwise. False by default.
-- `changePred`: Function. `(a, b) => boolean`. Function to evaluate if value is different from initial value. By default, will do a deep object value equality and compare dates by value.
-- `id`: Any. Used to uniquely identify the store. Mainly useful for values part of a list.
+One of the key advantages of using Specma with Svelte-Specma is the ability to **define validation specs once and reuse them across both client and server**. This ensures consistency, reduces duplication, and makes your codebase more maintainable.
 
-## Outputs
+### Basic Pattern
 
-- `id`: Any. A pass-through of the store's creation `id`.
+Define your specs in a shared module that can be imported by both client and server code:
 
-- `isRequired`: Boolean. Is the store value required? Based on the `required` creation argument.
+```js
+// filepath: shared/specs/userSpecs.js
+// Shared validation specs - works in both browser and Node.js
 
-- `spec`: The predicate function used to derive a validation result.
+export const emailSpec = (v) => {
+  const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailPattern.test(v) || "Invalid email address";
+};
 
-- `activate`: Async function. `(Boolean = true) => Promise`. Method to de/activate the store validation. If set to true, will immediately trigger validation and return a promise that resolves to the `valid` result property.
+export const passwordSpec = (v) =>
+  v.length >= 8 ? true : "Password must be at least 8 characters";
 
-- `reset`: Function. `(Any = initialValue) => undefined`. Reset the store to a new initial value (or the initial one if no argument) and deactivate the store.
+export const usernameSpec = (v) =>
+  v && v.length >= 3 ? true : "Username must be at least 3 characters";
 
-- `set`: Function. `(Any, shouldActivate = false) => undefined`. Set the store's internal value to a new one. Will trigger validation if store is active. If `shouldActivate = true`, activates the store after setting the value.
+export const ageSpec = (v) =>
+  typeof v === "number" && v >= 18 && v <= 120
+    ? true
+    : "Age must be between 18 and 120";
 
-- `submit`: Function. `(value) => {}`. Method to first activate then handle the current value. `submitting` state is set to `true` during submit.
+export const phoneSpec = (v) => /^\d{10}$/.test(v) || "Phone must be 10 digits";
+```
 
-- `subscribe`: Function. `(fn) => unsubscribe`. The Svelte store's subscribe method. Usually used in Svelte components with a reactive autosubscription declaration (`$: storeState = $store`). The function argument will be called with the updated internal state (see below) each time it changes. Returns an unsubscribe function that can be called when component unmounts to prevent memory leaks.
+### Client-Side Usage (Svelte)
 
-  - `value`: Any. The internal state value, which can be modified with the store's methods.
+```svelte
+<!-- filepath: src/routes/register/+page.svelte -->
+<script>
+  import { specable, register } from "svelte-specma";
+  import { emailSpec, passwordSpec, usernameSpec } from "$lib/shared/specs/userSpecs";
+
+  const email = specable("", { id: "email", required: true, spec: emailSpec });
+  const password = specable("", { id: "password", required: true, spec: passwordSpec });
+  const username = specable("", { id: "username", required: true, spec: usernameSpec });
+
+  async function handleSubmit() {
+    // Activate all fields
+    email.activate();
+    password.activate();
+    username.activate();
+
+    if ($email.valid && $password.valid && $username.valid) {
+      // Submit to server
+      const response = await fetch("/api/register", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          email: $email.value,
+          password: $password.value,
+          username: $username.value
+        })
+      });
+
+      if (response.ok) {
+        console.log("Registration successful!");
+      }
+    }
+  }
+</script>
 
-  - `active`: Boolean. Is the store currently active? Default to `false`.
+<form on:submit|preventDefault={handleSubmit}>
+  <input use:register={username} placeholder="Username" />
+  {#if $username.active && $username.error}<p class="error">{$username.error}</p>{/if}
 
-  - `changed`: Boolean. Is the value different (value based deep-equality) from the initial value?
+  <input use:register={email} type="email" placeholder="Email" />
+  {#if $email.active && $email.error}<p class="error">{$email.error}</p>{/if}
 
-  - `valid`: Boolean. Is the value valid when checked against spec? Always `true` when store is not active. `false` if the store is validating asynchronously until a firm result is available.
+  <input use:register={password} type="password" placeholder="Password" />
+  {#if $password.active && $password.error}<p class="error">{$password.error}</p>{/if}
 
-  - `validating`: Boolean. Is the store currently validating asynchronously?
+  <button type="submit">Register</button>
+</form>
+```
 
-  - `submitting`: Boolean. Is the store currently submitting asynchronously?
+### Server-Side Usage (Node.js/SvelteKit)
 
-  - `error`: Any. Description of the error. Usually a string, but any value different than `true` returned from a predicate function validation.
+```js
+// filepath: src/routes/api/register/+server.js
+import { json } from "@sveltejs/kit";
+import { conform } from "specma";
+import {
+  emailSpec,
+  passwordSpec,
+  usernameSpec,
+} from "$lib/shared/specs/userSpecs";
+
+const registrationSpec = {
+  email: emailSpec,
+  password: passwordSpec,
+  username: usernameSpec,
+};
 
-  - `promise`: A promise of the validation result that resolves when asynchronous validation is completed. Property is always set even if result is synchronously available to allow waiting for resolution in any case.
+export async function POST({ request }) {
+  const data = await request.json();
 
-  - `id`: Any. A pass-through of the store's creation `id`.
+  // Validate using the same specs as the client
+  const result = conform(data, registrationSpec);
 
-# `collSpecable`
+  if (!result.valid) {
+    return json(
+      {
+        success: false,
+        errors: result.problems,
+      },
+      { status: 400 }
+    );
+  }
 
-A Svelte store used to validate a collection value (array, object, Map) against a Specma spec, including its children.
+  // Proceed with registration (save to database, etc.)
+  // ...
 
-The initial value is only used to generate all initial children specable stores, but the store's value is then derived from the values of those children stores. The `set` method actually sets the values of the underlying children stores.
+  return json({ success: true });
+}
+```
 
-A `collSpecable` offers methods to modify its children specable stores : `add`, `remove`, `update`.
+### Complex Nested Specs
 
-### Spec definition
+For more complex scenarios with nested objects and arrays:
 
 ```js
-import { and, spread } from "specma";
-
-/* The spec could be shared between client and server */
-export const baseSpec = {
-  name: (v = "") => v.length > 5 || "must be longer than 5 characters",
-  list: spread({
-    x: and(
-      (v) => typeof v === "number" || "must be a number",
-      (v) => v < 100 || "must be less than 100"
-    ),
-    y: (v) => ["foo", "bar"].includes(v) || "is not an acceptable choice",
-  }),
+// filepath: shared/specs/orderSpecs.js
+import { spread } from "specma";
+
+export const orderItemSpec = {
+  name: (v) => (v && v.length > 0) || "Product name is required",
+  quantity: (v) =>
+    (typeof v === "number" && v > 0) || "Quantity must be positive",
+  price: (v) => (typeof v === "number" && v >= 0) || "Invalid price",
+};
+
+export const shippingAddressSpec = {
+  street: (v) => (v && v.length > 0) || "Street is required",
+  city: (v) => (v && v.length > 0) || "City is required",
+  zipCode: (v) => /^\d{5}$/.test(v) || "Invalid ZIP code",
+  country: (v) => (v && v.length > 0) || "Country is required",
 };
+
+export const orderSpec = {
+  customerEmail: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) || "Invalid email",
+  items: spread(orderItemSpec),
+  shippingAddress: shippingAddressSpec,
+};
+```
+
+**Client usage:**
+
+```svelte
+<script>
+  import { specable } from "svelte-specma";
+  import { orderSpec } from "$lib/shared/specs/orderSpecs";
+
+  const order = specable(
+    {
+      customerEmail: "",
+      items: [],
+      shippingAddress: { street: "", city: "", zipCode: "", country: "" }
+    },
+    {
+      spec: orderSpec,
+      getId: { items: (item) => item.id },
+      required: {
+        customerEmail: true,
+        items: spread({ name: true, quantity: true, price: true }),
+        shippingAddress: { street: true, city: true, zipCode: true, country: true }
+      }
+    }
+  );
+
+  const priceConverter = {
+    toInput: (v) => v == null ? "" : String(v),
+    toValue: (s) => s === "" ? null : Number(s)
+  };
+
+  async function handleSubmit() {
+    await order.submit();
+
+    if ($order.valid) {
+      console.log("Order submitted:", $order.value);
+      // Perform API call here
+    } else {
+      console.log("Validation errors:", $order.errors);
+    }
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <div>
+    <label for="customerEmail">Email:</label>
+    <input id="customerEmail" type="email" use:register={order.getChild(["customerEmail"])} />
+    {#if $order.errors.customerEmail}
+      <p class="error">{$order.errors.customerEmail}</p>
+    {/if}
+  </div>
+
+  <div>
+    <label>Items:</label>
+    {#each $order.children as itemStore, index}
+      {@const item = $order.value[index]}
+      <div>
+        <input
+          placeholder="Product name"
+          bind:value={item.name}
+          on:blur={() => itemStore.activate()}
+        />
+
+        <input
+          type="number"
+          placeholder="Qty"
+          bind:value={item.quantity}
+          on:blur={() => itemStore.activate()}
+        />
+
+        <input
+          type="number"
+          step="0.01"
+          placeholder="Price"
+          bind:value={item.price}
+          on:blur={() => itemStore.activate()}
+        />
+
+        <button type="button" on:click={() => order.remove([index])}>Remove</button>
+
+        {#if $order.errors[index]}
+          <p class="error">{Object.values($order.errors[index]).join(", ")}</p>
+        {/if}
+      </div>
+    {/each}
+
+    <button type="button" on:click={() => order.add([{ id: Date.now(), name: "", quantity: 1, price: 0 }])}>
+      Add Item
+    </button>
+  </div>
+
+  <div>
+    <label>Shipping Address:</label>
+    <input
+      placeholder="Street"
+      use:register={order.getChild(["shippingAddress", "street"])}
+    />
+    {#if $order.errors["shippingAddress.street"]}
+      <p class="error">{$order.errors["shippingAddress.street"]}</p>
+    {/if}
+
+    <input
+      placeholder="City"
+      use:register={order.getChild(["shippingAddress", "city"])}
+    />
+    {#if $order.errors["shippingAddress.city"]}
+      <p class="error">{$order.errors["shippingAddress.city"]}</p>
+    {/if}
+
+    <input
+      placeholder="ZIP Code"
+      use:register={order.getChild(["shippingAddress", "zipCode"])}
+    />
+    {#if $order.errors["shippingAddress.zipCode"]}
+      <p class="error">{$order.errors["shippingAddress.zipCode"]}</p>
+    {/if}
+
+    <input
+      placeholder="Country"
+      use:register={order.getChild(["shippingAddress", "country"])}
+    />
+    {#if $order.errors["shippingAddress.country"]}
+      <p class="error">{$order.errors["shippingAddress.country"]}</p>
+    {/if}
+  </div>
+
+  <button type="submit" disabled={$order.submitting}>
+    {$order.submitting ? "Submitting..." : "Submit Order"}
+  </button>
+</form>
 ```
 
-### Usage with Svelte-Specma
+**Server usage:**
 
 ```js
-import { and, spread } from "specma";
-import { baseSpec } from "/some/shared/file";
+// filepath: src/routes/api/orders/+server.js
+import { conform } from "specma";
+import { orderSpec } from "$lib/shared/specs/orderSpecs";
 
-/* Client could enhance the base spec to add further validation
- * (async in this case) */
-const enhancedSpec = and(baseSpec, {
-  name: async (v = "") => await checkNameIsUnique(v),
-});
+export async function POST({ request }) {
+  const data = await request.json();
+  const result = conform(data, orderSpec);
 
-/* Will create a `collSpecable` store, since initial value is a collection */
-const store = specable(
-  { name: "Foo", list: [{ id: "1234", x: 20, y: "abc", z: null }] },
-  {
-    spec: enhancedSpec,
-    required: { name: 1, list: spread({ x: 1 }) },
-    fields: { name: 1, list: spread({ x: 1, y: 1, z: 1 }) },
-    getId: { list: ({ id }) => id },
-    id: "myColl",
+  if (!result.valid) {
+    return json({ success: false, errors: result.problems }, { status: 400 });
   }
-);
 
-/* Store static properties and methods */
-const {
-  id,
-  isRequired,
-  spec,
-  activate,
-  add,
-  getChild,
-  remove,
-  reset,
-  set,
-  update,
-  children,
-  stores,
-  subscribe,
-} = store;
-
-/* Store subscription internal state values */
-$: ({
-  value,
-  active,
-  changed,
-  valid,
-  validating,
-  error,
-  errors,
-  collErrors,
-  promise,
-  id,
-} = $store);
+  // Process order...
+  return json({ success: true, orderId: "12345" });
+}
 ```
 
-## Inputs
+### Benefits of Shared Specs
 
-- `initialValue`: Collection. The initial value that will generate all initial specable stores.
+1. **Single Source of Truth**: Define validation rules once, use everywhere
+2. **Consistency**: Client and server always validate the same way
+3. **Maintainability**: Changes to validation rules only need to be made in one place
+4. **Type Safety**: When using TypeScript, spec definitions can be typed once
+5. **Testing**: Write tests for specs once, applicable to both environments
+6. **Composability**: Build complex specs from smaller, reusable spec functions
 
-- `spec`: Collection. The Specma spec.
-- `required`: Collection. A deeply nested collection description of the required fields. Requiredness is defined at the root store to keep specs more reusable.
-- `fields`: Collection. A deeply nested collection description of which fields to expect, that will ensure that those fields are defined as children specable stores. Undeclared field values will be treated as constant and won't be displayed as children stores.
-- `getId`: Collection. A deeply nested collection description of how a subcollection should define the `id` of its children. Can be defined the same way as a spec (with `and`, `spread`, etc.), where the predicate function of a level has the shape `(value, key) => id`. If no function is provided, array items' store will be assigned a unique random id, while objects will use their key as id.
-- `changePred`: Collection. A deeply nested collection description of change predicates (see `predCheckable` inputs). Can be defined the same way as `getId`.
-- `id`: Used to uniquely identify the store. Mainly useful for values part of a list.
+## API summary
 
-## Outputs
+- `configure(specma)`: set the Specma implementation (required).
+- `specable(initialValue, options)`: factory — returns `predSpecable` or `collSpecable`.
+- `predSpecable`: single-value store exposing: `{ subscribe, set, reset, activate, submit, id, isRequired, spec }`.
+  - status fields in subscribe payload: `value`, `active`, `changed`, `valid`, `validating`, `submitting`, `error`, `promise`, `id`.
+- `collSpecable`: collection-aware store exposing collection helpers:
+  - `add`, `remove`, `getChild`, `getChildren`, `update`, `set` (partial/complete), `reset`, `activate`, `submit`.
+  - `children`: readable store of child specable stores.
+  - subscribe payload contains aggregated status plus `errors` and flattened `errors` list.
+- `register`: Svelte action: `use:register` on input elements (or pass `[store, {toInput,toValue}]`).
 
-- `id`: Any. A pass-through of the store's creation `id`.
+## Real-world patterns
 
-- `isRequired`: Boolean. Is the store value required? Based on the `required` creation argument.
+- **Lazy validation**: create stores inactive by default and call `activate()` on blur or submit.
+- **Centralized form submit**: call `submit()` on a `collSpecable` which will activate children and run configured `onSubmit` handlers.
+- **Reuse specs between server and client**: define Specma specs once and share them in server validation and Svelte forms.
+- **Composable validation**: build complex specs from smaller, reusable spec functions.
 
-- `spec`: Any. A pass-through of the store's creation spec.
+## Tips & best practices
 
-- `activate`: Async function. `(Boolean = true) => Promise`. Method to de/activate the store validation, including all its children stores. If set to true, will immediately trigger validation and return a promise that resolves to the `valid` result property.
+- Call `configure(specma)` only once (e.g. in your app entry).
+- Use `required` and `fields` options to avoid creating child stores for unneeded fields.
+- For lists, supply `getId` so children retain identity across updates.
+- Treat `predSpecable.submit` as the place to perform side effects (server calls); it can return a Promise.
+- Use `register` for simple inputs — it reduces boilerplate for common cases.
+- **Extract specs into shared modules** for reuse across client and server.
+- **Use Specma helpers** like `spread()` for working with collections.
 
-- `add`: Function. `(coll) => store`. Method to add new children specable stores. Argument should be declared as a collection of the same type as the store's value. Returns the store for chaining.
+## Comprehensive Examples
 
-- `getChild`: Function. `(path = []) => store`. Method to retrieve a deeply nested child store from a path of keys (not ids) such as `["students", 0, "name"]`. Returns `null` if no store found.
+### Example 1: Simple Login Form with Email and Password Validation
 
-- `getChildren`: Function. `() => storesCollection`. Method to retrieve the current collection of children stores without having to subscribe to the `children` substore. Unlike the `stores` property, the return value of this method will be current each time it is called.
+This example demonstrates a basic login form with synchronous validation for email and password fields.
 
-- `remove`: Function. `(idsToRemove) => store`. Method to remove children specable stores. Will remove stores by their id. Returns the store for chaining.
+```svelte
+<!-- LoginForm.svelte -->
+<script>
+  import { specable, register } from "svelte-specma";
+
+  const email = specable("", {
+    id: "email",
+    required: true,
+    spec: (v) => {
+      const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      return emailPattern.test(v) || "Invalid email address";
+    }
+  });
+
+  const password = specable("", {
+    id: "password",
+    required: true,
+    spec: (v) => (v.length >= 8 ? true : "Password must be at least 8 characters")
+  });
+
+  function handleSubmit() {
+    email.activate();
+    password.activate();
+
+    if ($email.valid && $password.valid) {
+      console.log("Form submitted:", { email: $email.value, password: $password.value });
+    }
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <div>
+    <label for="email">Email:</label>
+    <input id="email" type="email" use:register={email} />
+    {#if $email.active && $email.error}
+      <p class="error">{$email.error}</p>
+    {/if}
+  </div>
+
+  <div>
+    <label for="password">Password:</label>
+    <input id="password" type="password" use:register={password} />
+    {#if $password.active && $password.error}
+      <p class="error">{$password.error}</p>
+    {/if}
+  </div>
+
+  <button type="submit">Login</button>
+</form>
+
+<style>
+  .error { color: red; font-size: 0.875rem; }
+</style>
+```
 
-- `set`: Function. `(coll, partial = false, shouldActivate = false) => store`. Method to recursively set the values of the collection's underlying stores. If `partial = true`, sets only the values that are not `undefined`. If `shouldActivate = true`, activates the store after setting the value. Returns the store for chaining.
+### Example 2: User Profile Form with Nested Validation
 
-- `update`: Function. `(fn) => store`. Method to modify the children specable stores collection by applying a function `(storesCollection) => storesCollection` to it that returns a modified children stores collection. It operates on the collection of children stores, NOT the underlying value. To update the value itself, use `set` with a modified `$store.value`. Useful for instance to reorder the children based on their id. Returns the store for chaining.
+This example shows a more complex form with nested object validation including cross-field validation.
 
-- `children`: Svelte readable store. A store that holds a reactive collection of the children specable stores that compose the collection. Subscribe to it to watch changes to a list of children, where some could be added, removed, reordered, etc.
+```svelte
+<!-- UserProfileForm.svelte -->
+<script>
+  import { specable, register } from "svelte-specma";
+
+  const profile = specable(
+    {
+      username: "",
+      age: null,
+      contact: {
+        email: "",
+        phone: ""
+      }
+    },
+    {
+      spec: {
+        username: (v) => (v && v.length >= 3 ? true : "Username must be at least 3 characters"),
+        age: (v) => (typeof v === "number" && v >= 18 && v <= 120 ? true : "Age must be between 18 and 120"),
+        contact: {
+          email: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) || "Invalid email",
+          phone: (v) => /^\d{10}$/.test(v) || "Phone must be 10 digits"
+        }
+      },
+      required: {
+        username: true,
+        age: true,
+        contact: { email: true }
+      }
+    }
+  );
+
+  const ageConverter = {
+    toInput: (v) => v == null ? "" : String(v),
+    toValue: (s) => s === "" ? null : Number(s)
+  };
+
+  async function handleSubmit() {
+    await profile.submit();
+
+    if ($profile.valid) {
+      console.log("Profile submitted:", $profile.value);
+      // Perform API call here
+    } else {
+      console.log("Validation errors:", $profile.errors);
+    }
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <div>
+    <label for="username">Username:</label>
+    <input id="username" use:register={profile.getChild(["username"])} />
+    {#if $profile.errors.username}
+      <p class="error">{$profile.errors.username}</p>
+    {/if}
+  </div>
+
+  <div>
+    <label for="age">Age:</label>
+    <input id="age" type="number" use:register={[profile.getChild(["age"]), ageConverter]} />
+    {#if $profile.errors.age}
+      <p class="error">{$profile.errors.age}</p>
+    {/if}
+  </div>
+
+  <div>
+    <label for="email">Email:</label>
+    <input id="email" type="email" use:register={profile.getChild(["contact", "email"])} />
+    {#if $profile.errors["contact.email"]}
+      <p class="error">{$profile.errors["contact.email"]}</p>
+    {/if}
+  </div>
+
+  <div>
+    <label for="phone">Phone (optional):</label>
+    <input id="phone" type="tel" use:register={profile.getChild(["contact", "phone"])} />
+    {#if $profile.errors["contact.phone"]}
+      <p class="error">{$profile.errors["contact.phone"]}</p>
+    {/if}
+  </div>
+
+  <button type="submit" disabled={$profile.submitting}>
+    {$profile.submitting ? "Submitting..." : "Save Profile"}
+  </button>
+</form>
+```
 
-- `stores`: Collection. Same as `children`, but non-reactive. Useful to destructure children stores that won't change over time, such as the fixed fields in a flat form, without having to subscribe first.
+### Example 3: Dynamic List Management (Shopping Cart)
 
-- `submit`: Function. `(value) => {}`. Method to first activate then handle the current value. `submitting` state is set to `true` during submit.
+This example demonstrates managing a dynamic list with add/remove operations and per-item validation.
 
-- `subscribe`: Function. Same as `predSpecable`, but with added state properties, listed below.
+```svelte
+<!-- ShoppingCart.svelte -->
+<script>
+  import { specable } from "svelte-specma";
+  import { spread } from "specma";
+
+  const itemSpec = {
+    name: (v) => (v && v.length > 0 ? true : "Product name is required"),
+    quantity: (v) => (typeof v === "number" && v > 0 ? true : "Quantity must be positive"),
+    price: (v) => (typeof v === "number" && v >= 0 ? true : "Invalid price")
+  };
+
+  const cart = specable(
+    [],
+    {
+      spec: spread(itemSpec),
+      getId: (item) => item.id,
+      required: spread({ name: true, quantity: true, price: true })
+    }
+  );
+
+  let nextId = 1;
+
+  function addItem() {
+    cart.add([{
+      id: String(nextId++),
+      name: "",
+      quantity: 1,
+      price: 0
+    }]);
+  }
 
-  - `error`: Any. The collection's own predicate spec error result.
+  function removeItem(id) {
+    const index = $cart.value.findIndex(item => item.id === id);
+    if (index !== -1) {
+      cart.remove([index]);
+    }
+  }
 
-  - `errors`: Array. Array of `[{ error, path, which, isColl }]` containing all error descriptions. Useful to display all errors in a centralized location on a form, for instance.
+  function calculateTotal() {
+    return $cart.value.reduce((sum, item) => sum + (item.quantity || 0) * (item.price || 0), 0);
+  }
 
-    - `error`: Any. Description of the error.
-    - `path`: Array. List of the complete path from root to error node.
-    - `which`: String. Same as `path`, but joined with dots to form a string. Useful to lookup predefined captions in a dictionnary.
-    - `isColl`: Boolean. Indicates if the error is on a collection value.
+  async function checkout() {
+    await cart.submit();
 
-  - `collErrors`: Array. Same as `errors`, but containing only the errors with the `isColl` flag. Useful to display collection errors in a central location, while primitive field errors are displayed near their input in a form, for instance.
+    if ($cart.valid) {
+      console.log("Checkout:", $cart.value);
+      console.log("Total:", calculateTotal());
+      // Perform checkout API call
+    }
+  }
+</script>
+
+<div>
+  <h2>Shopping Cart</h2>
+
+  {#each $cart.children as itemStore, index}
+    {@const item = $cart.value[index]}
+    <div class="cart-item">
+      <input
+        placeholder="Product name"
+        bind:value={item.name}
+        on:blur={() => itemStore.activate()}
+      />
+
+      <input
+        type="number"
+        placeholder="Qty"
+        bind:value={item.quantity}
+        on:blur={() => itemStore.activate()}
+      />
+
+      <input
+        type="number"
+        step="0.01"
+        placeholder="Price"
+        bind:value={item.price}
+        on:blur={() => itemStore.activate()}
+      />
+
+      <button type="button" on:click={() => removeItem(item.id)}>Remove</button>
+
+      {#if $cart.errors[index]}
+        <p class="error">{Object.values($cart.errors[index]).join(", ")}</p>
+      {/if}
+    </div>
+  {/each}
+
+  <button type="button" on:click={addItem}>Add Item</button>
+
+  {#if $cart.value.length > 0}
+    <div class="total">
+      <strong>Total: ${calculateTotal().toFixed(2)}</strong>
+    </div>
+    <button on:click={checkout} disabled={$cart.submitting}>
+      {$cart.submitting ? "Processing..." : "Checkout"}
+    </button>
+  {/if}
+</div>
+
+<style>
+  .cart-item { display: flex; gap: 0.5rem; margin-bottom: 0.5rem; }
+  .error { color: red; font-size: 0.875rem; }
+  .total { margin-top: 1rem; font-size: 1.25rem; }
+</style>
+```
 
-# `register`
+### Example 4: Async Validation (Username Availability Check)
 
-The `register` function facilitates usage of the [`predSpecable`](#predSpecable) store in conjunction to a form input. It is designed to be used with the `use:register` directive:
+This example shows how to use asynchronous validation to check if a username is available.
 
 ```svelte
-<input use:register="{predSpecableStore}" />
+<!-- UsernameCheckForm.svelte -->
+<script>
+  import { specable, register } from "svelte-specma";
+
+  const username = specable("", {
+    id: "username",
+    required: true,
+    spec: (v) => (v.length >= 3 ? true : "Username must be at least 3 characters")
+  });
+
+  let checking = false;
+  let available = false;
+
+  async function checkAvailability() {
+    checking = true;
+    available = false;
+
+    // Simulate an API call to check username availability
+    const isAvailable = await new Promise((resolve) => {
+      setTimeout(() => {
+        resolve(Math.random() > 0.5);
+      }, 1000);
+    });
+
+    checking = false;
+    available = isAvailable;
+
+    if (!isAvailable) {
+      username.setError("Username is already taken");
+    } else {
+      username.clearError();
+    }
+  }
+
+  function handleSubmit() {
+    username.activate();
+
+    if ($username.valid && available) {
+      console.log("Form submitted:", { username: $username.value });
+    }
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <div>
+    <label for="username">Username:</label>
+    <input id="username" use:register={username} />
+    {#if $username.active && $username.error}
+      <p class="error">{$username.error}</p>
+    {/if}
+    <button type="button" on:click={checkAvailability} disabled={checking}>
+      {#if checking}Checking...{#else}Check Availability{/if}
+    </button>
+    {#if available}
+      <p class="available">Username is available!</p>
+    {:else if $username.active && !$username.valid}
+      <p class="error">Username must be at least 3 characters</p>
+    {/if}
+  </div>
+
+  <button type="submit">Submit</button>
+</form>
+
+<style>
+  .error { color: red; font-size: 0.875rem; }
+  .available { color: green; font-size: 0.875rem; }
+</style>
 ```
 
-Doing so will:
+### Example 5: Shared Validation (Full Stack)
 
-- update the store's value on input;
-- update the input on store value change;
-- activate the store on input blur;
-- remove all listeners and subscriptions when input is unmounted.
+This example demonstrates the full power of reusable specs across client and server.
 
-If the expected value's type is not the same as the HTML input's one (if validation expects an number or a JS Date instance, for example), `use:register` can be used with a list of arguments where the second one is an object with keys `{ toInput, toValue }`:
+**Shared specs:**
 
-- `toInput`: Function. `(value) => htmlInputValue`;
-- `toValue`: Function. `(htmlInputValue) => value`;
+```js
+// filepath: lib/shared/specs/productSpecs.js
+import { spread } from "specma";
+
+export const productNameSpec = (v) =>
+  v && v.length >= 3 && v.length <= 100
+    ? true
+    : "Product name must be 3-100 characters";
+
+export const productPriceSpec = (v) =>
+  typeof v === "number" && v >= 0 && v <= 1000000
+    ? true
+    : "Price must be between 0 and 1,000,000";
+
+export const productDescriptionSpec = (v) =>
+  v && v.length >= 10 && v.length <= 500
+    ? true
+    : "Description must be 10-500 characters";
+
+export const productCategorySpec = (v) =>
+  ["electronics", "clothing", "food", "books", "other"].includes(v)
+    ? true
+    : "Invalid category";
+
+export const productSpec = {
+  name: productNameSpec,
+  price: productPriceSpec,
+  description: productDescriptionSpec,
+  category: productCategorySpec,
+};
 
-For example, if the expected value is a number, it could be used like so:
+export const productRequired = {
+  name: true,
+  price: true,
+  description: true,
+  category: true,
+};
+```
+
+**Client-side form:**
 
 ```svelte
-<input
-  use:register="{[predSpecableStore, { toValue: (x) => x && +x }]}"
-/>
+<!-- filepath: src/routes/products/new/+page.svelte -->
+<script>
+  import { specable, register } from "svelte-specma";
+  import { productSpec, productRequired } from "$lib/shared/specs/productSpecs";
+
+  const product = specable(
+    { name: "", price: null, description: "", category: "" },
+    { spec: productSpec, required: productRequired }
+  );
+
+  const priceConverter = {
+    toInput: (v) => v == null ? "" : String(v),
+    toValue: (s) => s === "" ? null : Number(s)
+  };
+
+  async function handleSubmit() {
+    await product.submit();
+
+    if ($product.valid) {
+      const response = await fetch("/api/products", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify($product.value)
+      });
+
+      if (response.ok) {
+        alert("Product created successfully!");
+      } else {
+        const error = await response.json();
+        alert(`Server error: ${JSON.stringify(error.errors)}`);
+      }
+    }
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <input use:register={product.getChild(["name"])} placeholder="Product name" />
+  {#if $product.errors.name}<p class="error">{$product.errors.name}</p>{/if}
+
+  <input use:register={[product.getChild(["price"]), priceConverter]}
+         type="number" step="0.01" placeholder="Price" />
+  {#if $product.errors.price}<p class="error">{$product.errors.price}</p>{/if}
+
+  <textarea use:register={product.getChild(["description"])}
+            placeholder="Description"></textarea>
+  {#if $product.errors.description}<p class="error">{$product.errors.description}</p>{/if}
+
+  <select use:register={product.getChild(["category"])}>
+    <option value="">Select category</option>
+    <option value="electronics">Electronics</option>
+    <option value="clothing">Clothing</option>
+    <option value="food">Food</option>
+    <option value="books">Books</option>
+    <option value="other">Other</option>
+  </select>
+  {#if $product.errors.category}<p class="error">{$product.errors.category}</p>{/if}
+
+  <button type="submit" disabled={$product.submitting}>
+    {$product.submitting ? "Creating..." : "Create Product"}
+  </button>
+</form>
 ```
 
-In any other case, the store should be used explicitely:
+**Server-side validation:**
 
-```svelte
-<input
-  value={$age.value}
-  on:input={(e) => age.set(+e.target.value)}
-  on:blur={() => age.activate()}
-/>
+```js
+// filepath: src/routes/api/products/+server.js
+import { json } from "@sveltejs/kit";
+import { conform } from "specma";
+import { productSpec } from "$lib/shared/specs/productSpecs";
+
+export async function POST({ request }) {
+  const data = await request.json();
+
+  // Validate using the exact same specs as the client
+  const result = conform(data, productSpec);
+
+  if (!result.valid) {
+    return json(
+      {
+        success: false,
+        errors: result.problems,
+      },
+      { status: 400 }
+    );
+  }
+
+  // Save to database
+  // const productId = await db.products.create(result.value);
+
+  return json({
+    success: true,
+    productId: "mock-id-12345",
+  });
+}
 ```
+
+This example demonstrates:
+
+- **Spec extraction** into a shared module
+- **Client-side** reactive validation with Svelte stores
+- **Server-side** validation using the same specs
+- **Consistent validation** across the full stack
+- **Type safety** and maintainability improvements