What is Themis?

<!-- In a Svelte component -->
<script lang="ts">
  import { selectTodoById, selectItemCount } from '$lib/todos/todos-selectors';

  const count = selectItemCount();        // Readable<number>
  const todo  = selectTodoById(todoId);   // Readable<Todo | undefined>
</script>

<p>{$count} items</p>
<p>{$todo?.title}</p>

// In a React component
import { selectTodoById, selectItemCount } from './todos/todos-selectors';

// Preferred: direct signal call returns ReadonlySignal<R>
const countSignal = selectItemCount();      // ReadonlySignal<number>
const todoSignal  = selectTodoById(id);     // ReadonlySignal<Todo | undefined>

function TodoTitle({ id }: { id: string }) {
  // .useValue() returns plain R — use only when a plain value is required
  const todo = selectTodoById.useValue(id);
  return <span>{todo?.title}</span>;
}

import { call, put, takeLatest } from 'typed-redux-saga';
import { selectItemCount, selectTodoById } from './todos/todos-selectors';

function* fetchDetailSaga(action: ReturnType<typeof loadTodo>) {
  // Use .effect() — the only correct way to read selectors in sagas
  const count = yield* selectItemCount.effect();
  const todo  = yield* selectTodoById.effect(action.payload[0]);
  // ...
}

import { createAction, createAsyncAction }
  from '@augmentcode/themis/utils/store/create-action';

// Plain action — no args, no payload
export const increment = createAction('counter/increment');

// Action with typed payload
export const setCount = createAction('counter/setCount', (value: number) => value);

// Action with multiple args mapped to a payload object
export const updateUser = createAction(
  'users/update',
  (id: string, changes: Partial<User>) => ({ id, changes })
);

// Async action — carries .success and .failure sub-actions
export const fetchTodos = createAsyncAction<[], void, Todo[]>(
  'todos/fetch',       // asyncActionType
  'todos/fetch/stages' // stagesActionType
);
// fetchTodos()          → StoreAsyncAction
// fetchTodos.success(todos) → dispatched by saga on success
// fetchTodos.failure(err)   → dispatched by saga on error

import { createReducer } from '@augmentcode/themis/utils/store/create-reducer';
import { increment, setCount, fetchTodos } from './counter-slice';

type CounterState = { count: number; loading: boolean };

export const counterReducer = createReducer<CounterState>({ count: 0, loading: false })
  .with(increment, (state) => ({ ...state, count: state.count + 1 }))
  .with(setCount,  (state, { payload: [value] }) => ({ ...state, count: value }))
  .with(fetchTodos,         (state) => ({ ...state, loading: true }))
  .with(fetchTodos.success, (state) => ({ ...state, loading: false }))
  .with(fetchTodos.failure, (state) => ({ ...state, loading: false }));

import { createBooleanPreference }
  from '@augmentcode/themis/utils/store/boolean-preference';

const darkMode = createBooleanPreference<SettingsState, 'darkMode'>({
  sliceName:       'settings',
  field:           'darkMode',
  setActionName:   'settings/setDarkMode',
  toggleActionName:'settings/toggleDarkMode',
});

// Provides: darkMode.setAction(true/false), darkMode.toggleAction()
// Register in your reducer builder:
const settingsReducer = createReducer<SettingsState>({ darkMode: false });
darkMode.register(settingsReducer);

import { createCollection, addItem, addItems, getItem,
  upsertItem, updateItem, removeItem, getItems, filterItems,
  decreaseRefsCount, increaseRefsCount }
  from '@augmentcode/themis/utils/collections/collection-utils';

type Todo = { id: string; title: string; completed: boolean };

// Empty collection keyed on 'id'
let todos = createCollection<Todo, 'id'>('id');

// Seed with initial items
todos = createCollection<Todo, 'id'>('id', [
  { id: '1', title: 'Buy milk',    completed: false },
  { id: '2', title: 'Write tests', completed: true  },
]);

// Add (no-op if ID already exists)
todos = addItem(todos, { id: '3', title: 'Deploy', completed: false });
todos = addItems(todos, [item4, item5]);

// Upsert (add if new, replace if exists)
todos = upsertItem(todos, { id: '1', title: 'Buy oat milk', completed: false });

// Partial update — unspecified fields preserved
todos = updateItem(todos, { id: '1', completed: true });

// Remove by ID
todos = removeItem(todos, '3');

// O(1) lookup
const todo = getItem(todos, '1');         // Todo | undefined
const all  = getItems(todos);             // Todo[] in insertion order
const done = filterItems(todos, (t): t is Todo => t.completed);

// Reference counting for shared entities
import { addItemAndCountRef, decreaseRefsCount, getRefsCount }
  from '@augmentcode/themis/utils/collections/collection-utils';

// Add item and set its ref count to 1
users = addItemAndCountRef(users, newUser);

// Another consumer claims a reference
users = increaseRefsCount(users, userId);

// Consumer releases — item removed automatically when count hits 0
users = decreaseRefsCount(users, userId);

// In a reducer:
.with(removeContext, (state, { payload: [id] }) => ({
  ...state,
  users: decreaseRefsCount(state.users, id),
}))

// Access collections through selectors, not directly in components
import { getItem, getItems } from '@augmentcode/themis/utils/collections/collection-utils';
import { store } from '$lib/store';

export const selectTodosCollection = store.createSelector(
  (state) => state.todos.collection
);

export const selectTodo = store.createSelector(
  (state, id: string) => getItem(selectTodosCollection.select(state), id)
);

export const selectAllTodos = store.createSelector(
  (state) => getItems(selectTodosCollection.select(state))
);

import { retryWithTimeout } from '@augmentcode/themis/saga';
import { call, put } from 'typed-redux-saga';

function* syncRemoteState() {
  const outcome = yield* retryWithTimeout(
    function* () {
      yield* call(api.syncRemoteState);
    },
    {
      maxRetries: 2,
      timeoutMs:  30_000,
      getDelayMs: (attempt) => 500 * (attempt + 1), // 500 ms, 1 s, ...
      onAttemptError: (err, attempt) =>
        console.warn(`Attempt ${attempt} failed:`, err),
    }
  );
  // outcome: "success" | "retries-exhausted" | "timeout"
  if (outcome !== 'success') yield* put(syncFailed(outcome));
}

import { wrapStreamingGenerator } from '@augmentcode/themis/saga';
import { put } from 'typed-redux-saga';

function* consumeStream(stream: AsyncGenerator<MessageChunk, void, unknown>) {
  yield* wrapStreamingGenerator(
    stream,
    function* (chunk) {
      yield* put(messageChunkReceived(chunk));
    },
    { timeoutMs: 30_000, onError: (err) => reportStreamError(err) }
  );
}

import { waitFor } from '@augmentcode/themis/saga';

function* awaitReady() {
  const ready = yield* waitFor(
    selectIsReady,
    [],
    (value) => value === true,
    10_000 // optional timeout ms
  );
  if (!ready) yield* put(initTimedOut());
}