@xen-orchestra/web-core 0.26.1 → 0.28.0

package/lib/packages/remote-resource/README.md

@@ -0,0 +1,115 @@
+# `defineRemoteResource` documentation
+
+This utility will create a function that can be used to fetch data from a remote resource (i.e., an API endpoint)
+
+When called, a subscription to the resource is registered.
+
+If multiple Components call that same function, a subscription will be registered for each of them.
+
+They will share the same data and state, which means that the data will be fetched only once and shared across all Components.
+
+The fetch will start automatically when at least one Component is using the resource, then, when the last Component releases the resource, the polling will stop.
+
+The data is cached for a certain duration, so if a Component remounts in the frame time, the data will be retrieved from the cache to be displayed immediately, while the data is being fetched again in the background.
+
+## Basic usage
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: '/api/path/to/resource',
+})
+```
+
+By default, the initial data (`TData`) will be `undefined`, the returned state will be `{ data: Ref<TData> }` and when new data is received, it will just replace the previous one.
+
+```typescript
+const { data } = useMyResource()
+```
+
+## Initial data, state and received data handling
+
+The initial data, the state and what happen when data is retrieved can be customized by passing the `initialData`, `state` and `onDataReceived` properties:
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: '/api/path/to/resource',
+  initialData: () => {} as Partial<MyResource>,
+  state: (data) => {
+    return {
+      myResource: data,
+      customProp: computed(() => data.foobar)
+    }
+  },
+  onDataReceived: (currentData, receivedData) => {
+    deepMerge(currentData.value, receivedData)
+  }
+}
+
+const { myResource, customProp } = useMyResource()
+```
+
+## Context
+
+The context is available in the `$context` property of the returned state.
+
+It contains the following properties:
+
+| Property      | Type                              | Description                                                                        |
+| ------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
+| `scope`       | `EffectScope`                     | The Vue effect scope used to be shared across the resource and its dependencies    |
+| `args`        | `any[]`                           | The arguments passed to the `useMyResource` function                               |
+| `isReady`     | `ComputedRef<boolean>`            | Indicates if the resource is ready (i.e., the data has been fetched at least once) |
+| `hasError`    | `ComputedRef<boolean>`            | Indicates if an error occurred during the last fetch                               |
+| `lastError`   | `ComputedRef<Error \| undefined>` | The last error that occurred during the fetch, if any                              |
+| `isEnabled`   | `Ref<boolean>`                    | Whether the resource is enabled (execute the request) or not                       |
+| `enable`      | `() => void`                      | Function to manually enable the resource                                           |
+| `disable`     | `() => void`                      | Function to manually disable the resource                                          |
+| `forceReload` | `() => void`                      | Function to manually reload the resource                                           |
+
+```typescript
+const { myResource, $context } = useMyResource()
+```
+
+It's also passed as the second argument of the `state` builder and can be used to extend the resource state.
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: '/api/path/to/resource',
+  state: (data, context) => ({
+    myResource: data,
+    isMyResourceReady: context.isReady,
+  }),
+})
+
+const { myResource, isMyResourceReady } = useMyResource()
+```
+
+## Dynamic URLs
+
+You can define a dynamic URL by using a function that returns the URL string.
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: (id: string) => `/api/path/to/resource/${id}`,
+})
+
+const { id } = defineProps<{
+  id: string
+}>()
+
+const { data } = useMyResource(() => id)
+```
+
+## Polling and caching
+
+By default, the resource will poll for updates every 30 seconds and cache the result for 10 seconds.
+
+This can be customized by passing the `pollingIntervalMs` and `cacheDurationMs` properties:
+
+```typescript
+const useMyResource = defineRemoteResource({
+  url: '/api/path/to/resource',
+  pollingIntervalMs: 60_000, // Poll every 60 seconds
+  cacheDurationMs: 5 * 60_000, // Cache for 5 minutes
+})
+```

package/lib/packages/remote-resource/define-remote-resource.ts

