@oimdb/react 1.1.0 → 1.2.0

package/README.md

@@ -8,7 +8,8 @@ React integration for OIMDB - Hooks for selection and subscription with reactive
 
 ## Features
 
-- **Reactive Integration**: Hooks work with `OIMReactiveCollection` and `OIMReactiveIndex` from `@oimdb/core`
+- **Reactive Integration**: Hooks work with `OIMReactiveCollection` and reactive indexes from `@oimdb/core`
+- **Index Type Support**: Separate hooks for SetBased indexes (return `Set<TPk>`) and ArrayBased indexes (return `TPk[]`)
 - **Automatic Subscription**: Uses `useSyncExternalStore` for optimal React 18+ performance
 - **Event Coalescing**: Leverages OIMDB's built-in event coalescing for efficient updates
 - **Type Safety**: Full TypeScript support with advanced generic type inference
@@ -26,16 +27,28 @@ npm install @oimdb/react @oimdb/core
 ### Basic Setup
 
 ```typescript
-import { OIMEventQueue, OIMRICollection, OIMReactiveIndexManual } from '@oimdb/core';
+import { 
+  OIMEventQueue, 
+  OIMRICollection, 
+  OIMReactiveIndexManualSetBased,
+  OIMReactiveIndexManualArrayBased 
+} from '@oimdb/core';
 import { 
   useSelectEntitiesByPks, 
-  useSelectEntitiesByIndexKey,
+  useSelectEntitiesByIndexKeySetBased,
+  useSelectEntitiesByIndexKeyArrayBased,
   useSelectEntityByPk 
 } from '@oimdb/react';
 
 // Create event queue and reactive collections
 const queue = new OIMEventQueue();
-const userTeamIndex = new OIMReactiveIndexManual<string, string>(queue);
+
+// Choose index type based on your needs:
+// - SetBased: for frequent add/remove operations, order doesn't matter
+// - ArrayBased: for full replacements or when order/sorting matters
+const userTeamIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
+const deckCardsIndex = new OIMReactiveIndexManualArrayBased<string, string>(queue);
+
 const usersCollection = new OIMRICollection(queue, {
   collectionOpts: { selectPk: (user: User) => user.id },
   indexes: { byTeam: userTeamIndex },
@@ -79,14 +92,27 @@ function UserList({ userIds }: { userIds: string[] }) {
 
 ### Index-based Selection
 
+OIMDB provides separate hooks for SetBased and ArrayBased indexes:
+
+#### SetBased Indexes (returns Set)
+
 ```typescript
