feat: add version shorthand + createCrudTransitions helper

Author: edvincandon

ARCHITECTURE.md

@@ -329,9 +329,26 @@ createTransitions('todos::add')({
 });
 ```
 
+### `createCrudTransitions<T>(namespace, key)` / `createCrudTransitions<T>()(namespace, keys)`
+
+High-level helper that composes `crudPrepare` + `createTransitions` with golden-path modes:
+
+```typescript
+// Single-key
+const todo = createCrudTransitions<Todo>('todos', 'id');
+// todo.create → DISPOSABLE (drop on fail)
+// todo.update → DEFAULT (flag on fail)
+// todo.remove → REVERTIBLE (stash on fail)
+
+// Multi-key — curried for key inference
+const item = createCrudTransitions<ProjectTodo>()('projects', ['projectId', 'id']);
+```
+
+Each operation returns a full transition set (`.stage`, `.amend`, `.commit`, `.fail`, `.stash`, `.match`).
+
 ### `crudPrepare<T>(key)` / `crudPrepare<T>()(keys)`
 
-Factory for CRUD prepare functions that couple `transitionId === entityId`:
+Factory for CRUD prepare functions that couple `transitionId === entityId`. Use when you need custom modes or per-operation preparators:
 
 ```typescript
 // Single-key (recordState, listState)

README.md

@@ -62,46 +62,43 @@ npm install @lostsolution/optimistron
 
 ```typescript
 import { configureStore, createSelector } from '@reduxjs/toolkit';
-import { optimistron, createTransitions, crudPrepare, recordState, TransitionMode } from '@lostsolution/optimistron';
+import { optimistron, createCrudTransitions, recordState } from '@lostsolution/optimistron';
 
 // 1. Define your entity
 type Todo = { id: string; value: string; done: boolean; revision: number };
 
-// 2. Create CRUD prepare functions (couples transitionId === entityId)
-const crud = crudPrepare<Todo>('id');
-
-// 3. Create transition action creators
-const createTodo = createTransitions('todos::add', TransitionMode.DISPOSABLE)(crud.create);
-const editTodo = createTransitions('todos::edit')(crud.update); // DEFAULT mode
-const deleteTodo = createTransitions('todos::delete', TransitionMode.REVERTIBLE)(crud.remove);
+// 2. Create CRUD transition actions (golden-path modes built in)
+const todo = createCrudTransitions<Todo>('todos', 'id');
 
-// 4. Create the optimistic reducer
+// 3. Create the optimistic reducer
 const { reducer: todos, selectors } = optimistron(
     'todos',
     {} as Record<string, Todo>,
     recordState<Todo>({
         key: 'id',
-        compare: (a, b) => (a.revision === b.revision ? 0 : a.revision > b.revision ? 1 : -1),
+        version: (t) => t.revision,
         eq: (a, b) => a.done === b.done && a.value === b.value,
     }),
-    { create: createTodo, update: editTodo, remove: deleteTodo },
+    { create: todo.create, update: todo.update, remove: todo.remove },
 );
 
-// 5. Wire up the store
+// 4. Wire up the store
 const store = configureStore({ reducer: { todos } });
 
-// 6. Select optimistic state (memoize with createSelector)
+// 5. Select optimistic state (memoize with createSelector)
 const selectTodos = createSelector(
     (state: RootState) => state.todos,
     selectors.selectOptimistic((todos) => Object.values(todos.committed)),
 );
 
-// 7. Dispatch transitions
-dispatch(createTodo.stage(todo)); // optimistic — shows immediately
-dispatch(createTodo.commit(todo.id)); // server confirmed — becomes committed state
-dispatch(createTodo.fail(todo.id, error)); // server rejected — flagged as failed
+// 6. Dispatch transitions
+dispatch(todo.create.stage(item)); // optimistic — shows immediately
+dispatch(todo.create.commit(item.id)); // server confirmed — becomes committed state
+dispatch(todo.create.fail(item.id, error)); // server rejected — dropped (DISPOSABLE)
 ```
 
+> `createCrudTransitions` composes `crudPrepare` + `createTransitions` with golden-path modes: **DISPOSABLE** create, **DEFAULT** update, **REVERTIBLE** remove. For custom modes or per-operation preparators, use `crudPrepare` + `createTransitions` directly.
+
 ---
 
 ## Three Rules
