@piveau/sdk-vue 0.0.0-alpha-2.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/__tests__/defineResourceGetters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/defineResourceGetters.test.js

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import * as z from "zod";
+import { nextTick, ref } from "vue-demi";
+import { defineResourceSearchOptions } from "../createUseResourceSearch.js";
+import { defineGetters, toComputedGetters } from "../getters.js";
+describe("defineResourceGetters", () => {
+  it("should work", async () => {
+    const ctx = defineResourceSearchOptions({
+      baseUrl: `https://open.bydata.de/api/hub/search`,
+      index: "dataset",
+      schema: z.object({
+        foo: z.string(),
+        bar: z.number()
+      }),
+      facets: ["categories", "publisher", "catalog"]
+    });
+    const getters = defineGetters({
+      schema: z.object({
+        foo: z.string(),
+        bar: z.number()
+      }),
+      ctx,
+      getters: {
+        /**
+         * Gets the test result
+         */
+        getTestResult: (data) => {
+          return `${data.foo}${data.bar}`;
+        },
+        getOtherTestResult: () => {
+          return "otherTest";
+        },
+        getBaseUrl: (_, ctx2) => {
+          return ctx2?.baseUrl;
+        },
+        getFullTestResult: (data, ctx2) => {
+          return `${data.foo}${data.bar}${ctx2?.baseUrl}`;
+        }
+      }
+    });
+    expect(
+      getters.getTestResult({
+        foo: "test",
+        bar: 123
+      })
+    ).toBe("test123");
+    expect(getters.getOtherTestResult()).toBe("otherTest");
+    expect(
+      getters.getBaseUrl(
+        {
+          foo: "test",
+          bar: 123
+        },
+        ctx
+      )
+    ).toBe(ctx.baseUrl);
+    expect(
+      getters.getFullTestResult(
+        {
+          foo: "test",
+          bar: 123
+        },
+        ctx
+      )
+    ).toBe(`test123${ctx.baseUrl}`);
+  });
+  it("should work with computed getters", async () => {
+    const ctx = defineResourceSearchOptions({
+      baseUrl: `https://open.bydata.de/api/hub/search`,
+      index: "dataset",
+      schema: z.object({
+        foo: z.string(),
+        bar: z.number()
+      }),
+      facets: ["categories", "publisher", "catalog"]
+    });
+    const getters = defineGetters({
+      schema: z.object({
+        foo: z.string(),
+        bar: z.number()
+      }),
+      ctx,
+      getters: {
+        getTestResult: (data2) => {
+          return `${data2.foo}${data2.bar}`;
+        },
+        getOtherTestResult: () => {
+          return "otherTest";
+        },
+        getBaseUrl: (_, ctx2) => {
+          return ctx2?.baseUrl;
+        },
+        getFullTestResult: (data2, ctx2) => {
+          return `${data2.foo}${data2.bar}${ctx2?.baseUrl}`;
+        }
+      }
+    });
+    const data = ref({
+      foo: "test",
+      bar: 123
+    });
+    const computedGetters = toComputedGetters(
+      { data, getters, ctx }
+    );
+    expect(computedGetters.getTestResult.value).toBe("test123");
+    expect(computedGetters.getOtherTestResult.value).toBe("otherTest");
+    expect(computedGetters.getBaseUrl.value).toBe(ctx.baseUrl);
+    expect(computedGetters.getFullTestResult.value).toBe(`test123${ctx.baseUrl}`);
+    data.value = {
+      foo: "foo",
+      bar: 456
+    };
+    await nextTick();
+    expect(computedGetters.getTestResult.value).toBe("foo456");
+    expect(computedGetters.getOtherTestResult.value).toBe("otherTest");
+    expect(computedGetters.getBaseUrl.value).toBe(ctx.baseUrl);
+    expect(computedGetters.getFullTestResult.value).toBe(`foo456${ctx.baseUrl}`);
+  });
+});

package/dist/__tests__/testUtils.d.ts

@@ -0,0 +1,10 @@
+export declare const defaultQueryClientConfig: {
+    defaultOptions: {
+        queries: {
+            refetchOnWindowFocus: false;
+            retry: false;
+            staleTime: number;
+            gcTime: number;
+        };
+    };
+};

package/dist/__tests__/testUtils.js

