@piveau/sdk-vue 0.0.0-alpha.0

package/README.md

@@ -0,0 +1,66 @@
+# @piveau/sdk-vue
+
+Asynchronous state management for interacting with piveau services in Vue.js.
+
+Looking for a standalone API client? Try @piveau/sdk-core
+
+## Quick Features
+
+- Provides intelligent client-side caching, background updates, and optimistic updates of piveau backend data state in a declarative way, powered by [@tanstack/vue-query](https://github.com/TanStack/query)
+- Composable utility functions to help you model real-world use cases easier, e.g., facets, search, and pagination
+- Runtime resource schema validation and model type inference powered by [Zod](https://zod.dev/)
+- Shape data from API to your data model using getters
+- Vue 3 compatible
+- Supports Server-Side Rendering with Nuxt
+- Written with TypeScript
+
+## Usage
+
+<table>
+<tbody valign=top align=left>
+<tr><th>
+Node 20+, Vue 3
+</th><td>
+
+Install with <code>npm/pnpm install @piveau/sdk-vue</code>, or <code>yarn add @piveau/sdk-vue</code>. For better devtooling, we recommend installing @piveau/sdk-core and vue-query with <code>npm/pnpm install @piveau/sdk-core @tanstack/vue-query@5</code>.
+
+**Recommended**: In `main.ts`, setup the plugin:
+```js
+import { createApp } from 'vue'
+import { plugin } from '@piveau/sdk-vue'
+import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query'
+import App from './App.vue'
+
+const qc = new QueryClient()
+
+const app = createApp(App)
+
+app.use(VueQueryPlugin, {
+  queryClient: qc,
+})
+
+app.use(plugin, {
+  queryClient: qc,
+})
+```
+
+</td></tr>
+<tr><th>
+Node 20+, Nuxt 3
+</th><td>
+*Work in Progress* See https://tanstack.com/query/latest/docs/framework/vue/guides/ssr and register the sdk-vue plugin as above
+</td></tr>
+</tbody>
+</table>
+
+## piveau API Support
+
+- `/search/filter={filter}` for searching resources
+- `/search/{index}/{id}` for fetching a single resource
+
+## Work in Progress
+
+- hub
+- consus
+- metrics
+- statistics

package/dist/index.d.mts

@@ -0,0 +1,165 @@
+import { ToRef, Ref, ComputedRef, MaybeRef, MaybeRefOrGetter, InjectionKey, App } from 'vue-demi';
+import { UseQueryReturnType, QueryClient } from '@tanstack/vue-query';
+import { GetResourceResult, SearchParamsBase, SearchResult, SearchResultFacetGroup, SearchParams } from '@piveau/sdk-core';
+import * as z from 'zod';
+
+/**
+ * Type of an object of Getters that infers the argument.
+ */
+type GettersTree<TModelSchema = any, TContext = any> = Record<string, ((data: TModelSchema, ctx?: TContext) => any) | (() => any)>;
+
+type MyUseQueryReturnType<TD, TE> = UseQueryReturnType<TD, TE>;
+interface UseResourceResultNoData<TModelSchema = any, TContext = any, TGetterTree extends GettersTree<TModelSchema, TContext> = GettersTree<TModelSchema, TContext>> {
+    isSuccess: false;
+    result: ComputedRef<undefined>;
+    getters: {
+        [K in keyof TGetterTree]: ComputedRef<null>;
+    };
+}
+interface UseResourceResultWithData<TModelSchema = any, TContext = any, TGetterTree extends GettersTree<TModelSchema, TContext> = GettersTree<TModelSchema, TContext>> {
+    isSuccess: true;
+    result: ComputedRef<TModelSchema>;
+    getters: {
+        [K in keyof TGetterTree]: ComputedRef<ReturnType<TGetterTree[K]>>;
+    };
+}
+type UseResourceResultBase<TModelSchema = any, TContext = any, TGetterTree extends GettersTree<TModelSchema, TContext> = GettersTree<TModelSchema, TContext>> = UseResourceResultNoData<TModelSchema, TContext, TGetterTree> | UseResourceResultWithData<TModelSchema, TContext, TGetterTree>;
+type UseResourceResult<TModelSchema = any, TContext = any, TGetterTree extends GettersTree<TModelSchema, TContext> = GettersTree<TModelSchema, TContext>, TResult = UseResourceResultBase<TModelSchema, TContext, TGetterTree>> = {
+    [K in keyof TResult]: K extends 'isSuccess' ? ToRef<TResult[K]> : TResult[K];
+} & {
+    query: MyUseQueryReturnType<GetResourceResult<TModelSchema>, Error>;
+    isLoading: Ref<boolean> | Ref<true> | Ref<false>;
+    isFetching: Ref<boolean>;
+};
+
+type Reffify<T> = {
+    [key in keyof T]: MaybeRef<T[key]>;
+};
+type SearchParamsRef = Reffify<SearchParamsBase>;
+interface SelectedFacetItemObject {
+    id: string;
+    title: Record<string, string> | string;
+    count: number;
+}
+type SelectedFacetItemList = (SelectedFacetItemObject | string)[];
+type FacetRef<TFacetNames extends string = string> = {
+    readonly [key in TFacetNames]?: MaybeRef<SelectedFacetItemList>;
+};
+
+interface SearchResultFacetGroupLocalized {
+    id: string;
+    title: string;
+    items: {
+        id: string;
+        title: string | undefined;
+        count: number;
+    }[];
+}
+interface UseSearchFactoryReturn<TFacetNames extends string, TModelSchema, TGettersTree extends GettersTree<TModelSchema, any>> {
+    /**
+     * The search query object.
+     *
+     * @see https://tanstack.com/query/latest/docs/framework/vue/reference/useQuery
+     */
+    query: UseQueryReturnType<SearchResult<TModelSchema>, Error>;
+    /**
+     * The available facets for the current search results.
+     */
+    getAvailableFacets: ComputedRef<SearchResultFacetGroup[]>;
+    /**
+     * The available facets for the current search results with localized titles.
+     */
+    getAvailableFacetsLocalized: (locale?: MaybeRefOrGetter<string>) => ComputedRef<SearchResultFacetGroupLocalized[]>;
+    /**
+     * The search results.
+     */
+    getSearchResults: ComputedRef<TModelSchema[] | undefined>;
+    /**
+     * The total number of search results.
+     */
+    getSearchResultsCount: ComputedRef<number>;
+    /**
+     * The total number of pages of search results based on the current limit parameter.
+     * If the limit is not set or is less than or equal to 0, this will return `NaN`.
+     */
+    getSearchResultsPagesCount: ComputedRef<number>;
+    /**
+     * Whether the search query is loading.
+     */
+    isLoading: ComputedRef<boolean>;
+    /**
+     * Whether the search query is fetching.
+     */
+    isFetching: ComputedRef<boolean>;
+    /**
+     * Get a facet by its ID.
+     */
+    getFacetById: <TFacetName extends TFacetNames>(facetId: TFacetName) => ComputedRef<SearchResultFacetGroup | undefined>;
+    /**
+     * Go to the next page of search results.
+     */
+    nextPage: () => void;
+    /**
+     * Go to the previous page of search results.
+     */
+    previousPage: () => void;
+    /**
+     * Convert a model schema to a computed object of getters.
+     */
+    toGetters: (data: MaybeRefOrGetter<TModelSchema>) => {
+        [K in keyof TGettersTree]: ComputedRef<ReturnType<TGettersTree[K]>>;
+    };
+    queryParams: SearchParamsRef;
+}
+
+type _UseQueryReturnType<TData, TError> = UseQueryReturnType<TData, TError>;
+interface ResourceSearchOptions<TFacetNames extends string, TIndex extends string = string, TModelSchema = any> {
+    baseUrl: string;
+    index: TIndex;
+    indexDetails?: string;
+    facets?: TFacetNames[];
+    schema: z.Schema<TModelSchema>;
+    enabled?: MaybeRefOrGetter<boolean>;
+    locale?: MaybeRefOrGetter<string>;
+    dateFormatter?: (datetime: string) => string;
+}
+interface GeneralOptions<TModelSchema = any> {
+    fetcherFn?: (_options: {
+        params: SearchParams;
+        additionalParams?: any;
+        headers?: Record<string, string>;
+    }) => Promise<SearchResult<TModelSchema>>;
+    qc?: QueryClient;
+}
+interface CreateUseResourceSearchParams<TFacetNames extends string, TGettersTree extends GettersTree<TModelSchema, ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>>, TIndex extends string = string, TModelSchema = any> {
+    resourceSearchOptions: ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>;
+    options?: GeneralOptions<TModelSchema>;
+    getters: TGettersTree;
+}
+declare function defineResourceSearchOptions<TFacetNames extends string, TIndex extends string = string, TModelSchema = any>(options: ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>): ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>;
+declare function createUseResourceSearch<TFacetNames extends string, TGettersTree extends GettersTree<TModelSchema, ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>>, TIndex extends string = string, TModelSchema = any>({ resourceSearchOptions, options, getters, }: CreateUseResourceSearchParams<TFacetNames, TGettersTree, TIndex, TModelSchema>): {
+    useSearch: (params: {
+        queryParams?: Reffify<SearchParamsBase> | undefined;
+        selectedFacets?: FacetRef<string> | undefined;
+    }) => UseSearchFactoryReturn<string, TModelSchema, TGettersTree>;
+    useResources: (params: {
+        queryParams?: Reffify<SearchParamsBase> | undefined;
+        selectedFacets?: FacetRef<string> | undefined;
+    }) => UseSearchFactoryReturn<string, TModelSchema, TGettersTree>;
+    useResource: (resourceId: MaybeRefOrGetter<string>) => UseResourceResult<TModelSchema, ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>, TGettersTree, UseResourceResultBase<TModelSchema, ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>, TGettersTree>>;
+    refSyncedWithRouteQuery: <T extends string | number, K = T extends string ? string : T extends number ? number : never>(searchParam: keyof SearchParamsBase, defaultValue?: MaybeRefOrGetter<T> | undefined) => Ref<K>;
+    refSyncedWithRouteQueryFacet: <T_1 extends string[]>(searchParam: TFacetNames, defaultValue?: MaybeRefOrGetter<T_1> | undefined) => Ref<string[]>;
+    getters: TGettersTree;
+    resourceSearchOptions: ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>;
+};
+
+interface PluginOptions {
+    queryClient?: QueryClient;
+}
+declare const keyQueryClient: InjectionKey<QueryClient>;
+declare const plugin: {
+    install(app: App, options?: PluginOptions): void;
+};
+declare function useQueryClient(): QueryClient | null;
+
+export { type CreateUseResourceSearchParams, type GeneralOptions, type PluginOptions, type ResourceSearchOptions, type _UseQueryReturnType, createUseResourceSearch, defineResourceSearchOptions, keyQueryClient, plugin, useQueryClient };

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+import { ToRef, Ref, ComputedRef, MaybeRef, MaybeRefOrGetter, InjectionKey, App } from 'vue-demi';
+import { UseQueryReturnType, QueryClient } from '@tanstack/vue-query';
+import { GetResourceResult, SearchParamsBase, SearchResult, SearchResultFacetGroup, SearchParams } from '@piveau/sdk-core';
+import * as z from 'zod';
+
+/**
+ * Type of an object of Getters that infers the argument.
+ */
+type GettersTree<TModelSchema = any, TContext = any> = Record<string, ((data: TModelSchema, ctx?: TContext) => any) | (() => any)>;
+
+type MyUseQueryReturnType<TD, TE> = UseQueryReturnType<TD, TE>;
+interface UseResourceResultNoData<TModelSchema = any, TContext = any, TGetterTree extends GettersTree<TModelSchema, TContext> = GettersTree<TModelSchema, TContext>> {
+    isSuccess: false;
+    result: ComputedRef<undefined>;
+    getters: {
+        [K in keyof TGetterTree]: ComputedRef<null>;
+    };
+}
+interface UseResourceResultWithData<TModelSchema = any, TContext = any, TGetterTree extends GettersTree<TModelSchema, TContext> = GettersTree<TModelSchema, TContext>> {
+    isSuccess: true;
+    result: ComputedRef<TModelSchema>;
+    getters: {
+        [K in keyof TGetterTree]: ComputedRef<ReturnType<TGetterTree[K]>>;
+    };
+}
+type UseResourceResultBase<TModelSchema = any, TContext = any, TGetterTree extends GettersTree<TModelSchema, TContext> = GettersTree<TModelSchema, TContext>> = UseResourceResultNoData<TModelSchema, TContext, TGetterTree> | UseResourceResultWithData<TModelSchema, TContext, TGetterTree>;
+type UseResourceResult<TModelSchema = any, TContext = any, TGetterTree extends GettersTree<TModelSchema, TContext> = GettersTree<TModelSchema, TContext>, TResult = UseResourceResultBase<TModelSchema, TContext, TGetterTree>> = {
+    [K in keyof TResult]: K extends 'isSuccess' ? ToRef<TResult[K]> : TResult[K];
+} & {
+    query: MyUseQueryReturnType<GetResourceResult<TModelSchema>, Error>;
+    isLoading: Ref<boolean> | Ref<true> | Ref<false>;
+    isFetching: Ref<boolean>;
+};
+
+type Reffify<T> = {
+    [key in keyof T]: MaybeRef<T[key]>;
+};
+type SearchParamsRef = Reffify<SearchParamsBase>;
+interface SelectedFacetItemObject {
+    id: string;
+    title: Record<string, string> | string;
+    count: number;
+}
+type SelectedFacetItemList = (SelectedFacetItemObject | string)[];
+type FacetRef<TFacetNames extends string = string> = {
+    readonly [key in TFacetNames]?: MaybeRef<SelectedFacetItemList>;
+};
+
+interface SearchResultFacetGroupLocalized {
+    id: string;
+    title: string;
+    items: {
+        id: string;
+        title: string | undefined;
+        count: number;
+    }[];
+}
+interface UseSearchFactoryReturn<TFacetNames extends string, TModelSchema, TGettersTree extends GettersTree<TModelSchema, any>> {
+    /**
+     * The search query object.
+     *
+     * @see https://tanstack.com/query/latest/docs/framework/vue/reference/useQuery
+     */
+    query: UseQueryReturnType<SearchResult<TModelSchema>, Error>;
+    /**
+     * The available facets for the current search results.
+     */
+    getAvailableFacets: ComputedRef<SearchResultFacetGroup[]>;
+    /**
+     * The available facets for the current search results with localized titles.
+     */
+    getAvailableFacetsLocalized: (locale?: MaybeRefOrGetter<string>) => ComputedRef<SearchResultFacetGroupLocalized[]>;
+    /**
+     * The search results.
+     */
+    getSearchResults: ComputedRef<TModelSchema[] | undefined>;
+    /**
+     * The total number of search results.
+     */
+    getSearchResultsCount: ComputedRef<number>;
+    /**
+     * The total number of pages of search results based on the current limit parameter.
+     * If the limit is not set or is less than or equal to 0, this will return `NaN`.
+     */
+    getSearchResultsPagesCount: ComputedRef<number>;
+    /**
+     * Whether the search query is loading.
+     */
+    isLoading: ComputedRef<boolean>;
+    /**
+     * Whether the search query is fetching.
+     */
+    isFetching: ComputedRef<boolean>;
+    /**
+     * Get a facet by its ID.
+     */
+    getFacetById: <TFacetName extends TFacetNames>(facetId: TFacetName) => ComputedRef<SearchResultFacetGroup | undefined>;
+    /**
+     * Go to the next page of search results.
+     */
+    nextPage: () => void;
+    /**
+     * Go to the previous page of search results.
+     */
+    previousPage: () => void;
+    /**
+     * Convert a model schema to a computed object of getters.
+     */
+    toGetters: (data: MaybeRefOrGetter<TModelSchema>) => {
+        [K in keyof TGettersTree]: ComputedRef<ReturnType<TGettersTree[K]>>;
+    };
+    queryParams: SearchParamsRef;
+}
+
+type _UseQueryReturnType<TData, TError> = UseQueryReturnType<TData, TError>;
+interface ResourceSearchOptions<TFacetNames extends string, TIndex extends string = string, TModelSchema = any> {
+    baseUrl: string;
+    index: TIndex;
+    indexDetails?: string;
+    facets?: TFacetNames[];
+    schema: z.Schema<TModelSchema>;
+    enabled?: MaybeRefOrGetter<boolean>;
+    locale?: MaybeRefOrGetter<string>;
+    dateFormatter?: (datetime: string) => string;
+}
+interface GeneralOptions<TModelSchema = any> {
+    fetcherFn?: (_options: {
+        params: SearchParams;
+        additionalParams?: any;
+        headers?: Record<string, string>;
+    }) => Promise<SearchResult<TModelSchema>>;
+    qc?: QueryClient;
+}
+interface CreateUseResourceSearchParams<TFacetNames extends string, TGettersTree extends GettersTree<TModelSchema, ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>>, TIndex extends string = string, TModelSchema = any> {
+    resourceSearchOptions: ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>;
+    options?: GeneralOptions<TModelSchema>;
+    getters: TGettersTree;
+}
+declare function defineResourceSearchOptions<TFacetNames extends string, TIndex extends string = string, TModelSchema = any>(options: ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>): ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>;
+declare function createUseResourceSearch<TFacetNames extends string, TGettersTree extends GettersTree<TModelSchema, ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>>, TIndex extends string = string, TModelSchema = any>({ resourceSearchOptions, options, getters, }: CreateUseResourceSearchParams<TFacetNames, TGettersTree, TIndex, TModelSchema>): {
+    useSearch: (params: {
+        queryParams?: Reffify<SearchParamsBase> | undefined;
+        selectedFacets?: FacetRef<string> | undefined;
+    }) => UseSearchFactoryReturn<string, TModelSchema, TGettersTree>;
+    useResources: (params: {
+        queryParams?: Reffify<SearchParamsBase> | undefined;
+        selectedFacets?: FacetRef<string> | undefined;
+    }) => UseSearchFactoryReturn<string, TModelSchema, TGettersTree>;
+    useResource: (resourceId: MaybeRefOrGetter<string>) => UseResourceResult<TModelSchema, ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>, TGettersTree, UseResourceResultBase<TModelSchema, ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>, TGettersTree>>;
+    refSyncedWithRouteQuery: <T extends string | number, K = T extends string ? string : T extends number ? number : never>(searchParam: keyof SearchParamsBase, defaultValue?: MaybeRefOrGetter<T> | undefined) => Ref<K>;
+    refSyncedWithRouteQueryFacet: <T_1 extends string[]>(searchParam: TFacetNames, defaultValue?: MaybeRefOrGetter<T_1> | undefined) => Ref<string[]>;
+    getters: TGettersTree;
+    resourceSearchOptions: ResourceSearchOptions<TFacetNames, TIndex, TModelSchema>;
+};
+
+interface PluginOptions {
+    queryClient?: QueryClient;
+}
+declare const keyQueryClient: InjectionKey<QueryClient>;
+declare const plugin: {
+    install(app: App, options?: PluginOptions): void;
+};
+declare function useQueryClient(): QueryClient | null;
+
+export { type CreateUseResourceSearchParams, type GeneralOptions, type PluginOptions, type ResourceSearchOptions, type _UseQueryReturnType, createUseResourceSearch, defineResourceSearchOptions, keyQueryClient, plugin, useQueryClient };

package/dist/index.mjs

@@ -0,0 +1,479 @@
+import { computed, toValue, reactive, toRefs, unref, markRaw, isVue2, inject } from 'vue-demi';
+import { useQuery, keepPreviousData, QueryClient } from '@tanstack/vue-query';
+import { getResourceById, searchResource } from '@piveau/sdk-core';
+import { useRoute, useRouter } from 'vue-router';
+import { useRouteQuery } from '@vueuse/router';
+import { z } from 'zod';
+
+function assertQueryClient(qc) {
+  if (!qc)
+    throw new Error("QueryClient not found");
+}
+function extractFacetId(facet) {
+  return typeof facet === "string" ? facet : facet.id;
+}
+function mapToFacetIds(facets) {
+  if (typeof facets === "string")
+    return [facets];
+  return facets.map(extractFacetId);
+}
+function getRepresentativeLocaleOf({ candidates = [], preferredLocale = [] }) {
+  if (candidates.length === 0)
+    return "";
+  if (!preferredLocale || preferredLocale.length === 0)
+    return candidates[0];
+  const priorityListArray = Array.isArray(preferredLocale) ? preferredLocale : [preferredLocale];
+  for (const locale of priorityListArray) {
+    if (candidates.includes(locale))
+      return locale;
+  }
+  return candidates[0];
+}
+function getTranslationFor(obj, preferredLocale) {
+  if (!obj)
+    return "";
+  const locale = getRepresentativeLocaleOf({ candidates: Object.keys(obj), preferredLocale });
+  if (!locale)
+    return "";
+  return obj[locale];
+}
+
+function toComputedGetters({
+  data,
+  getters,
+  ctx
+}) {
+  return Object.keys(getters || {}).reduce(
+    (computedGetters, name) => {
+      const getter = getters[name];
+      computedGetters[name] = computed(() => {
+        const dataValue = toValue(data);
+        if (!dataValue)
+          return null;
+        if (typeof getter === "function")
+          return getter(dataValue, ctx);
+      });
+      return computedGetters;
+    },
+    {}
+  );
+}
+
+function useSearchQueryParams(initialValue) {
+  const queryParams = reactive({
+    ...{
+      aggregation: null,
+      aggregationAllFields: null,
+      aggregationFields: null,
+      autocomplete: null,
+      bboxMaxLat: null,
+      bboxMaxLon: null,
+      bboxMinLat: null,
+      bboxMinLon: null,
+      boost: null,
+      countryData: null,
+      dataServices: null,
+      facetGroupOperator: null,
+      facetOperator: null,
+      fields: null,
+      filterDistributions: null,
+      globalAggregation: null,
+      includes: null,
+      limit: null,
+      maxDate: null,
+      minDate: null,
+      maxScoring: null,
+      minScoring: null,
+      page: null,
+      q: null,
+      scroll: null,
+      sort: null,
+      showScore: null,
+      vocabulary: null,
+      superCatalogue: null
+    },
+    ...initialValue
+  });
+  function setFacetOperator(operator) {
+    queryParams.facetOperator = operator;
+  }
+  function setFacetGroupOperator(operator) {
+    queryParams.facetGroupOperator = operator;
+  }
+  function setDataServices(dataServices) {
+    queryParams.dataServices = dataServices;
+  }
+  function setSuperCatalogue(val) {
+    queryParams.superCatalogue = val;
+  }
+  function setPage(val) {
+    queryParams.page = val;
+  }
+  function setQuery(val) {
+    queryParams.q = val;
+  }
+  function setSort(val) {
+    queryParams.sort = val;
+  }
+  function setLimit(val) {
+    queryParams.limit = val;
+  }
+  function setDatasetGeoBounds({ minLon, minLat, maxLon, maxLat }) {
+    queryParams.bboxMinLon = minLon;
+    queryParams.bboxMinLat = minLat;
+    queryParams.bboxMaxLon = maxLon;
+    queryParams.bboxMaxLat = maxLat;
+  }
+  function setMinScoring(val) {
+    queryParams.minScoring = val;
+  }
+  function setCountryData(val) {
+    queryParams.countryData = val;
+  }
+  function setDataScope(val) {
+    queryParams.countryData = val;
+  }
+  return {
+    queryParams: toRefs(queryParams),
+    setFacetOperator,
+    setFacetGroupOperator,
+    setDataServices,
+    setSuperCatalogue,
+    setPage,
+    setQuery,
+    setSort,
+    setLimit,
+    setDatasetGeoBounds,
+    setMinScoring,
+    setCountryData,
+    setDataScope
+  };
+}
+
+function useSearchFactory(options) {
+  const useSearch = function({
+    queryParams = {},
+    selectedFacets = {},
+    additionalParams = {},
+    headers = {}
+  }) {
+    const {
+      index,
+      enabled = true,
+      qc,
+      ctx = {},
+      getters,
+      fetcherFn
+    } = options;
+    assertQueryClient(qc);
+    const { queryParams: resolvedQueryParams } = useSearchQueryParams(queryParams);
+    const reactiveQueryParams = reactive(resolvedQueryParams);
+    reactiveQueryParams.limit = reactiveQueryParams.limit || 10;
+    const computedSelectedFacetIds = computed(() => {
+      const facets = toValue(selectedFacets);
+      const keys = Object.keys(facets);
+      const selected = {};
+      for (const key of keys) {
+        const value = facets[key];
+        selected[key] = mapToFacetIds(unref(value));
+      }
+      return selected;
+    });
+    const query = useQuery(
+      {
+        queryKey: computed(() => [
+          "pv-resources",
+          index,
+          reactiveQueryParams,
+          unref(computedSelectedFacetIds),
+          toValue(additionalParams),
+          toValue(headers)
+        ]),
+        queryFn: async () => markRaw(await fetcherFn({
+          params: {
+            ...reactiveQueryParams,
+            facets: computedSelectedFacetIds.value
+          },
+          additionalParams: toValue(additionalParams),
+          headers: toValue(headers)
+        })),
+        placeholderData: keepPreviousData,
+        staleTime: 1e3 * 60 * 2,
+        enabled
+      },
+      qc
+    );
+    const getAvailableFacets = computed(() => {
+      if (query.isError.value)
+        return [];
+      const facets = query.data?.value?.result.facets;
+      return facets || [];
+    });
+    const getAvailableFacetsLocalized = (locale) => {
+      return computed(() => {
+        const resolvedLocale = toValue(locale) || ctx.locale || "en";
+        const facets = getAvailableFacets.value;
+        if (!facets)
+          return [];
+        return facets.map((facet) => {
+          return {
+            ...facet,
+            items: facet.items.map((item) => {
+              return {
+                ...item,
+                title: typeof item.title === "string" ? item.title : getTranslationFor(item.title, resolvedLocale)
+              };
+            })
+          };
+        });
+      });
+    };
+    const getSearchResults = computed(() => {
+      if (query.isError.value)
+        return void 0;
+      const results = query.data?.value?.result.results;
+      return results;
+    });
+    const getSearchResultsCount = computed(() => {
+      const count = query.data?.value?.result.count;
+      return count ?? 0;
+    });
+    const getSearchResultsPagesCount = computed(() => {
+      const count = getSearchResultsCount.value;
+      const limit = reactiveQueryParams.limit;
+      if (!limit || limit <= 0)
+        return Number.NaN;
+      return Math.ceil((count ?? 0) / limit);
+    });
+    const isLoading = computed(() => {
+      return query.isLoading.value;
+    });
+    const isFetching = computed(() => {
+      return query.isFetching.value;
+    });
+    function getFacetById(facetId) {
+      return computed(() => {
+        const facets = query.data?.value?.result.facets;
+        if (!facets)
+          return void 0;
+        const facet = facets?.find((f) => f.id === facetId);
+        if (!facet)
+          return void 0;
+        return {
+          ...facet,
+          id: facetId
+        };
+      });
+    }
+    function nextPage() {
+      reactiveQueryParams.page = (reactiveQueryParams.page || 0) + 1;
+    }
+    function previousPage() {
+      reactiveQueryParams.page = Math.max(
+        (reactiveQueryParams.page || 0) - 1,
+        0
+      );
+    }
+    function toGetters(data) {
+      return toComputedGetters({
+        data,
+        getters,
+        ctx
+      });
+    }
+    const returnObject = {
+      query,
+      getAvailableFacets,
+      getSearchResults,
+      getSearchResultsCount,
+      getSearchResultsPagesCount,
+      isLoading,
+      isFetching,
+      getAvailableFacetsLocalized,
+      getFacetById,
+      nextPage,
+      previousPage,
+      toGetters,
+      queryParams: toRefs(reactiveQueryParams)
+    };
+    return returnObject;
+  };
+  return useSearch;
+}
+
+function useResourceFactory(options) {
+  function useResource(resourceId) {
+    const {
+      index,
+      indexSearch = index,
+      baseUrl,
+      enabled = true,
+      qc,
+      ctx = {},
+      getters = {},
+      fetcherFn
+    } = options;
+    assertQueryClient(qc);
+    const resolvedIndex = computed(() => index ?? indexSearch);
+    const query = useQuery(
+      {
+        queryKey: computed(() => [
+          "pv-resource",
+          toValue(resolvedIndex),
+          toValue(resourceId)
+        ]),
+        queryFn: async () => {
+          const a = await fetcherFn({
+            baseUrl,
+            resource: toValue(resolvedIndex),
+            id: toValue(resourceId)
+          });
+          return a;
+        },
+        // placeholderData: keepPreviousData,
+        initialData() {
+          const cache = qc.getQueriesData({
+            queryKey: computed(() => ["pv-resources", resolvedIndex.value])
+          });
+          const values = cache.flatMap(([_, value]) => value?.result?.results ?? []).find((resource) => {
+            const schema = z.object({
+              id: z.string()
+            });
+            const result2 = schema.safeParse(resource);
+            if (result2.success)
+              return result2.data.id === toValue(resourceId);
+            return false;
+          });
+          if (!values)
+            return void 0;
+          const resultObj = {
+            result: values,
+            success: true
+          };
+          return resultObj;
+        },
+        enabled
+      },
+      qc
+    );
+    const result = computed(() => query.data.value?.result);
+    const computedGetters = toComputedGetters({
+      data: computed(() => query.data.value?.result),
+      getters,
+      ctx
+    });
+    const obj = {
+      query,
+      isSuccess: query.isSuccess,
+      isLoading: query.isLoading,
+      isFetching: query.isFetching,
+      result,
+      getters: { ...computedGetters }
+    };
+    return obj;
+  }
+  return useResource;
+}
+
+function defineResourceSearchOptions(options) {
+  return options;
+}
+function createUseResourceSearch({
+  resourceSearchOptions,
+  options,
+  getters
+}) {
+  async function defaultFetcherFn(_opts) {
+    const res = await searchResource({
+      baseUrl: resourceSearchOptions.baseUrl,
+      params: {
+        ..._opts.params,
+        filter: resourceSearchOptions.index
+      },
+      additionalParams: _opts.additionalParams,
+      headers: _opts.headers
+    });
+    return res.data;
+  }
+  const {
+    fetcherFn = defaultFetcherFn,
+    qc = useQueryClient()
+  } = options || {};
+  const {
+    schema
+  } = resourceSearchOptions;
+  assertQueryClient(qc);
+  const useSearch = useSearchFactory({
+    schema,
+    ctx: resourceSearchOptions,
+    getters,
+    index: resourceSearchOptions.index,
+    fetcherFn,
+    enabled: resourceSearchOptions.enabled,
+    qc
+  });
+  const useResource = useResourceFactory({
+    schema,
+    ctx: resourceSearchOptions,
+    getters,
+    baseUrl: resourceSearchOptions.baseUrl,
+    fetcherFn: async (_options) => {
+      return getResourceById(_options);
+    },
+    index: resourceSearchOptions.indexDetails ?? resourceSearchOptions.index,
+    indexSearch: resourceSearchOptions.index,
+    qc
+  });
+  function refSyncedWithRouteQuery(searchParam, defaultValue) {
+    const route = useRoute();
+    const router = useRouter();
+    return useRouteQuery(searchParam, defaultValue, {
+      router,
+      route,
+      mode: "push"
+    });
+  }
+  function refSyncedWithRouteQueryFacet(searchParam, defaultValue) {
+    const route = useRoute();
+    const router = useRouter();
+    return useRouteQuery(searchParam, defaultValue, {
+      // always transform the value to an array
+      transform: (value) => {
+        if (Array.isArray(value))
+          return value;
+        if (typeof value === "string")
+          return [value];
+        return [];
+      },
+      router,
+      route,
+      mode: "push"
+    });
+  }
+  return {
+    useSearch,
+    useResources: useSearch,
+    useResource,
+    refSyncedWithRouteQuery,
+    refSyncedWithRouteQueryFacet,
+    getters,
+    resourceSearchOptions
+  };
+}
+
+const keyQueryClient = Symbol("");
+const plugin = {
+  install(app, options = {}) {
+    const qc = options.queryClient || new QueryClient();
+    if (isVue2)
+      throw new Error("Vue 2 is not supported");
+    else
+      app.provide(keyQueryClient, qc);
+  }
+};
+function useQueryClient() {
+  const maybeQueryClient = inject(keyQueryClient, null);
+  return maybeQueryClient;
+}
+
+export { createUseResourceSearch, defineResourceSearchOptions, keyQueryClient, plugin, useQueryClient };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@piveau/sdk-vue",
+  "type": "module",
+  "version": "0.0.0-alpha.0",
+  "private": false,
+  "description": "Asynchronous state management for interacting with piveau services using Vue",
+  "author": "Fraunhofer FOKUS",
+  "license": "Apache-2.0",
+  "keywords": [],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./dist/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "peerDependencies": {
+    "vue": ">=3.0.0",
+    "vue-router": ">=4.0.0"
+  },
+  "dependencies": {
+    "@piveau/sdk-core": "workspace:^",
+    "@tanstack/vue-query": "^5.24.1",
+    "@vueuse/core": "^10.8.0",
+    "@vueuse/router": "^10.9.0",
+    "pinia": "^2.1.7",
+    "vue-demi": ">=0.14.7",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "msw": "^2.2.1",
+    "typescript": "^5.3.3",
+    "unbuild": "^2.0.0",
+    "vue": "^3.4.20",
+    "vue-router": "^4.2.5"
+  }
+}