@hf-chimera/store 0.1.0 → 0.2.0

package/README.md

@@ -1,19 +1,14 @@
-# Chimera Store
+# @hf-chimera/store
 
-A cross-platform, reactive cache management library with intelligent
-deduplication and efficient data synchronization. Chimera Store provides a
-powerful API for managing cached data with built-in querying, filtering,
-ordering, and real-time updates.
+Core store library for Chimera Store - a cross-platform, reactive cache management library with intelligent deduplication and efficient data synchronization.
 
 ## Features
 
-- **🔄 Cross-Platform Reactivity**: Works seamlessly across web, mobile, and desktop platforms
 - **💾 Intelligent Cache Management**: Automatic deduplication and memory-efficient caching
-- **🔍 Advanced Querying**: Built-in filtering, and sorting support (Pagination in development)
+- **🔍 Advanced Querying**: Built-in filtering and sorting support
 - **⚡ Real-Time Updates**: Event-driven architecture with automatic cache invalidation
 - **🎯 Type Safety**: Full TypeScript support with comprehensive type definitions
 - **🛡️ Error Handling**: Robust error handling with detailed error messages
-- **📦 Modular Architecture**: Composable components for flexible integration
 - **🌐 Universal Compatibility**: Works with any data source (REST APIs, GraphQL, WebSockets, etc.)
 
 ## Installation
@@ -26,124 +21,82 @@ yarn add @hf-chimera/store
 pnpm add @hf-chimera/store
 ```
 
+## Framework Integrations
+
+- **React**: Use [`@hf-chimera/react`](../adapters/react) for React hooks
+- **Vue**: Use [`@hf-chimera/vue`](../adapters/vue) for Vue 3 composables
+- **Query Builder**: Use [`@hf-chimera/query-builder`](../qb) for fluent query building
+
 ## Quick Start
 
 ### Basic Setup
 
 ```typescript
-import { ChimeraStore } from '@hf-chimera/store';
+import { createChimeraEntityStore } from "@hf-chimera/store";
 
-// Define your entity types
+// Define your entity type
 type User = {
-	id: string;
-	name: string;
-	email: string;
-	age: number;
-};
-
-type Post = {
-	id: string;
-	title: string;
-	content: string;
-	authorId: string;
-	createdAt: Date;
+  id: number;
+  name: string;
+  email: string;
+  age: number;
 };
 
