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

package/src/composables/useEventStream.ts

@@ -0,0 +1,314 @@
+import {
+  getCurrentInstance,
+  getCurrentScope,
+  onMounted,
+  onScopeDispose,
+  ref,
+  shallowRef,
+  type Ref,
+} from 'vue'
+
+export type EventStreamTransport = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>
+
+export interface EventStreamMessage<TData = string> {
+  event: string
+  data: TData
+  id?: string
+  retry?: number
+  raw: string
+}
+
+export interface EventStreamOptions<TData = string> {
+  transport?: EventStreamTransport
+  headers?: HeadersInit
+  credentials?: RequestCredentials
+  immediate?: boolean
+  reconnect?: boolean
+  reconnectDelayMs?: number
+  parseJson?: boolean
+  shouldReconnect?: (cause?: unknown) => boolean
+  onOpen?: () => void
+  onMessage?: (message: EventStreamMessage<TData>) => void
+  onError?: (cause: unknown) => void
+  onClose?: (cause?: unknown) => void
+  errorLabel?: string
+}
+
+export interface UseEventStreamReturn<TData = string> {
+  isConnected: Ref<boolean>
+  isConnecting: Ref<boolean>
+  error: Ref<string | null>
+  lastMessage: Ref<EventStreamMessage<TData> | null>
+  lastEventId: Ref<string | null>
+  start: () => void
+  stop: () => void
+}
+
+interface ParsedEventStreamBlock<TData> {
+  message?: EventStreamMessage<TData>
+  id?: string
+  retry?: number
+}
+
+class EventStreamResponseError extends Error {
+  constructor(readonly response: Response, label: string) {
+    super(`${label} failed with HTTP ${response.status}`)
+    this.name = 'EventStreamResponseError'
+  }
+}
+
+/** Parse one complete SSE block without owning connection policy. */
+export function parseEventStreamBlock<TData>(
+  block: string,
+  parseJson: boolean,
+): ParsedEventStreamBlock<TData> | null {
+  let event = 'message'
+  let id: string | undefined
+  let retry: number | undefined
+  const dataLines: string[] = []
+
+  for (const line of block.split(/\r\n|\r|\n/)) {
+    if (!line || line.startsWith(':')) continue
+    const separator = line.indexOf(':')
+    const field = separator === -1 ? line : line.slice(0, separator)
+    const value = separator === -1
+      ? ''
+      : line.slice(separator + 1).replace(/^ /, '')
+
+    if (field === 'event') event = value || 'message'
+    if (field === 'data') dataLines.push(value)
+    if (field === 'id' && !value.includes('\0')) id = value
+    if (field === 'retry' && /^\d+$/.test(value)) retry = Number(value)
+  }
+
+  if (!dataLines.length && id === undefined && retry === undefined) return null
+  const data = dataLines.join('\n')
+  return {
+    message: dataLines.length
+      ? {
+          event,
+          data: (parseJson && data ? JSON.parse(data) : data) as TData,
+          id,
+          retry,
+          raw: block,
+        }
+      : undefined,
+    id,
+    retry,
+  }
+}
+
+/** Shared fetch-based SSE lifecycle with cancellation and reconnect safety. */
+export function useEventStream<TData = string>(
+  url: string | (() => string),
+  options: EventStreamOptions<TData> = {},
+): UseEventStreamReturn<TData> {
+  const isConnected = ref(false)
+  const isConnecting = ref(false)
+  const error = ref<string | null>(null)
+  const lastMessage = shallowRef<EventStreamMessage<TData> | null>(null)
+  const lastEventId = ref<string | null>(null)
+  let controller: AbortController | null = null
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  let reconnectDelayMs = options.reconnectDelayMs ?? 2_000
+  let stopped = true
+  let generation = 0
+
+  function clearReconnectTimer(): void {
+    if (reconnectTimer === null) return
+    clearTimeout(reconnectTimer)
+    reconnectTimer = null
+  }
+
+  function ownsConnection(
+    connectionGeneration: number,
+    connectionController: AbortController,
+  ): boolean {
+    return !stopped
+      && generation === connectionGeneration
+      && controller === connectionController
+  }
+
+  function scheduleReconnect(connectionGeneration: number, cause?: unknown): void {
+    if (stopped || generation !== connectionGeneration) return
+    if (options.reconnect === false || options.shouldReconnect?.(cause) === false) {
+      stopped = true
+      return
+    }
+    clearReconnectTimer()
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null
+      if (stopped || generation !== connectionGeneration) return
+      void connect(connectionGeneration)
+    }, reconnectDelayMs)
+  }
+
+  function dispatchBlock(
+    block: string,
+    connectionGeneration: number,
+    connectionController: AbortController,
+  ): void {
+    const parsed = parseEventStreamBlock<TData>(block, options.parseJson ?? false)
+    if (!parsed || !ownsConnection(connectionGeneration, connectionController)) return
+    if (parsed.id !== undefined) {
+      lastEventId.value = parsed.id
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+    }
+    if (parsed.retry !== undefined) reconnectDelayMs = parsed.retry
+    const message = parsed.message
+    if (!message || !ownsConnection(connectionGeneration, connectionController)) return
+    lastMessage.value = message
+    if (!ownsConnection(connectionGeneration, connectionController)) return
+    options.onMessage?.(message)
+  }
+
+  async function consume(
+    body: ReadableStream<Uint8Array>,
+    connectionGeneration: number,
+    connectionController: AbortController,
+  ): Promise<void> {
+    const connectionReader = body.getReader()
+    reader = connectionReader
+    const decoder = new TextDecoder()
+    let buffer = ''
+    try {
+      for (;;) {
+        const { value, done } = await connectionReader.read()
+        if (!ownsConnection(connectionGeneration, connectionController)) return
+        buffer += decoder.decode(value, { stream: !done })
+
+        let boundary = /(?:\r\n|\r|\n){2}/.exec(buffer)
+        while (boundary?.index !== undefined) {
+          const block = buffer.slice(0, boundary.index)
+          buffer = buffer.slice(boundary.index + boundary[0].length)
+          dispatchBlock(block, connectionGeneration, connectionController)
+          if (!ownsConnection(connectionGeneration, connectionController)) return
+          boundary = /(?:\r\n|\r|\n){2}/.exec(buffer)
+        }
+
+        if (!done) continue
+        if (buffer) dispatchBlock(buffer, connectionGeneration, connectionController)
+        return
+      }
+    } finally {
+      if (reader === connectionReader) reader = null
+      connectionReader.releaseLock()
+    }
+  }
+
+  async function connect(connectionGeneration: number): Promise<void> {
+    if (stopped || generation !== connectionGeneration) return
+    controller?.abort()
+    const connectionController = new AbortController()
+    controller = connectionController
+    isConnecting.value = true
+    if (!ownsConnection(connectionGeneration, connectionController)) return
+    error.value = null
+    if (!ownsConnection(connectionGeneration, connectionController)) return
+
+    let cause: unknown
+    try {
+      const headers = new Headers(options.headers)
+      headers.set('Accept', 'text/event-stream')
+      if (lastEventId.value && !headers.has('Last-Event-ID')) {
+        headers.set('Last-Event-ID', lastEventId.value)
+      }
+      const transport = options.transport ?? globalThis.fetch?.bind(globalThis)
+      if (!transport) throw new Error('[MINT SDK] fetch is required for event streams.')
+      const response = await transport(typeof url === 'function' ? url() : url, {
+        method: 'GET',
+        headers,
+        credentials: options.credentials ?? 'same-origin',
+        signal: connectionController.signal,
+      })
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      if (!response.ok) {
+        throw new EventStreamResponseError(response, options.errorLabel ?? 'Event stream')
+      }
+      if (!response.body) {
+        throw new Error(`${options.errorLabel ?? 'Event stream'} response did not include a readable body.`)
+      }
+
+      isConnected.value = true
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      isConnecting.value = false
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      options.onOpen?.()
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      await consume(response.body, connectionGeneration, connectionController)
+    } catch (errorCause) {
+      cause = errorCause
+      if (
+        ownsConnection(connectionGeneration, connectionController)
+        && !isAbortError(errorCause)
+      ) {
+        error.value = errorCause instanceof Error
+          ? errorCause.message
+          : `${options.errorLabel ?? 'Event stream'} failed`
+        if (ownsConnection(connectionGeneration, connectionController)) {
+          options.onError?.(errorCause)
+        }
+      }
+    } finally {
+      if (ownsConnection(connectionGeneration, connectionController)) {
+        isConnecting.value = false
+        if (!ownsConnection(connectionGeneration, connectionController)) return
+        isConnected.value = false
+        if (!ownsConnection(connectionGeneration, connectionController)) return
+        controller = null
+        options.onClose?.(cause)
+        if (!stopped && generation === connectionGeneration) {
+          scheduleReconnect(connectionGeneration, cause)
+        }
+      }
+    }
+  }
+
+  function start(): void {
+    if (!stopped) return
+    stopped = false
+    clearReconnectTimer()
+    generation += 1
+    void connect(generation)
+  }
+
+  function stop(): void {
+    if (stopped) return
+    stopped = true
+    generation += 1
+    clearReconnectTimer()
+    controller?.abort()
+    controller = null
+    if (reader) void reader.cancel().catch(() => undefined)
+    reader = null
+    isConnecting.value = false
+    isConnected.value = false
+  }
+
+  const currentInstance = getCurrentInstance()
+  if (currentInstance && options.immediate !== false && typeof window === 'undefined') {
+    onMounted(start)
+  }
+  if (getCurrentScope()) onScopeDispose(stop)
+  if (options.immediate !== false && (typeof window !== 'undefined' || !currentInstance)) {
+    start()
+  }
+
+  return {
+    isConnected,
+    isConnecting,
+    error,
+    lastMessage,
+    lastEventId,
+    start,
+    stop,
+  }
+}
+
+function isAbortError(cause: unknown): boolean {
+  return cause instanceof DOMException && cause.name === 'AbortError'
+}