+import { useSelectEntitiesByIndexKeySetBased, useSelectPksByIndexKeySetBased } from '@oimdb/react';
+
 function TeamMembers({ teamId }: { teamId: string }) {
-  const teamUsers = useSelectEntitiesByIndexKey(
+  // For SetBased indexes, use SetBased hooks
+  const teamUsers = useSelectEntitiesByIndexKeySetBased(
     usersCollection,
-    usersCollection.indexes.byTeam,
+    usersCollection.indexes.byTeam, // OIMReactiveIndexManualSetBased
     teamId
   );
 
+  // Or get just the PKs as Set
+  const teamUserIds = useSelectPksByIndexKeySetBased(
+    usersCollection.indexes.byTeam,
+    teamId
+  ); // Returns Set<string>
+
   return (
     <div>
       {teamUsers.map((user, index) => (
@@ -99,6 +125,37 @@ function TeamMembers({ teamId }: { teamId: string }) {
 }
 ```
 
+#### ArrayBased Indexes (returns Array)
+
+```typescript
+import { useSelectEntitiesByIndexKeyArrayBased, useSelectPksByIndexKeyArrayBased } from '@oimdb/react';
+
+function DeckCards({ deckId }: { deckId: string }) {
+  // For ArrayBased indexes, use ArrayBased hooks
+  const cards = useSelectEntitiesByIndexKeyArrayBased(
+    cardsCollection,
+    cardsCollection.indexes.byDeck, // OIMReactiveIndexManualArrayBased
+    deckId
+  );
+
+  // Or get just the PKs as Array (preserves order)
+  const cardIds = useSelectPksByIndexKeyArrayBased(
+    cardsCollection.indexes.byDeck,
+    deckId
+  ); // Returns string[] (preserves order/sorting)
+
+  return (
+    <div>
+      {cards.map((card, index) => (
+        <div key={card?.id || index}>
+          {card ? `${index + 1}. ${card.name}` : 'Loading...'}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
 ## React Context Integration
 
 For applications with multiple collections, use the React Context pattern for centralized management:
@@ -108,8 +165,7 @@ For applications with multiple collections, use the React Context pattern for ce
 ```typescript
 import { 
   OIMRICollectionsProvider, 
-  useOIMCollectionsContext,
-  StrictCollectionsDictionary 
+  useOIMCollectionsContext
 } from '@oimdb/react';
 
 interface User {
@@ -126,7 +182,8 @@ interface Team {
 function createCollections() {
   const queue = new OIMEventQueue();
   
-  const userTeamIndex = new OIMReactiveIndexManual<string, string>(queue);
+  // Use SetBased for frequent add/remove operations
+  const userTeamIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
   const usersCollection = new OIMRICollection(queue, {
     collectionOpts: { selectPk: (user: User) => user.id },
     indexes: { byTeam: userTeamIndex },
@@ -140,9 +197,156 @@ function createCollections() {
   return { users: usersCollection, teams: teamsCollection } as const;
 }
 
-type AppCollections = StrictCollectionsDictionary<ReturnType<typeof createCollections>>;
+type AppCollections = ReturnType<typeof createCollections>;
+```
+
+## TypeScript Typing Strategies
+
+For maximum type safety, you should properly type your collections dictionary. There are two main approaches, similar to how Redux handles state typing:
+
+### Approach 1: Using `typeof` (Recommended for Simple Cases)
+
+The simplest approach is to use TypeScript's `typeof` operator to infer types from your collection instances:
+
+```typescript
+import { OIMEventQueue, OIMRICollection, OIMReactiveIndexManual } from '@oimdb/core';
+
+interface User {
+  id: string;
+  name: string;
+  teamId: string;
+}
+
+interface Team {
+  id: string;
+  name: string;
+}
+
+// Create collections
+const queue = new OIMEventQueue();
+const userTeamIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
+const usersCollection = new OIMRICollection(queue, {
+  collectionOpts: { selectPk: (user: User) => user.id },
+  indexes: { byTeam: userTeamIndex },
+});
+
+const teamsCollection = new OIMRICollection(queue, {
+  collectionOpts: { selectPk: (team: Team) => team.id },
+  indexes: {},
+});
+
+// Infer types using typeof
+const collections = {
+  users: usersCollection,
+  teams: teamsCollection,
+} as const;
+
+// Extract the type
+type AppCollections = typeof collections;
+```
+
+**Usage:**
+```typescript
+function MyComponent() {
+  const { users, teams } = useOIMCollectionsContext<AppCollections>();
+  // users and teams are fully typed with all their generics preserved
+}
+```
+
+### Approach 2: Creating Explicit Types (Recommended for Complex Projects)
+
+For larger applications or when you need more control, create explicit type definitions similar to Redux's approach:
+
+```typescript
+import { 
+  OIMEventQueue, 
+  OIMRICollection, 
+  OIMReactiveIndexManualSetBased 
+} from '@oimdb/core';
+import type { 
+  TOIMPk, 
+  OIMIndexSetBased, 
+  OIMReactiveIndexSetBased 
+} from '@oimdb/core';
+
+interface User {
+  id: string;
+  name: string;
+  teamId: string;
+}
+
+interface Team {
+  id: string;
+  name: string;
+}
+
+// Define your collection types explicitly
+type UserCollection = OIMRICollection<
+  User,
+  string,
+  'byTeam',
+  string,
+  OIMIndexSetBased<string, string>,
+  OIMReactiveIndexSetBased<string, string, OIMIndexSetBased<string, string>>
+>;
+
+type TeamCollection = OIMRICollection<
+  Team,
+  string,
+  never,
+  never,
+  OIMIndexSetBased<never, never>,
+  OIMReactiveIndexSetBased<never, never, OIMIndexSetBased<never, never>>
+>;
+
+// Define your collections dictionary type
+interface AppCollections {
+  users: UserCollection;
+  teams: TeamCollection;
+}
+
+// Factory function that returns properly typed collections
+function createCollections(): AppCollections {
+  const queue = new OIMEventQueue();
+  const userTeamIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
+  
+  return {
+    users: new OIMRICollection(queue, {
+      collectionOpts: { selectPk: (user: User) => user.id },
+      indexes: { byTeam: userTeamIndex },
+    }) as UserCollection,
+    
+    teams: new OIMRICollection(queue, {
+      collectionOpts: { selectPk: (team: Team) => team.id },
+      indexes: {},
+    }) as TeamCollection,
+  };
+}
+```
+
+**Usage:**
+```typescript
+function MyComponent() {
+  const { users, teams } = useOIMCollectionsContext<AppCollections>();
+  // Full type safety with explicit types
+}
 ```
 
+### When to Use Each Approach
+
+- **Use `typeof`** when:
+  - You have simple collection setups
+  - You want TypeScript to infer everything automatically
+  - You prefer less boilerplate
+  - Your collections are created in one place
+
+- **Use explicit types** when:
+  - You need to share types across multiple files
+  - You want to document your data structure explicitly
+  - You're building a library or shared module
+  - You need to ensure type consistency across your application
+  - You prefer Redux-style explicit typing patterns
+
 ### Provider Setup
 
 ```typescript
@@ -165,9 +369,10 @@ function UserDashboard() {
   
   // Use collections with hooks
   const allUsers = useSelectEntitiesByPks(users, []);
-  const teamMembers = useSelectEntitiesByIndexKey(
+  // Use appropriate hook based on index type
+  const teamMembers = useSelectEntitiesByIndexKeySetBased(
     users,
-    users.indexes.byTeam,
+    users.indexes.byTeam, // SetBased index
     'team1'
   );
   
@@ -227,51 +432,105 @@ Subscribes to multiple entities from a reactive collection.
 **Returns:**
 - `(TEntity | undefined)[]` - Array of entities (undefined for missing entities)
 
-### `useSelectEntitiesByIndexKey(reactiveCollection, reactiveIndex, key)`
+### Index-based Selection Hooks
+
+OIMDB provides separate hooks for SetBased and ArrayBased indexes to ensure type safety and correct return types.
+
+#### SetBased Index Hooks
 
-Subscribes to entities indexed by a specific key.
+##### `useSelectEntitiesByIndexKeySetBased(reactiveCollection, reactiveIndex, key)`
+
+Subscribes to entities indexed by a specific key from a SetBased index.
 
 **Parameters:**
 - `reactiveCollection: OIMReactiveCollection<TEntity, TPk>` - Reactive collection instance
-- `reactiveIndex: OIMReactiveIndex<TKey, TPk, TIndex>` - Reactive index instance
+- `reactiveIndex: OIMReactiveIndexSetBased<TKey, TPk, TIndex>` - SetBased reactive index instance
 - `key: TKey` - Index key to query
 
 **Returns:**
 - `(TEntity | undefined)[]` - Array of entities for the given index key
 
-### `useSelectEntitiesByIndexKeys(reactiveCollection, reactiveIndex, keys)`
+##### `useSelectEntitiesByIndexKeysSetBased(reactiveCollection, reactiveIndex, keys)`
 
-Subscribes to entities indexed by multiple keys.
+Subscribes to entities indexed by multiple keys from a SetBased index.
 
 **Parameters:**
 - `reactiveCollection: OIMReactiveCollection<TEntity, TPk>` - Reactive collection instance
-- `reactiveIndex: OIMReactiveIndex<TKey, TPk, TIndex>` - Reactive index instance
+- `reactiveIndex: OIMReactiveIndexSetBased<TKey, TPk, TIndex>` - SetBased reactive index instance
 - `keys: readonly TKey[]` - Array of index keys to query
 
 **Returns:**
 - `(TEntity | undefined)[]` - Array of entities for the given index keys
 
-### `useSelectPksByIndexKey(reactiveIndex, key)`
+##### `useSelectPksByIndexKeySetBased(reactiveIndex, key)`
+
+Subscribes to primary keys indexed by a specific key from a SetBased index.
+
+**Parameters:**
+- `reactiveIndex: OIMReactiveIndexSetBased<TKey, TPk, TIndex>` - SetBased reactive index instance
+- `key: TKey` - Index key to query
+
+**Returns:**
+- `Set<TPk>` - Set of primary keys for the given index key
+
+##### `useSelectPksByIndexKeysSetBased(reactiveIndex, keys)`
+
+Subscribes to primary keys indexed by multiple keys from a SetBased index.
+
+**Parameters:**
+- `reactiveIndex: OIMReactiveIndexSetBased<TKey, TPk, TIndex>` - SetBased reactive index instance
+- `keys: readonly TKey[]` - Array of index keys to query
+
+**Returns:**
+- `Map<TKey, Set<TPk>>` - Map of index keys to their corresponding primary key Sets
+
+#### ArrayBased Index Hooks
 
-Subscribes to primary keys indexed by a specific key.
+##### `useSelectEntitiesByIndexKeyArrayBased(reactiveCollection, reactiveIndex, key)`
+
+Subscribes to entities indexed by a specific key from an ArrayBased index.
 
 **Parameters:**
-- `reactiveIndex: OIMReactiveIndex<TKey, TPk, TIndex>` - Reactive index instance
+- `reactiveCollection: OIMReactiveCollection<TEntity, TPk>` - Reactive collection instance
+- `reactiveIndex: OIMReactiveIndexArrayBased<TKey, TPk, TIndex>` - ArrayBased reactive index instance
 - `key: TKey` - Index key to query
 
 **Returns:**
-- `TPk[]` - Array of primary keys for the given index key
+- `(TEntity | undefined)[]` - Array of entities for the given index key (preserves order)
 
-### `useSelectPksByIndexKeys(reactiveIndex, keys)`
+##### `useSelectEntitiesByIndexKeysArrayBased(reactiveCollection, reactiveIndex, keys)`
 
-Subscribes to primary keys indexed by multiple keys.
+Subscribes to entities indexed by multiple keys from an ArrayBased index.
 
 **Parameters:**
-- `reactiveIndex: OIMReactiveIndex<TKey, TPk, TIndex>` - Reactive index instance
+- `reactiveCollection: OIMReactiveCollection<TEntity, TPk>` - Reactive collection instance
+- `reactiveIndex: OIMReactiveIndexArrayBased<TKey, TPk, TIndex>` - ArrayBased reactive index instance
 - `keys: readonly TKey[]` - Array of index keys to query
 
 **Returns:**
-- `Map<TKey, TPk[]>` - Map of index keys to their corresponding primary keys
+- `(TEntity | undefined)[]` - Array of entities for the given index keys (preserves order)
+
+##### `useSelectPksByIndexKeyArrayBased(reactiveIndex, key)`
+
+Subscribes to primary keys indexed by a specific key from an ArrayBased index.
+
+**Parameters:**
+- `reactiveIndex: OIMReactiveIndexArrayBased<TKey, TPk, TIndex>` - ArrayBased reactive index instance
+- `key: TKey` - Index key to query
+
+**Returns:**
+- `TPk[]` - Array of primary keys for the given index key (preserves order/sorting)
+
+##### `useSelectPksByIndexKeysArrayBased(reactiveIndex, keys)`
+
+Subscribes to primary keys indexed by multiple keys from an ArrayBased index.
+
+**Parameters:**
+- `reactiveIndex: OIMReactiveIndexArrayBased<TKey, TPk, TIndex>` - ArrayBased reactive index instance
+- `keys: readonly TKey[]` - Array of index keys to query
+
+**Returns:**
+- `Map<TKey, TPk[]>` - Map of index keys to their corresponding primary key arrays (preserves order)
 
 ## Context API Reference
 
@@ -306,17 +565,9 @@ Creates a custom collections context with specific typing.
 
 ### Type Utilities
 
-#### `StrictCollectionsDictionary<T>`
-
-Ensures collections dictionary maintains exact types.
-
 #### `CollectionsDictionary`
 
-Base type for any collections dictionary.
-
-#### `ExtractEntityType<T>`, `ExtractPkType<T>`, etc.
-
-Type utilities for extracting specific types from collections.
+Base type for any collections dictionary. Use `typeof` to extract types from your collection instances, or define explicit types using `OIMRICollection` generics.
 
 ## Architecture
 
@@ -327,7 +578,19 @@ The hooks work directly with OIMDB reactive objects:
 ```typescript
 // Use reactive collections and indexes directly
 const user = useSelectEntityByPk(reactiveCollection, 'user123');
-const posts = useSelectEntitiesByIndexKey(reactiveCollection, reactiveIndex, 'tech');
+
+// Use appropriate hook based on index type
+const posts = useSelectEntitiesByIndexKeySetBased(
+  reactiveCollection, 
+  reactiveIndexSetBased, // SetBased index
+  'tech'
+);
+
+const orderedCards = useSelectEntitiesByIndexKeyArrayBased(
+  reactiveCollection,
+  reactiveIndexArrayBased, // ArrayBased index
+  'deck1'
+);
 ```
 
 ### Event Subscription
@@ -339,6 +602,15 @@ Hooks automatically subscribe to OIMDB reactive events using `useSyncExternalSto
 - **Optimized subscriptions**: Subscribe only to specific keys for efficient updates
 - **Automatic cleanup**: Unsubscribe when component unmounts
 
+### Index Type Selection
+
+When working with indexes, choose the appropriate hook based on your index type:
+
+- **SetBased indexes** (`OIMReactiveIndexManualSetBased`): Use `*SetBased` hooks (e.g., `useSelectPksByIndexKeySetBased`) - returns `Set<TPk>`
+- **ArrayBased indexes** (`OIMReactiveIndexManualArrayBased`): Use `*ArrayBased` hooks (e.g., `useSelectPksByIndexKeyArrayBased`) - returns `TPk[]` (preserves order)
+
+This ensures type safety and correct return types. TypeScript will enforce the correct hook usage based on your index type.
+
 ### Performance
 
 - **React 18+ Integration**: Uses `useSyncExternalStore` for optimal performance
@@ -353,8 +625,18 @@ Hooks automatically subscribe to OIMDB reactive events using `useSyncExternalSto
 
 ```typescript
 import React from 'react';
-import { OIMEventQueue, OIMRICollection, OIMReactiveIndexManual } from '@oimdb/core';
-import { useSelectEntityByPk, useSelectEntitiesByPks, useSelectEntitiesByIndexKey } from '@oimdb/react';
+import { 
+  OIMEventQueue, 
+  OIMRICollection, 
+  OIMReactiveIndexManualSetBased,
+  OIMReactiveIndexManualArrayBased 
+} from '@oimdb/core';
+import { 
+  useSelectEntityByPk, 
+  useSelectEntitiesByPks, 
+  useSelectEntitiesByIndexKeySetBased,
+  useSelectEntitiesByIndexKeyArrayBased 
+} from '@oimdb/react';
 
 interface User {
   id: string;
@@ -366,7 +648,8 @@ interface User {
 // Setup
 function createUserCollection() {
   const queue = new OIMEventQueue();
-  const teamIndex = new OIMReactiveIndexManual<string, string>(queue);
+  // Use SetBased for frequent add/remove operations
+  const teamIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
   
   return new OIMRICollection(queue, {
     collectionOpts: { selectPk: (user: User) => user.id },
@@ -386,9 +669,10 @@ function UserProfile({ userId }: { userId: string }) {
 }
 
 function TeamDashboard({ teamId }: { teamId: string }) {
-  const teamMembers = useSelectEntitiesByIndexKey(
+  // Use SetBased hook for SetBased index
+  const teamMembers = useSelectEntitiesByIndexKeySetBased(
     usersCollection,
-    usersCollection.indexes.byTeam,
+    usersCollection.indexes.byTeam, // OIMReactiveIndexManualSetBased
     teamId
   );
   
@@ -396,7 +680,7 @@ function TeamDashboard({ teamId }: { teamId: string }) {
     <div>
       <h3>Team Members ({teamMembers.length})</h3>
       {teamMembers.map(user => (
-        <div key={user.id}>{user.name}</div>
+        <div key={user?.id}>{user?.name}</div>
       ))}
     </div>
   );
@@ -444,10 +728,20 @@ const user = useEntity(userStorage, 'user123');
 const users = useEntities(userStorage, userIds);
 const posts = useIndex(postStorage, categoryIndex, 'tech');
 
-// v1.x - Reactive collections
+// v1.x - Reactive collections with typed indexes
 const user = useSelectEntityByPk(reactiveCollection, 'user123');
 const users = useSelectEntitiesByPks(reactiveCollection, userIds);
-const posts = useSelectEntitiesByIndexKey(reactiveCollection, reactiveIndex, 'tech');
+// Use appropriate hook based on index type
+const posts = useSelectEntitiesByIndexKeySetBased(
+  reactiveCollection, 
+  reactiveIndexSetBased, 
+  'tech'
+);
+const orderedItems = useSelectEntitiesByIndexKeyArrayBased(
+  reactiveCollection,
+  reactiveIndexArrayBased,
+  'category1'
+);
 ```
 
 ### Collection Creation