-// Define your entity map
-type EntityMap = {
-	users: User;
-	posts: Post;
-};
-
-// Create store configuration
-const store = new ChimeraStore<EntityMap>({
-	query: {
-		defaults: {
-			trustQuery: true,
-			// idGetter can be a string (object key) or a function
-			// String: Uses the specified property as the ID (e.g., 'id', 'uuid', 'key')
-			// Function: Custom ID extraction logic (entityName, value) => string | number
-			idGetter: 'id',
-		},
-		entities: {
-			// Define configuration for each entity in your EntityMap
-			// Each entity must have its own fetchers, updaters, deleters, and creators
-			users: {
-				collectionFetcher: async (params, requestParams) => {
-					const response = await fetch(`/api/users`, {
-						signal: requestParams.signal,
-					});
-					return { data: await response.json() };
-				},
-				itemFetcher: async (params, requestParams) => {
-					const response = await fetch(`/api/users/${params.id}`, {
-						signal: requestParams.signal,
-					});
-					return { data: await response.json() };
-				},
-				itemUpdater: async (item, requestParams) => {
-					const response = await fetch(`/api/users/${item.id}`, {
-						method: 'PUT',
-						body: JSON.stringify(item),
-						signal: requestParams.signal,
-					});
-					return { data: await response.json() };
-				},
-				itemDeleter: async (id, requestParams) => {
-					await fetch(`/api/users/${id}`, {
-						method: 'DELETE',
-						signal: requestParams.signal,
-					});
-					return { result: { id, success: true } };
-				},
-				itemCreator: async (item, requestParams) => {
-					const response = await fetch(`/api/users`, {
-						method: 'POST',
-						body: JSON.stringify(item),
-						signal: requestParams.signal,
-					});
-					return { data: await response.json() };
-				},
-			},
-			posts: {
-				collectionFetcher: async (params, requestParams) => {
-					const response = await fetch(`/api/posts`, {
-						signal: requestParams.signal,
-					});
-					return { data: await response.json() };
-				},
-				itemFetcher: async (params, requestParams) => {
-					const response = await fetch(`/api/posts/${params.id}`, {
-						signal: requestParams.signal,
-					});
-					return { data: await response.json() };
-				},
-				itemUpdater: async (item, requestParams) => {
-					const response = await fetch(`/api/posts/${item.id}`, {
-						method: 'PUT',
-						body: JSON.stringify(item),
-						signal: requestParams.signal,
-					});
-					return { data: await response.json() };
-				},
-				itemDeleter: async (id, requestParams) => {
-					await fetch(`/api/posts/${id}`, {
-						method: 'DELETE',
-						signal: requestParams.signal,
-					});
-					return { result: { id, success: true } };
-				},
-				itemCreator: async (item, requestParams) => {
-					const response = await fetch(`/api/posts`, {
-						method: 'POST',
-						body: JSON.stringify(item),
-						signal: requestParams.signal,
-					});
-					return { data: await response.json() };
-				},
-			},
-		},
-	},
+// Create an entity store
+const userStore = createChimeraEntityStore<"user", User>({
+  name: "user",
+  idGetter: "id", // Can be a string (property name) or function
+  trustQuery: true,
+
+  // Collection fetcher - fetch multiple items
+  collectionFetcher: async (params, requestParams) => {
+    const response = await fetch(`/api/users`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ filter: params.filter, order: params.order }),
+      signal: requestParams.signal,
+    });
+    return { data: await response.json() };
+  },
+
+  // Item fetcher - fetch single item by ID
+  itemFetcher: async (params, requestParams) => {
+    const response = await fetch(`/api/users/${params.id}`, {
+      signal: requestParams.signal,
+    });
+    return { data: await response.json() };
+  },
+
+  // Item creator - create new item
+  itemCreator: async (item, requestParams) => {
+    const response = await fetch(`/api/users`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(item),
+      signal: requestParams.signal,
+    });
+    return { data: await response.json() };
+  },
+
+  // Item updater - update existing item
+  itemUpdater: async (item, requestParams) => {
+    const response = await fetch(`/api/users/${item.id}`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(item),
+      signal: requestParams.signal,
+    });
+    return { data: await response.json() };
+  },
+
+  // Item deleter - delete item by ID
+  itemDeleter: async (id, requestParams) => {
+    await fetch(`/api/users/${id}`, {
+      method: "DELETE",
+      signal: requestParams.signal,
+    });
+    return { result: { id, success: true } };
+  },
 });
 ```
 
@@ -151,76 +104,68 @@ const store = new ChimeraStore<EntityMap>({
 
 ```typescript
 import {
-	ChimeraStore,
-	chimeraCreateConjunction,
-	chimeraCreateOperator,
-	chimeraCreateOrderBy,
-	ChimeraOrderNulls
-} from '@hf-chimera/store';
-
-// Get a repository for a specific entity
-const userRepo = store.from('users');
-const postRepo = store.from('posts');
+  chimeraCreateConjunction,
+  chimeraCreateOperator,
+  chimeraCreateOrderBy,
+  ChimeraOrderNulls,
+} from "@hf-chimera/store";
 
 // Create a new user
