@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.4

package/src/composables/useRackEditor.ts

@@ -0,0 +1,223 @@
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import type { Rack, SlotPosition, WellPlateFormat, Well } from '../types'
+
+export interface UseRackEditorOptions {
+  defaultFormat?: WellPlateFormat
+  defaultInjectionVolume?: number
+  maxRacks?: number
+  minRacks?: number
+}
+
+export interface UseRackEditorReturn {
+  racks: Ref<Rack[]>
+  activeRack: ComputedRef<Rack | undefined>
+  activeRackId: Ref<string>
+
+  addRack(name?: string): Rack
+  removeRack(rackId: string): void
+  reorderRacks(fromIndex: number, toIndex: number): void
+  updateRack(rackId: string, data: Partial<Rack>): void
+  setActiveRack(rackId: string): void
+
+  setWellData(rackId: string, wellId: string, data: Partial<Well>): void
+  clearWell(rackId: string, wellId: string): void
+  clearAllWells(rackId: string): void
+  fillSeries(rackId: string, prefix?: string): void
+
+  getAllWells(): Array<{ rackId: string; wellId: string; well: Partial<Well> }>
+  totalSampleCount: ComputedRef<number>
+  reset(): void
+}
+
+const SLOT_CYCLE: SlotPosition[] = ['R', 'G', 'B', 'Y']
+
+const PLATE_CONFIGS: Record<WellPlateFormat, { rows: number; cols: number }> = {
+  6: { rows: 2, cols: 3 },
+  12: { rows: 3, cols: 4 },
+  24: { rows: 4, cols: 6 },
+  48: { rows: 6, cols: 8 },
+  54: { rows: 6, cols: 9 },
+  96: { rows: 8, cols: 12 },
+  384: { rows: 16, cols: 24 },
+}
+
+let globalIdCounter = 0
+
+function generateId(): string {
+  globalIdCounter++
+  return `rack-${Date.now()}-${globalIdCounter}`
+}
+
+/** Manages a set of sample racks with well-level assignment, series fill, and multi-rack reordering. */
+export function useRackEditor(
+  initialRacks?: Rack[],
+  options?: UseRackEditorOptions,
+): UseRackEditorReturn {
+  const defaultFormat = options?.defaultFormat ?? 54
+  const defaultInjVol = options?.defaultInjectionVolume ?? 5
+  const maxRacks = options?.maxRacks ?? 10
+  const minRacks = options?.minRacks ?? 1
+
+  function createDefaultRack(name?: string, slotIndex?: number): Rack {
+    const slot = SLOT_CYCLE[(slotIndex ?? 0) % SLOT_CYCLE.length]!
+    return {
+      id: generateId(),
+      name: name ?? `Rack ${racks.value.length + 1}`,
+      format: defaultFormat,
+      slot,
+      injectionVolume: defaultInjVol,
+      wells: {},
+    }
+  }
+
+  const racks = ref<Rack[]>(
+    initialRacks && initialRacks.length > 0
+      ? initialRacks.map(r => ({ ...r }))
+      : [createDefaultRack('Rack 1', 0)]
+  ) as Ref<Rack[]>
+
+  const activeRackId = ref<string>(racks.value[0]?.id ?? '')
+
+  const activeRack = computed(() =>
+    racks.value.find(r => r.id === activeRackId.value) ?? racks.value[0]
+  )
+
+  function addRack(name?: string): Rack {
+    if (racks.value.length >= maxRacks) {
+      return racks.value[racks.value.length - 1]!
+    }
+    const rack = createDefaultRack(name, racks.value.length)
+    racks.value.push(rack)
+    activeRackId.value = rack.id
+    return rack
+  }
+
+  function removeRack(rackId: string): void {
+    if (racks.value.length <= minRacks) return
+    const index = racks.value.findIndex(r => r.id === rackId)
+    if (index === -1) return
+    racks.value.splice(index, 1)
+    if (activeRackId.value === rackId && racks.value[0]) {
+      activeRackId.value = racks.value[0].id
+    }
+  }
+
+  function reorderRacks(fromIndex: number, toIndex: number): void {
+    if (fromIndex < 0 || fromIndex >= racks.value.length) return
+    if (toIndex < 0 || toIndex >= racks.value.length) return
+    if (fromIndex === toIndex) return
+    const [moved] = racks.value.splice(fromIndex, 1)
+    if (moved) {
+      racks.value.splice(toIndex, 0, moved)
+    }
+  }
+
+  function updateRack(rackId: string, data: Partial<Rack>): void {
+    const rack = racks.value.find(r => r.id === rackId)
+    if (!rack) return
+    if (data.name !== undefined) rack.name = data.name
+    if (data.format !== undefined) rack.format = data.format
+    if (data.slot !== undefined) rack.slot = data.slot
+    if (data.injectionVolume !== undefined) rack.injectionVolume = data.injectionVolume
+    if (data.wells !== undefined) rack.wells = data.wells
+  }
+
+  function setActiveRack(rackId: string): void {
+    if (racks.value.some(r => r.id === rackId)) {
+      activeRackId.value = rackId
+    }
+  }
+
+  function setWellData(rackId: string, wellId: string, data: Partial<Well>): void {
+    const rack = racks.value.find(r => r.id === rackId)
+    if (!rack) return
+    rack.wells[wellId] = { ...rack.wells[wellId], ...data }
+  }
+
+  function clearWell(rackId: string, wellId: string): void {
+    const rack = racks.value.find(r => r.id === rackId)
+    if (!rack) return
+    delete rack.wells[wellId]
+  }
+
+  function clearAllWells(rackId: string): void {
+    const rack = racks.value.find(r => r.id === rackId)
+    if (!rack) return
+    rack.wells = {}
+  }
+
+  function fillSeries(rackId: string, prefix: string = 'S'): void {
+    const rack = racks.value.find(r => r.id === rackId)
+    if (!rack) return
+
+    const config = PLATE_CONFIGS[rack.format]
+    if (!config) return
+
+    let counter = 1
+    for (let row = 0; row < config.rows; row++) {
+      for (let col = 0; col < config.cols; col++) {
+        const rowLabel = String.fromCharCode(65 + row)
+        const wellId = `${rowLabel}${col + 1}`
+        // Only fill empty wells
+        if (!rack.wells[wellId]?.sampleType) {
+          const paddedNum = String(counter).padStart(3, '0')
+          rack.wells[wellId] = {
+            id: wellId,
+            row,
+            col,
+            state: 'filled',
+            sampleType: 'sample',
+            metadata: {
+              label: `${prefix}${paddedNum}`,
+              injectionVolume: rack.injectionVolume,
+              injectionCount: 1,
+            },
+          }
+        }
+        counter++
+      }
+    }
+  }
+
+  function getAllWells(): Array<{ rackId: string; wellId: string; well: Partial<Well> }> {
+    const result: Array<{ rackId: string; wellId: string; well: Partial<Well> }> = []
+    for (const rack of racks.value) {
+      for (const [wellId, well] of Object.entries(rack.wells)) {
+        result.push({ rackId: rack.id, wellId, well })
+      }
+    }
+    return result
+  }
+
+  const totalSampleCount = computed(() => {
+    let count = 0
+    for (const rack of racks.value) {
+      count += Object.keys(rack.wells).length
+    }
+    return count
+  })
+
+  function reset(): void {
+    const rack = createDefaultRack('Rack 1', 0)
+    racks.value = [rack]
+    activeRackId.value = rack.id
+  }
+
+  return {
+    racks,
+    activeRack,
+    activeRackId,
+    addRack,
+    removeRack,
+    reorderRacks,
+    updateRack,
+    setActiveRack,
+    setWellData,
+    clearWell,
+    clearAllWells,
+    fillSeries,
+    getAllWells,
+    totalSampleCount,
+    reset,
+  }
+}

