@mrck-labs/vanaheim-shared

Shared types, constants, utilities, and state management for the Vanaheim ecosystem

This package provides common code used by both Vanaheim Desktop (Electron) and MobileHorizon (React Native/Expo).

Installation

npm install @mrck-labs/vanaheim-shared

Peer Dependencies:

• jotai (optional) - Required only if using the /atoms module

Modules

Types (/types)

Database entity types matching the Supabase schema:

import type {
  // Focus
  FocusSession,
  NewFocusSession,
  FocusCategory,
  FocusSessionFilters,

  // Expenses & Income
  Expense,
  NewExpense,
  ExpenseCategory,
  Income,
  NewIncome,
  IncomeCategory,

  // Health
  HealthHabit,
  HealthCategory,
  HealthCompletion,

  // And more...
} from "@mrck-labs/vanaheim-shared/types";

Constants (/constants)

Shared constants and enums:

import {
  CURRENCIES, // ['CHF', 'USD', 'EUR', 'PLN']
  CURRENCY_SYMBOLS, // { CHF: 'CHF', USD: '$', ... }
  FREQUENCIES, // ['monthly', 'yearly', '6-monthly', ...]
  DEFAULT_FOCUS_DURATIONS, // [15, 25, 30, 45, 60, 90]
  FOCUS_STATUS, // ['active', 'completed', 'abandoned']
  SETTING_KEYS,
  API_URLS,
} from "@mrck-labs/vanaheim-shared/constants";

Utilities (/utils)

Common utility functions:

import {
  formatTime, // (seconds) => "02:05"
  formatTotalTime, // (seconds) => "1h 30m"
  formatCurrency, // (amount, currency) => "CHF 1'234.56"
  formatRelativeTime, // (dateStr) => "2h ago"
  generateId, // () => UUID v4
  truncate, // (str, maxLength) => "Hello..."
} from "@mrck-labs/vanaheim-shared/utils";

Query Keys (/query)

Centralized TanStack Query cache key factory:

import { queryKeys } from "@mrck-labs/vanaheim-shared/query";

// In query hooks
useQuery({ queryKey: queryKeys.focusSessions.today() });
useQuery({ queryKey: queryKeys.expenses.list({ isActive: true }) });

// Invalidating
queryClient.invalidateQueries({ queryKey: queryKeys.focusSessions.all });

Covered modules: expenses, expenseCategories, expensePayments, incomes, incomeCategories, incomePayments, exchangeRates, focusSessions, focusCategories, settings, lieuDays, efLinks, bankConnections, bankTransactions, healthCategories, healthHabits, healthCompletions, healthStats, promptCategories, promptLabels, prompts, trainingActivities, trainingSessions, plannedSessions, races, trainingStats, strava, journalEntries, journalData, chatConversations, chatMessages, googleCalendar, linear

Focus Atoms (/atoms)

Jotai atoms for focus timer state management:

import {
  // Types
  type TimerStatus, // 'idle' | 'running' | 'paused' | 'completed'
  type ActiveSession,

  // Core atoms
  timerStatusAtom,
  targetSecondsAtom,
  elapsedSecondsAtom,
  activeSessionAtom,

  // Derived atoms
  remainingSecondsAtom,
  progressAtom, // 0 to 1
  progressPercentAtom, // 0 to 100
  formattedRemainingAtom, // "24:59"
  formattedElapsedAtom, // "00:01"
} from "@mrck-labs/vanaheim-shared/atoms";

Date Utilities (/date)

Comprehensive date manipulation:

import {
  // Core
  getTodayString, // "2024-12-16"
  parseLocalDate, // Avoids timezone issues
  formatDateString, // Date => "2024-12-16"

  // Checks
  isToday,
  isOverdue,
  isDueSoon, // Within N days

  // Arithmetic
  addDays,
  subtractDays,
  getYesterdayString,
  getTomorrowString,

  // ISO helpers (for DB queries)
  getStartOfDayISO,
  getEndOfDayISO,

  // Week utilities
  getWeekStartString,
  getWeekEndString,
  formatWeekRange,

  // Display formatting
  formatFullDate, // "Monday, December 15, 2024"
  formatDateHeader, // "Today" | "Tomorrow" | "Overdue"
  formatRelativeDueDate, // "Due in 3 days"
} from "@mrck-labs/vanaheim-shared/date";

Usage in Projects

Vanaheim Desktop

// src/lib/queryClient.ts
export { queryKeys } from '@mrck-labs/vanaheim-shared/query'

// src/atoms/focus.ts
export { timerStatusAtom, ... } from '@mrck-labs/vanaheim-shared/atoms'

MobileHorizon

// src/hooks/queries/useFocusQueries.ts
import { queryKeys } from '@mrck-labs/vanaheim-shared/query'

// src/atoms/focus.ts
export { timerStatusAtom, ... } from '@mrck-labs/vanaheim-shared/atoms'

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Type check
npm run typecheck

# Clean build artifacts
npm run clean

Release

This package uses changesets for version management.

See RELEASE_GUIDE.md for detailed release instructions.

License

MIT