-const newUserQuery = userRepo.createItem({
-	name: 'John Doe',
-	email: 'john@example.com',
-	age: 30,
+const newUserQuery = userStore.createItem({
+  name: "John Doe",
+  email: "john@example.com",
+  age: 30,
 });
 
 // Listen for creation events
-newUserQuery.on('created', (query) => {
-	console.log('User created:', query.data);
+newUserQuery.on("created", (query) => {
+  console.log("User created:", query.data);
 });
 
 // Get a specific user
-const userQuery = userRepo.getItem('user-123');
+const userQuery = userStore.getItem(123);
 
 // Listen for data updates
-userQuery.on('ready', (query) => {
-	console.log('User loaded:', query.data);
+userQuery.on("ready", (query) => {
+  console.log("User loaded:", query.data);
 });
 
 // Update user data
-userQuery.mutable.name = 'Jane Doe';
+userQuery.mutable.name = "Jane Doe";
 await userQuery.commit();
 
 // Get a collection with filtering and sorting
-const activeUsersQuery = userRepo.getCollection({
-	filter: chimeraCreateConjunction('and', [
-		chimeraCreateOperator('gte', 'age', 18),
-	]),
-	order: [
-		chimeraCreateOrderBy('name', false, ChimeraOrderNulls.Last),
-	],
+const activeUsersQuery = userStore.getCollection({
+  filter: chimeraCreateConjunction("and", [
+    chimeraCreateOperator("gte", "age", 18),
+  ]),
+  order: [chimeraCreateOrderBy("name", false, ChimeraOrderNulls.Last)],
 });
 
 // Listen for collection updates
-activeUsersQuery.on('updated', (query, items, oldItems) => {
-	console.log('Active users updated:', items);
+activeUsersQuery.on("updated", (query, items, oldItems) => {
+  console.log("Active users updated:", items);
 });
 
 // External updates (e.g., from WebSocket)
-store.updateOne('users', {
-	id: 'user-123',
-	name: 'Updated Name',
-	email: 'updated@example.com',
-	age: 31,
+userStore.updateOne({
+  id: 123,
+  name: "Updated Name",
+  email: "updated@example.com",
+  age: 31,
 });
 ```
 
 ## Core Concepts
 
-### Store Architecture
+### Entity Store
 
-Chimera Store is built around several key concepts:
+Each entity type has its own `ChimeraEntityStore` instance created via `createChimeraEntityStore`. This provides:
 
-1. **Store**: The main entry point that manages all entities
-2. **Repository**: Entity-specific data management with query capabilities
-3. **Query**: Represents a specific data request (single item or collection)
-4. **Cache**: Intelligent deduplication and memory management
-5. **Events**: Real-time updates and state synchronization
+- **Isolated caching** per entity type
+- **Type-safe operations** for that specific entity
+- **Event-driven updates** for real-time synchronization
+- **Query management** with automatic deduplication
 
 ### Query Types
 
@@ -247,34 +192,66 @@ Flexible ordering with support for:
 
 ## API Reference
 
-### ChimeraStore
+### createChimeraEntityStore
 
-The main store class that manages all entities and provides cross-entity
-operations.
+The main function to create an entity store instance.
 
-#### Constructor
+#### Signature
 
 ```typescript
-const store = new ChimeraStore<EntityMap>(config)
+function createChimeraEntityStore<
+  TEntityName extends string,
+  TItem extends object,
+>(
+  config: ChimeraQueryEntityConfig<TEntityName, TItem, OperatorsMap>,
+): ChimeraEntityStore<TEntityName, TItem, OperatorsMap>;
 ```
 
-#### Methods
+#### Parameters
 
-- `from<EntityName>(entityName: EntityName)`: Get repository for specific entity
-- `updateOne<EntityName>(entityName: EntityName, item: EntityMap[EntityName])`: Update single item
-- `updateMany<EntityName>(entityName: EntityName, items: Iterable<EntityMap[EntityName]>)`: Update multiple items
-- `deleteOne<EntityName>(entityName: EntityName, id: ChimeraEntityId)`: Delete single item
-- `deleteMany<EntityName>(entityName: EntityName, ids: Iterable<ChimeraEntityId>)`: Delete multiple items
+- `config`: Entity configuration object containing:
+  - `name`: Entity name (string)
+  - `idGetter`: Property name (string) or function to extract ID from entity
+  - `trustQuery`: Whether to trust query results (boolean)
+  - `collectionFetcher`: Function to fetch multiple items
+  - `itemFetcher`: Function to fetch single item by ID
+  - `itemCreator`: Function to create new item
+  - `itemUpdater`: Function to update existing item
+  - `itemDeleter`: Function to delete item by ID
+  - Optional: `batchedCreator`, `batchedUpdater`, `batchedDeleter` for batch operations
+  - Optional: `updateDebounceTimeout` for debouncing updates
 
-### ChimeraEntityRepository
+#### Returns
 
-Entity-specific repository with query capabilities.
+`ChimeraEntityStore<TEntityName, TItem, OperatorsMap>` instance
+
+### ChimeraEntityStore
+
+Entity-specific store with query capabilities.
+
+#### Properties
+
+- `name`: Entity name (readonly)
 
 #### Methods
 
 - `createItem(item: DeepPartial<Item>, meta?: any)`: Create new item
 - `getItem(id: ChimeraEntityId, meta?: any)`: Get single item
 - `getCollection(params: ChimeraCollectionParams)`: Get filtered/sorted collection
+- `updateOne(item: Item)`: Update single item externally
+- `updateMany(items: Item[])`: Update multiple items externally
+- `deleteOne(id: ChimeraEntityId)`: Delete single item externally
+- `deleteMany(ids: ChimeraEntityId[])`: Delete multiple items externally
+- `updateMixed(toAdd: Item[], toDelete: ChimeraEntityId[])`: Mixed update/delete operation
+
+#### Events
+
+- `initialized`: Store initialized
+- `itemAdded`: Item added to cache
+- `itemUpdated`: Item updated
+- `updated`: Multiple items updated
+- `itemDeleted`: Item deleted
+- `deleted`: Multiple items deleted
 
 ### ChimeraItemQuery
 
@@ -287,6 +264,7 @@ Represents a single item query with full CRUD operations.
 - `state`: Current query state
 - `ready`: Whether data is available
 - `inProgress`: Whether operation is in progress
+- `id`: Item ID
 
 #### Methods
 
@@ -355,119 +333,22 @@ Collection queries implement the standard Array interface:
 
 ## Advanced Usage
 
-### Custom Filter Operators
-
-```typescript
-const customFilterConfig = {
-	...chimeraDefaultFilterConfig,
-	operators: {
-		...chimeraDefaultFilterConfig.operators,
-		// Custom operator for text search
-		textSearch: (text: string, searchTerm: string) =>
-			text.toLowerCase().includes(searchTerm.toLowerCase()),
-	},
-};
-
-const store = new ChimeraStore<EntityMap, typeof customFilterConfig.operators>({
-	filter: customFilterConfig,
-	// ... other config
-});
-```
-
-### Complex Filtering Examples
-
-```typescript
-import {
-	chimeraCreateConjunction,
-	chimeraCreateOperator,
-	chimeraCreateOrderBy,
-	ChimeraOrderNulls
-} from '@hf-chimera/store';
-
-// Simple filter: users with age >= 18
-const adultUsers = userRepo.getCollection({
-	filter: chimeraCreateOperator('gte', 'age', 18),
-});
-
-// Complex filter: active users with specific age range and email domain
-const activeUsers = userRepo.getCollection({
-	filter: chimeraCreateConjunction('and', [
-		chimeraCreateOperator('gte', 'age', 18),
-		chimeraCreateOperator('lte', 'age', 65),
-		chimeraCreateOperator('endsWith', 'email', '@company.com'),
-		chimeraCreateOperator('eq', 'isActive', true),
-	]),
-});
-
-// OR filter: users with specific names or email domains
-const specificUsers = userRepo.getCollection({
-	filter: chimeraCreateConjunction('or', [
-		chimeraCreateOperator('in', 'name', ['John', 'Jane', 'Bob']),
-		chimeraCreateOperator('endsWith', 'email', '@gmail.com'),
-	]),
-});
-
-// Nested filters: complex business logic
-const premiumUsers = userRepo.getCollection({
-	filter: chimeraCreateConjunction('and', [
-		chimeraCreateOperator('gte', 'age', 21),
-		chimeraCreateConjunction('or', [
-			chimeraCreateOperator('gte', 'subscriptionLevel', 'premium'),
-			chimeraCreateOperator('gte', 'totalSpent', 1000),
-		]),
-		chimeraCreateOperator('neq', 'status', 'suspended'),
-	]),
-});
-
-// Text search with multiple conditions
-const searchResults = userRepo.getCollection({
-	filter: chimeraCreateConjunction('and', [
-		chimeraCreateConjunction('or', [
-			chimeraCreateOperator('contains', 'name', searchTerm),
-			chimeraCreateOperator('contains', 'email', searchTerm),
-		]),
-		chimeraCreateOperator('eq', 'isActive', true),
-	]),
-	order: [
-		chimeraCreateOrderBy('name', false, ChimeraOrderNulls.Last),
-		chimeraCreateOrderBy('createdAt', true, ChimeraOrderNulls.Last), // newest first
-	],
-});
-```
-
-### Custom Order Comparators
-
-```typescript
-const customOrderConfig = {
-	...chimeraDefaultOrderConfig,
-	primitiveComparator: (a: unknown, b: unknown, nulls: ChimeraOrderNulls) => {
-		// Custom comparison logic
-		if (typeof a === 'string' && typeof b === 'string') {
-			return a.localeCompare(b, undefined, { numeric: true });
-		}
-		return chimeraDefaultOrderConfig.primitiveComparator(a, b, nulls);
-	},
-};
-```
-
 ### Event Handling
 
 ```typescript
 // Listen to store-level events
-store.on('itemAdded', (repository, item) => {
-	console.log('Item added to', repository, item);
+userStore.on("itemAdded", ({ instance, item }) => {
+  console.log("Item added:", item);
 });
 
-// Listen to repository events
-const userRepo = store.from('users');
-userRepo.on('itemUpdated', (repo, item, oldItem) => {
-	console.log('User updated:', item, 'was:', oldItem);
+userStore.on("itemUpdated", ({ instance, item, oldItem }) => {
+  console.log("User updated:", item, "was:", oldItem);
 });
 
 // Listen to query events
-const userQuery = userRepo.getItem('user-123');
-userQuery.on('updated', (query, item, oldItem) => {
-	console.log('Query updated:', item);
+const userQuery = userStore.getItem(123);
+userQuery.on("updated", (query, item, oldItem) => {
+  console.log("Query updated:", item);
 });
 ```
 
@@ -475,85 +356,21 @@ userQuery.on('updated', (query, item, oldItem) => {
 
 ```typescript
 // Optimistic update with rollback
-const userQuery = userRepo.getItem('user-123');
+const userQuery = userStore.getItem(123);
 
 // Update optimistically
-userQuery.mutable.name = 'New Name';
+userQuery.mutable.name = "New Name";
 
 try {
-	await userQuery.commit();
-	console.log('Update successful');
+  await userQuery.commit();
+  console.log("Update successful");
 } catch (error) {
-	// Rollback on error
-	await userQuery.refetch();
-	console.log('Update failed, rolled back');
+  // Rollback on error
+  await userQuery.refetch();
+  console.log("Update failed, rolled back");
 }
 ```
 
-## Configuration Options
-
-### Query Configuration
-
-```typescript
-type ConfigExample = {
-	query: {
-		defaults: {
-			trustQuery: boolean; // Trust external data providers
-			idGetter: ((entityName: string, value: unknown) => string | number) | string; // Default ID getter
-			collectionFetcher?: (params: any, request: {
-				signal?: AbortSignal
-			}) => Promise<{ data: any[] }>;
-			itemFetcher?: (params: any, request: {
-				signal?: AbortSignal
-			}) => Promise<{ data: any }>;
-			itemUpdater?: (item: any, request: { signal?: AbortSignal }) => Promise<{
-				data: any
-			}>;
-			itemDeleter?: (id: string | number, request: {
-				signal?: AbortSignal
-			}) => Promise<{ result?: any }>;
-			itemCreator?: (item: any, request: { signal?: AbortSignal }) => Promise<{
-				data: any
-			}>;
-			// ... batched operations
-		};
-		entities: {
-			[entityName: string]: {
-				// Entity-specific overrides
-			};
-		};
-	};
-};
-```
-
-### Filter Configuration
-
-```typescript
-type FilterConfigExample = {
-	filter: {
-		operators: {
-			eq: <T>(a: T, b: T) => boolean;
-			neq: <T>(a: T, b: T) => boolean;
-			gt?: (a: number, b: number) => boolean;
-			// ... custom operators
-		};
-		getFilterKey?: (input: unknown) => string; // Cache key generator for filters
-		getOperatorKey?: (input: unknown) => string; // Cache key generator for operators
-	};
-};
-```
-
-### Order Configuration
-
-```typescript
-type OrderConfigExample = {
-	order: {
-		primitiveComparator: (a: unknown, b: unknown, nulls: ChimeraOrderNulls) => number; // Custom comparator
-		getKey: (input: unknown) => string; // Cache key generator
-	};
-};
-```
-
 ## Performance Considerations
 
 ### Memory Management
@@ -564,7 +381,7 @@ type OrderConfigExample = {
 
 ### Caching Strategy
 
-- Collection queries are cached by a filter/order combination
+- Collection queries are cached by filter/order combination
 - Item queries are cached by ID
 - Cache keys are generated automatically for optimal performance
 
@@ -572,6 +389,7 @@ type OrderConfigExample = {
 
 - Batch operations for multiple updates
 - Optimistic updates for better UX
+- Debounced updates to reduce API calls
 
 ## Browser Support
 
@@ -579,20 +397,13 @@ type OrderConfigExample = {
 - **Node.js**: 14.17.0+ with `--harmony-weak-refs` flag, 16.0.0+ stable
 - **TypeScript**: 4.5+ recommended
 
-## Contributing
+## Learn More
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests for new functionality
-5. Submit a pull request
+- [Main Documentation](../../README.md)
+- [React Integration](../adapters/react/README.md)
+- [Vue Integration](../adapters/vue/README.md)
+- [Query Builder](../qb/README.md)
 
 ## License
 
-MIT License — see [LICENSE](LICENSE) file for details.
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/hf-chimera/store/issues)
-- **Documentation**: [GitHub Wiki](https://github.com/hf-chimera/store/wiki)
-- **Discussions**: [GitHub Discussions](https://github.com/hf-chimera/store/discussions) 
+MIT License — see [LICENSE](../../LICENSE) file for details.