reselect-kit 1.0.1 → 1.1.1

package/README.md

@@ -21,13 +21,15 @@ A powerful toolkit that extends the capabilities of @veksa/reselect and @veksa/r
 - **Bound Selectors** - Create selectors with predefined parameters for reuse across components
 - **Adapted Selectors** - Transform selector parameters to simplify composition and reuse
 - **Enhanced Structured Selectors** - Better typed alternatives to createStructuredSelector with caching support
+- **Batched Store Reads** - Read a whole group of selectors through a single store subscription with `useSelectors`
 - **Key Selector Composition** - Compose key selectors for complex cache keys in re-reselect
 - **Custom Caching** - Optimize performance with advanced garbage collection and cache strategies
 - **TypeScript Support** - Full TypeScript type definitions with strict typing
 
 ## Installation
 
-reselect-kit requires **TypeScript 5.8 or later**.
+reselect-kit requires **TypeScript 5.4 or later** — the floor the type tests run
+against on every commit, together with every minor up to 7.0.
 
 ### Using npm or yarn
 
@@ -39,6 +41,37 @@ npm install reselect-kit
 yarn add reselect-kit
 ```
 
+### Upgrading from 1.0.x
+
+Props are no longer a type parameter of their own: a selector is typed by the
+tuple of arguments it takes after `state`, and a parametric selector is simply
+one whose tuple is not empty. Call sites that let the types be inferred are
+unaffected. Ones that spell the type arguments out move the props into the tuple:
+
+```typescript
+// before
+useSelector<State, PersonProps, Person>(getPerson, { personId: 1 });
+createPathSelector<State, Person, PersonProps>(getPerson);
+createChainSelector<State, PersonProps, Person>(getPerson);
+
+// after
+useSelector<State, Person, [PersonProps]>(getPerson, { personId: 1 });
+createPathSelector<State, Person, [PersonProps]>(getPerson);
+createChainSelector<State, Person, [PersonProps]>(getPerson);
+```
+
+`createCachedSequenceSelector` infers everything from the array it is given, so
+its type arguments cannot be written out at all — annotate `state` in the
+selectors instead.
+
+Two more consequences of the same change:
+
+- a sequence returns a tuple of the individual result types rather than `R[]`,
+  which is what makes each position keep its own type;
+- a chain step that reads props now makes them required for the whole built
+  selector even when the base selector had none. That type used to be dropped,
+  so this surfaces as a new error on code that was already passing the props.
+
 ## Examples
 
 ### Comparing @veksa/reselect, @veksa/re-reselect, and reselect-kit
@@ -101,11 +134,11 @@ import { createPathSelector } from 'reselect-kit';
 const getUser = createPathSelector((state) => state.user);
 
 // For parametric selectors
-const getUserByUserId = createPathSelector((state, userId) => state.users?.[userId]);
+const getUserByUserId = createPathSelector((state, props) => state.users?.[props.userId]);
 
-// Usage:
-const address = getUser(state).address(); // Safely returns undefined if path is broken
-const userAddress = getUserByUserId(state, '123').address(); // With parameters
+// Walking the path builds a selector; calling it reads the store
+const address = getUser.address()(state); // Safely returns undefined if path is broken
+const userAddress = getUserByUserId.address()(state, { userId: '123' }); // With parameters
 ```
 
 reselect-kit provides safer property access with path selectors that handle null/undefined values automatically.
@@ -186,13 +219,14 @@ const getUserByNameAndRole = createSelector(
   (users, userName, userRole) => users[userName][userRole],
 );
 