package/src/composables/useExpansionSet.ts

@@ -0,0 +1,117 @@
+import { computed, ref, toValue, watch, type ComputedRef, type Ref } from 'vue'
+
+export type ExpansionSetSource<T> =
+  | T
+  | Ref<T>
+  | ComputedRef<T>
+  | (() => T)
+
+export interface UseExpansionSetOptions {
+  defaultIds?: ExpansionSetSource<readonly string[] | null | undefined>
+  allIds?: ExpansionSetSource<readonly string[] | null | undefined>
+  expandAll?: ExpansionSetSource<boolean | null | undefined>
+}
+
+export interface UseExpansionSetReturn {
+  expandedIds: Ref<Set<string>>
+  expandedList: ComputedRef<string[]>
+  isExpanded: (id: string) => boolean
+  expand: (id: string) => void
+  collapse: (id: string) => void
+  toggle: (id: string) => boolean
+  expandMany: (ids: readonly string[]) => void
+  setExpanded: (ids: readonly string[]) => void
+  collapseAll: () => void
+  reset: () => void
+}
+
+/** Shared expansion state for trees, grouped selectors, and disclosure lists. */
+export function useExpansionSet(options: UseExpansionSetOptions = {}): UseExpansionSetReturn {
+  const expandedIds = ref(new Set(normalizeIds(toValue(options.defaultIds))))
+  const expandedList = computed(() => [...expandedIds.value])
+
+  if (options.expandAll !== undefined) {
+    watch(
+      () => toValue(options.expandAll),
+      (shouldExpandAll) => {
+        if (shouldExpandAll === undefined || shouldExpandAll === null) return
+        if (shouldExpandAll) {
+          setExpanded(normalizeIds(toValue(options.allIds)))
+        } else {
+          reset()
+        }
+      },
+      { immediate: true },
+    )
+  }
+
+  if (options.allIds !== undefined) {
+    watch(
+      () => normalizeIds(toValue(options.allIds)),
+      (ids) => {
+        if (toValue(options.expandAll)) {
+          setExpanded(ids)
+        }
+      },
+    )
+  }
+
+  function isExpanded(id: string): boolean {
+    return expandedIds.value.has(id)
+  }
+
+  function expand(id: string) {
+    if (expandedIds.value.has(id)) return
+    expandedIds.value = new Set([...expandedIds.value, id])
+  }
+
+  function collapse(id: string) {
+    if (!expandedIds.value.has(id)) return
+    const next = new Set(expandedIds.value)
+    next.delete(id)
+    expandedIds.value = next
+  }
+
+  function toggle(id: string): boolean {
+    if (expandedIds.value.has(id)) {
+      collapse(id)
+      return false
+    }
+    expand(id)
+    return true
+  }
+
+  function expandMany(ids: readonly string[]) {
+    expandedIds.value = new Set([...expandedIds.value, ...normalizeIds(ids)])
+  }
+
+  function setExpanded(ids: readonly string[]) {
+    expandedIds.value = new Set(normalizeIds(ids))
+  }
+
+  function collapseAll() {
+    expandedIds.value = new Set()
+  }
+
+  function reset() {
+    setExpanded(normalizeIds(toValue(options.defaultIds)))
+  }
+
+  return {
+    expandedIds,
+    expandedList,
+    isExpanded,
+    expand,
+    collapse,
+    toggle,
+    expandMany,
+    setExpanded,
+    collapseAll,
+    reset,
+  }
+}
+
+function normalizeIds(ids: readonly string[] | null | undefined): string[] {
+  if (!ids) return []
+  return [...new Set(ids.filter(Boolean))]
+}

