@hf-chimera/react 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hewston Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,241 +1,241 @@
-# ChimeraEntityStore React Integration
-
-This package provides React hooks for seamless integration with ChimeraEntityStore, enabling reactive data management in React applications.
-
-## Features
-
-- **React Hooks**: Custom hooks for managing ChimeraEntityStore queries
-- **TypeScript Support**: Full type safety with TypeScript
-- **Automatic State Management**: Automatic re-rendering when data changes
-
-## Installation
-
-```bash
-# Install both the core store and React adapter
-npm install @hf-chimera/store @hf-chimera/react
-
-# React is a peer dependency
-npm install react
-
-# Or install all at once
-npm install @hf-chimera/store @hf-chimera/react react
-```
-
-## Usage
-
-### For React Applications
-
-Import from the React-specific entry point:
-
-```tsx
-import { createChimeraHooks } from "@hf-chimera/store/react";
-// In your app, call createChimeraHooks(store) and export the returned hooks
-```
-
-### For Non-React Applications
-
-Import from the main package:
-
-```ts
-import { createChimeraEntityStore } from "@hf-chimera/store";
-import { createChimeraStoreHooks } from "@hf-chimera/react";
-```
-
-## Quick Start
-
-### 1. Prepare hooks for the store
-
-Use the `createChimeraStoreHooks` function to create hooks for your entity store:
-
-```ts
-import { createChimeraStoreHooks } from "@hf-chimera/react";
-import { createChimeraEntityStore } from "@hf-chimera/store";
-
-// Define your entity type
-type Customer = {
-  id: number;
-  name: string;
-  email: string;
-};
-
-// Create your entity store instance
-const customerStore = createChimeraEntityStore<"customer", Customer>({
-  name: "customer",
-  idGetter: "id",
-  async collectionFetcher(params, requestParams) {
-    const response = await fetch("/api/customers", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ filter: params.filter, order: params.order }),
-      signal: requestParams.signal,
-    });
-    return { data: await response.json() };
-  },
-  async itemFetcher(params, requestParams) {
-    const response = await fetch(`/api/customers/${params.id}`, {
-      signal: requestParams.signal,
-    });
-    return { data: await response.json() };
-  },
-  // ... other CRUD operations
-});
-
-// Create hooks bound to your customer store
-// This generates: useChimeraCustomerStore, useChimeraCustomerCollection, useChimeraCustomerItem
-export const {
-  useChimeraCustomerStore,
-  useChimeraCustomerCollection,
-  useChimeraCustomerItem,
-} = createChimeraStoreHooks(customerStore);
-```
-
-### 2. Use Collection Queries
-
-```tsx
-import { useChimeraCustomerCollection } from "./store";
-
-function CustomerList() {
-  const customers = useChimeraCustomerCollection({
-    filter: { status: "active" },
-    order: [{ field: "name", direction: "asc" }],
-  });
-
-  if (!customers.ready) return <div>Loading...</div>;
-  if (customers.lastError)
-    return <div>Error: {String(customers.lastError)}</div>;
-
-  return (
-    <div>
-      {customers.map((customer) => (
-        <div key={customer.id}>
-          {customer.name}
-          <button onClick={() => customers.delete(customer.id)}>Delete</button>
-        </div>
-      ))}
-      <button onClick={() => customers.create({ name: "New Customer" })}>
-        Add Customer
-      </button>
-    </div>
-  );
-}
-```
-
-### 3. Use Item Queries
-
-```tsx
-import { useChimeraCustomerItem } from "./store";
-
-function CustomerDetail({ customerId }: { customerId: string }) {
-  const customer = useChimeraCustomerItem(customerId);
-
-  if (!customer.ready) return <div>Loading...</div>;
-  if (customer.lastError) return <div>Error: {String(customer.lastError)}</div>;
-  if (!customer.data) return <div>Customer not found</div>;
-
-  const handleUpdate = () => {
-    customer.mutable.name = "Updated Name";
-    customer.commit();
-  };
-
-  return (
-    <div>
-      <h3>{customer.data.name}</h3>
-      <button onClick={handleUpdate}>Update Name</button>
-    </div>
-  );
-}
-```
-
-### 4. Using with Query Builder
-
-You can use the `ChimeraQueryBuilder` with React hooks by passing a builder function instead of the query descriptor. This provides a more fluent and type-safe API:
-
-```tsx
-import { useChimeraCollection, useChimeraItem } from "./store";
-
-function ActiveUsers() {
-  // Pass a builder function - the hook will call it and build the query
-  const activeUsers = useChimeraCollection("customer", (q) => {
-    q.where("email", "contains", "@example.com").orderBy("createdAt", true);
-  });
-
-  if (!activeUsers.ready) {
-    return <div>Loading...</div>;
-  }
-
-  return (
-    <div>
-      {activeUsers.map((user) => (
-        <div key={user.id}>{user.name}</div>
-      ))}
-    </div>
-  );
-}
-```
-
-**Complex Query with Groups:**
-
-```tsx
-import { useChimeraCollection } from "./store";
-
-function FeaturedOrders() {
-  const orders = useChimeraCollection("order", (q) => {
-    q.where("status", "eq", "completed")
-      // Must be either high value OR from VIP customer
-      .group("or", (group) => {
-        group
-          .where("totalAmount", "gte", 1000)
-          .where("customerId", "in", [1, 2, 3]); // VIP customers
-      })
-      // But not cancelled
-      .whereNot("status", "eq", "cancelled")
-      .orderBy("totalAmount", true);
-  });
-
-  return (
-    <div>
-      {orders.map((order) => (
-        <div key={order.id}>{order.productName}</div>
-      ))}
-    </div>
-  );
-}
-```
-
-For more information on using the query builder, see the [ChimeraQueryBuilder documentation](../../qb/README.md).
-
-## API Reference
-
-### Hooks
-
-#### `useChimeraCustomerCollection<Meta>(params, deps?)`
-
-Hook for collection queries with automatic state management.
-
-**Parameters:**
-
-- `entityName: EntityName` - Name of the entity
-- `params: ChimeraCollectionParams | QueryBuilderCreator` - Query parameters or query builder function
-- `deps?: unknown[]` - Optional dependency array for memoization
-
-**Returns:** `ChimeraCollectionQuery<Item, OperatorsMap>`, see [ChimeraCollectionQuery documentation](../../../README.md#chimeracollectionquery)
-
-#### `useChimeraItem<Store, EntityName, Meta>(entityName, id, meta?)`
-
-Hook for individual item queries with automatic state management.
-
-**Parameters:**
-
-- `entityName: EntityName` - Name of the entity
-- `id: ChimeraEntityId` - Item ID
-- `meta?: Meta` - Optional metadata
-
-**Returns:** `ChimeraItemQuery<Item>`, see [ChimeraCollectionQuery documentation](../../../README.md#chimeraitemquery)
-
-## Tips
-
-1. **Type Safety**: Use `getChimeraTypedHooks` for full type safety
-2. **Error Handling**: Always check `ready` and `lastError` properties
-3. **Optimistic Updates**: Use the `mutable` property for optimistic updates on item queries
-4. **Batch Operations**: Use batch operations for multiple items when possible
-5. **Query Builder**: Use the query builder function syntax for better type safety and readability
+# ChimeraEntityStore React Integration
+
+This package provides React hooks for seamless integration with ChimeraEntityStore, enabling reactive data management in React applications.
+
+## Features
+
+- **React Hooks**: Custom hooks for managing ChimeraEntityStore queries
+- **TypeScript Support**: Full type safety with TypeScript
+- **Automatic State Management**: Automatic re-rendering when data changes
+
+## Installation
+
+```bash
+# Install both the core store and React adapter
+npm install @hf-chimera/store @hf-chimera/react
+
+# React is a peer dependency
+npm install react
+
+# Or install all at once
+npm install @hf-chimera/store @hf-chimera/react react
+```
+
+## Usage
+
+### For React Applications
+
+Import from the React-specific entry point:
+
+```tsx
+import { createChimeraHooks } from "@hf-chimera/store/react";
+// In your app, call createChimeraHooks(store) and export the returned hooks
+```
+
+### For Non-React Applications
+
+Import from the main package:
+
+```ts
+import { createChimeraEntityStore } from "@hf-chimera/store";
+import { createChimeraStoreHooks } from "@hf-chimera/react";
+```
+
+## Quick Start
+
+### 1. Prepare hooks for the store
+
+Use the `createChimeraStoreHooks` function to create hooks for your entity store:
+
+```ts
+import { createChimeraStoreHooks } from "@hf-chimera/react";
+import { createChimeraEntityStore } from "@hf-chimera/store";
+
+// Define your entity type
+type Customer = {
+  id: number;
+  name: string;
+  email: string;
+};
+
+// Create your entity store instance
+const customerStore = createChimeraEntityStore<"customer", Customer>({
+  name: "customer",
+  idGetter: "id",
+  async collectionFetcher(params, requestParams) {
+    const response = await fetch("/api/customers", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ filter: params.filter, order: params.order }),
+      signal: requestParams.signal,
+    });
+    return { data: await response.json() };
+  },
+  async itemFetcher(params, requestParams) {
+    const response = await fetch(`/api/customers/${params.id}`, {
+      signal: requestParams.signal,
+    });
+    return { data: await response.json() };
+  },
+  // ... other CRUD operations
+});
+
+// Create hooks bound to your customer store
+// This generates: useChimeraCustomerStore, useChimeraCustomerCollection, useChimeraCustomerItem
+export const {
+  useChimeraCustomerStore,
+  useChimeraCustomerCollection,
+  useChimeraCustomerItem,
+} = createChimeraStoreHooks(customerStore);
+```
+
+### 2. Use Collection Queries
+
+```tsx
+import { useChimeraCustomerCollection } from "./store";
+
+function CustomerList() {
+  const customers = useChimeraCustomerCollection({
+    filter: { status: "active" },
+    order: [{ field: "name", direction: "asc" }],
+  });
+
+  if (!customers.ready) return <div>Loading...</div>;
+  if (customers.lastError)
+    return <div>Error: {String(customers.lastError)}</div>;
+
+  return (
+    <div>
+      {customers.map((customer) => (
+        <div key={customer.id}>
+          {customer.name}
+          <button onClick={() => customers.delete(customer.id)}>Delete</button>
+        </div>
+      ))}
+      <button onClick={() => customers.create({ name: "New Customer" })}>
+        Add Customer
+      </button>
+    </div>
+  );
+}
+```
+
+### 3. Use Item Queries
+
+```tsx
+import { useChimeraCustomerItem } from "./store";
+
+function CustomerDetail({ customerId }: { customerId: string }) {
+  const customer = useChimeraCustomerItem(customerId);
+
+  if (!customer.ready) return <div>Loading...</div>;
+  if (customer.lastError) return <div>Error: {String(customer.lastError)}</div>;
+  if (!customer.data) return <div>Customer not found</div>;
+
+  const handleUpdate = () => {
+    customer.mutable.name = "Updated Name";
+    customer.commit();
+  };
+
+  return (
+    <div>
+      <h3>{customer.data.name}</h3>
+      <button onClick={handleUpdate}>Update Name</button>
+    </div>
+  );
+}
+```
+
+### 4. Using with Query Builder
+
+You can use the `ChimeraQueryBuilder` with React hooks by passing a builder function instead of the query descriptor. This provides a more fluent and type-safe API:
+
+```tsx
+import { useChimeraCollection, useChimeraItem } from "./store";
+
+function ActiveUsers() {
+  // Pass a builder function - the hook will call it and build the query
+  const activeUsers = useChimeraCollection("customer", (q) => {
+    q.where("email", "contains", "@example.com").orderBy("createdAt", true);
+  });
+
+  if (!activeUsers.ready) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div>
+      {activeUsers.map((user) => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+**Complex Query with Groups:**
+
+```tsx
+import { useChimeraCollection } from "./store";
+
+function FeaturedOrders() {
+  const orders = useChimeraCollection("order", (q) => {
+    q.where("status", "eq", "completed")
+      // Must be either high value OR from VIP customer
+      .group("or", (group) => {
+        group
+          .where("totalAmount", "gte", 1000)
+          .where("customerId", "in", [1, 2, 3]); // VIP customers
+      })
+      // But not cancelled
+      .whereNot("status", "eq", "cancelled")
+      .orderBy("totalAmount", true);
+  });
+
+  return (
+    <div>
+      {orders.map((order) => (
+        <div key={order.id}>{order.productName}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+For more information on using the query builder, see the [ChimeraQueryBuilder documentation](../../qb/README.md).
+
+## API Reference
+
+### Hooks
+
+#### `useChimeraCustomerCollection<Meta>(params, deps?)`
+
+Hook for collection queries with automatic state management.
+
+**Parameters:**
+
+- `entityName: EntityName` - Name of the entity
+- `params: ChimeraCollectionParams | QueryBuilderCreator` - Query parameters or query builder function
+- `deps?: unknown[]` - Optional dependency array for memoization
+
+**Returns:** `ChimeraCollectionQuery<Item, OperatorsMap>`, see [ChimeraCollectionQuery documentation](../../../README.md#chimeracollectionquery)
+
+#### `useChimeraItem<Store, EntityName, Meta>(entityName, id, meta?)`
+
+Hook for individual item queries with automatic state management.
+
+**Parameters:**
+
+- `entityName: EntityName` - Name of the entity
+- `id: ChimeraEntityId` - Item ID
+- `meta?: Meta` - Optional metadata
+
+**Returns:** `ChimeraItemQuery<Item>`, see [ChimeraCollectionQuery documentation](../../../README.md#chimeraitemquery)
+
+## Tips
+
+1. **Type Safety**: Use `getChimeraTypedHooks` for full type safety
+2. **Error Handling**: Always check `ready` and `lastError` properties
+3. **Optimistic Updates**: Use the `mutable` property for optimistic updates on item queries
+4. **Batch Operations**: Use batch operations for multiple items when possible
+5. **Query Builder**: Use the query builder function syntax for better type safety and readability

package/package.json

@@ -1,48 +1,50 @@
 {
-	"name": "@hf-chimera/react",
-	"version": "0.2.0",
-	"description": "Cross-end reactivity API - React adapter",
-	"license": "MIT",
-	"author": "hewston",
-	"keywords": [
-		"reactivity",
-		"reactive",
-		"react",
-		"hooks",
-		"typescript",
-		"state-management"
-	],
-	"type": "module",
-	"types": "./dist/index.d.ts",
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.js",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"require": "./dist/index.cjs",
-			"import": "./dist/index.js"
-		}
-	},
-	"files": [
-		"dist"
-	],
-	"bugs": {
-		"url": "https://github.com/hf-chimera/store/issues"
-	},
-	"repository": {
-		"url": "https://github.com/hf-chimera/store"
-	},
-	"peerDependencies": {
-		"@hf-chimera/store": "workspace:^",
-		"@hf-chimera/adapters-shared": "workspace:^",
-		"react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
-	},
-	"scripts": {
-		"build": "tsdown",
-		"changeset:patch": "node ../../../scripts/changeset-patch.mjs @hf-chimera/react"
-	},
-	"publishConfig": {
-		"access": "public",
-		"provenance": true
-	}
-}
+  "name": "@hf-chimera/react",
+  "version": "0.2.1",
+  "description": "Cross-end reactivity API - React adapter",
+  "license": "MIT",
+  "author": "hewston",
+  "keywords": [
+    "reactivity",
+    "reactive",
+    "react",
+    "hooks",
+    "typescript",
+    "state-management"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "bugs": {
+    "url": "https://github.com/hf-chimera/store/issues"
+  },
+  "repository": {
+    "url": "https://github.com/hf-chimera/store"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+    "@hf-chimera/store": "~0.2.0"
+  },
+  "dependencies": {
+    "@hf-chimera/adapters-shared": "~0.2.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "changeset:patch": "node ../../../scripts/changeset-patch.mjs @hf-chimera/react"
+  }
+}