-const getAdmin = createAdaptedSelector(getUserByNameAndRole, (props) => ({
-  userName: props.userName,
+const getAdmin = createAdaptedSelector(getUserByNameAndRole, (props: { name: string }) => ({
+  userName: props.name,
   userRole: 'admin',
 }));
 
-// Usage:
-const admin = getAdmin(state); // Same as getUserByName(state, {userName: 'admin'})
+// Usage: the adapted selector takes the props the mapping accepts
+const admin = getAdmin(state, { name: 'alice' });
+// Same as getUserByNameAndRole(state, {userName: 'alice', userRole: 'admin'})
 ```
 
 #### Chain Selectors
@@ -223,17 +257,46 @@ import { createCachedStructuredSelector } from 'reselect-kit';
 const getUserProfile = createCachedStructuredSelector({
   name: (state) => state.user.name,
   email: (state) => state.user.email,
-  address: createPathSelector(
-    (state) => state.user,
-    (user) => user?.contact?.address,
-  ),
-})((state, userId) => userId);
+  address: createPathSelector((state) => state.user).contact.address(),
+})({
+  keySelector: (state, props) => props.userId,
+});
 
 // Usage:
-const profile = getUserProfile(state, '123');
+const profile = getUserProfile(state, { userId: '123' });
 // Returns: { name: 'John', email: 'john@example.com', address: { ... } }
 ```
 
+### Reading a Batch of Selectors in a Component
+
+The same structural idea at the call site: `useSelectors` takes an object of
+selectors and reads them all through one store subscription.
+
+```typescript
+import { useSelectors } from 'reselect-kit';
+
+const QuoteRow = ({ symbol }) => {
+  const { bid, ask, volume } = useSelectors({ bid: getBid, ask: getAsk, volume: getVolume }, { symbol });
+
+  return <Row bid={bid} ask={ask} volume={volume} />;
+};
+```
+
+Which of the two to use is a question of where the memoization should live, not
+of speed — they perform the same:
+
+|              | `createCachedStructuredSelector`              | `useSelectors`                   |
+| ------------ | --------------------------------------------- | -------------------------------- |
+| What it is   | a selector: composable, usable outside React  | a read at the call site only     |
+| Memoization  | one module-level cache, keyed                 | one slot per component instance  |
+| Cache key    | a key selector is required                    | none                             |
+| Cache sizing | must hold every live row, or it thrashes      | dies with the component          |
+| Sharing      | two components with the same key compute once | every component computes its own |
+
+Reuse the batch elsewhere, or feed it into another selector — build a structured
+selector. If the batch is simply "what this component reads", reach for the hook
+and skip the key selector and the cache sizing.
+
 ### Key Selector Composition
 
 ```typescript
@@ -269,13 +332,19 @@ createChainSelector(baseSelector).map(transformFn).build();
 Transforms the output of the previous selector by creating a new selector based on its result. This is where the real power of chain selectors comes in, allowing composition of selectors where the output of one becomes the context for creating the next.
 
 ```typescript
-chain<S2, R2>(fn: (result: R1) => Selector<S2, R2>, options?: ChainSelectorOptions): SelectorMonad
-chain<S2, P2, R2>(fn: (result: R1) => Selector<S2, R2, [P2]>, options?: ChainSelectorOptions): SelectorMonad
+chain<S2, R2, Params2>(
+  fn: (result: R1) => (state: S2, ...params: Params2) => R2,
+  options?: ChainSelectorOptions,
+): ChainSelectorResult
 ```
 
 - **fn** - Function that receives the previous selector's result and returns a new selector
 - **options** - Optional configuration for caching and key selection
 
+A step reading props adds them to what the built selector requires, whether or
+not the base selector had any: the arguments of every level are merged rather
+than the level having to match the base.
+
 **Examples:**
 
 ```typescript
@@ -319,6 +388,29 @@ Transforms the output of the selector with a simple transformation function. Unl
 map<R2>(fn: (result: R1) => R2, options?: ChainSelectorOptions): SelectorMonad
 ```
 
+###### Keyed levels
+
+A level only gets a keyed cache when its key can actually vary. Where the key is
+a constant, the cache would hold a single entry for the lifetime of the chain
+while every call still paid for the key computation and the lookup guarding it,
+so the level is built as a plain memoized selector instead — the same mapping
+without the layer.
+
+What each level knows about its key differs:
+
+- a `map` level derives a plain `() => output`, never a cached selector, so its
+  key is its base's own and is composed once at build time. A chain of `map`s
+  over a plain (uncached) selector composes to the default key, and the built
+  selector then carries neither `keySelector` nor `cache`;
+- a `chain` level cannot know its key at build time, because the selector it
+  derives exists only per call and may itself be cached — chaining a bound
+  cached selector off a plain base is the ordinary case. So it always carries a
+  `keySelector` that resolves the derived selector's key. Over an uncached base
+  that key evaluates to the default, but it is not the default _selector_, so a
+  level built on top of it does take the keyed path and holds a single entry.
+
+Chaining off a cached selector is where those caches earn their keep.
+
 ###### build
 
 Completes the chain and returns the final selector function that can be used in components.
@@ -329,43 +421,56 @@ build(): Selector<S, R, Params>
 
 #### createPathSelector
 
-Creates a selector that safely accesses nested properties.
+Creates a selector that safely accesses nested properties. Property access walks
+the path and the call terminates it, producing the selector.
 
 ```typescript
-createPathSelector(sourceSelector, pathFn);
+createPathSelector(sourceSelector).some.nested.path();
 ```
 
 #### createBoundSelector
 
-Creates a selector with predefined parameters.
+Creates a selector with predefined props. Whatever the binding does not supply
+stays required; a binding covering every prop leaves a plain selector.
 
 ```typescript
-createBoundSelector(selector, getParams);
+createBoundSelector(selector, binding);
 ```
 
 #### createAdaptedSelector
 
-Adapts a selector to work with a different parameter shape.
+Adapts a selector to work with a different props shape. The adapted selector
+takes the props the mapping accepts, in place of the ones the base selector reads.
 
 ```typescript
-createAdaptedSelector(selector, paramsAdapter);
+createAdaptedSelector(selector, propsAdapter);
 ```
 
 #### createCachedStructuredSelector
 
-Creates a structured selector with caching support.
+Creates a structured selector with caching support. The second call takes either
+re-reselect's options object or the key selector on its own.
 
 ```typescript
-createCachedStructuredSelector(selectors)(keySelector);
+createCachedStructuredSelector(selectors)({ keySelector });
 ```
 
+The key selector is typed from the batch, so its `state` and props are the ones
+the batch reads.
+
+The second call needs a way to derive the key: a `keySelector`, given on its own
+or inside the options, or a `keySelectorCreator` that produces one. re-reselect
+types both as optional, so an options object carrying neither compiles and then
+throws on the first read.
+
 #### createEmptySelector
 
 Creates a selector that always returns `undefined` regardless of input. Useful as a placeholder or for conditional selection logic.
 
 ```typescript
 const emptySelector = createEmptySelector(baseSelector);
-// Always returns undefined while maintaining the original selector's signature
+// Always returns undefined; the result widens to `R | undefined` and the
+// selector takes whatever arguments it is called with
 ```
 
 #### createPropSelector
@@ -378,12 +483,7 @@ const propSelector = createPropSelector();
 
 // In a chain
 const userByIdSelector = createChainSelector(propSelector)
-  .chain((props) =>
-    createPathSelector(
-      (state) => state.users[props.userId],
-      (user) => user,
-    ),
-  )
+  .chain((props) => createPathSelector((state) => state.users[props.userId]).profile())
   .build();
 ```
 
@@ -400,7 +500,10 @@ const getUserSettings = createSegmentSelector(
 
 #### createSequenceSelector
 
-Creates a selector that returns an array of results from multiple selectors.
+Runs a group of selectors and collects their results positionally. The result is
+a tuple of the individual result types, and `state` and the extra arguments are
+merged across the group, so a single parametric member makes props required for
+the whole sequence.
 
 ```typescript
 const getUserStats = createSequenceSelector([
@@ -409,7 +512,163 @@ const getUserStats = createSequenceSelector([
   (state) => state.user.likesCount,
 ]);
 
-// Returns [postsCount, followersCount, likesCount]
+// getUserStats(state) returns [postsCount, followersCount, likesCount]
+```
+
+#### createCachedSequenceSelector
+
+The cached counterpart of `createSequenceSelector`: the second call takes
+re-reselect's options, with the key selector typed from the group.
+
+```typescript
+const getPostStats = createCachedSequenceSelector([
+  (state, props) => state.posts[props.postId].likes,
+  (state, props) => state.posts[props.postId].comments,
+])({
+  keySelector: (state, props) => props.postId,
+});
+
+// getPostStats(state, { postId: 1 }) returns [likes, comments]
+```
+
+### Hooks
+
+#### useSelector
+
+Reads one selector from the store. Props are compared shallowly, so an inline
+object literal does not invalidate the selector on every render.
+
+```typescript
+const price = useSelector(getPrice, { symbol });
+```
+
+#### useSelectors
+
+Reads a batch of selectors through a **single** store subscription and returns
+their results as one object.
+
+```typescript
+const { symbol, bid, ask } = useSelectors(
+  { symbol: getSymbol, bid: getBid, ask: getAsk },
+  { symbol },
+);
+```
+
+The props argument follows the batch: it is rejected when no selector takes
+props, required as soon as one requires them, and optional when every selector
+that reads props declares them optional. The props of the batch are intersected,
+so one object satisfies every member.
+
+Every member is read as `selector(state, props)`, so a selector that requires a
+third argument does not belong in a batch — the batch has nothing to pass for it
+and it arrives as `undefined`.
+
+Seven `useSelector` calls in a row component mean seven store listeners, seven
+`useSyncExternalStore` instances and seven snapshot comparisons per dispatch;
+`useSelectors` collapses them into one of each. The result object keeps its
+reference while every field is unchanged, so an update that touches nothing the
+row reads does not re-render it.
+
+The trade-off against separate hooks is granularity: any tracked state segment
+changing re-runs the whole batch, which for memoized selectors is a cache hit
+per field. See [Reading a Batch of Selectors in a Component](#reading-a-batch-of-selectors-in-a-component)
+for how this compares with a structured selector.
+
+### Key Selectors
+
+#### stringComposeKeySelectors
+
+Composes several key selectors into one that joins their keys with `:`. The
+result carries its inputs as `dependencies`, which is what lets
+`createBoundSelector` drop the key selectors whose props it has bound.
+
+```typescript
+const keySelector = stringComposeKeySelectors(
+  (state, props) => props.userId,
+  (state, props) => props.view,
+);
+
+// keySelector(state, { userId: '123', view: 'details' }) returns '123:details'
+```
+
+#### arrayComposeKeySelectors
+
+The same composition, producing an array key instead of a string — for cache
+objects that take multi-part keys, such as [TreeCache](#treecache). Nested array
+keys are flattened.
+
+```typescript
+const keySelector = arrayComposeKeySelectors(
+  (state, props) => props.userId,
+  (state, props) => props.view,
+);
+
+// keySelector(state, { userId: '123', view: 'details' }) returns ['123', 'details']
+```
+
+#### createKeySelectorComposer
+
+Builds a composer of your own from a function that reduces N key selectors into
+one. Both composers above are built with it.
+
+```typescript
+const commaComposeKeySelectors = createKeySelectorComposer(
+  (...keySelectors) =>
+    (state, props) =>
+      keySelectors.map((keySelector) => keySelector(state, props)).join(),
+);
+```
+
+#### createKeySelectorCreator
+
+Builds the `keySelectorCreator` that re-reselect calls to derive a selector's key
+from its inputs: it collects the key selectors of every cached input, flattens
+already-composed ones, drops duplicates and the default key, and composes what is
+left with the given composer.
+
+```typescript
+const fullNameSelector = createCachedSelector(
+  [personByMessageIdSelector],
+  toFullName,
+)({
+  keySelectorCreator: createKeySelectorCreator(stringComposeKeySelectors),
+});
+```
+
+A chain builds its own creator from the `keySelectorComposer` it was given, so
+inside a chain the composer is what you configure, not the creator.
+
+#### defaultKeySelector
+
+The key of a selector that has nothing to key on — a single constant. Key
+composition drops it, so a chain whose key cannot vary carries no cache at all.
+
+#### ChainSelectorOptions
+
+The options every chain level accepts, either on `createChainSelector` itself or
+per `chain` / `map` call. A per-level object overrides what the chain was created
+with, and the merged result carries to the levels after it.
+
+```typescript
+type ChainSelectorOptions = {
+  // called per level, so each one gets its own cache object
+  createSelectorOptions?: () => { selectorCreator; cacheObject };
+  keySelectorComposer?: KeySelectorComposer;
+};
+```
+
+### Debugging
+
+#### setDebugMode / isDebugMode
+
+Debug mode makes every creator tag the selectors it builds with a readable
+`selectorName`, composed from the names of what they were built from. It is off
+by default, since the names cost string work on every build.
+
+```typescript
+import { setDebugMode } from 'reselect-kit';
+
+setDebugMode(process.env.NODE_ENV !== 'production');
 ```
 
 ### Cache Objects
@@ -418,12 +677,17 @@ const getUserStats = createSequenceSelector([
 
 Implements a hierarchical cache structure for nested key support. Unlike flat cache objects, TreeCache allows for efficiently caching and retrieving selectors with complex, multi-part keys.
 
+Pair it with [arrayComposeKeySelectors](#arraycomposekeyselectors), which is what
+produces the multi-part keys it exists for.
+
 ```typescript
+import { FlatObjectCache } from '@veksa/re-reselect';
 import { TreeCache } from 'reselect-kit';
 
-// Create a TreeCache instance
+// The options object is required; `cacheObjectCreator` inside it is not, and
+// defaults to a FlatObjectCache per level
 const cache = new TreeCache({
-  cacheObjectCreator: () => new FlatObjectCache(), // Optional custom cache factory
+  cacheObjectCreator: () => new FlatObjectCache(),
 });
 
 // Use with complex keys (automatically normalized to arrays)
@@ -449,6 +713,11 @@ const cache = new IntervalMapCache();
 cache.set('key', selectorData);
 ```
 
+The sweep runs on a 10-second interval and evicts entries untouched for that
+long; reading an entry refreshes it. `initGarbageCollector` schedules through
+`window`, so it is a no-op where there is none — on the server the cache simply
+keeps what it is given. Calling it more than once does not stack collectors.
+
 ### Comparing with @veksa/reselect and @veksa/re-reselect
 
 | Feature                     | @veksa/reselect | @veksa/re-reselect | reselect-kit         |
@@ -462,6 +731,8 @@ cache.set('key', selectorData);
 | Advanced key composition    | ×               | Limited            | ✓                    |
 | Cache garbage collection    | ×               | ×                  | ✓                    |
 | Hierarchical caching        | ×               | ×                  | ✓                    |
+| Props-aware React hooks     | ×               | ×                  | ✓                    |
+| Batched store subscription  | ×               | ×                  | ✓                    |
 | Typescript support          | ✓               | ✓                  | ✓ (enhanced)         |
 
 ## Contributing