@@ -0,0 +1,294 @@
+import type { ResourceContext, UseRemoteResource } from '@core/packages/remote-resource/types.ts'
+import type { VoidFunction } from '@core/types/utility.type.ts'
+import { ifElse } from '@core/utils/if-else.utils.ts'
+import { type MaybeRef, noop, useTimeoutPoll } from '@vueuse/core'
+import { merge } from 'lodash-es'
+import readNDJSONStream from 'ndjson-readablestream'
+import {
+  computed,
+  type ComputedRef,
+  type EffectScope,
+  getCurrentScope,
+  type MaybeRefOrGetter,
+  onScopeDispose,
+  reactive,
+  type Ref,
+  ref,
+  toRef,
+  toValue,
+  watch,
+} from 'vue'
+
+const DEFAULT_CACHE_DURATION_MS = 10_000
+
+const DEFAULT_POLLING_INTERVAL_MS = 30_000
+
+export function defineRemoteResource<
+  TData,
+  TState extends object = { data: Ref<TData> },
+  TArgs extends any[] = [],
+>(config: {
+  url: string | ((...args: TArgs) => string)
+  initialData: () => TData
+  state?: (data: Ref<NoInfer<TData>>, context: ResourceContext<TArgs>) => TState
+  onDataReceived?: (data: Ref<NoInfer<TData>>, receivedData: any) => void
+  cacheDurationMs?: number
+  pollingIntervalMs?: number
+  stream?: boolean
+}): UseRemoteResource<TState, TArgs>
+
+export function defineRemoteResource<TData, TState extends object, TArgs extends any[] = []>(config: {
+  url: string | ((...args: TArgs) => string)
+  state?: (data: Ref<TData | undefined>, context: ResourceContext<TArgs>) => TState
+  onDataReceived?: (data: Ref<TData | undefined>, receivedData: any) => void
+  cacheDurationMs?: number
+  pollingIntervalMs?: number
+  stream?: boolean
+}): UseRemoteResource<TState, TArgs>
+
+export function defineRemoteResource<
+  TData,
+  TState extends object = { data: Ref<TData> },
+  TArgs extends any[] = [],
+>(config: {
+  url: string | ((...args: TArgs) => string)
+  initialData?: () => TData
+  state?: (data: Ref<TData>, context: ResourceContext<TArgs>) => TState
+  onDataReceived?: (data: Ref<NoInfer<TData>>, receivedData: any) => void
+  cacheDurationMs?: number
+  pollingIntervalMs?: number
+  stream?: boolean
+}) {
+  const cache = new Map<
+    string,
+    {
+      count: number
+      pause: VoidFunction
+      resume: VoidFunction
+      state: object
+      isReady: Ref<boolean>
+      isFetching: Ref<boolean>
+      lastError: Ref<Error | undefined>
+      hasError: ComputedRef<boolean>
+    }
+  >()
+
+  const buildUrl = typeof config.url === 'string' ? () => config.url as string : config.url
+
+  const buildData = config.initialData ?? (() => undefined as TData | undefined)
+
+  const buildState = config.state ?? ((data: Ref<TData>) => ({ data }))
+
+  const cacheDuration = config.cacheDurationMs ?? DEFAULT_CACHE_DURATION_MS
+
+  const pollingInterval = config.pollingIntervalMs ?? DEFAULT_POLLING_INTERVAL_MS
+
+  const onDataReceived =
+    config.onDataReceived ??
+    ((data: Ref<TData>, receivedData: any) => {
+      if (!config.stream || data.value === undefined) {
+        data.value = receivedData
+        return
+      }
+
+      if (Array.isArray(data.value) && Array.isArray(receivedData)) {
+        data.value.push(...receivedData)
+        return
+      }
+
+      merge(data.value, receivedData)
+    })
+
+  function subscribeToUrl(url: string) {
+    const entry = cache.get(url)
+
+    if (!entry) {
+      return
+    }
+
+    entry.count += 1
+
+    if (entry.count === 1) {
+      entry.resume()
+    }
+  }
+
+  function unsubscribeFromUrl(url: string) {
+    const entry = cache.get(url)
+
+    if (!entry) {
+      return
+    }
+
+    entry.count -= 1
+
+    if (entry.count > 0) {
+      return
+    }
+
+    entry.pause()
+
+    setTimeout(() => {
+      cache.delete(url)
+    }, cacheDuration)
+  }
+
+  function registerUrl(url: string, context: ResourceContext<TArgs>) {
+    if (cache.has(url)) {
+      return
+    }
+
+    const isReady = ref(false)
+
+    const isFetching = ref(false)
+
+    const lastError = ref<Error>()
+
+    const hasError = computed(() => lastError.value !== undefined)
+
+    const data = ref(buildData()) as Ref<TData>
+
+    async function execute() {
+      try {
+        isFetching.value = true
+
+        const response = await fetch(url)
+
+        if (!response.ok) {
+          lastError.value = Error(`Failed to fetch: ${response.statusText}`)
+          return
+        }
+
+        if (!response.body) {
+          return
+        }
+
+        if (config.stream) {
+          for await (const event of readNDJSONStream(response.body)) {
+            onDataReceived(data, event)
+          }
+        } else {
+          onDataReceived(data, await response.json())
+        }
+
+        isReady.value = true
+      } catch (error) {
+        lastError.value = error instanceof Error ? error : new Error(String(error))
+      } finally {
+        isFetching.value = false
+      }
+    }
+
+    let pause: VoidFunction = noop
+    let resume: VoidFunction = execute
+
+    if (pollingInterval > 0) {
+      const timeoutPoll = useTimeoutPoll(execute, pollingInterval, {
+        immediateCallback: true,
+        immediate: false,
+      })
+
+      pause = timeoutPoll.pause
+      resume = timeoutPoll.resume
+    }
+
+    const state = buildState(data, context)
+
+    cache.set(url, {
+      count: 0,
+      pause,
+      resume,
+      state,
+      isReady,
+      isFetching,
+      lastError,
+      hasError,
+    })
+  }
+
+  function initializeUrl(url: ComputedRef<string>, context: ResourceContext<TArgs>) {
+    watch(
+      url,
+      (toUrl, fromUrl) => {
+        registerUrl(toUrl, context)
+
+        if (context.isEnabled.value) {
+          subscribeToUrl(toUrl)
+        }
+
+        if (fromUrl) {
+          unsubscribeFromUrl(fromUrl)
+        }
+      },
+      { immediate: true }
+    )
+  }
+
+  return function useRemoteResource(
+    optionsOrParentContext?: { isEnabled?: MaybeRef<boolean>; scope?: EffectScope },
+    ...args: { [K in keyof TArgs]: MaybeRefOrGetter<TArgs[K]> }
+  ) {
+    const scope = optionsOrParentContext?.scope ?? getCurrentScope()
+
+    if (!scope) {
+      throw new Error('No effect scope found. Please provide a scope or use this function within a Vue component.')
+    }
+
+    const isEnabled = toRef(optionsOrParentContext?.isEnabled ?? true)
+
+    return scope.run(() => {
+      const url = computed(() => buildUrl(...(args.map(arg => toValue(arg)) as TArgs)))
+
+      onScopeDispose(() => {
+        unsubscribeFromUrl(url.value)
+      })
+
+      const context: ResourceContext<TArgs> = {
+        scope,
+        args,
+        isReady: computed(() => cache.get(url.value)?.isReady.value ?? false),
+        isFetching: computed(() => cache.get(url.value)?.isFetching?.value ?? false),
+        lastError: computed(() => cache.get(url.value)?.lastError.value),
+        hasError: computed(() => cache.get(url.value)?.hasError.value ?? false),
+        isEnabled,
+        enable: () => {
+          isEnabled.value = true
+        },
+        disable: () => {
+          isEnabled.value = false
+        },
+        forceReload: () => {
+          cache.get(url.value)?.pause()
+          cache.get(url.value)?.resume()
+        },
+      }
+
+      initializeUrl(url, context)
+
+      const state = reactive({} as TState)
+
+      ifElse(
+        isEnabled,
+        () => subscribeToUrl(url.value),
+        () => unsubscribeFromUrl(url.value)
+      )
+
+      watch(
+        url,
+        () => {
+          Object.assign(state, cache.get(url.value)!.state)
+        },
+        { immediate: true }
+      )
+
+      return {
+        ...Object.fromEntries(
+          Object.entries(state).map(([key, value]) =>
+            typeof value === 'function' ? [key, value] : [key, toRef(state, key as any)]
+          )
+        ),
+        $context: context,
+      }
+    })!
+  }
+}