@@ -117,8 +114,13 @@ dispatch(createTodo.fail(todo.id, error)); // server rejected — flagged as fai
 Entities need a **monotonically increasing version** — `revision`, `updatedAt`, a sequence number. This is how sanitization tells "newer" from "stale":
 
 ```typescript
-compare: (a, b) => 0 | 1 | -1; // version ordering
-eq: (a, b) => boolean; // content equality at same version
+// Shorthand — extracts version, compare is generated automatically
+version: (item) => item.revision,
+eq: (a, b) => boolean,
+
+// Full control — provide your own compare
+compare: (a, b) => 0 | 1 | -1,
+eq: (a, b) => boolean,
 ```
 
 Without versioning, conflict detection degrades to content equality only.
@@ -227,8 +229,6 @@ All selectors are returned from `optimistron()` on the `selectors` object — th
 ### Optimistic state
 
 ```typescript
-const { selectors } = optimistron('todos', initial, handler, config);
-
 const selectTodos = createSelector(
     (state: RootState) => state.todos,
     selectors.selectOptimistic((todos) => Object.values(todos.committed)),
@@ -238,7 +238,6 @@ const selectTodos = createSelector(
 ### Per-entity status
 
 ```typescript
-const { selectors } = optimistron('todos', initial, handler, config);
 
 selectors.selectIsOptimistic(id)(state.todos); // pending?
 selectors.selectIsFailed(id)(state.todos); // failed?

src/actions/crud-transitions.ts

@@ -0,0 +1,58 @@
+import { TransitionMode } from '~/transitions';
+import { crudPrepare } from './crud';
+import { createTransitions } from './transitions';
+
+/**
+ * High-level helper that composes `crudPrepare` + `createTransitions`
+ * with golden-path transition modes:
+ * - **create** → `DISPOSABLE` (drop on fail — entity never existed server-side)
+ * - **update** → `DEFAULT` (flag on fail — consumer decides)
+ * - **remove** → `REVERTIBLE` (stash on fail — undo via trailing reversion)
+ *
+ * Single-key:
+ * ```ts
+ * const todo = createCrudTransitions<Todo>('todos', 'id');
+ * todo.create.stage(item);
+ * todo.update.stage({ id, value: 'new' });
+ * todo.remove.stage({ id });
+ * ```
+ *
+ * Multi-key (curried for Keys inference):
+ * ```ts
+ * const item = createCrudTransitions<Item>()('items', ['groupId', 'itemId']);
+ * ```
+ */
+export function createCrudTransitions<T extends Record<string, any>>(): <
+    const Keys extends readonly [keyof T & string, ...(keyof T & string)[]],
+>(
+    namespace: string,
+    keys: Keys,
+) => {
+    create: ReturnType<typeof createTransitions>;
+    update: ReturnType<typeof createTransitions>;
+    remove: ReturnType<typeof createTransitions>;
+};
+
+export function createCrudTransitions<T extends Record<string, any>>(
+    namespace: string,
+    key: keyof T & string,
+): {
+    create: ReturnType<typeof createTransitions>;
+    update: ReturnType<typeof createTransitions>;
+    remove: ReturnType<typeof createTransitions>;
+};
+
+export function createCrudTransitions<T extends Record<string, any>>(namespace?: string, key?: keyof T & string): any {
+    const build = (ns: string, crud: ReturnType<typeof crudPrepare<T>>) => ({
+        create: createTransitions(`${ns}::create`, TransitionMode.DISPOSABLE)(crud.create),
+        update: createTransitions(`${ns}::update`, TransitionMode.DEFAULT)(crud.update),
+        remove: createTransitions(`${ns}::remove`, TransitionMode.REVERTIBLE)(crud.remove),
+    });
+
+    if (namespace !== undefined && key !== undefined) {
+        return build(namespace, crudPrepare<T>(key));
+    }
+
+    return <const Keys extends readonly [keyof T & string, ...(keyof T & string)[]]>(ns: string, keys: Keys) =>
+        build(ns, crudPrepare<T>()(keys) as any);
+}

src/actions/index.ts

@@ -1,5 +1,6 @@
 export { createCommitMatcher, createTransition, createTransitions, resolveTransition } from './transitions';
 export { crudPrepare } from './crud';