package/src/composables/useExperimentData.ts

@@ -0,0 +1,136 @@
+import { shallowRef, computed, type Ref, type ComputedRef } from 'vue'
+import { useApi, type UseApiReturn } from './useApi'
+import { useRequestSyncState } from './useRequestSyncState'
+import {
+  extractSampleNamesFromDesignData,
+  extractSampleOptionsFromDesignData,
+  unwrapExperimentDesignData,
+} from './experimentDesignData'
+import type { TreeNode, SummaryData, SelectOption } from '../types'
+
+export interface UseExperimentDataOptions {
+  apiBaseUrl?: string
+  immediate?: boolean
+}
+
+export interface UseExperimentDataReturn {
+  /** Raw experiment data response from `/experiments/{id}/data`, or null. */
+  data: Ref<Record<string, unknown> | null>
+  /** Plugin-defined design_data payload unwrapped from platform response shapes, or null. */
+  designData: ComputedRef<Record<string, unknown> | null>
+  /** Sample values extracted from design_data for SampleSelector-style components. */
+  sampleNames: ComputedRef<string[]>
+  /** Sample options extracted from design_data for select/dropdown components. */
+  sampleOptions: ComputedRef<SelectOption<string>[]>
+  /** Hierarchy tree rows normalised from `tree_data` or `treeData`. */
+  treeData: ComputedRef<TreeNode[]>
+  /** Table rows normalised from `table_data` or `tableData`. */
+  tableData: ComputedRef<Record<string, unknown>[]>
+  /** Summary payload normalised from `summary_data` or `summaryData`, or null. */
+  summaryData: ComputedRef<SummaryData | null>
+  /** Whether experiment data is currently loading. */
+  isLoading: Ref<boolean>
+  /** Error message from the last failed fetch, or null. */
+  error: Ref<string | null>
+  /** Timestamp of the last successful experiment data fetch, or null. */
+  lastLoadedAt: Ref<Date | null>
+  /** Fetch experiment data for an experiment id. */
+  fetch: (experimentId: number) => Promise<Record<string, unknown> | null>
+  /** Refetch the most recently fetched experiment id. */
+  refresh: () => Promise<void>
+  /** Clear local experiment data and current fetch target. */
+  clear: () => void
+}
+
+/** Fetches and normalises experiment output data (tree, table, summary) from the platform API. */
+export function useExperimentData(
+  options: UseExperimentDataOptions = {},
+): UseExperimentDataReturn {
+  const data = shallowRef<Record<string, unknown> | null>(null)
+  const request = useRequestSyncState('Failed to fetch experiment data')
+  const isLoading = request.loading
+  const error = request.error
+  const lastLoadedAt = request.lastLoadedAt
+  let lastExperimentId: number | null = null
+  let api: UseApiReturn | null = null
+
+  function getApi(): UseApiReturn {
+    api ??= useApi({ baseUrl: options.apiBaseUrl })
+    return api
+  }
+
+  const designData = computed<Record<string, unknown> | null>(() =>
+    unwrapExperimentDesignData(data.value),
+  )
+
+  const sampleNames = computed<string[]>(() =>
+    extractSampleNamesFromDesignData(designData.value),
+  )
+
+  const sampleOptions = computed<SelectOption<string>[]>(() =>
+    extractSampleOptionsFromDesignData(designData.value),
+  )
+
+  const treeData = computed<TreeNode[]>(() => {
+    if (!designData.value) return []
+    const tree = designData.value.tree_data ?? designData.value.treeData
+    return Array.isArray(tree) ? tree as TreeNode[] : []
+  })
+
+  const tableData = computed<Record<string, unknown>[]>(() => {
+    if (!designData.value) return []
+    const table = designData.value.table_data ?? designData.value.tableData
+    return Array.isArray(table) ? table as Record<string, unknown>[] : []
+  })
+
+  const summaryData = computed<SummaryData | null>(() => {
+    if (!designData.value) return null
+    const summary = designData.value.summary_data ?? designData.value.summaryData
+    if (summary && typeof summary === 'object' && 'metadata' in (summary as Record<string, unknown>)) {
+      return summary as SummaryData
+    }
+    return null
+  })
+
+  async function fetchData(experimentId: number): Promise<Record<string, unknown> | null> {
+    lastExperimentId = experimentId
+    try {
+      data.value = await request.run(
+        () => getApi().get<Record<string, unknown>>(`/experiments/${experimentId}/data`),
+        { success: 'load', errorMessage: 'Failed to fetch experiment data' },
+      )
+      return data.value
+    } catch {
+      data.value = null
+      return null
+    }
+  }
+
+  async function refresh(): Promise<void> {
+    if (lastExperimentId !== null) {
+      await fetchData(lastExperimentId)
+    }
+  }
+
+  function clear(): void {
+    data.value = null
+    lastExperimentId = null
+    request.clearError()
+  }
+
+  return {
+    data,
+    designData,
+    sampleNames,
+    sampleOptions,
+    treeData,
+    tableData,
+    summaryData,
+    isLoading,
+    error,
+    lastLoadedAt,
+    fetch: fetchData,
+    refresh,
+    clear,
+  }
+}