@@ -0,0 +1,10 @@
+export const defaultQueryClientConfig = {
+  defaultOptions: {
+    queries: {
+      refetchOnWindowFocus: false,
+      retry: false,
+      staleTime: Number.POSITIVE_INFINITY,
+      gcTime: Number.POSITIVE_INFINITY
+    }
+  }
+};

package/dist/__tests__/useResourceFactory.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/useResourceFactory.test.js

@@ -0,0 +1,125 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as z from "zod";
+import { QueryClient } from "@tanstack/vue-query";
+import { computed, effectScope, nextTick, reactive, ref, toRef, toValue, watch } from "vue-demi";
+import { syncRef, until, watchOnce } from "@vueuse/core";
+import { useResourceFactory } from "../useResourceFactory.js";
+import { defaultQueryClientConfig } from "./testUtils.js";
+const schema = z.object({
+  foo: z.string()
+});
+function createUseResource(qc, cb) {
+  const useResource = useResourceFactory({
+    baseUrl: "https://example.org",
+    schema,
+    index: "dataset",
+    indexSearch: "dataset",
+    qc,
+    enabled: true,
+    ctx: {
+      locale: "en"
+    },
+    fetcherFn: cb
+  }, (data, ctx) => {
+    const getHelloFoo = computed(() => `$hello ${toValue(data)?.foo}`);
+    const getFoo = computed(() => toValue(data)?.foo);
+    const getFooCapitalized = computed(() => toValue(data)?.foo.toUpperCase());
+    const getContextualFoo = computed(() => `${toValue(data)?.foo}-${toValue(ctx)?.locale}`);
+    return {
+      getHelloFoo,
+      getFoo,
+      getFooCapitalized,
+      getContextualFoo
+    };
+  });
+  return useResource;
+}
+describe("useResourceFactory", () => {
+  const fetcherSpy = vi.fn(({ id }) => {
+    const mockResult = {
+      success: true,
+      result: {
+        foo: id ?? "bar"
+      }
+    };
+    return Promise.resolve(mockResult);
+  });
+  let useResource = {};
+  beforeEach(() => {
+    vi.clearAllMocks();
+    const qc = new QueryClient(defaultQueryClientConfig);
+    useResource = createUseResource(qc, fetcherSpy);
+  });
+  it("should return a function", async () => {
+    expect(useResource).toBeTypeOf("function");
+  });
+  it("should call fetcherFn", async () => {
+    const scope = effectScope(true);
+    const hasResult = ref(false);
+    const result = ref({});
+    const helloFoo = ref("");
+    const id = ref("some-id");
+    const headers = ref({ foo: "bar" });
+    await scope.run(async () => {
+      const resourceQuery = useResource(id, { headers });
+      syncRef(resourceQuery.result, result, { direction: "ltr" });
+      watchOnce(() => resourceQuery.query.isSuccess.value, async (_count) => {
+        if (resourceQuery.isSuccess.value === true)
+          resourceQuery.result.value;
+        await nextTick();
+        hasResult.value = true;
+      });
+      watch(() => resourceQuery.resultEnhanced.value?.getHelloFoo, (value) => {
+        helloFoo.value = value;
+      });
+    });
+    await until(() => !!hasResult.value).toBe(true);
+    expect(fetcherSpy).toHaveBeenCalledTimes(1);
+    expect(fetcherSpy).toHaveBeenCalledWith({
+      baseUrl: "https://example.org",
+      resource: "dataset",
+      id: "some-id",
+      headers: { foo: "bar" }
+    });
+    expect(result.value).toEqual({ foo: "some-id" });
+    id.value = "some-other-id";
+    headers.value = { foo: "baz" };
+    await nextTick();
+    await nextTick();
+    expect(fetcherSpy).toHaveBeenCalledTimes(2);
+    await until(() => !!result.value).toBe(true);
+    expect(result.value).toEqual({ foo: "some-other-id" });
+    expect(helloFoo.value).toBe("$hello some-other-id");
+  });
+  it("should properly apply setup", async () => {
+    const scope = effectScope(true);
+    const hasResult = ref(false);
+    const result = ref({});
+    const id = ref("some-id");
+    await scope.run(async () => {
+      const resourceQuery = reactive(useResource(id));
+      syncRef(toRef(resourceQuery.result), result, { direction: "ltr" });
+      watchOnce(() => resourceQuery.isSuccess, async (_count) => {
+        await nextTick();
+        hasResult.value = true;
+      });
+      await until(() => !!resourceQuery.isSuccess).toBe(true);
+      await nextTick();
+      expect(resourceQuery.isSuccess).toBe(true);
+      if (resourceQuery.isSuccess) {
+        expect(resourceQuery.resultEnhanced.getFoo).toBe("some-id");
+        expect(resourceQuery.resultEnhanced.getFooCapitalized).toBe("SOME-ID");
+        expect(resourceQuery.resultEnhanced.getContextualFoo).toBe("some-id-en");
+      }
+      id.value = "some-other-id";
+      await nextTick();
+      await until(() => !!resourceQuery.isSuccess).toBe(true);
+      expect(resourceQuery.isSuccess).toBe(true);
+      if (resourceQuery.isSuccess) {
+        expect(resourceQuery.resultEnhanced.getFoo).toBe("some-other-id");
+        expect(resourceQuery.resultEnhanced.getFooCapitalized).toBe("SOME-OTHER-ID");
+        expect(resourceQuery.resultEnhanced.getContextualFoo).toBe("some-other-id-en");
+      }
+    });
+  });
+});

