riducers 1.2.5 → 2.0.0

package/README.md

@@ -1,34 +1,328 @@
-# Dynamic Reducers for id based entities
+# riducers
 
-Plug and play reducers to frontend entity based RESTful APIs.
+Plug-and-play Redux reducers for entity-based state management. Supports four state types optimized for different use cases.
 
-These reducers come with insert, delete, replace, clear, and sort action types. Intercept AJAX API calls and dispatch appropriate events to maintain the entity states in redux automagically. 
+## Installation
 
-## Usage
+```bash
+npm install riducers
+```
+
+## State Types
+
+| Type | State Shape | Best For |
+|------|-------------|----------|
+| `list` | `ModelObj[]` | Ordered collections |
+| `map` | `{ [id]: ModelObj }` | Fast lookups by ID |
+| `mapList` | `{ [key]: ModelObj[] }` | Grouped/categorized data |
+| `static` | `ModelObj \| null` | Single objects (auth, settings) |
 
-### Initializing the reducers
+## Quick Start
 
-```TypeScript
+```typescript
 import { configureStore } from '@reduxjs/toolkit'
 import { reducerBuilder } from 'riducers'
-import { combineReducers } from 'redux'
 
-const reducer = {
-  users: reducerBuilder('user', {stateType: 'list'}),
-  auth: reducerBuilder('auth', {}),
-  ui: {
-    api: reducerBuilder('ui/api', { stateType: 'map'}),
+const store = configureStore({
+  reducer: {
+    users: reducerBuilder('users', { stateType: 'list' }),
+    usersById: reducerBuilder('usersById', { stateType: 'map' }),
+    tasksByProject: reducerBuilder('tasks', { stateType: 'mapList', mapKeyName: 'projectId' }),
+    currentUser: reducerBuilder('currentUser'),
   }
+})
+```
+
+---
+
+## 1. List Reducer (`stateType: 'list'`)
+
+Stores entities as an ordered array. Supports: `insert`, `unshift`, `replace`, `delete`, `shift`, `sort`, `clear`.
+
+```typescript
+const usersReducer = reducerBuilder('users', { stateType: 'list' })
+```
+
+### Actions & State Transitions
+
+```typescript
+// Initial state
+state = []
+
+// insert - append items
+dispatch({ type: 'users/insert', payload: { id: 1, name: 'Alice' } })
+state = [{ id: 1, name: 'Alice' }]
+
+dispatch({ type: 'users/insert', payload: [{ id: 2, name: 'Bob' }, { id: 3, name: 'Carol' }] })
+state = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Carol' }]
+
+// unshift - prepend item
+dispatch({ type: 'users/unshift', payload: { id: 0, name: 'Zoe' } })
+state = [{ id: 0, name: 'Zoe' }, { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Carol' }]
+
+// delete - remove by id
+dispatch({ type: 'users/delete', payload: { id: 2 } })
+state = [{ id: 0, name: 'Zoe' }, { id: 1, name: 'Alice' }, { id: 3, name: 'Carol' }]
+
+// shift - remove first item
+dispatch({ type: 'users/shift' })
+state = [{ id: 1, name: 'Alice' }, { id: 3, name: 'Carol' }]
+
+// sort - reorder (default: ascending by keyName)
+dispatch({ type: 'users/sort' })
+state = [{ id: 1, name: 'Alice' }, { id: 3, name: 'Carol' }]
+
+// sort with custom comparator
+dispatch({ type: 'users/sort', sort: (a, b) => b.id - a.id })
+state = [{ id: 3, name: 'Carol' }, { id: 1, name: 'Alice' }]
+
+// replace - replace entire state
+dispatch({ type: 'users/replace', payload: [{ id: 10, name: 'New' }] })
+state = [{ id: 10, name: 'New' }]
+
+// clear - reset to initial state
+dispatch({ type: 'users/clear' })
+state = []
+```
+
+### With Auto-Sort
+
+```typescript
+const sortedReducer = reducerBuilder('users', {
+  stateType: 'list',
+  sort: (a, b) => a.name.localeCompare(b.name)
+})
+
+dispatch({ type: 'users/insert', payload: [{ id: 1, name: 'Zoe' }, { id: 2, name: 'Alice' }] })
+state = [{ id: 2, name: 'Alice' }, { id: 1, name: 'Zoe' }]  // auto-sorted
+```
+
+---
+
+## 2. Map Reducer (`stateType: 'map'`)
+
+Stores entities keyed by ID for O(1) lookups. Supports: `insert`, `replace`, `delete`, `clear`.
+
+```typescript
+const usersReducer = reducerBuilder('users', { stateType: 'map' })
+```
+
+### Actions & State Transitions
+
+```typescript
+// Initial state
+state = {}
+
+// insert - add/update items
+dispatch({ type: 'users/insert', payload: { id: 1, name: 'Alice' } })
+state = { 1: { id: 1, name: 'Alice' } }
+
+dispatch({ type: 'users/insert', payload: [{ id: 2, name: 'Bob' }, { id: 3, name: 'Carol' }] })
+state = {
+  1: { id: 1, name: 'Alice' },
+  2: { id: 2, name: 'Bob' },
+  3: { id: 3, name: 'Carol' }
 }
 
-const store = configureStore({ reducer })
+// insert updates existing item
+dispatch({ type: 'users/insert', payload: { id: 1, name: 'Alice Updated' } })
+state = {
+  1: { id: 1, name: 'Alice Updated' },
+  2: { id: 2, name: 'Bob' },
+  3: { id: 3, name: 'Carol' }
+}
+
+// delete - remove by id
+dispatch({ type: 'users/delete', payload: { id: 2 } })
+state = {
+  1: { id: 1, name: 'Alice Updated' },
+  3: { id: 3, name: 'Carol' }
+}
 
-store.dispatch('user/insert', {payload: [{id: 1, name: 'John'}]})
-store.dispatch('user/delete', {payload: [{id: 1}]})
-store.dispatch('user/replace', {payload: [{id: 1, name: 'Foo'}, {id: 2, name: 'Bar'}]})
-store.dispatch('user/sort', {})
-store.dispatch('user/clear', {})
+// replace - replace entire state
+dispatch({ type: 'users/replace', payload: [{ id: 10, name: 'New' }] })
+state = { 10: { id: 10, name: 'New' } }
 
+// clear - reset to initial state
+dispatch({ type: 'users/clear' })
+state = {}
 ```
 
-See the Jest tests (test/main.test.ts) for more action types and uses.
+### Shorthand Syntax
+
+Map reducers support using the key directly as the action type:
+
+```typescript
+// Insert/update using key as action type
+dispatch({ type: 'users/123', payload: { name: 'Alice' } })
+state = { 123: { id: 123, name: 'Alice' } }
+
+// Delete by dispatch with no payload
+dispatch({ type: 'users/123', payload: null })
+state = {}
+```
+
+---
+
+## 3. MapList Reducer (`stateType: 'mapList'`)
+
+Groups entities into keyed arrays—ideal for categorized data. Requires `mapKeyName`. Supports: `insert`, `unshift`, `replace`, `delete`, `shift`, `sort`, `clear`.
+
+```typescript
+const tasksReducer = reducerBuilder('tasks', {
+  stateType: 'mapList',
+  keyName: 'id',
+  mapKeyName: 'projectId',
+  initialState: {}
+})
+```
+
+### Actions & State Transitions
+
+```typescript
+// Initial state
+state = {}
+
+// insert - items grouped by mapKeyName
+dispatch({ type: 'tasks/insert', payload: { id: 1, projectId: 'a', title: 'Task 1' } })
+state = {
+  a: [{ id: 1, projectId: 'a', title: 'Task 1' }]
+}
+
+dispatch({ type: 'tasks/insert', payload: [
+  { id: 2, projectId: 'a', title: 'Task 2' },
+  { id: 3, projectId: 'b', title: 'Task 3' }
+]})
+state = {
+  a: [{ id: 1, projectId: 'a', title: 'Task 1' }, { id: 2, projectId: 'a', title: 'Task 2' }],
+  b: [{ id: 3, projectId: 'b', title: 'Task 3' }]
+}
+
+// delete - items removed across all groups, empty groups removed
+dispatch({ type: 'tasks/delete', payload: { id: 3 } })
+state = {
+  a: [{ id: 1, projectId: 'a', title: 'Task 1' }, { id: 2, projectId: 'a', title: 'Task 2' }]
+}
+
+// sort - sorts within each group
+dispatch({ type: 'tasks/sort', sort: (a, b) => b.id - a.id })
+state = {
+  a: [{ id: 2, projectId: 'a', title: 'Task 2' }, { id: 1, projectId: 'a', title: 'Task 1' }]
+}
+
+// shift - removes first item from each group
+dispatch({ type: 'tasks/shift' })
+state = {
+  a: [{ id: 1, projectId: 'a', title: 'Task 1' }]
+}
+
+// replace - replace entire state
+dispatch({ type: 'tasks/replace', payload: [{ id: 10, projectId: 'x', title: 'New' }] })
+state = {
+  x: [{ id: 10, projectId: 'x', title: 'New' }]
+}
+
+// clear - reset to initial state
+dispatch({ type: 'tasks/clear' })
+state = {}
+```
+
+---
+
+## 4. Static Reducer (default)
+
+Stores a single object or null. Supports: `insert`, `replace`, `delete`, `clear`.
+
+```typescript
+const authReducer = reducerBuilder('auth')
+```
+
+### Actions & State Transitions
+
+```typescript
+// Initial state
+state = null
+
+// insert - set the object
+dispatch({ type: 'auth/insert', payload: { userId: 1, token: 'abc123' } })
+state = { userId: 1, token: 'abc123' }
+
+// replace - replace entire object
+dispatch({ type: 'auth/replace', payload: { userId: 2, token: 'xyz789' } })
+state = { userId: 2, token: 'xyz789' }
+
+// delete - set to null
+dispatch({ type: 'auth/delete' })
+state = null
+
+// clear - reset to initial state
+dispatch({ type: 'auth/clear' })
+state = null
+```
+
+---
+
+## Options
+
+```typescript
+interface ReducerOpts {
+  stateType?: 'list' | 'map' | 'static' | 'mapList'  // default: 'static'
+  keyName?: string       // ID field name, default: 'id'
+  mapKeyName?: string    // Required for mapList - key to group by
+  sort?: SortFn          // Auto-sort on insert
+  initialState?: any     // Custom initial state
+}
+```
+
+## Full Store Example
+
+```typescript
+import { configureStore } from '@reduxjs/toolkit'
+import { reducerBuilder } from 'riducers'
+
+const store = configureStore({
+  reducer: {
+    // Ordered list of posts
+    posts: reducerBuilder('posts', { stateType: 'list' }),
+    
+    // Users indexed by ID for quick lookup
+    users: reducerBuilder('users', { stateType: 'map' }),
+    
+    // Comments grouped by postId
+    comments: reducerBuilder('comments', {
+      stateType: 'mapList',
+      mapKeyName: 'postId',
+      initialState: {}
+    }),
+    
+    // Current authenticated user
+    auth: reducerBuilder('auth'),
+  }
+})
+
+// After some dispatches, state might look like:
+// {
+//   posts: [
+//     { id: 1, title: 'Hello World' },
+//     { id: 2, title: 'Redux Tips' }
+//   ],
+//   users: {
+//     1: { id: 1, name: 'Alice' },
+//     2: { id: 2, name: 'Bob' }
+//   },
+//   comments: {
+//     1: [
+//       { id: 101, postId: 1, text: 'Great post!' },
+//       { id: 102, postId: 1, text: 'Thanks!' }
+//     ],
+//     2: [
+//       { id: 201, postId: 2, text: 'Very helpful' }
+//     ]
+//   },
+//   auth: { userId: 1, token: 'abc123' }
+// }
+```
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "riducers",
-  "version": "1.2.5",
-  "description": "Dynamic reducers with insert, delete, replace, clear, and sort actions on 'id' based list of objects",
+  "version": "2.0.0",
+  "description": "Plug-and-play Redux reducers for entity-based state management. Supports list, map, mapList, and static state types with built-in insert, delete, replace, sort, and clear actions.",
   "main": "dist/index.js",
   "module": "esm/index.js",
   "files": [
@@ -26,13 +26,13 @@
   "author": "Yusuf Bhabhrawala",
   "license": "ISC",
   "devDependencies": {
-    "@types/jest": "^29.2.0",
-    "jest": "^29.2.1",
-    "rimraf": "^3.0.2",
-    "ts-jest": "^29.0.3",
-    "typescript": "^4.8.4"
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "rimraf": "^6.1.3",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "redux": "^4.2.1"
+    "redux": "^5.0.1"
   }
 }

package/src/helpers.ts

@@ -0,0 +1,27 @@
+import { ModelObj, SortFn } from "./types";
+
+/**
+ * Creates a sort function that sorts by a specific key
+ */
+export const keySort = (key: string): SortFn => (a: ModelObj, b: ModelObj) => {
+  if (typeof a[key] === "number" && typeof b[key] === "number") {
+    return a[key] - b[key];
+  } else if (typeof a[key] === "string" && typeof b[key] === "string") {
+    return a[key].localeCompare(b[key]);
+  }
+  return 0;
+};
+
+/**
+ * Normalizes payload to always be an array
+ */
+export const normalizePayload = <T>(payload: T | T[]): T[] => {
+  return Array.isArray(payload) ? payload : [payload];
+};
+
+/**
+ * Initializes state with default value if undefined/null
+ */
+export const initializeState = <T>(state: T | undefined | null, defaultValue: T): T => {
+  return state ?? defaultValue;
+};

package/src/index.ts

@@ -1,241 +1,244 @@
-type Id = number | string;
+import { ReducerOpts, ReducerAction, ModelObj, SortFn } from "./types";
+import { mapInsertReducer, mapDeleteReducer, mapReplaceReducer } from "./mapReducers";
+import {
+  listInsertReducer,
+  listUnshiftReducer,
+  listSortReducer,
+  listDeleteReducer,
+  listShiftReducer,
+  listReplaceReducer
+} from "./listReducers";
+import {
+  mapListInsertReducer,
+  mapListDeleteReducer,
+  mapListReplaceReducer,
+  mapListSortReducer,
+  mapListShiftReducer,
+  mapListUnshiftReducer,
+  MapListState
+} from "./mapListReducers";
+import { objInsertReducer, objReplaceReducer, objDeleteReducer } from "./objReducers";
+
+// Re-export types for external usage
+export * from "./types";
+export { keySort } from "./helpers";
 
-interface ModelObj {
-  [key: string]: any;
-}
-
-type SortFn = (a: ModelObj, b: ModelObj) => number;
-
-interface ListAction {
-  payload: ModelObj | ModelObj[];
-  sort?: SortFn;
-  keyName: string;
-  mapKeyName?: string;
-  isMapList: boolean;
-}
-
-interface MapAction {
-  payload: ModelObj | ModelObj[];
-  sort?: SortFn;
-  keyName: string;
-}
-
-interface ListSortAction {
-  sort?: SortFn;
-  keyName: string;
-  mapKeyName?: string;
-  isMapList: boolean;
-}
-
-const keySort = (key: string) => (a: ModelObj, b: ModelObj) => {
-  if (typeof a[key] === "number" && typeof b[key] === "number") return a[key] - b[key];
-  else if (typeof a[key] === "string" && typeof b[key] === "string") return a[key].localeCompare(b[key]);
-  return 0;
-};
+const OPS = ["insert", "replace", "delete", "clear", "sort"];
 
-const mapInsertReducer = (state: ModelObj, action: MapAction) => {
-  if (!state) state = {};
-  let resp: ModelObj[] = Array.isArray(action.payload) ? action.payload : [action.payload];
-  let newState = { ...state };
-  for (let i in resp) {
-    if (resp[i]?.[action.keyName]) newState[resp[i][action.keyName]] = { ...resp[i] };
+/**
+ * Gets the default initial state based on state type
+ */
+const getDefaultInitialState = (stateType: string): any => {
+  switch (stateType) {
+    case "list":
+      return [];
+    case "map":
+      return {};
+    default:
+      return null;
   }
-  return newState;
 };
 
-const mapDeleteReducer = (state: ModelObj, action: MapAction) => {
-  if (!state) state = {};
-  let resp: ModelObj[] = Array.isArray(action.payload) ? action.payload : [action.payload];
-  let newState = { ...state };
-  for (let i in resp) {
-    delete newState[resp[i][action.keyName]];
+/**
+ * Handles map-specific operation normalization
+ * When using map type, allows using the key as the operation (e.g., "users/123" for insert/delete)
+ */
+const normalizeMapOperation = (
+  op: string,
+  payload: any,
+  keyName: string
+): { op: string; payload: any } => {
+  if (!OPS.includes(op)) {
+    if (payload && !Array.isArray(payload)) {
+      payload[keyName] = op;
+      return { op: "insert", payload };
+    }
+    if (!payload) {
+      const newPayload: ModelObj = { [keyName]: op };
+      return { op: "delete", payload: newPayload };
+    }
   }
-  return newState;
+  return { op, payload };
 };
 
-const mapReplaceReducer = (state: ModelObj, action: MapAction) => {
-  let newState = {} as any;
-  let resp: ModelObj[] = Array.isArray(action.payload) ? action.payload : [action.payload];
-  for (let i in resp) {
-    if (resp[i]?.[action.keyName]) newState[resp[i][action.keyName]] = { ...resp[i] };
+/**
+ * Handles list operations (insert, replace, delete, shift, sort)
+ */
+const handleListOperation = (
+  state: ModelObj[],
+  op: string,
+  payload: any,
+  sort: SortFn | undefined,
+  keyName: string,
+  initialState: any
+): ModelObj[] | undefined => {
+  const isMapList = false;
+  switch (op) {
+    case "insert":
+      if (payload) return listInsertReducer(state, { payload, sort, keyName, isMapList });
+      break;
+    case "unshift":
+      if (payload) return listUnshiftReducer(state, { payload, sort, keyName, isMapList });
+      break;
+    case "replace":
+      return listReplaceReducer(state, { payload, sort, keyName, isMapList });
+    case "delete":
+      return listDeleteReducer(state, { payload, keyName, isMapList });
+    case "shift":
+      return listShiftReducer(state);
+    case "clear":
+      return initialState;
+    case "sort":
+      return listSortReducer(state, { sort, keyName, isMapList });
   }
-  return newState;
+  return undefined;
 };
 
-const listInsertReducer = (state: ModelObj[], action: ListAction) => {
-  if (!state) state = [];
-  let resp: ModelObj[] = Array.isArray(action.payload) ? action.payload : [action.payload];
-
-  let newState = [...state];
-  let respMap: Id[] = resp.map((r: any) => r[action.keyName]);
-  let stateMap: Id[] = newState.map((r: any) => r[action.keyName]);
-  let toInsert: Id[] = respMap.filter((id: number | string) => stateMap.indexOf(id) < 0);
-  let toReplace: Id[] = respMap.filter((id: number | string) => stateMap.indexOf(id) >= 0);
-  for (let i in toReplace) {
-    let stateIndex = stateMap.indexOf(toReplace[i]);
-    let respIndex = respMap.indexOf(toReplace[i]);
-    newState[stateIndex] = { ...resp[respIndex] };
-  }
-  if (toInsert.length > 0) {
-    let inserts = toInsert.map((id: number | string) => resp[respMap.indexOf(id)]);
-    newState = [...newState, ...inserts];
+/**
+ * Handles mapList operations (insert, replace, delete, shift, sort, unshift)
+ * mapList is a hybrid: { [mapKeyValue]: ModelObj[] }
+ */
+const handleMapListOperation = (
+  state: MapListState,
+  op: string,
+  payload: any,
+  sort: SortFn | undefined,
+  keyName: string,
+  mapKeyName: string,
+  initialState: any
+): MapListState | undefined => {
+  switch (op) {
+    case "insert":
+      if (payload) return mapListInsertReducer(state, { payload, sort, keyName, mapKeyName });
+      break;
+    case "unshift":
+      if (payload) return mapListUnshiftReducer(state, { payload, sort, keyName, mapKeyName });
+      break;
+    case "replace":
+      return mapListReplaceReducer(state, { payload, sort, keyName, mapKeyName });
+    case "delete":
+      return mapListDeleteReducer(state, { payload, keyName, mapKeyName });
+    case "shift":
+      return mapListShiftReducer(state);
+    case "clear":
+      return initialState;
+    case "sort":
+      return mapListSortReducer(state, { sort, keyName, mapKeyName });
   }
-  if (action?.sort) newState.sort(action?.sort);
-  return newState;
-};
-
-const listUnshiftReducer = (state: ModelObj[], action: ListAction) => {
-  if (!state) state = [];
-  let resp: ModelObj[] = Array.isArray(action.payload) ? action.payload : [action.payload];
-
-  let newState = [...resp, ...state];
-  return newState;
-}
-
-const listSortReducer = (state: ModelObj[], action: ListSortAction) => {
-  if (!state) state = [];
-  let newState = [...state];
-  let sort = action?.sort ? action.sort : keySort(action.keyName);
-  newState.sort(sort);
-  return newState;
+  return undefined;
 };
 
-const listDeleteReducer = (state: ModelObj[], action: ListAction) => {
-  if (!state || !Array.isArray(state)) state = [];
-  let newState = [...state];
-  let resp: ModelObj[] = Array.isArray(action.payload) ? action.payload : [action.payload];
-
-  let stateMap: Id[] = newState.map((s: any) => s[action.keyName]);
-  for (let i in resp) {
-    let index = stateMap.indexOf(resp[i][action.keyName]);
-    if (index >= 0) newState.splice(index, 1);
+/**
+ * Handles map operations (insert, replace, delete, clear)
+ */
+const handleMapOperation = (
+  state: ModelObj,
+  op: string,
+  payload: any,
+  keyName: string,
+  initialState: any
+): ModelObj | null | undefined => {
+  switch (op) {
+    case "insert":
+      if (payload) return mapInsertReducer(state, { payload, keyName });
+      break;
+    case "replace":
+      return mapReplaceReducer(state, { payload, keyName });
+    case "delete":
+      return mapDeleteReducer(state, { payload, keyName });
+    case "clear":
+      return initialState;
   }
-  return newState;
+  return undefined;
 };
 
-const listShiftReducer = (state: ModelObj[]) => {
-  if (!state || !Array.isArray(state)) state = [];
-  let newState = [...state];
-  newState.shift();
-  return newState;
-}
-
-const listReplaceReducer = (state: ModelObj[], action: ListAction) => {
-  let resp: ModelObj[] = Array.isArray(action.payload) ? action.payload : [action.payload];
-  resp = resp.map((r: any) => ({ ...r }));
-  if (action?.sort) resp.sort(action?.sort);
-  return resp;
-};
-
-const objInsertReducer = (state: any, action: { payload: any }) => {
-  return action.payload;
+/**
+ * Handles static/object operations (insert, replace, delete, clear)
+ */
+const handleStaticOperation = (
+  state: any,
+  op: string,
+  payload: any,
+  initialState: any
+): any | undefined => {
+  switch (op) {
+    case "insert":
+      return objInsertReducer(state, { payload });
+    case "replace":
+      return objReplaceReducer(state, { payload });
+    case "delete":
+      return objDeleteReducer();
+    case "clear":
+      return initialState;
+  }
+  return undefined;
 };
 
-const objReplaceReducer = (state: any, action: { payload: any }) => {
-  return action.payload;
-};
+/**
+ * Builds a reducer function for managing state with various operations
+ */
+function reducerBuilder(key: string, opts?: ReducerOpts) {
+  const stateType = opts?.stateType ?? "static";
+  const isList = stateType === "list";
+  const isMap = stateType === "map";
+  const isMapList = stateType === "mapList";
 
-const objDeleteReducer = () => {
-  return null;
-};
+  if (isMapList && !opts?.mapKeyName) {
+    throw new Error("mapKeyName is required for stateType: mapList");
+  }
 
-interface ReducerOpts {
-  stateType?: "list" | "map" | "static" | "mapList";
-  sort?: SortFn;
-  keyName?: string;
-  mapKeyName?: string;
-  initialState?: any;
-}
+  // Use provided initialState if defined, otherwise get default based on state type
+  const initialState = opts?.initialState !== undefined ? opts.initialState : getDefaultInitialState(stateType);
+  const actionPattern = new RegExp(`^${key}/([^\/]+)$`);
 
-const OPS = ["insert", "replace", "delete", "clear", "sort"];
-function reducerBuilder(key: string, opts?: ReducerOpts) {
-  let initialState = opts?.initialState;
-  let stateType = opts?.stateType ?? "static";
-  let isList = stateType === "list";
-  let isMap = stateType === "map";
-  let isMapList = stateType === "mapList";
-
-  if (isMapList && !opts?.mapKeyName) throw new Error("mapKeyName is required for stateType: mapList");
-
-  if (initialState === undefined) {
-    if (isList) initialState = [];
-    else if (isMap) initialState = {};
-    else initialState = null;
-  }
-  return (state: any, action: { type: string; payload?: any; sort?: (a: ModelObj, b: ModelObj) => number }) => {
+  return (state: any, action: ReducerAction): any => {
+    // Initialize state
     if (state === undefined) {
-      if (initialState !== undefined) return initialState;
-      else if (isList) return [];
-      else if (isMap) return {};
-      else if (isMapList) return {};
-      else return null;
+      return initialState !== undefined ? initialState : getDefaultInitialState(stateType);
     }
-    let rx = new RegExp(`^${key}/([^\/]+)$`);
-    let m = action.type.match(rx);
-    if (!m) return state;
 
-    let op = m[1];
+    // Match action type
+    const match = action.type.match(actionPattern);
+    if (!match) return state;
+
+    let op = match[1];
     let payload = action.payload;
-    let keyName = opts?.keyName ?? "id";
-    let mapKeyName = opts?.mapKeyName;
-
-    if (isMap && !OPS.includes(op)) {
-      if (payload && !Array.isArray(payload)) {
-        payload[keyName] = op;
-        op = "insert";
-      }
-      if (!payload) {
-        payload = {};
-        payload[keyName] = op;
-        op = "delete";
-      }
+    const keyName = opts?.keyName ?? "id";
+    const mapKeyName = opts?.mapKeyName;
+    const sort = action.sort ?? opts?.sort;
+
+    // Handle map-specific operation normalization
+    if (isMap) {
+      const normalized = normalizeMapOperation(op, payload, keyName);
+      op = normalized.op;
+      payload = normalized.payload;
     }
 
-    let sort = action.sort ?? opts?.sort;
-    if (op === "insert") {
-
-      if ((isList || isMapList) && payload) return listInsertReducer(state, { payload, sort, keyName, mapKeyName, isMapList });
-      else if (isMap && payload) return mapInsertReducer(state, { payload, keyName });
-      return objInsertReducer(state, { payload });
-      
-    } else if (op === 'unshift') {
-      if (isList && payload) return listUnshiftReducer(state, { payload, sort, keyName, mapKeyName, isMapList });
-      else {
-        console.error(`unshift is only valid for stateType: list or mapList`);
-      }
-    } else if (op === "replace") {
-
-      if (isList || isMapList) return listReplaceReducer(state, { payload, sort, keyName, mapKeyName, isMapList });
-      else if (isMap) return mapReplaceReducer(state, { payload, keyName });
-      return objReplaceReducer(state, { payload });
-
-    } else if (op === "delete") {
-
-      if (isList || isMapList) return listDeleteReducer(state, { payload, keyName, mapKeyName, isMapList });
-      else if (isMap) return mapDeleteReducer(state, { payload, keyName });
-      return objDeleteReducer();
-
-    } else if (op === "shift") {
-      if (isList || isMapList) return listShiftReducer(state);
-      else {
-        console.error(`unshift is only valid for stateType: list or mapList`);
-      }
-
-    } else if (op === "clear") {
-
-      return initialState;
-
-    } else if (op === "sort") {
-
-      if (isList || isMapList) return listSortReducer(state, { sort, keyName, mapKeyName, isMapList });
+    // Handle operations based on state type
+    let result: any;
 
+    if (isList) {
+      result = handleListOperation(state, op, payload, sort, keyName, initialState);
+    } else if (isMapList) {
+      result = handleMapListOperation(state, op, payload, sort, keyName, mapKeyName!, initialState);
+    } else if (isMap) {
+      result = handleMapOperation(state, op, payload, keyName, initialState);
     } else {
+      result = handleStaticOperation(state, op, payload, initialState);
+    }
 
-      console.error(`unknown op (${op}) in action type: ${action.type}. Op should be one of: insert, delete, replace, clear, or sort.`);
+    if (result !== undefined) {
+      return result;
+    }
 
+    // Unknown operation
+    if (!["insert", "unshift", "replace", "delete", "shift", "clear", "sort"].includes(op)) {
+      console.error(
+        `unknown op (${op}) in action type: ${action.type}. Op should be one of: insert, delete, replace, clear, or sort.`
+      );
     }
-    
-    return state || (isList ? [] : isMap ? {} : null);
+
+    return state || getDefaultInitialState(stateType);
   };
 }
 

package/src/listReducers.ts

@@ -0,0 +1,86 @@
+import { ModelObj, Id, ListAction, ListSortAction } from "./types";
+import { normalizePayload, initializeState, keySort } from "./helpers";
+
+/**
+ * Helper to get key mappings from items
+ */
+const getKeyMap = (items: ModelObj[], keyName: string): Id[] => {
+  return items.map((item: ModelObj) => item[keyName]);
+};
+
+/**
+ * Helper to find items to insert (not in state) and items to replace (in state)
+ */
+const partitionItems = (respMap: Id[], stateMap: Id[]) => {
+  const toInsert = respMap.filter((id: Id) => stateMap.indexOf(id) < 0);
+  const toReplace = respMap.filter((id: Id) => stateMap.indexOf(id) >= 0);
+  return { toInsert, toReplace };
+};
+
+export const listInsertReducer = (state: ModelObj[], action: ListAction): ModelObj[] => {
+  const currentState = initializeState(state, []);
+  const items = normalizePayload(action.payload);
+  
+  let newState = [...currentState];
+  const respMap = getKeyMap(items, action.keyName);
+  const stateMap = getKeyMap(newState, action.keyName);
+  const { toInsert, toReplace } = partitionItems(respMap, stateMap);
+  
+  // Update existing items
+  for (const id of toReplace) {
+    const stateIndex = stateMap.indexOf(id);
+    const respIndex = respMap.indexOf(id);
+    newState[stateIndex] = { ...items[respIndex] };
+  }
+  
+  // Add new items
+  if (toInsert.length > 0) {
+    const inserts = toInsert.map((id: Id) => items[respMap.indexOf(id)]);
+    newState = [...newState, ...inserts];
+  }
+  
+  if (action?.sort) {
+    newState.sort(action.sort);
+  }
+  
+  return newState;
+};
+
+export const listUnshiftReducer = (state: ModelObj[], action: ListAction): ModelObj[] => {
+  const currentState = initializeState(state, []);
+  const items = normalizePayload(action.payload);
+  return [...items, ...currentState];
+};
+
+export const listSortReducer = (state: ModelObj[], action: ListSortAction): ModelObj[] => {
+  const currentState = initializeState(state, []);
+  const newState = [...currentState];
+  const sort = action?.sort ?? keySort(action.keyName);
+  newState.sort(sort);
+  return newState;
+};
+
+export const listDeleteReducer = (state: ModelObj[], action: ListAction): ModelObj[] => {
+  const currentState = !state || !Array.isArray(state) ? [] : state;
+  const items = normalizePayload(action.payload);
+  const deleteKeys = new Set<Id>(getKeyMap(items, action.keyName));
+  return currentState.filter((item: ModelObj) => !deleteKeys.has(item[action.keyName]));
+};
+
+export const listShiftReducer = (state: ModelObj[]): ModelObj[] => {
+  const currentState = !state || !Array.isArray(state) ? [] : state;
+  const newState = [...currentState];
+  newState.shift();
+  return newState;
+};
+
+export const listReplaceReducer = (state: ModelObj[], action: ListAction): ModelObj[] => {
+  const items = normalizePayload(action.payload);
+  const result = items.map((item: ModelObj) => ({ ...item }));
+  
+  if (action?.sort) {
+    result.sort(action.sort);
+  }
+  
+  return result;
+};

package/src/mapListReducers.ts

@@ -0,0 +1,193 @@
+import { ModelObj, Id, SortFn, MapListAction, MapListSortAction } from "./types";
+import { normalizePayload, initializeState, keySort } from "./helpers";
+
+/**
+ * State structure for mapList: { [mapKeyValue]: ModelObj[] }
+ */
+export type MapListState = { [key: string]: ModelObj[] };
+
+/**
+ * Helper to get key value from an item
+ */
+const getKeyValue = (item: ModelObj, keyName: string): Id => item[keyName];
+
+/**
+ * Helper to get map key value from an item
+ */
+const getMapKeyValue = (item: ModelObj, mapKeyName: string): string => String(item[mapKeyName]);
+
+/**
+ * Helper to insert/update an item in a list by keyName
+ */
+const upsertInList = (
+  list: ModelObj[],
+  item: ModelObj,
+  keyName: string,
+  sort?: SortFn
+): ModelObj[] => {
+  const itemKey = getKeyValue(item, keyName);
+  const existingIndex = list.findIndex((i) => getKeyValue(i, keyName) === itemKey);
+  
+  let newList: ModelObj[];
+  if (existingIndex >= 0) {
+    // Update existing item
+    newList = [...list];
+    newList[existingIndex] = { ...item };
+  } else {
+    // Add new item
+    newList = [...list, { ...item }];
+  }
+  
+  if (sort) {
+    newList.sort(sort);
+  }
+  
+  return newList;
+};
+
+/**
+ * Helper to delete items from a list by keyName
+ */
+const deleteFromList = (
+  list: ModelObj[],
+  keysToDelete: Set<Id>,
+  keyName: string
+): ModelObj[] => {
+  return list.filter((item) => !keysToDelete.has(getKeyValue(item, keyName)));
+};
+
+/**
+ * Insert items into the mapList structure
+ * Groups items by mapKeyName, each group is a list managed by keyName
+ */
+export const mapListInsertReducer = (
+  state: MapListState,
+  action: MapListAction
+): MapListState => {
+  const currentState = initializeState(state, {});
+  const items = normalizePayload(action.payload);
+  const newState = { ...currentState };
+  
+  for (const item of items) {
+    if (!item?.[action.keyName] || !item?.[action.mapKeyName]) continue;
+    
+    const mapKey = getMapKeyValue(item, action.mapKeyName);
+    const existingList = newState[mapKey] || [];
+    newState[mapKey] = upsertInList(existingList, item, action.keyName, action.sort);
+  }
+  
+  return newState;
+};
+
+/**
+ * Delete items from the mapList structure
+ * Removes items by keyName, removes empty map keys
+ */
+export const mapListDeleteReducer = (
+  state: MapListState,
+  action: MapListAction
+): MapListState => {
+  const currentState = initializeState(state, {});
+  const items = normalizePayload(action.payload);
+  const keysToDelete = new Set<Id>(items.map((item) => getKeyValue(item, action.keyName)));
+  
+  const newState: MapListState = {};
+  
+  for (const [mapKey, list] of Object.entries(currentState)) {
+    const filteredList = deleteFromList(list, keysToDelete, action.keyName);
+    if (filteredList.length > 0) {
+      newState[mapKey] = filteredList;
+    }
+  }
+  
+  return newState;
+};
+
+/**
+ * Replace entire mapList state with new items
+ */
+export const mapListReplaceReducer = (
+  state: MapListState,
+  action: MapListAction
+): MapListState => {
+  const items = normalizePayload(action.payload);
+  const newState: MapListState = {};
+  
+  for (const item of items) {
+    if (!item?.[action.keyName] || !item?.[action.mapKeyName]) continue;
+    
+    const mapKey = getMapKeyValue(item, action.mapKeyName);
+    const existingList = newState[mapKey] || [];
+    newState[mapKey] = [...existingList, { ...item }];
+  }
+  
+  // Sort each list if sort function provided
+  if (action.sort) {
+    for (const mapKey of Object.keys(newState)) {
+      newState[mapKey].sort(action.sort);
+    }
+  }
+  
+  return newState;
+};
+
+/**
+ * Sort all lists within the mapList structure
+ */
+export const mapListSortReducer = (
+  state: MapListState,
+  action: MapListSortAction
+): MapListState => {
+  const currentState = initializeState(state, {});
+  const sort = action.sort ?? keySort(action.keyName);
+  const newState: MapListState = {};
+  
+  for (const [mapKey, list] of Object.entries(currentState)) {
+    const sortedList = [...list];
+    sortedList.sort(sort);
+    newState[mapKey] = sortedList;
+  }
+  
+  return newState;
+};
+
+/**
+ * Shift (remove first item) from all lists in mapList
+ * Removes empty map keys after shift
+ */
+export const mapListShiftReducer = (state: MapListState): MapListState => {
+  const currentState = initializeState(state, {});
+  const newState: MapListState = {};
+  
+  for (const [mapKey, list] of Object.entries(currentState)) {
+    const shiftedList = [...list];
+    shiftedList.shift();
+    if (shiftedList.length > 0) {
+      newState[mapKey] = shiftedList;
+    }
+  }
+  
+  return newState;
+};
+
+/**
+ * Unshift (add to beginning) items into mapList
+ */
+export const mapListUnshiftReducer = (
+  state: MapListState,
+  action: MapListAction
+): MapListState => {
+  const currentState = initializeState(state, {});
+  const items = normalizePayload(action.payload);
+  const newState = { ...currentState };
+  
+  for (const item of items) {
+    if (!item?.[action.keyName] || !item?.[action.mapKeyName]) continue;
+    
+    const mapKey = getMapKeyValue(item, action.mapKeyName);
+    const existingList = newState[mapKey] || [];
+    newState[mapKey] = [{ ...item }, ...existingList];
+  }
+  
+  return newState;
+};

package/src/mapReducers.ts

@@ -0,0 +1,41 @@
+import { ModelObj, MapAction } from "./types";
+import { normalizePayload, initializeState } from "./helpers";
+
+export const mapInsertReducer = (state: ModelObj, action: MapAction): ModelObj => {
+  const currentState = initializeState(state, {});
+  const items = normalizePayload(action.payload);
+  const newState = { ...currentState };
+  
+  for (const item of items) {
+    if (item?.[action.keyName]) {
+      newState[item[action.keyName]] = { ...item };
+    }
+  }
+  
+  return newState;
+};
+
+export const mapDeleteReducer = (state: ModelObj, action: MapAction): ModelObj => {
+  const currentState = initializeState(state, {});
+  const items = normalizePayload(action.payload);
+  const newState = { ...currentState };
+  
+  for (const item of items) {
+    delete newState[item[action.keyName]];
+  }
+  
+  return newState;
+};
+
+export const mapReplaceReducer = (state: ModelObj, action: MapAction): ModelObj => {
+  const items = normalizePayload(action.payload);
+  const newState: ModelObj = {};
+  
+  for (const item of items) {
+    if (item?.[action.keyName]) {
+      newState[item[action.keyName]] = { ...item };
+    }
+  }
+  
+  return newState;
+};

package/src/objReducers.ts

@@ -0,0 +1,11 @@
+export const objInsertReducer = <T>(state: T, action: { payload: T }): T => {
+  return action.payload;
+};
+
+export const objReplaceReducer = <T>(state: T, action: { payload: T }): T => {
+  return action.payload;
+};
+
+export const objDeleteReducer = (): null => {
+  return null;
+};

package/src/types.ts

@@ -0,0 +1,55 @@
+export type Id = number | string;
+
+export interface ModelObj {
+  [key: string]: any;
+}
+
+export type SortFn = (a: ModelObj, b: ModelObj) => number;
+
+export interface ListAction {
+  payload: ModelObj | ModelObj[];
+  sort?: SortFn;
+  keyName: string;
+  mapKeyName?: string;
+  isMapList: boolean;
+}
+
+export interface MapAction {
+  payload: ModelObj | ModelObj[];
+  sort?: SortFn;
+  keyName: string;
+}
+
+export interface ListSortAction {
+  sort?: SortFn;
+  keyName: string;
+  mapKeyName?: string;
+  isMapList: boolean;
+}
+
+export interface MapListAction {
+  payload: ModelObj | ModelObj[];
+  sort?: SortFn;
+  keyName: string;
+  mapKeyName: string;
+}
+
+export interface MapListSortAction {
+  sort?: SortFn;
+  keyName: string;
+  mapKeyName: string;
+}
+
+export interface ReducerOpts {
+  stateType?: "list" | "map" | "static" | "mapList";
+  sort?: SortFn;
+  keyName?: string;
+  mapKeyName?: string;
+  initialState?: any;
+}
+
+export interface ReducerAction {
+  type: string;
+  payload?: any;
+  sort?: SortFn;
+}