cogsbox-state 0.5.7 → 0.5.9

package/README.md

@@ -1,386 +1,628 @@
-# Cobgsbox State
+# Cogsbox State: A Practical Guide
 
-> ⚠️ **Warning**: This package is currently a work in progress and not ready for production use. The API is unstable and subject to breaking changes. Please do not use in production environments.
+> **⚠️ WARNING**: This README is AI-generated based on the current implementation of Cogsbox State. The library is under active development and APIs are subject to change. Always refer to the official documentation or source code for the most up-to-date information.
 
----
+## Getting Started
 
-Cobgsbox State is a state management library that provides a fluent interface for managing complex state in React applications.
+Cogsbox State is a React state management library that provides a fluent interface for managing complex state.
 
-## Installation
+### Basic Setup
 
-```bash
-npm install cogsbox-state
-```
-
-## Features
-
-- 🎯 **Simplified Deep Updates**
-
-    ```typescript
-    // Instead of setState(prev => ({ ...prev, deep: { ...prev.deep, value: newValue }}))
-    updater.deep.value.update(newValue);
-    ```
-
-- 🔄 **Fluent Array Operations**
-
-    ```typescript
-    // Find, filter, and update in one chain
-    updater.items.findWith("id", "123").status.update("complete");
-    ```
-
-- 📝 **Smart Form Handling**
-
-    - Automatic debouncing
-    - Validation integration
-    - Form state synchronization
-
-- 🔍 **Powerful Array Methods**
+```typescript
+// 1. Define your initial state
+const InitialState = {
+  users: [],
+  settings: {
+    darkMode: false,
+    notifications: true
+  },
+  cart: {
+    items: [],
+    total: 0
+  }
+};
 
-    - Filter with state access
-    - Flatten nested arrays
-    - Unique insertions
-    - Map with updaters
+// 2. Create the state hook
+export const { useCogsState } = createCogsState(InitialState);
 
-- 🔄 **State Sync Features**
+// 3. Use in your component
+function MyComponent() {
+  const cart = useCogsState("cart");
 
-    - Server synchronization
-    - Local storage persistence
-    - Optimistic updates
+  // Access values
+  const cartItems = cart.items.get();
+  const total = cart.total.get();
 
-- 🛠 **Developer Experience**
+  // Update values
+  const addItem = (item) => {
+    cart.items.insert(item);
+    cart.total.update(total + item.price);
+  };
 
-    - Full TypeScript support
-    - Path autocompletion
-    - Runtime type checking
+  return (
+    // Your component JSX
+  );
+}
+```
 
-- ⚡ **Performance**
-    - Granular updates
-    - Automatic optimization
-    - Path-based subscriptions
+## Core Concepts
 
-## Initialization
+### Accessing State
 
 ```typescript
-// Define your state shape
-interface Product {
-    id: string;
-    name: string;
-    price: number;
-    categories: string[];
-    variants: {
-        id: string;
-        color: string;
-        size: string;
-        stock: number;
-    }[];
-}
-
-interface CartItem {
-    productId: string;
-    variantId: string;
-    quantity: number;
-}
-
-const InitialState = {
-    catalog: {
-        products: [] as Product[],
-        categories: [] as string[],
-        filters: {
-            priceRange: { min: 0, max: 100 },
-            selectedCategories: [] as string[],
-            search: "",
-        },
-        sortBy: "price_asc" as "price_asc" | "price_desc" | "name",
-    },
-    cart: {
-        items: [] as CartItem[],
-        couponCode: "",
-        shipping: {
-            address: "",
-            method: "standard" as "standard" | "express",
-            cost: 0,
-        },
-    },
-    ui: {
-        sidebarOpen: false,
-        activeProductId: null as string | null,
-        notifications: [] as {
-            id: string;
-            message: string;
-            type: "success" | "error";
-        }[],
-    },
-};
+// Get the entire state object
+const entireCart = cart.get();
 
-// Create state hook
-export const { useCogsState } = createCogsState(InitialState);
+// Access a specific property
+const cartItems = cart.items.get();
 
-// Use in component
-const [state, updater] = useCogsState("catalog");
+// Access nested properties
+const firstItemPrice = cart.items.index(0).price.get();
 ```
 