package/dist/__tests__/useSearchFactory.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/useSearchFactory.test.js

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as z from "zod";
+import { QueryClient } from "@tanstack/vue-query";
+import { computed, effectScope, nextTick, ref, toValue } from "vue-demi";
+import { until, watchOnce } from "@vueuse/core";
+import { useSearchFactory } from "../useSearchFactory.js";
+import { defaultQueryClientConfig } from "./testUtils.js";
+function createUseSearch(qc, cb) {
+  const useSearch = useSearchFactory({
+    ctx: {
+      baseUrl: "https://foo.bar"
+    },
+    schema: z.object({
+      foo: z.string(),
+      bar: z.number()
+    }),
+    index: "dataset",
+    qc,
+    fetcherFn: cb
+  }, (data) => {
+    const v = toValue(data);
+    return {
+      foobar: computed(() => `${v?.foo}${v?.bar}`),
+      barfoo: computed(() => `${v?.bar}${v?.foo}`),
+      nono: 123
+    };
+  });
+  return useSearch;
+}
+describe("useSearchFactory", () => {
+  const fetcherSpy = vi.fn((_) => {
+    const mockResult = {
+      result: {
+        count: 1e3,
+        facets: [],
+        index: "dataset",
+        results: [{ foo: "test", bar: 123 }, { foo: "test2", bar: 456 }]
+      }
+    };
+    return Promise.resolve(mockResult);
+  });
+  let useSearch = {};
+  beforeEach(() => {
+    vi.clearAllMocks();
+    const qc = new QueryClient(defaultQueryClientConfig);
+    useSearch = createUseSearch(qc, fetcherSpy);
+  });
+  it("should return a function", async () => {
+    expect(useSearch).toBeTypeOf("function");
+  });
+  it("should call fetcherFn", async () => {
+    const scope = effectScope(true);
+    const qExpected = "query";
+    const limitExpected = 123;
+    const headerExpected = {
+      foo: "bar"
+    };
+    const q = ref(qExpected);
+    const limit = ref(limitExpected);
+    const headers = ref(headerExpected);
+    const count = ref(-1);
+    const results = ref([]);
+    await scope.run(async () => {
+      const { getSearchResultsCount, getSearchResultsEnhanced } = useSearch({
+        queryParams: {
+          q,
+          limit
+        },
+        headers
+      });
+      watchOnce(() => getSearchResultsCount.value, (_count) => {
+        count.value = _count;
+        if (getSearchResultsEnhanced.value) {
+          results.value = getSearchResultsEnhanced.value;
+        }
+      });
+    });
+    await until(() => count.value !== -1).toBe(true);
+    expect(fetcherSpy).toHaveBeenCalledTimes(1);
+    expect(fetcherSpy.mock.calls[0]?.[0].params.q).toBe(qExpected);
+    expect(fetcherSpy.mock.calls[0]?.[0].params.limit).toBe(limitExpected);
+    expect(fetcherSpy.mock.calls[0]?.[0].params.facets).toEqual({});
+    expect(fetcherSpy.mock.calls[0]?.[0].headers.foo).toBe("bar");
+    expect(results.value).toHaveLength(2);
+    expect(results.value[0].foobar).toBe("test123");
+    expect(results.value[0].barfoo).toBe("123test");
+    expect(results.value[1].foobar).toBe("test2456");
+    expect(results.value[1].barfoo).toBe("456test2");
+    q.value = "foo";
+    q.value = "new query";
+    limit.value = 456;
+    headers.value = {
+      foo: "baz"
+    };
+    await nextTick();
+    expect(fetcherSpy).toHaveBeenCalledTimes(2);
+    expect(fetcherSpy.mock.calls[1]?.[0].params.q).toBe("new query");
+    expect(fetcherSpy.mock.calls[1]?.[0].params.limit).toBe(456);
+    expect(fetcherSpy.mock.calls[1]?.[0].params.facets).toEqual({});
+    expect(fetcherSpy.mock.calls[1]?.[0].headers.foo).toBe("baz");
+  });
+});