package/src/composables/useExperimentSamples.ts

@@ -0,0 +1,142 @@
+import {
+  computed,
+  inject,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+import type { SelectOption } from '../types'
+import { APP_EXPERIMENT_KEY } from './useAppExperiment'
+import {
+  extractSampleNamesFromDesignData,
+  extractSampleOptionsFromDesignData,
+  unwrapExperimentDesignData,
+  type ExtractExperimentSamplesOptions,
+} from './experimentDesignData'
+import { parseExperimentId } from './platformContextHelpers'
+import { useExperimentData } from './useExperimentData'
+
+export type ExperimentIdSource = MaybeRefOrGetter<number | string | null | undefined>
+export type ExperimentDesignDataSource = MaybeRefOrGetter<Record<string, unknown> | null | undefined>
+
+export interface UseExperimentSamplesOptions extends ExtractExperimentSamplesOptions {
+  /** Experiment id to load from `/experiments/{id}/data`; defaults to provided AppExperiment context. */
+  experimentId?: ExperimentIdSource
+  /** Pre-fetched design_data or full platform design-data response. */
+  designData?: ExperimentDesignDataSource
+  /** API base URL override for platform calls. */
+  apiBaseUrl?: string
+  /** Auto-load when an experiment id becomes available. Defaults to true. */
+  immediate?: boolean
+  /** Enable or disable automatic loading while keeping derived samples reactive. Defaults to true. */
+  enabled?: MaybeRefOrGetter<boolean>
+  /** Use `useAppExperiment` provided state when `experimentId` is not set. Defaults to true. */
+  syncAppExperiment?: boolean
+}
+
+export interface UseExperimentSamplesReturn {
+  /** Experiment id currently used for automatic sample loading. */
+  experimentId: ComputedRef<number | undefined>
+  /** Raw `/experiments/{id}/data` response when loaded through the platform API. */
+  data: Ref<Record<string, unknown> | null>
+  /** Plugin-defined design_data payload from props or platform response. */
+  designData: ComputedRef<Record<string, unknown> | null>
+  /** SampleSelector-compatible string values extracted from design_data. */
+  samples: ComputedRef<string[]>
+  /** Select/dropdown-friendly sample options extracted from design_data. */
+  sampleOptions: ComputedRef<SelectOption<string>[]>
+  isLoading: Ref<boolean>
+  error: Ref<string | null>
+  lastLoadedAt: Ref<Date | null>
+  /** Fetch samples for a specific experiment id, defaulting to the resolved id. */
+  fetch: (experimentId?: number | string | null) => Promise<Record<string, unknown> | null>
+  /** Refetch the current experiment id. */
+  refresh: () => Promise<void>
+  /** Clear fetched platform data. */
+  clear: () => void
+}
+
+/** Loads experiment design_data and derives samples for SampleSelector-style UIs. */
+export function useExperimentSamples(
+  options: UseExperimentSamplesOptions = {},
+): UseExperimentSamplesReturn {
+  const appExperiment = options.syncAppExperiment === false
+    ? undefined
+    : inject(APP_EXPERIMENT_KEY, undefined)
+  const experimentData = useExperimentData({ apiBaseUrl: options.apiBaseUrl })
+
+  const experimentId = computed<number | undefined>(() => {
+    const explicitId = parseExperimentId(toValue(options.experimentId))
+    return explicitId ?? parseExperimentId(appExperiment?.experimentId.value)
+  })
+
+  const explicitDesignData = computed<Record<string, unknown> | null>(() =>
+    unwrapExperimentDesignData(toValue(options.designData) ?? null),
+  )
+
+  const designData = computed<Record<string, unknown> | null>(() =>
+    explicitDesignData.value ?? experimentData.designData.value,
+  )
+
+  const extractOptions = computed<ExtractExperimentSamplesOptions>(() => ({
+    includeControls: options.includeControls,
+  }))
+
+  const samples = computed<string[]>(() =>
+    extractSampleNamesFromDesignData(designData.value, extractOptions.value),
+  )
+
+  const sampleOptions = computed<SelectOption<string>[]>(() =>
+    extractSampleOptionsFromDesignData(designData.value, extractOptions.value),
+  )
+
+  const enabled = computed(() => toValue(options.enabled) ?? true)
+
+  async function fetchSamples(
+    id: number | string | null | undefined = experimentId.value,
+  ): Promise<Record<string, unknown> | null> {
+    const parsedId = parseExperimentId(id)
+    if (parsedId === undefined) {
+      experimentData.clear()
+      return null
+    }
+    return experimentData.fetch(parsedId)
+  }
+
+  watch(
+    () => ({
+      designData: explicitDesignData.value,
+      enabled: enabled.value,
+      experimentId: experimentId.value,
+    }),
+    ({ designData: currentDesignData, enabled: isEnabled, experimentId: currentExperimentId }) => {
+      if (options.immediate === false || !isEnabled) return
+      if (currentDesignData) {
+        experimentData.clear()
+        return
+      }
+      if (currentExperimentId === undefined) {
+        experimentData.clear()
+        return
+      }
+      void experimentData.fetch(currentExperimentId)
+    },
+    { immediate: options.immediate !== false },
+  )
+
+  return {
+    experimentId,
+    data: experimentData.data,
+    designData,
+    samples,
+    sampleOptions,
+    isLoading: experimentData.isLoading,
+    error: experimentData.error,
+    lastLoadedAt: experimentData.lastLoadedAt,
+    fetch: fetchSamples,
+    refresh: experimentData.refresh,
+    clear: experimentData.clear,
+  }
+}