package/src/composables/useReagentSeries.ts

@@ -0,0 +1,91 @@
+/**
+ * Composable for generating dilution series used in plate-based experiments.
+ * Provides geometric series generation from presets (2x, 3x, ½ log, 10x)
+ * and utility functions for series manipulation.
+ */
+
+export interface LevelEntry {
+  value: number
+  replicates: number
+}
+
+export interface DilutionPreset {
+  label: string
+  factor: number | 'half-log'
+}
+
+export const DEFAULT_PRESETS: DilutionPreset[] = [
+  { label: '2x', factor: 2 },
+  { label: '3x', factor: 3 },
+  { label: '½ log', factor: 'half-log' },
+  { label: '10x', factor: 10 },
+]
+
+export const DEFAULT_UNITS = ['µM', 'nM', 'mM', 'pM']
+
+function resolveFactor(factor: number | 'half-log'): number {
+  return factor === 'half-log' ? Math.sqrt(10) : factor
+}
+
+function roundToSignificant(value: number, digits: number = 4): number {
+  if (value === 0) return 0
+  const magnitude = Math.floor(Math.log10(Math.abs(value))) + 1
+  const factor = Math.pow(10, digits - magnitude)
+  return Math.round(value * factor) / factor
+}
+
+export function generateDilutionSeries(
+  startConcentration: number,
+  count: number,
+  factor: number | 'half-log',
+  defaultReplicates: number = 1,
+): LevelEntry[] {
+  if (count < 1 || startConcentration <= 0) return []
+
+  const divisor = resolveFactor(factor)
+  const levels: LevelEntry[] = []
+
+  for (let i = 0; i < count; i++) {
+    levels.push({
+      value: roundToSignificant(startConcentration / Math.pow(divisor, i)),
+      replicates: defaultReplicates,
+    })
+  }
+
+  return levels
+}
+
+export interface UseReagentSeriesReturn {
+  generateSeries: (
+    start: number,
+    count: number,
+    factor: number | 'half-log',
+    defaultReplicates?: number,
+  ) => LevelEntry[]
+  sortLevels: (levels: LevelEntry[], order?: 'asc' | 'desc') => LevelEntry[]
+  totalPositions: (levels: LevelEntry[]) => number
+}
+
+/** Generates and sorts geometric dilution series (2x, 3x, ½ log, 10x) for plate-based experiments. */
+export function useReagentSeries(): UseReagentSeriesReturn {
+  function generateSeries(
+    start: number,
+    count: number,
+    factor: number | 'half-log',
+    defaultReplicates: number = 1,
+  ): LevelEntry[] {
+    return generateDilutionSeries(start, count, factor, defaultReplicates)
+  }
+
+  function sortLevels(levels: LevelEntry[], order: 'asc' | 'desc' = 'desc'): LevelEntry[] {
+    return [...levels].sort((a, b) =>
+      order === 'desc' ? b.value - a.value : a.value - b.value,
+    )
+  }
+
+  function totalPositions(levels: LevelEntry[]): number {
+    return levels.reduce((sum, l) => sum + l.replicates, 0)
+  }
+
+  return { generateSeries, sortLevels, totalPositions }
+}