package/lib/packages/remote-resource/types.ts

@@ -0,0 +1,28 @@
+import type { MaybeRef } from '@vueuse/core'
+import type { MaybeRefOrGetter } from '@vueuse/shared'
+import type { ComputedRef, EffectScope, Ref, ToRef } from 'vue'
+
+export type ResourceContext<TArgs extends any[]> = {
+  scope: EffectScope
+  args: { [K in keyof TArgs]: MaybeRefOrGetter<TArgs[K]> }
+  isReady: ComputedRef<boolean>
+  isFetching: ComputedRef<boolean>
+  hasError: ComputedRef<boolean>
+  lastError: ComputedRef<Error | undefined>
+  isEnabled: Ref<boolean>
+  enable: () => void
+  disable: () => void
+  forceReload: () => void
+}
+
+export type UseRemoteResource<TState, TArgs extends any[]> = (
+  optionsOrParentContext?: {
+    isEnabled?: MaybeRef<boolean>
+    scope?: EffectScope
+  },
+  ...args: { [K in keyof TArgs]: MaybeRefOrGetter<TArgs[K]> }
+) => {
+  [K in keyof TState]: TState[K] extends (...args: any[]) => any ? TState[K] : ToRef<TState[K]>
+} & {
+  $context: ResourceContext<TArgs>
+}