package/dist/__tests__/useSearchQueryParams.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/useSearchQueryParams.test.js

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import { reactive, ref } from "vue-demi";
+import { useSearchQueryParams } from "../useSearchQueryParams.js";
+describe("useSearchQueryParams", () => {
+  it("should provide queryParams", () => {
+    const { queryParams } = useSearchQueryParams();
+    expect(queryParams).toBeDefined();
+    expect(reactive(queryParams)).toStrictEqual({
+      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
+    });
+  });
+  it("should reactively update queryParams when using setters", () => {
+    const {
+      queryParams,
+      setFacetOperator,
+      setDataScope,
+      setDataServices,
+      setSuperCatalogue,
+      setDatasetGeoBounds,
+      setFacetGroupOperator,
+      setLimit,
+      setMinScoring,
+      setPage,
+      setQuery,
+      setSort
+    } = useSearchQueryParams();
+    setFacetOperator("AND");
+    setDataScope(true);
+    setDataServices(false);
+    setSuperCatalogue("test");
+    setDatasetGeoBounds({ minLon: 1, maxLon: 2, minLat: 3, maxLat: 4 });
+    setFacetGroupOperator("OR");
+    setLimit(10);
+    setMinScoring(0.5);
+    setPage(1);
+    setQuery("test");
+    setSort("title+asc");
+    expect(queryParams.facetOperator.value).toBe("AND");
+    expect(queryParams.countryData.value).toBe(true);
+    expect(queryParams.dataServices.value).toBe(false);
+    expect(queryParams.superCatalogue.value).toBe("test");
+    expect(queryParams.bboxMinLon.value).toBe(1);
+    expect(queryParams.bboxMaxLon.value).toBe(2);
+    expect(queryParams.bboxMinLat.value).toBe(3);
+    expect(queryParams.bboxMaxLat.value).toBe(4);
+    expect(queryParams.facetGroupOperator.value).toBe("OR");
+    expect(queryParams.limit.value).toBe(10);
+    expect(queryParams.minScoring.value).toBe(0.5);
+    expect(queryParams.page.value).toBe(1);
+    expect(queryParams.q.value).toBe("test");
+    expect(queryParams.sort.value).toBe("title+asc");
+  });
+  it("should reactively update queryParams when updating reactive params", () => {
+    const facetOperator = ref("AND");
+    const { queryParams } = useSearchQueryParams({
+      facetOperator
+    });
+    facetOperator.value = "OR";
+    expect(queryParams.facetOperator.value).toBe("OR");
+  });
+});

package/dist/composables/locale.d.ts

@@ -0,0 +1,27 @@
+import type { InjectionKey, MaybeRefOrGetter } from 'vue-demi';
+export interface LocaleMessages {
+    [key: string]: LocaleMessages | string;
+}
+export type DateFormats = 'short' | 'medium' | 'long';
+export type DateLike = Date | string | number;
+export type DateFormatStrings = {
+    [key in DateFormats]?: string;
+};
+export interface LocaleInstance {
+    name: string;
+    messages: MaybeRefOrGetter<LocaleMessages>;
+    currentLocale: MaybeRefOrGetter<string>;
+    fallbackLocale: MaybeRefOrGetter<string>;
+    t: (key: string, ...params: unknown[]) => string;
+    n: (value: number) => string;
+    d: (value: DateLike, format?: DateFormats, locale?: Intl.LocalesArgument) => string;
+}
+export interface LocaleOptions {
+    messages?: LocaleMessages;
+    locale?: string;
+    fallback?: string;
+    dateFormatStrings?: DateFormatStrings;
+    adapter?: LocaleInstance;
+}
+export declare const localeKey: InjectionKey<LocaleInstance>;
+export declare function useLocale(): LocaleInstance;