+export { createCrudTransitions } from './crud-transitions';
 export type {
     ActionMeta,
     EmptyPayload,

src/index.ts

@@ -1,4 +1,4 @@
-export { createTransition, createTransitions, crudPrepare } from './actions';
+export { createCrudTransitions, createTransition, createTransitions, crudPrepare } from './actions';
 export { optimistron } from './optimistron';
 export { listState } from './state/list';
 export { nestedRecordState, recordState } from './state/record';

src/state/list.ts

@@ -1,6 +1,6 @@
 import { OptimisticMergeResult } from '~/transitions';
 import type { StringKeys } from '~/utils/types';
-import type { CrudActionMap, VersioningOptions, WiredStateHandler } from '~state/types';
+import { resolveCompare, type CrudActionMap, type VersioningOptions, type WiredStateHandler } from '~state/types';
 
 export type ListStateOptions<T> = VersioningOptions<T> & { key: StringKeys<T> };
 
@@ -16,7 +16,8 @@ export type ListStateOptions<T> = VersioningOptions<T> & { key: StringKeys<T> };
 export const listState = <T extends Record<string, any>>(
     options: ListStateOptions<T>,
 ): WiredStateHandler<T[], T, Partial<T>, Partial<T>, CrudActionMap<T, Partial<T>, Partial<T>>> => {
-    const { key, compare, eq } = options;
+    const { key, eq } = options;
+    const compare = resolveCompare(options);
 
     return {
         create: (state: T[], item: T) => {

src/state/record.ts

@@ -3,7 +3,7 @@ import { OptimisticMergeResult } from '~/transitions';
 import type { Obj } from '~/utils/path';
 import { getAt, removeAt, setAt } from '~/utils/path';
 import type { Maybe, StringKeys } from '~/utils/types';
-import type { CrudActionMap, VersioningOptions, WiredStateHandler } from '~state/types';
+import { resolveCompare, type CrudActionMap, type VersioningOptions, type WiredStateHandler } from '~state/types';
 
 export type RecordStateOptions<T> = VersioningOptions<T> & { key: StringKeys<T> };
 export type NestedRecordStateOptions<T, Keys extends readonly StringKeys<T>[]> = VersioningOptions<T> & { keys: Keys };
@@ -45,7 +45,8 @@ export const nestedRecordState =
     > => {
         type State = RecursiveRecordState<Keys, T>;
 
-        const { keys, compare, eq } = options;
+        const { keys, eq } = options;
+        const compare = resolveCompare(options);
 
         /** Extracts path IDs from a DTO using the keys tuple */
         const extractPath = (dto: Record<string, any>): string[] => keys.map((k) => String(dto[k]));
@@ -135,11 +136,11 @@ export const nestedRecordState =
  * This is a depth-1 specialization of `nestedRecordState`.
  * Handler types use `Partial<T>` for update/remove DTOs — narrower types
  * are enforced at dispatch time via `crudPrepare`. */
-export const recordState = <T extends Record<string, any>>({
-    key,
-    compare,
-    eq,
-}: RecordStateOptions<T>): WiredStateHandler<RecordState<T>, T, Partial<T>, Partial<T>, CrudActionMap<T, Partial<T>, Partial<T>>> => {
+export const recordState = <T extends Record<string, any>>(
+    options: RecordStateOptions<T>,
+): WiredStateHandler<RecordState<T>, T, Partial<T>, Partial<T>, CrudActionMap<T, Partial<T>, Partial<T>>> => {
+    const { key, eq } = options;
+    const compare = resolveCompare(options);
     const nested = nestedRecordState<T>()({ keys: [key], compare, eq });
 
     return {

src/state/singular.ts

@@ -1,6 +1,6 @@
 import { OptimisticMergeResult } from '~/transitions';
 import type { MaybeNull } from '~/utils/types';
-import type { CrudActionMap, VersioningOptions, WiredStateHandler } from './types';
+import { resolveCompare, type CrudActionMap, type VersioningOptions, type WiredStateHandler } from './types';
 
 export type SingularStateOptions<T> = VersioningOptions<T>;
 
@@ -12,7 +12,8 @@ export type SingularStateOptions<T> = VersioningOptions<T>;
 export const singularState = <T extends object>(
     options: SingularStateOptions<T>,
 ): WiredStateHandler<MaybeNull<T>, T, Partial<T>, void, CrudActionMap<T, Partial<T>, void>> => {
-    const { compare, eq } = options;
+    const { eq } = options;
+    const compare = resolveCompare(options);
 
     return {
         create: (_: MaybeNull<T>, item: T) => item,

src/state/types.ts

@@ -7,15 +7,35 @@ export type TransitionState<T> = {
 };
 
 export type VersioningOptions<T> = {
-    /** Given two items returns a sorting result.
-     * This allows checking for valid updates or conflicts.
-     * Return -1 if `a` is "smaller" than `b`
-     * Return 0 if `a` equals `b`
-     * Return 1 if `b` is "greater" than `a` */
-    compare: (a: T, b: T) => 0 | 1 | -1;
     /** Equality checker - it can potentially be different
      * than comparing. */
     eq: (a: T, b: T) => boolean;
+} & (
+    | {
+          /** Given two items returns a sorting result.
+           * Return -1 if `a` is "smaller" than `b`
+           * Return 0 if `a` equals `b`
+           * Return 1 if `b` is "greater" than `a` */
+          compare: (a: T, b: T) => 0 | 1 | -1;
+      }
+    | {
+          /** Shorthand — extracts a comparable version from an item.
+           * Generates `compare` automatically via `>` / `===`. */
+          version: (item: T) => number;
+      }
+);
+
+/** Resolves a `VersioningOptions` into a concrete `compare` function.
+ * If `version` shorthand is provided, generates `compare` from it. */
+export const resolveCompare = <T>(options: VersioningOptions<T>): ((a: T, b: T) => 0 | 1 | -1) => {
+    if ('compare' in options) return options.compare;
+    const { version } = options;
+    return (a, b) => {
+        const va = version(a);
+        const vb = version(b);
+        if (va === vb) return 0;
+        return va > vb ? 1 : -1;
+    };
 };
 
 /** Type-narrowing action matcher — `.match()` narrows the action's payload.

test/unit/actions.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 
-import { createTransitions, crudPrepare, resolveTransition } from '~actions';
+import { createCrudTransitions, createTransitions, crudPrepare, resolveTransition } from '~actions';
 import { META_KEY } from '~constants';
 import { TransitionMode, Operation } from '~transitions';
 
@@ -251,3 +251,68 @@ describe('crudPrepare', () => {
         });
     });
 });
+
+describe('createCrudTransitions', () => {
+    type Item = { id: string; name: string; revision: number };
+
+    describe('single-key', () => {
+        const crud = createCrudTransitions<Item>('items', 'id');
+
+        test('create uses DISPOSABLE mode', () => {
+            const item: Item = { id: 'i1', name: 'test', revision: 0 };
+            const result = crud.create.stage(item);
+
+            expect(result.payload).toEqual(item);
+            expect(result.meta[META_KEY].id).toBe('i1');
+            expect(result.meta[META_KEY].mode).toBe(TransitionMode.DISPOSABLE);
+        });
+
+        test('update uses DEFAULT mode', () => {
+            const result = crud.update.stage({ id: 'i1', name: 'updated' });
+
+            expect(result.meta[META_KEY].id).toBe('i1');
+            expect(result.meta[META_KEY].mode).toBe(TransitionMode.DEFAULT);
+        });
+
+        test('remove uses REVERTIBLE mode', () => {
+            const result = crud.remove.stage({ id: 'i1' });
+
+            expect(result.meta[META_KEY].id).toBe('i1');
+            expect(result.meta[META_KEY].mode).toBe(TransitionMode.REVERTIBLE);
+        });
+
+        test('each operation has commit/fail/stash', () => {
+            expect(crud.create.commit('i1').meta[META_KEY].operation).toBe(Operation.COMMIT);
+            expect(crud.update.fail('i1', new Error()).meta[META_KEY].operation).toBe(Operation.FAIL);
+            expect(crud.remove.stash('i1').meta[META_KEY].operation).toBe(Operation.STASH);
+        });
+    });
+
+    describe('multi-key', () => {
+        type Nested = { groupId: string; itemId: string; value: string };
+        const crud = createCrudTransitions<Nested>()('nested', ['groupId', 'itemId']);
+
+        test('create derives transitionId from keys', () => {
+            const item: Nested = { groupId: 'g1', itemId: 'i1', value: 'test' };
+            const result = crud.create.stage(item);
+
+            expect(result.payload).toEqual(item);
+            expect(result.meta[META_KEY].id).toBe('g1/i1');
+            expect(result.meta[META_KEY].mode).toBe(TransitionMode.DISPOSABLE);
+        });
+
+        test('update uses DEFAULT mode with joined key', () => {
+            const result = crud.update.stage({ groupId: 'g1', itemId: 'i1', value: 'updated' });
+
+            expect(result.meta[META_KEY].id).toBe('g1/i1');
+            expect(result.meta[META_KEY].mode).toBe(TransitionMode.DEFAULT);
+        });
+
+        test('remove uses REVERTIBLE mode with joined key', () => {
+            const result = crud.remove.stage({ groupId: 'g1', itemId: 'i1' });
+
+            expect(result.meta[META_KEY].id).toBe('g1/i1');
+            expect(result.meta[META_KEY].mode).toBe(TransitionMode.REVERTIBLE);
+        });
+    });
+});