package/lib/packages/threshold/README.md

@@ -0,0 +1,30 @@
+# `useThreshold`
+
+`useThreshold` composable allows defining payloads for different thresholds.
+
+It returns the payload of the highest matching threshold for that value.
+
+## Arguments
+
+| Argument       | Type                                                                 | Required | Description                           |
+| -------------- | -------------------------------------------------------------------- | :------: | ------------------------------------- |
+| `currentValue` | `MaybeRefOrGetter<number>`                                           |    ✓     | The value to check against thresholds |
+| `config`       | `MaybeRefOrGetter<Record<number, TPayload> & { default: TPayload }>` |    ✓     | The thresholds configuration          |
+
+## Returns
+
+`ComputedRef<{ value: number | undefined; payload: TPayload }>`
+
+## Example
+
+```ts
+const threshold = useThreshold(value, {
+  50: 'orange',
+  100: 'red',
+  default: 'green',
+})
+
+// value = 20 → threshold = { value: undefined, payload: 'green' }
+// value = 70 → threshold = { value: 50, payload: 'orange' }
+// value = 130 → threshold = { value: 100, payload: 'red' }
+```

package/lib/packages/threshold/type.ts

@@ -0,0 +1,3 @@
+export type ThresholdConfig<TPayload> = Record<number, TPayload> & { default: TPayload }
+
+export type ThresholdResult<TPayload> = { value: number | undefined; payload: TPayload }

package/lib/packages/threshold/use-threshold.ts

@@ -0,0 +1,19 @@
+import type { ThresholdConfig, ThresholdResult } from '@core/packages/threshold/type.ts'
+import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from 'vue'
+
+export function useThreshold<TPayload>(
+  rawCurrentValue: MaybeRefOrGetter<number>,
+  rawConfig: MaybeRefOrGetter<ThresholdConfig<TPayload>>
+): ComputedRef<ThresholdResult<TPayload>> {
+  const currentValue = computed(() => toValue(rawCurrentValue))
+
+  const config = computed(() => toValue(rawConfig))
+
+  return computed(
+    () =>
+      Object.entries(config.value)
+        .map(([value, payload]) => ({ value: value === 'default' ? -Infinity : Number(value), payload }))
+        .sort((a, b) => b.value - a.value)
+        .find(threshold => currentValue.value >= threshold.value)!
+  )
+}

package/lib/types/object-icon.type.ts

@@ -1,43 +1,3 @@
-import type { IconDefinition } from '@fortawesome/fontawesome-common-types'
-
-export type ObjectIconSize = 'extra-small' | 'small' | 'medium'
-
 export type VmState = 'running' | 'halted' | 'paused' | 'suspended'
 
 export type HostState = 'running' | 'halted' | 'maintenance'