package/src/composables/useRequestSyncState.ts

@@ -0,0 +1,126 @@
+import { ref, type Ref } from 'vue'
+
+export type RequestSyncSuccessKind = 'load' | 'save' | 'run'
+
+export interface RequestSyncRunOptions {
+  success?: RequestSyncSuccessKind
+  errorMessage?: string
+}
+
+export interface UseRequestSyncStateReturn {
+  /** Whether a request is in progress. */
+  loading: Ref<boolean>
+  /** Message from the last failed request, or null. */
+  error: Ref<string | null>
+  /** Timestamp of the last successful load operation, or null. */
+  lastLoadedAt: Ref<Date | null>
+  /** Timestamp of the last successful save operation, or null. */
+  lastSavedAt: Ref<Date | null>
+  /** Timestamp of the last successful run operation, or null. */
+  lastRunAt: Ref<Date | null>
+  /** Clear the current error without changing loading or timestamps. */
+  clearError: () => void
+  /** Convert thrown values into a developer-facing error message. */
+  readErrorMessage: (value: unknown, fallback?: string) => string
+  /** Store and return a normalized error message. */
+  setError: (value: unknown, fallback?: string) => string
+  /** Mark the resource as successfully loaded. */
+  markLoaded: (date?: Date) => void
+  /** Mark the resource as successfully saved. */
+  markSaved: (date?: Date) => void
+  /** Mark the operation as successfully run. */
+  markRun: (date?: Date) => void
+  /** Run a request with shared loading/error handling and optional sync marking. */
+  run: <T>(operation: () => Promise<T>, options?: RequestSyncRunOptions) => Promise<T>
+}
+
+/** Shared loading/error/timestamp state for generated plugin request helpers. */
+export function useRequestSyncState(
+  defaultErrorMessage = 'Request failed.',
+): UseRequestSyncStateReturn {
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+  const lastLoadedAt = ref<Date | null>(null)
+  const lastSavedAt = ref<Date | null>(null)
+  const lastRunAt = ref<Date | null>(null)
+
+  function clearError(): void {
+    error.value = null
+  }
+
+  function readErrorMessage(value: unknown, fallback = defaultErrorMessage): string {
+    if (value instanceof Error && value.message) {
+      return value.message
+    }
+    if (typeof value === 'string' && value.trim()) {
+      return value
+    }
+    if (
+      typeof value === 'object'
+      && value !== null
+      && 'message' in value
+      && typeof (value as { message?: unknown }).message === 'string'
+      && (value as { message: string }).message
+    ) {
+      return (value as { message: string }).message
+    }
+    return fallback
+  }
+
+  function setError(value: unknown, fallback?: string): string {
+    const message = readErrorMessage(value, fallback)
+    error.value = message
+    return message
+  }
+
+  function markLoaded(date = new Date()): void {
+    lastLoadedAt.value = date
+  }
+
+  function markSaved(date = new Date()): void {
+    lastSavedAt.value = date
+  }
+
+  function markRun(date = new Date()): void {
+    lastRunAt.value = date
+  }
+
+  async function run<T>(
+    operation: () => Promise<T>,
+    options: RequestSyncRunOptions = {},
+  ): Promise<T> {
+    loading.value = true
+    clearError()
+    try {
+      const response = await operation()
+      if (options.success === 'load') {
+        markLoaded()
+      } else if (options.success === 'save') {
+        markSaved()
+      } else if (options.success === 'run') {
+        markRun()
+      }
+      return response
+    } catch (err) {
+      setError(err, options.errorMessage)
+      throw err
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return {
+    loading,
+    error,
+    lastLoadedAt,
+    lastSavedAt,
+    lastRunAt,
+    clearError,
+    readErrorMessage,
+    setError,
+    markLoaded,
+    markSaved,
+    markRun,
+    run,
+  }
+}

package/src/composables/useResourceCrud.ts

@@ -0,0 +1,245 @@
+import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+
+export type ResourceKey = string | number
+
+export interface ResourceCrudAdapter<TItem, TCreate = Partial<TItem>, TUpdate = Partial<TItem>, TKey extends ResourceKey = ResourceKey> {
+  list: () => Promise<TItem[]>
+  create?: (payload: TCreate) => Promise<TItem>
+  update?: (key: TKey, payload: TUpdate) => Promise<TItem>
+  remove?: (key: TKey) => Promise<void>
+}
+
+export interface UseResourceCrudOptions<
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+> {
+  adapter: ResourceCrudAdapter<TItem, TCreate, TUpdate, TKey>
+  initialItems?: readonly TItem[]
+  getKey?: (item: TItem) => TKey
+  readErrorMessage?: (error: unknown) => string
+}
+
+export interface UseResourceCrudReturn<TItem, TCreate, TUpdate, TKey extends ResourceKey> {
+  items: Ref<TItem[]>
+  loading: ShallowRef<boolean>
+  saving: ShallowRef<boolean>
+  deleting: ShallowRef<boolean>
+  error: Ref<string | null>
+  isBusy: ComputedRef<boolean>
+  load: () => Promise<TItem[]>
+  createItem: (payload: TCreate) => Promise<TItem>
+  updateItem: (key: TKey, payload: TUpdate) => Promise<TItem>
+  deleteItem: (keyOrItem: TKey | TItem) => Promise<void>
+  setItems: (items: readonly TItem[]) => void
+  upsertLocal: (item: TItem) => void
+  removeLocal: (keyOrItem: TKey | TItem) => void
+  clearError: () => void
+}
+
+/** Common list/create/update/delete state wrapper for generated plugin clients. */
+export function useResourceCrud<
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+>(
+  options: UseResourceCrudOptions<TItem, TCreate, TUpdate, TKey>,
+): UseResourceCrudReturn<TItem, TCreate, TUpdate, TKey> {
+  const items = ref<TItem[]>([...(options.initialItems ?? [])]) as Ref<TItem[]>
+  const loading = shallowRef(false)
+  const saving = shallowRef(false)
+  const deleting = shallowRef(false)
+  const error = ref<string | null>(null)
+  const isBusy = computed(() => loading.value || saving.value || deleting.value)
+
+  const readMessage = options.readErrorMessage ?? readErrorMessage
+  const getKey = options.getKey ?? defaultGetKey<TKey, TItem>
+
+  function clearError(): void {
+    error.value = null
+  }
+
+  function setError(err: unknown): void {
+    error.value = readMessage(err)
+  }
+
+  function setItems(nextItems: readonly TItem[]): void {
+    items.value = [...nextItems]
+  }
+
+  function upsertLocal(item: TItem): void {
+    const key = getKey(item)
+    const index = items.value.findIndex(existing => getKey(existing) === key)
+    if (index === -1) {
+      items.value = [...items.value, item]
+      return
+    }
+    items.value = [
+      ...items.value.slice(0, index),
+      item,
+      ...items.value.slice(index + 1),
+    ]
+  }
+
+  function removeLocal(keyOrItem: TKey | TItem): void {
+    const key = resolveKey(keyOrItem, getKey)
+    items.value = items.value.filter(item => getKey(item) !== key)
+  }
+
+  async function load(): Promise<TItem[]> {
+    loading.value = true
+    clearError()
+    try {
+      const result = await options.adapter.list()
+      setItems(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function createItem(payload: TCreate): Promise<TItem> {
+    if (!options.adapter.create) {
+      throw new Error('[MINT SDK] Resource adapter does not implement create().')
+    }
+    saving.value = true
+    clearError()
+    try {
+      const result = await options.adapter.create(payload)
+      upsertLocal(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      saving.value = false
+    }
+  }
+
+  async function updateItem(key: TKey, payload: TUpdate): Promise<TItem> {
+    if (!options.adapter.update) {
+      throw new Error('[MINT SDK] Resource adapter does not implement update().')
+    }
+    saving.value = true
+    clearError()
+    try {
+      const result = await options.adapter.update(key, payload)
+      upsertLocal(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      saving.value = false
+    }
+  }
+
+  async function deleteItem(keyOrItem: TKey | TItem): Promise<void> {
+    if (!options.adapter.remove) {
+      throw new Error('[MINT SDK] Resource adapter does not implement remove().')
+    }
+    const key = resolveKey(keyOrItem, getKey)
+    deleting.value = true
+    clearError()
+    try {
+      await options.adapter.remove(key)
+      removeLocal(key)
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      deleting.value = false
+    }
+  }
+
+  return {
+    items,
+    loading,
+    saving,
+    deleting,
+    error,
+    isBusy,
+    load,
+    createItem,
+    updateItem,
+    deleteItem,
+    setItems,
+    upsertLocal,
+    removeLocal,
+    clearError,
+  }
+}
+
+export interface PluginResourceClientOptions<
+  TClient,
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+> {
+  client: TClient
+  list: (client: TClient) => Promise<TItem[]>
+  create?: (client: TClient, payload: TCreate) => Promise<TItem>
+  update?: (client: TClient, key: TKey, payload: TUpdate) => Promise<TItem>
+  remove?: (client: TClient, key: TKey) => Promise<void>
+}
+
+export function createPluginResourceClient<
+  TClient,
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+>(
+  options: PluginResourceClientOptions<TClient, TItem, TCreate, TUpdate, TKey>,
+): ResourceCrudAdapter<TItem, TCreate, TUpdate, TKey> {
+  return {
+    list: () => options.list(options.client),
+    create: options.create
+      ? payload => options.create!(options.client, payload)
+      : undefined,
+    update: options.update
+      ? (key, payload) => options.update!(options.client, key, payload)
+      : undefined,
+    remove: options.remove
+      ? key => options.remove!(options.client, key)
+      : undefined,
+  }
+}
+
+function defaultGetKey<TKey extends ResourceKey, TItem>(item: TItem): TKey {
+  if (item && typeof item === 'object' && 'id' in item) {
+    return (item as { id: ResourceKey }).id as TKey
+  }
+  throw new Error('[MINT SDK] Resource items need an id field or a getKey option.')
+}
+
+function resolveKey<TItem, TKey extends ResourceKey>(
+  keyOrItem: TKey | TItem,
+  getKey: (item: TItem) => TKey,
+): TKey {
+  if (typeof keyOrItem === 'string' || typeof keyOrItem === 'number') {
+    return keyOrItem as TKey
+  }
+  return getKey(keyOrItem as TItem)
+}
+
+function readErrorMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message
+  if (typeof value === 'string' && value.trim()) return value
+  if (
+    typeof value === 'object'
+    && value !== null
+    && 'message' in value
+    && typeof (value as { message?: unknown }).message === 'string'
+    && (value as { message: string }).message.trim()
+  ) {
+    return (value as { message: string }).message
+  }
+  return 'Request failed.'
+}