package/dist/composables/locale.js

@@ -0,0 +1,8 @@
+import { inject } from "vue-demi";
+export const localeKey = Symbol("locale");
+export function useLocale() {
+  const locale = inject(localeKey);
+  if (!locale)
+    throw new Error("[piveau-kit] Could not inject locale instance. Did you forget to install the `@piveau/sdk-vue` plugin?");
+  return locale;
+}

package/dist/composables/usePropertyTable.d.ts

@@ -0,0 +1 @@
+export declare function usePropertyTable(): void;

package/dist/composables/usePropertyTable.js

@@ -0,0 +1,2 @@
+export function usePropertyTable() {
+}

package/dist/defineHubSearch.d.ts

@@ -0,0 +1,37 @@
+import type { SearchParamsBase, SearchResult } from '@piveau/sdk-core';
+import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue-demi';
+import type * as z from 'zod';
+import type { QueryClient } from '@tanstack/vue-query';
+export interface DefineHubSearchOptions<TIndex extends string, TFacetNames extends string, TModelSchema> {
+    baseUrl: string;
+    index: TIndex;
+    indexDetails?: string;
+    enabled?: MaybeRefOrGetter<boolean>;
+    schema: z.Schema<TModelSchema>;
+    facets?: TFacetNames[];
+    defaultOptions?: {
+        dateFormatter?: (datetime: string) => string;
+        locale?: MaybeRefOrGetter<string>;
+        searchFetcherFn?: () => Promise<SearchResult<TModelSchema>>;
+        resourceFetcherFn?: () => Promise<SearchResult<TModelSchema>>;
+        qc?: QueryClient;
+    };
+}
+export type _ExtractComputedRefsFromSetup<TSetup> = {
+    [K in keyof TSetup as TSetup[K] extends ComputedRef ? K : never]: TSetup[K];
+};
+export type _ExtractComputedRefsFromSetupUnrwapped<TSetup> = TSetup extends _ExtractComputedRefsFromSetup<TSetup> ? {
+    [K in keyof _ExtractComputedRefsFromSetup<TSetup>]: TSetup[K] extends ComputedRef<infer t> ? t : never;
+} : never;
+export declare function defineHubSearch<TIndex extends string, TFacetNames extends string, TModelSchema, TSetup extends object>(options: DefineHubSearchOptions<TIndex, TFacetNames, TModelSchema>, setup?: (data: MaybeRefOrGetter<TModelSchema | undefined>, ctx?: DefineHubSearchOptions<TIndex, TFacetNames, TModelSchema>) => TSetup): {
+    useSearch: (params: import("./useSearchFactory.js").UseSearchParams<TFacetNames>) => import("./useSearchFactory.js").UseSearchFactoryReturn<TFacetNames, TModelSchema, TSetup>;
+    useResource: import("./useResourceFactory.js").UseResourceFunction<TSetup, TModelSchema | undefined>;
+    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[]>;
+    setup: ((data: MaybeRefOrGetter<TModelSchema | undefined>, ctx?: DefineHubSearchOptions<TIndex, TFacetNames, TModelSchema>) => TSetup) | undefined;
+};
+export type HubSearchIntegrationOptions<TModelSchema> = DefineHubSearchOptions<string, string, TModelSchema>;
+export declare function defineHubSearchIntegration<TModelSchema, TSetup>(schema: z.Schema<TModelSchema>, setup: (data: MaybeRefOrGetter<TModelSchema | undefined>, ctx?: HubSearchIntegrationOptions<TModelSchema>) => TSetup): {
+    setup: (data: MaybeRefOrGetter<TModelSchema | undefined>, ctx?: HubSearchIntegrationOptions<TModelSchema>) => TSetup;
+    schema: z.ZodType<TModelSchema, z.ZodTypeDef, TModelSchema>;
+};