-## Updater API
-
-### Basic Updates
-
-#### `.update()`
-
-Updates state value directly.
+### Updating State
 
 ```typescript
 // Direct update
-updater.catalog.filters.search.update("blue shoes");
+cart.settings.darkMode.update(true);
 
-// Functional update
-updater.cart.items[0].quantity.update((prev) => prev + 1);
+// Functional update (based on previous value)
+cart.cart.total.update((prev) => prev + 10);
 
 // Deep update
-updater.catalog.products
-    .findWith("id", "123")
-    .variants[0].stock.update((prev) => prev - 1);
+cart.users.findWith("id", "123").name.update("New Name");
 ```
 
-#### `.get()`
+## Working with Arrays
 
-Gets current state value.
+### Basic Array Operations
 
 ```typescript
-const searchTerm = updater.catalog.filters.search.get();
-const cartTotal = updater.cart.items
-    .get()
-    .reduce((sum, item) => sum + item.quantity, 0);
-```
+// Add an item
+cart.cart.items.insert({ id: "prod1", name: "Product 1", price: 29.99 });
+
+// Remove an item at index
+cart.cart.items.cut(2);
 
-### Array Operations
+// Find and update an item
+cart.cart.items.findWith("id", "prod1").quantity.update((prev) => prev + 1);
 
-#### `.insert()`
+// Update item at specific index
+cart.cart.items.index(0).price.update(19.99);
+```
 
-Inserts an item into an array.
+### Advanced Array Methods
 
 ```typescript
-// Add product
-updater.catalog.products.insert({
-    id: "123",
-    name: "Running Shoes",
-    price: 99.99,
-    categories: ["shoes", "sports"],
-    variants: [],
-});
+// Map with access to updaters
+cart.cart.items.stateMap((item, itemUpdater) => (
+  <CartItem
+    key={item.id}
+    item={item}
+    onQuantityChange={qty => itemUpdater.quantity.update(qty)}
+  />
+));
+
+// Filter items while maintaining updater capabilities
+const inStockItems = cart.products.stateFilter(product => product.stock > 0);
+
+// Insert only if the item doesn't exist
+cart.cart.items.uniqueInsert(
+  { id: "prod1", quantity: 1 },
+  ["id"] // fields to check for uniqueness
+);
 
-// Add to cart
-updater.cart.items.insert((prev) => ({
-    productId: "123",
-    variantId: "v1",
-    quantity: 1,
-}));
+// Flatten nested arrays by property
+const allVariants = cart.products.stateFlattenOn("variants");
 ```
 
-#### `.uniqueInsert()`
+## Reactivity Control
+
+Cogsbox offers different ways to control when components re-render:
 
-Inserts only if item doesn't exist (checks deep equality).
+### Component Reactivity (Default)
+
+Re-renders when any accessed value changes.
 
 ```typescript