-
-export type SrState = 'connected' | 'partially-connected' | 'disconnected'
-
-export type BackupRepositoryState = 'connected' | 'disconnected'
-
-export type NetworkState = 'connected' | 'disconnected'
-
-export type SupportedStateByType = {
-  host: HostState
-  vm: VmState
-  sr: SrState
-  'backup-repository': BackupRepositoryState
-  network: NetworkState
-}
-
-export type SupportedType = keyof SupportedStateByType
-
-export type SupportedState<TType extends SupportedType> = SupportedStateByType[TType]
-
-export type StatusConfig = {
-  icon: IconDefinition
-  color: `--${string}`
-  translate: {
-    x: [number, number, number]
-    y: [number, number, number]
-  }
-}
-
-export type TypeConfig<TType extends SupportedType> = {
-  mainIcon: IconDefinition
-  states: Record<SupportedState<TType>, StatusConfig>
-}
-
-export type ObjectIconConfig = {
-  [K in SupportedType]: TypeConfig<K>
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xen-orchestra/web-core",
   "type": "module",
-  "version": "0.26.1",
+  "version": "0.28.0",
   "private": false,
   "exports": {
     "./*": {
@@ -26,7 +26,7 @@
     "human-format": "^1.2.1",
     "iterable-backoff": "^0.1.0",
     "lodash-es": "^4.17.21",
-    "ndjson-readablestream": "^1.2.0",
+    "ndjson-readablestream": "^1.3.0",
     "placement.js": "^1.0.0-beta.5",
     "simple-icons": "^14.14.0",
     "vue-echarts": "^6.6.8"

package/lib/components/icon/NewVtsIcon.vue

@@ -1,49 +0,0 @@
-<template>
-  <DisplayIcon v-if="icon" class="vts-icon" :class="className" :icon />
-</template>
-
-<script lang="ts" setup>
-import { type IconName, icons } from '@core/icons'
-import { DisplayIcon } from '@core/packages/icon'
-import { toVariants } from '@core/utils/to-variants.util.ts'
-import { computed } from 'vue'
-
-export type IconSize = 'small' | 'medium' | 'large' | 'current'
-
-const { size, name } = defineProps<{
-  size: IconSize
-  name: IconName
-}>()
-
-const className = computed(() =>
-  toVariants({
-    size: size === 'current' ? undefined : size,
-  })
-)
-
-const icon = computed(() => {
-  const icon = icons[name]
-
-  if (icon === undefined) {
-    console.warn(`Icon "${name}" not found.`)
-  }
-
-  return icon
-})
-</script>
-
-<style lang="postcss" scoped>
-.vts-icon {
-  &.size--small {
-    font-size: 1.2rem;
-  }
-
-  &.size--medium {
-    font-size: 1.6rem;
-  }
-
-  &.size--large {
-    font-size: 2rem;
-  }
-}
-</style>

package/lib/components/ui/complex-icon/UiComplexIcon.vue

@@ -1,45 +0,0 @@
-<!-- v2 -->
-<template>
-  <FontAwesomeLayers :class="toVariants({ size })" class="ui-complex-icon">
-    <slot />
-  </FontAwesomeLayers>
-</template>
-
-<script lang="ts" setup>
-import { toVariants } from '@core/utils/to-variants.util'
-import { FontAwesomeLayers } from '@fortawesome/vue-fontawesome'
-
-defineProps<{
-  size: 'small' | 'medium' | 'large'
-}>()
-</script>
-
-<style lang="postcss" scoped>
-.ui-complex-icon {
-  :nth-child(2) {
-    font-size: 0.5em;
-    transform: translate(100%, 80%);
-
-    :deep(path) {
-      stroke: var(--color-neutral-background-primary);
-      stroke-width: 100px;
-      stroke-linejoin: round;
-      paint-order: stroke;
-    }
-  }
-
-  /*SIZE VARIANTS*/
-
-  &.size--small {
-    font-size: 1.2rem;
-  }
-
-  &.size--medium {
-    font-size: 1.6rem;
-  }
-
-  &.size--large {
-    font-size: 2rem;
-  }
-}
-</style>