@morscherlab/mint-sdk 1.3.11 → 1.4.0-beta.10

package/src/composables/usePresence.ts

@@ -0,0 +1,110 @@
+import {
+  getCurrentScope,
+  onScopeDispose,
+  readonly,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+import { useApi } from './useApi'
+import { currentPresence, subscribeRealtime, type RealtimeEvent } from './useRealtime'
+
+/**
+ * What a viewer does on a topic. The platform accepts a fixed set per topic
+ * kind: `experiment:{id}` takes all four labels, `project:{id}` only
+ * `viewing` and `editing`. `editing` means a form with unsaved edits is open;
+ * it is a hint, not a lock.
+ */
+export type PresenceActivity = 'viewing' | 'viewing_design' | 'viewing_results' | 'editing'
+
+/** One user with an open realtime stream on the topic. */
+export interface PresenceViewer {
+  user_id: string
+  activity: PresenceActivity
+}
+
+export interface UsePresenceReturn {
+  /** The viewers, `editing` first, at most 20; the current user is included. Empty while the stream is closed. */
+  viewers: Readonly<Ref<readonly PresenceViewer[]>>
+  /** Every viewer, also those beyond the 20 in `viewers`. */
+  count: Readonly<Ref<number>>
+  /** True while the shared realtime stream is open. */
+  connected: Readonly<Ref<boolean>>
+  /** Unsubscribe; also runs when the calling component or effect scope is disposed. */
+  stop: () => void
+}
+
+/**
+ * Who else views an `experiment:{id}` or `project:{id}` topic (RFC #439).
+ *
+ * Built on `useRealtime`: the tab's open stream on the topic is its presence,
+ * and `presence.changed` events update `viewers`. When `activity` is given,
+ * the label is sent to `POST /api/presence/activity` when the call starts on
+ * an open stream, each time the stream opens and each time the label changes;
+ * `stop` (also the end of the calling scope) sets it back to `viewing`.
+ * Without it, the platform shows the tab as `viewing`. Like `useRealtime`, it needs the platform's `realtime`
+ * feature flag; check that flag first.
+ *
+ * @example
+ * const { viewers } = usePresence(
+ *   () => `experiment:${id.value}`,
+ *   () => (dirty.value ? 'editing' : 'viewing'),
+ * )
+ */
+export function usePresence(
+  topic: MaybeRefOrGetter<string>,
+  activity?: MaybeRefOrGetter<PresenceActivity>,
+): UsePresenceReturn {
+  const viewers = ref<readonly PresenceViewer[]>([])
+  const count = ref(0)
+  const api = activity === undefined ? null : useApi({ baseUrl: '/api' })
+
+  function report(label = toValue(activity)): void {
+    // Presence is a hint: a failed report never reaches the view.
+    api?.post('/presence/activity', { topic: toValue(topic), activity: label }).catch(() => {})
+  }
+
+  function show(event: RealtimeEvent | undefined): void {
+    viewers.value = (event?.viewers ?? []) as PresenceViewer[]
+    count.value = event?.count ?? 0
+  }
+
+  const realtime = subscribeRealtime(() => [toValue(topic)], (event) => {
+    // ponytail: a resync after a queue overflow keeps the last viewers until
+    // the next change; read the presence over REST here if that shows.
+    if (event.type === 'resync') report()
+    else if (event.type === 'presence.changed' && event.topic === toValue(topic)) show(event)
+  }, true)
+
+  // When the tab's open stream already views the topic, no open and no resync follow.
+  function load(): void {
+    const current = currentPresence(toValue(topic))
+    show(current)
+    if (current) report()
+  }
+  load()
+  const stopTopic = watch(() => toValue(topic), load)
+  // A closed stream shows nobody; the server sends the viewers again at the next open.
+  const stopConnected = watch(realtime.connected, (open) => { if (!open) show(undefined) })
+  // While the stream is closed the report waits for the resync of the next open.
+  const stopActivity = watch(() => toValue(activity), () => {
+    if (realtime.connected.value) report()
+  })
+
+  let stopped = false
+  function stop(): void {
+    if (stopped) return
+    stopped = true
+    stopTopic()
+    stopConnected()
+    stopActivity()
+    // The stream can stay open on the topic for other callers: drop this caller's label.
+    if (realtime.connected.value && toValue(activity) !== 'viewing') report('viewing')
+    realtime.stop()
+  }
+  if (getCurrentScope()) onScopeDispose(stop)
+
+  return { viewers: readonly(viewers), count: readonly(count), connected: realtime.connected, stop }
+}

package/src/composables/useRackEditor.ts

@@ -32,7 +32,7 @@ export interface UseRackEditorReturn {
   /**
    * Applies every PlateEditor intent to this state, so the component can hold
    * data it never mutates itself:
-   * `<PlateEditor :model-value="racks" :active-rack-id="activeRackId" v-on="plateEditorListeners" />`
+   * `<PlateEditor :model-value="racks" :active-rack="activeRackId" v-on="plateEditorListeners" />`
    */
   plateEditorListeners: PlateEditorListeners
 
@@ -51,7 +51,7 @@ export interface UseRackEditorReturn {
 
 /** Handlers for PlateEditor's intent events, keyed by event name (bind with `v-on`). */
 export interface PlateEditorListeners {
-  'update:activeRackId': (rackId: string) => void
+  'update:activeRack': (rackId: string) => void
   'rack-add': () => void
   'rack-remove': (rackId: string) => void
   'rack-reorder': (rackIds: string[]) => void
@@ -327,7 +327,7 @@ export function useRackEditor(
   }
 
   const plateEditorListeners: PlateEditorListeners = {
-    'update:activeRackId': setActiveRack,
+    'update:activeRack': setActiveRack,
     'rack-add': recorded(() => { addRack() }),
     'rack-remove': recorded(removeRack),
     'rack-reorder': recorded((rackIds: string[]) => {

package/src/composables/useRealtime.ts

@@ -0,0 +1,194 @@
+import {
+  getCurrentScope,
+  onScopeDispose,
+  readonly,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+
+/**
+ * One event of the platform's realtime stream (`GET /api/events`).
+ *
+ * Platform events carry no entity data: refetch the entity through REST.
+ * `type` is `resync` (refetch everything you show), the audit action of a
+ * committed write, such as `experiment.update` or `analysis.artifact_create`,
+ * or the `"<plugin>.<event>"` name of a plugin event, which carries `payload`.
+ * Only `usePresence` receives `presence.changed`.
+ */
+export interface RealtimeEvent {
+  type: string
+  id?: string
+  /**
+   * `experiment:{id}`, `project:{id}`, `experiments`, `user:{id}`, or a plugin's
+   * `plugin:{name}` / `plugin:{name}:experiment:{id}`; absent on `resync`.
+   */
+  topic?: string
+  /** A plugin event: the JSON payload the plugin published (at most 16 KiB). */
+  payload?: unknown
+  /** Changed fields of an update, when the write names them. */
+  fields?: string[] | null
+  actor_id?: string | null
+  request_id?: string | null
+  at?: string
+  /** `presence.changed`: the topic's viewers (at most 20, `editing` first). */
+  viewers?: { user_id: string, activity: string }[]
+  /** `presence.changed`: the number of viewers, also those beyond `viewers`. */
+  count?: number
+}
+
+export type RealtimeHandler = (event: RealtimeEvent) => void
+
+export interface UseRealtimeReturn {
+  /** True while the shared stream is open. */
+  connected: Readonly<Ref<boolean>>
+  /** Unsubscribe; also runs when the calling component or effect scope is disposed. */
+  stop: () => void
+}
+
+const EVENTS_URL = '/api/events'
+const RECONNECT_BASE_MS = 1_000
+const RECONNECT_MAX_MS = 30_000
+/** Merges the subscriptions of components that mount together into one connection. */
+const TOPIC_DEBOUNCE_MS = 50
+const RESYNC: RealtimeEvent = { type: 'resync' }
+
+interface Listener {
+  topics: () => string[]
+  handler: RealtimeHandler
+  /** Receives `presence.changed`; a write listener would refetch on each viewer change. */
+  presence: boolean
+}
+
+const listeners = new Set<Listener>()
+/** The last `presence.changed` of each topic of the open stream; the server sends one per topic at open. */
+const presence = new Map<string, RealtimeEvent>()
+const connected = ref(false)
+let source: EventSource | null = null
+let sourceTopics = ''
+let failures = 0
+let syncTimer: ReturnType<typeof setTimeout> | null = null
+let retryTimer: ReturnType<typeof setTimeout> | null = null
+
+function dispatch(event: RealtimeEvent): void {
+  const isPresence = event.type === 'presence.changed'
+  if (isPresence && event.topic) presence.set(event.topic, event)
+  for (const listener of [...listeners]) {
+    if (isPresence && !listener.presence) continue
+    if (event.type === 'resync' || (event.topic && listener.topics().includes(event.topic))) {
+      listener.handler(event)
+    }
+  }
+}
+
+function close(): void {
+  source?.close()
+  source = null
+  sourceTopics = ''
+  presence.clear()
+  connected.value = false
+}
+
+function open(topics: string): void {
+  const stream = new EventSource(`${EVENTS_URL}?topics=${encodeURIComponent(topics)}`)
+  source = stream
+  sourceTopics = topics
+  stream.onopen = () => {
+    connected.value = true
+    // The server subscribes only now: a write between a caller's REST load (or
+    // the close of the previous stream) and this point sent no event, so every caller refetches.
+    dispatch(RESYNC)
+    failures = 0
+  }
+  stream.onmessage = (message) => {
+    dispatch(JSON.parse(message.data) as RealtimeEvent)
+  }
+  stream.onerror = () => {
+    // EventSource retries a dropped connection itself but gives up after an
+    // HTTP error, so one backoff path handles both.
+    if (source !== stream) return
+    close()
+    // A topic change during the wait does not shorten it: the retry reads the topics when it runs.
+    if (syncTimer !== null) clearTimeout(syncTimer)
+    syncTimer = null
+    retryTimer = setTimeout(() => {
+      retryTimer = null
+      sync()
+    }, Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** failures))
+    failures += 1
+  }
+}
+
+function sync(): void {
+  syncTimer = null
+  const topics = [...new Set([...listeners].flatMap(listener => listener.topics()))].sort().join(',')
+  if (source && topics === sourceTopics) return
+  close()
+  if (topics) open(topics)
+}
+
+function schedule(): void {
+  if (retryTimer !== null) return
+  if (syncTimer !== null) clearTimeout(syncTimer)
+  syncTimer = setTimeout(sync, TOPIC_DEBOUNCE_MS)
+}
+
+/**
+ * Subscribe to topics of the platform's realtime stream.
+ *
+ * Every caller in a tab shares one `EventSource`, opened on the union of
+ * their topics and reopened when that union changes. `handler` receives the
+ * write events of the caller's own topics (not `presence.changed`, which goes
+ * to `usePresence`) plus every `resync`: one comes from the
+ * server when this tab fell behind, and one follows each open of the stream:
+ * the first open, each reconnect (backoff from 1 s to 30 s) and each reopen for
+ * a changed topic union. On `resync`, refetch. The union of all callers' topics
+ * in a tab may hold at most 50 topics; the platform refuses a larger stream.
+ *
+ * The stream authenticates with the session cookie, so it works in the
+ * platform and in plugin frontends served by it. It exists only when the
+ * platform's `realtime` feature flag is on; check that flag first.
+ *
+ * A plugin topic reaches a caller whose role may use the plugin; an
+ * experiment plugin topic also needs a caller who may view the experiment.
+ *
+ * @example
+ * useRealtime(() => [`experiment:${id.value}`], () => refetch())
+ * @example
+ * useRealtime(['plugin:drp'], (event) => {
+ *   if (event.type === 'drp.run.progress') progress.value = event.payload as RunProgress
+ * })
+ */
+export function useRealtime(
+  topics: MaybeRefOrGetter<string[]>,
+  handler: RealtimeHandler,
+): UseRealtimeReturn {
+  return subscribeRealtime(topics, handler, false)
+}
+
+/** The last `presence.changed` of `topic` while the open stream views it (for `usePresence`). */
+export function currentPresence(topic: string): RealtimeEvent | undefined {
+  return presence.get(topic)
+}
+
+/** `useRealtime`, and with `withPresence` also the `presence.changed` events (for `usePresence`). */
+export function subscribeRealtime(
+  topics: MaybeRefOrGetter<string[]>,
+  handler: RealtimeHandler,
+  withPresence: boolean,
+): UseRealtimeReturn {
+  const listener: Listener = { topics: () => toValue(topics), handler, presence: withPresence }
+  listeners.add(listener)
+  const stopWatch = watch(() => listener.topics().join(','), () => schedule())
+  schedule()
+
+  function stop(): void {
+    stopWatch()
+    if (listeners.delete(listener)) schedule()
+  }
+
+  if (getCurrentScope()) onScopeDispose(stop)
+  return { connected: readonly(connected), stop }
+}

package/src/composables/{useRequestSyncState.ts → useRequest.ts}

@@ -1,7 +1,7 @@
 import { ref, type Ref } from 'vue'
 import { readErrorMessage as readSharedErrorMessage } from '../utils/errors'
 
-export type RequestSyncSuccessKind = 'load' | 'save' | 'run'
+export type RequestKind = 'load' | 'save' | 'run'
 
 /**
  * The unit of work `run()` drives.
@@ -10,10 +10,11 @@ export type RequestSyncSuccessKind = 'load' | 'save' | 'run'
  * newer `run()` or by `cancel()`. Zero-argument operations stay valid and
  * simply ignore it.
  */
-export type RequestSyncOperation<T> = (signal: AbortSignal) => Promise<T>
+export type RequestOperation<T> = (signal: AbortSignal) => Promise<T>
 
-export interface RequestSyncRunOptions {
-  success?: RequestSyncSuccessKind
+export interface RequestRunOptions {
+  /** Which timestamp a successful run moves: `lastLoadedAt`, `lastSavedAt` or `lastRunAt`. */
+  kind?: RequestKind
   errorMessage?: string
   /**
    * Abort the previously started run when this one starts. Default `true`;
@@ -25,9 +26,9 @@ export interface RequestSyncRunOptions {
   signal?: AbortSignal
 }
 
-export interface UseRequestSyncStateReturn {
+export interface UseRequestReturn {
   /** Whether a request is in progress. */
-  loading: Ref<boolean>
+  isLoading: Ref<boolean>
   /** Message from the last failed request, or null. */
   error: Ref<string | null>
   /** Timestamp of the last successful load operation, or null. */
@@ -42,12 +43,6 @@ export interface UseRequestSyncStateReturn {
   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.
    *
@@ -55,7 +50,7 @@ export interface UseRequestSyncStateReturn {
    *
    * Every call takes a monotonically increasing token. Starting a run
    * supersedes any run started before it, and a superseded run writes **no**
-   * shared state when it finally settles: it does not clear `loading`, does not
+   * shared state when it finally settles: it does not clear `isLoading`, does not
    * set `error`, and does not move `lastLoadedAt` / `lastSavedAt` / `lastRunAt`.
    * Only the newest run owns those.
    *
@@ -68,19 +63,19 @@ export interface UseRequestSyncStateReturn {
    * run is superseded or `cancel()` is called, so an operation that forwards
    * the signal (`fetch(url, { signal })`) stops work instead of racing.
    */
-  run: <T>(operation: RequestSyncOperation<T>, options?: RequestSyncRunOptions) => Promise<T>
+  run: <T>(operation: RequestOperation<T>, options?: RequestRunOptions) => Promise<T>
   /**
-   * Abort the in-flight run and drop `loading`. The aborted run's completion
+   * Abort the in-flight run and drop `isLoading`. The aborted run's completion
    * is treated as stale and writes no state.
    */
   cancel: () => void
 }
 
-/** Shared loading/error/timestamp state for generated plugin request helpers. */
-export function useRequestSyncState(
+/** Loading, error and timestamp state for one request at a time; `run()` drives it. */
+export function useRequest(
   defaultErrorMessage = 'Request failed.',
-): UseRequestSyncStateReturn {
-  const loading = ref(false)
+): UseRequestReturn {
+  const isLoading = ref(false)
   const error = ref<string | null>(null)
   const lastLoadedAt = ref<Date | null>(null)
   const lastSavedAt = ref<Date | null>(null)
@@ -100,18 +95,6 @@ export function useRequestSyncState(
     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
-  }
-
   // Monotonic token guarding every write to the shared loading/error/timestamp
   // state. Overlapping runs settle in any order, and a superseded one must not
   // clear a newer run's loading flag or overwrite its error.
@@ -122,12 +105,12 @@ export function useRequestSyncState(
     runToken += 1
     activeController?.abort()
     activeController = null
-    loading.value = false
+    isLoading.value = false
   }
 
   async function run<T>(
-    operation: RequestSyncOperation<T>,
-    options: RequestSyncRunOptions = {},
+    operation: RequestOperation<T>,
+    options: RequestRunOptions = {},
   ): Promise<T> {
     if (options.abortPrevious !== false) {
       activeController?.abort()
@@ -149,18 +132,15 @@ export function useRequestSyncState(
 
     const isCurrent = (): boolean => token === runToken
 
-    loading.value = true
+    isLoading.value = true
     clearError()
     try {
       const response = await operation(controller.signal)
-      if (isCurrent()) {
-        if (options.success === 'load') {
-          markLoaded()
-        } else if (options.success === 'save') {
-          markSaved()
-        } else if (options.success === 'run') {
-          markRun()
-        }
+      if (isCurrent() && options.kind) {
+        const settledAt = new Date()
+        if (options.kind === 'load') lastLoadedAt.value = settledAt
+        else if (options.kind === 'save') lastSavedAt.value = settledAt
+        else lastRunAt.value = settledAt
       }
       return response
     } catch (err) {
@@ -170,7 +150,7 @@ export function useRequestSyncState(
       throw err
     } finally {
       if (isCurrent()) {
-        loading.value = false
+        isLoading.value = false
       }
       if (activeController === controller) {
         activeController = null
@@ -179,7 +159,7 @@ export function useRequestSyncState(
   }
 
   return {
-    loading,
+    isLoading,
     error,
     lastLoadedAt,
     lastSavedAt,
@@ -187,9 +167,6 @@ export function useRequestSyncState(
     clearError,
     readErrorMessage,
     setError,
-    markLoaded,
-    markSaved,
-    markRun,
     run,
     cancel,
   }

package/src/composables/useScheduleCalendarLayout.ts

@@ -5,7 +5,7 @@ import type {
   ScheduleBlockedSlot,
   ScheduleEventStatus,
 } from '../types/components'
-import { formatTime } from './useTimeUtils'
+import { formatTime } from '../utils/time'
 
 type ReadableRef<T> = Readonly<Ref<T>>
 

package/src/composables/useToast.ts

@@ -4,6 +4,9 @@ import type { Toast, ToastOptions } from '../types'
 const toasts = ref<Toast[]>([])
 let nextId = 0
 
+/** Options of `success()`, `error()`, `warning()` and `info()`: the message is the title. */
+type ToastMessageOptions = Omit<ToastOptions, 'title' | 'type'>
+
 /** Reactive global toast queue with success/error/warning/info variants and auto-dismiss timers. */
 export function useToast() {
   /** Push a structured toast. `progress: 'indeterminate'` is the in-progress form and never auto-dismisses. */
@@ -24,24 +27,24 @@ export function useToast() {
     return id
   }
 
-  function show(message: string, type: Toast['type'] = 'success', duration = 3500) {
-    push({ title: message, type, duration })
+  function notify(type: Toast['type'], duration: number, message: string, options: ToastMessageOptions = {}): number {
+    return push({ duration, ...options, title: message, type })
   }
 
-  function success(message: string, duration = 3500) {
-    show(message, 'success', duration)
+  function success(message: string, options?: ToastMessageOptions): number {
+    return notify('success', 3500, message, options)
   }
 
-  function error(message: string, duration = 5000) {
-    show(message, 'error', duration)
+  function error(message: string, options?: ToastMessageOptions): number {
+    return notify('error', 5000, message, options)
   }
 
-  function warning(message: string, duration = 4000) {
-    show(message, 'warning', duration)
+  function warning(message: string, options?: ToastMessageOptions): number {
+    return notify('warning', 4000, message, options)
   }
 
-  function info(message: string, duration = 3500) {
-    show(message, 'info', duration)
+  function info(message: string, options?: ToastMessageOptions): number {
+    return notify('info', 3500, message, options)
   }
 
   function dismiss(id: number) {
@@ -52,5 +55,5 @@ export function useToast() {
     toasts.value = []
   }
 
-  return { toasts, push, show, success, error, warning, info, dismiss, clear }
+  return { toasts, push, success, error, warning, info, dismiss, clear }
 }