-// Add category if not exists
-updater.catalog.categories.uniqueInsert("sports");
-
-// Add notification with unique ID
-updater.ui.notifications.uniqueInsert(
-    {
-        id: generateId(),
-        message: "Item added to cart",
-        type: "success",
-    },
-    ["id"],
+// Default behavior - re-renders when cart.items or cart.total changes
+const cart = useCogsState("cart");
+
+return (
+  <div>
+    <div>Items: {cart.items.get().length}</div>
+    <div>Total: {cart.total.get()}</div>
+  </div>
 );
 ```
 
-#### `.cut()`
+### Dependency-Based Reactivity
 
-Removes an item from an array.
+Re-renders only when specified dependencies change.
 
 ```typescript
-// Remove from cart
-updater.cart.items.cut(index);
-
-// Remove notification
-updater.ui.notifications.findWith("id", "notif-123").cut();
+// Only re-renders when items array or status changes
+const cart = useCogsState("cart", {
+  reactiveType: ["deps"],
+  reactiveDeps: (state) => [state.items, state.status],
+});
 ```
 
-#### `.findWith()`
+### Full Reactivity
 
-Finds an item in array by property comparison.
+Re-renders on any state change, even for unused properties.
 
 ```typescript
-// Find and update product
-updater.catalog.products.findWith("id", 123).price.update(99.99);
-
-// Find and update cart item
-updater.cart.items
-    .findWith("productId", 123)
-    .quantity.update((prev) => prev + 1);
+// Re-renders on any change to cart state
+const cart = useCogsState("cart", {
+  reactiveType: ["all"],
+});
 ```
 
-#### `.index()`
+### Signal-Based Reactivity
 
-Gets item at specific index with updater methods.
+Updates only the DOM elements that depend on changed values.
 
 ```typescript
-// Update first cart item
-updater.cart.items.index(0).quantity.update(2);
+// Most efficient - updates just the specific DOM elements
+return (
+  <div>
+    <div>Items: {cart.items.$derive(items => items.length)}</div>
+    <div>Total: {cart.total.$get()}</div>
+  </div>
+);
 ```
 
-#### `.stateEach()`
+## Form Integration
+
+Cogsbox State provides an intuitive form system to connect your state to form controls with built-in validation, error handling, and array support.
 
-Maps over array with access to item updater.
+### Basic Form Element Usage
+
+The `formElement` method serves as the bridge between state and UI:
 
 ```typescript
-// Apply discount to all products
-updater.catalog.products.stateEach((product, productUpdater) => {
-    productUpdater.price.update((price) => price * 0.9);
-});
+// Direct value/onChange pattern for complete control
+user.firstName.formElement((params) => (
+  <div>
+    <label className="block text-sm font-medium">First Name</label>
+    <input
+      type="text"
+      className="mt-1 block w-full rounded-md border-2 p-2"
+      value={params.get()}
+      onChange={(e) => params.set(e.target.value)}
+      onBlur={params.inputProps.onBlur}
+      ref={params.inputProps.ref}
+    />
+  </div>
+));
+
+// Using inputProps shorthand for simpler binding
+user.lastName.formElement((params) => (
+  <div>
+    <label className="block text-sm font-medium">Last Name</label>
+    <input
+      type="text"
+      className="mt-1 block w-full rounded-md border-2 p-2"
+      {...params.inputProps}
+    />
+  </div>
+));
 ```
 
-#### `.stateFilter()`
+### Form Validation Options
 
-Creates filtered view of array with updater methods.
+Cogsbox provides several approaches to validation:
 
 ```typescript
-// Get low stock variants
-const lowStock = updater.catalog.products.stateFilter((product) =>
-    product.variants.some((v) => v.stock < 5),
+// Custom validation message
+user.email.formElement(
+  (params) => (
+    <div>
+      <label>Email Address</label>
+      <input {...params.inputProps} type="email" />
+    </div>
+  ),
+  {
+    validation: {
+      message: "Please enter a valid email address"
+    }
+  }
 );
 
-// Update prices for filtered products
-lowStock.stateEach((product, productUpdater) => {
-    productUpdater.price.update((price) => price * 0.8);
-});
+// Hidden validation (show border but no message)
+user.lastName.formElement(
+  (params) => (
+    <div>
+      <label>Last Name</label>
+      <input
+        {...params.inputProps}
+        className={`input ${params.validationErrors().length > 0 ? 'border-red-500' : ''}`}
+      />
+    </div>
+  ),
+  {
+    validation: {
+      hideMessage: true
+    }
+  }
+);
+
+// Custom validation with onBlur
+user.phone.formElement((params) => (
+  <div>
+    <label>Phone Number</label>
+    <input
+      {...params.inputProps}
+      onBlur={(e) => {
+        if (e.target.value.length == 0 || isNaN(Number(e.target.value))) {
+          params.addValidationError("Please enter a valid phone number");
+        }
+      }}
+      placeholder="(555) 123-4567"
+    />
+  </div>
+));
 ```
 
-#### `.stateFlattenOn()`
+### Working with Form Arrays
 
-Flattens nested arrays by property.
+For managing collections like addresses:
 
 ```typescript
-// Get all variants across products
-const allVariants = updater.catalog.products.stateFlattenOn("variants");
-```
+function AddressesManager() {
+  const [currentAddressIndex, setCurrentAddressIndex] = useState(0);
+  const user = useCogsState("user");
+
+  // Add new address
+  const addNewAddress = () => {
+    user.addresses.insert({
+      street: "",
+      city: "",
+      state: "",
+      zipCode: "",
+      country: "USA",
+      isDefault: false,
+    });
+    setCurrentAddressIndex(user.addresses.get().length - 1);
+  };
 
-### Form Integration
+  return (
+    <div>
+      {/* Address tabs with validation indicators */}
+      <div className="flex space-x-2 mt-2">
+        {user.addresses.stateMap((_, setter, index) => {
+          const errorCount = setter.showValidationErrors().length;
+          return (
+            <button
+              key={index}
+              onClick={() => setCurrentAddressIndex(index)}
+              className={`rounded-lg flex items-center justify-center ${
+                errorCount > 0
+                  ? "border-red-500 bg-red-400"
+                  : currentAddressIndex === index
+                  ? "bg-blue-500 text-white"
+                  : "bg-gray-200"
+              }`}
+            >
+              {index + 1}
+              {errorCount > 0 && (
+                <div className="bg-red-500 text-white rounded-full">
+                  {errorCount}
+                </div>
+              )}
+            </button>
+          );
+        })}
+        <button onClick={addNewAddress}>Add</button>
+      </div>
+
+      {/* Current address form */}
+      {user.addresses.get().length > 0 && (
+        <div className="grid grid-cols-1 gap-4">
+          {/* Access fields with index() method */}
+          {user.addresses.index(currentAddressIndex).street.formElement(
+            (params) => (
+              <div>
+                <label>Street</label>
+                <input value={params.get()} onChange={(e) => params.set(e.target.value)} />
+              </div>
+            ),
+            {
+              validation: {
+                message: "Street address is required"
+              }
+            }
+          )}
+
+          {/* City and State in a row */}
+          <div className="grid grid-cols-2 gap-4">
+            {user.addresses.index(currentAddressIndex).city.formElement((params) => (
+              <div>
+                <label>City</label>
+                <input {...params.inputProps} />
+              </div>
+            ))}
+
+            {user.addresses.index(currentAddressIndex).state.formElement((params) => (
+              <div>
+                <label>State</label>
+                <input {...params.inputProps} />
+              </div>
+            ))}
+          </div>
+
+          {/* Boolean field handling */}
+          {user.addresses.index(currentAddressIndex).isDefault.formElement((params) => (
+            <div className="flex items-center">
+              <input
+                type="checkbox"
+                checked={params.get()}
+                onChange={(e) => params.set(e.target.checked)}
+                id={`default-address-${currentAddressIndex}`}
+              />
+              <label htmlFor={`default-address-${currentAddressIndex}`}>
+                Set as default address
+              </label>
+            </div>
+          ))}
+
+          {/* Remove address button */}
+          {user.addresses.get().length > 1 && (
+            <button
+              onClick={() => {
+                user.addresses.cut(currentAddressIndex);
+                setCurrentAddressIndex(Math.max(0, currentAddressIndex - 1));
+              }}
+            >
+              Remove Selected Address
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+```
 
-#### `.formElement()`
+### Form Actions
 
-Creates form control with validation.
+Cogsbox provides methods to manage form state:
 
 ```typescript
-updater.cart.shipping.address.formElement("shipping", ({ inputProps }) => (
-  <input {...inputProps} placeholder="Shipping address" />
-), {
-  validation: {
-    message: "Address is required",
-    onChange: { clear: ["shipping.address"] }
-  },
-  debounceTime: 300
-})
+// Reset form to initial state
+const handleReset = () => {
+  user.revertToInitialState();
+};
+
+// Validate all fields using Zod schema
+const handleSubmit = () => {
+  if (user.validateZodSchema()) {
+    // All valid, proceed with submission
+    submitData(user.get());
+  }
+};
 ```
 
-### Menu & Selection API
+### Setting Up Zod Validation
 
-#### `.setSelected()`
+```typescript
+// Setting up validation at initialization
+export const { useCogsState } = createCogsState({
+  user: {
+    initialState: {
+      firstName: "",
+      lastName: "",
+      email: "",
+      phone: "",
+      addresses: [
+        {
+          street: "",
+          city: "",
+          state: "",
+          zipCode: "",
+          country: "USA",
+          isDefault: false,
+        },
+      ],
+    },
+    validation: {
+      key: "userForm", // Used for error tracking
+      zodSchema: z.object({
+        firstName: z.string().min(1, "First name is required"),
+        lastName: z.string().min(1, "Last name is required"),
+        email: z.string().email("Please enter a valid email"),
+        phone: z.string().min(10, "Phone number must be at least 10 digits"),
+        addresses: z.array(
+          z.object({
+            street: z.string().min(1, "Street is required"),
+            city: z.string().min(1, "City is required"),
+            state: z.string().min(1, "State is required"),
+            zipCode: z
+              .string()
+              .min(5, "Zip code must be at least 5 characters"),
+            country: z.string(),
+            isDefault: z.boolean(),
+          })
+        ),
+      }),
+    },
+  },
+});
+```
 
-Marks an item as selected in a list.
+## Server Synchronization
 
 ```typescript
-// Select product
-updater.catalog.products[0].setSelected(true);
+// Setting up server sync
+const products = useCogsState("products", {
+  serverSync: {
+    syncKey: "products",
+    syncFunction: ({ state }) => api.updateProducts(state),
+    debounce: 1000, // ms
+    mutation: useMutation(api.updateProducts),
+  },
+});
 
-// Select category
-updater.catalog.categories.findWith("name", "sports").setSelected(true);
+// State is automatically synced with server after changes
+products.items.index(0).stock.update((prev) => prev - 1);
 ```
 
-#### `.getSelected()`
-
-Gets currently selected item from a list.
+## Local Storage Persistence
 
 ```typescript
-const selectedProduct = updater.catalog.products.getSelected();
+// Automatically save state to localStorage
+const cart = useCogsState("cart", {
+  localStorage: {
+    key: "shopping-cart",
+  },
+});
 ```
 
-[Rest of documentation remains the same...]
-
-## Examples
-
-### Product Catalog Management
+## Example: Shopping Cart
 
 ```typescript
-function ProductList() {
-  const [state, updater] = useCogsState("catalog", {
-    serverSync: {
-      syncKey: "products",
-      syncFunction: async ({ state }) => {
-        await api.updateProducts(state.products)
-      }
-    }
-  });
-
-  const filteredProducts = updater.products
-    .stateFilter(product =>
-      product.price >= state.filters.priceRange.min &&
-      product.price <= state.filters.priceRange.max &&
-      (state.filters.selectedCategories.length === 0 ||
-        product.categories.some(c => state.filters.selectedCategories.includes(c)))
+function ShoppingCart() {
+  const cart = useCogsState("cart");
+  const products = useCogsState("products");
+
+  const addToCart = (productId) => {
+    const product = products.items.findWith("id", productId).get();
+
+    cart.items.uniqueInsert(
+      {
+        productId,
+        name: product.name,
+        price: product.price,
+        quantity: 1
+      },
+      ["productId"],
+      // If product exists, update quantity instead
+      (existingItem) => ({
+        ...existingItem,
+        quantity: existingItem.quantity + 1
+      })
     );
 
+    // Update total
+    cart.total.update(prev => prev + product.price);
+  };
+
   return (
     <div>
-      {filteredProducts.stateEach((product, productUpdater) => (
-        <ProductCard
-          key={product.id}
-          product={product}
-          onUpdateStock={(variantId, newStock) =>
-            productUpdater
-              .variants
-              .findWith("id", variantId)
-              .stock
-              .update(newStock)
-          }
-        />
+      <h2>Your Cart</h2>
+
+      {cart.items.stateMap((item, itemUpdater) => (
+        <div key={item.productId} className="cart-item">
+          <div>{item.name}</div>
+          <div>${item.price}</div>
+
+          <div className="quantity">
+            <button onClick={() =>
+              itemUpdater.quantity.update(prev => Math.max(prev - 1, 0))
+            }>-</button>
+
+            <span>{item.quantity}</span>
+
+            <button onClick={() =>
+              itemUpdater.quantity.update(prev => prev + 1)
+            }>+</button>
+          </div>
+
+          <button onClick={() => itemUpdater.cut()}>Remove</button>
+        </div>
       ))}
+
+      <div className="cart-total">
+        <strong>Total:</strong> ${cart.total.get()}
+      </div>
     </div>
   );
 }
 ```
 
-### Shopping Cart Management
+## Session Support
 
-```typescript
-function CartManager() {
-  const [state, updater] = useCogsState("cart", {
-    localStorage: {
-      key: "shopping-cart"
-    }
-  });
-
-  const addToCart = (product: Product, variantId: string) => {
-    updater.items.uniqueInsert({
-      productId: product.id,
-      variantId,
-      quantity: 1
-    }, ['productId', 'variantId']);
-  };
+Cogsbox State supports session-based state management through the `useCogsConfig` hook, allowing you to isolate state for different user sessions:
 
-  return (
-    <div>
-      {updater.items.stateEach((item, itemUpdater) => (
-        <CartItem
-          key={item.productId}
-          item={item}
-          onUpdateQuantity={qty => itemUpdater.quantity.update(qty)}
-          onRemove={() => itemUpdater.cut()}
-        />
-      ))}
-    </div>
-  );
-}
+```typescript
+// Using session-specific state
+const cart = useCogsState("cart", {
+  localStorageKey: "user-cart", // Will be prefixed with sessionId
+  initState: {
+    initialState: {
+      items: [],
+      total: 0,
+    },
+  },
+});
 ```
 
-[Rest of TypeScript section remains the same...]
+## Performance Optimizations
+
+The library includes several performance optimizations:
+
+1. **Cache Management**: Cogsbox maintains a cache of proxy objects to reduce re-creation overhead.
+2. **Batched Updates**: State updates are batched where possible to minimize render cycles.
+3. **Signal-based DOM Updates**: Directly update DOM elements without re-rendering components.
+
+## Common Patterns and Tips
+
+1. **Path-based Updates**: Always use the fluent API to update nested properties.
+
+   ```typescript
+   // Good
+   user.users.index(0).address.city.update("New York");
+
+   // Avoid
+   user.update({ ...state, users: [...] });
+   ```
+
+2. **Working with Arrays**: Use the built-in array methods instead of manually updating array state.
+
+   ```typescript
+   // Good
+   user.users.insert(newUser);
+   user.users.findWith("id", 123).active.update(true);
+
+   // Avoid
+   user.users.update([...users, newUser]);
+   ```
+
+3. **Optimization**: Use the appropriate reactivity type for your needs.
+
+   ```typescript
+   // For lists where only specific items change frequently
+   user.items.stateMap((item) => (
+     <div>{item.$get()}</div>  // Only this item re-renders when changed
+   ));
+   ```
+
+4. **Form Management**: Use formElement for all form inputs to get automatic validation and debouncing.
+
+   ```typescript
+   profile.name.formElement(
+     ({ inputProps }) => <input {...inputProps} />,
+     { debounceTime: 300 }
+   );
+   ```
+
+5. **Middleware Support**: Add middleware for logging, analytics, or custom state processing:
+
+   ```typescript
+   const user = useCogsState("user", {
+     middleware: ({ update, updateLog }) => {
+       // Log all state changes
+       console.log("State update:", update);
+
+       // Trigger analytics
+       if (update.path.includes("preferences")) {
+         analytics.track("preferences_changed", update.newValue);
+       }
+     },
+   });
+   ```
+
+## API Reference
+
+For a comprehensive API reference, see the TypeScript interfaces and examples in the source code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogsbox-state",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "React state management library with form controls and server sync",
   "type": "module",
   "main": "./dist/index.js",