@narrative.io/jsonforms-provider-protocols 1.0.3

package/src/core/templating.ts

@@ -0,0 +1,27 @@
+export function renderTpl(str: string, ctx: unknown): string {
+  return str.replace(/\{\{\s*([^}]+)\s*\}\}/g, (_, path) => {
+    const trimmedPath = path.trim();
+    return String(
+      trimmedPath.split(".").reduce((a: unknown, k: string) => {
+        if (a && typeof a === "object" && k in a) {
+          return (a as Record<string, unknown>)[k];
+        }
+        return undefined;
+      }, ctx) ?? "",
+    );
+  });
+}
+export function renderObj<T = unknown>(obj: unknown, ctx: unknown): T {
+  if (!obj || typeof obj !== "object") return obj as T;
+  const out: Record<string, unknown> | unknown[] = Array.isArray(obj) ? [] : {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "string") {
+      (out as Record<string, unknown>)[k] = renderTpl(v, ctx);
+    } else if (v && typeof v === "object") {
+      (out as Record<string, unknown>)[k] = renderObj(v, ctx);
+    } else {
+      (out as Record<string, unknown>)[k] = v;
+    }
+  }
+  return out as T;
+}

package/src/core/types.ts

@@ -0,0 +1,46 @@
+export type ProviderItem = {
+  label: string;
+  value: unknown;
+  meta?: Record<string, unknown>;
+};
+export type ProviderOutput = {
+  items: ProviderItem[];
+  ttl?: number;
+  etag?: string;
+};
+
+export type ProviderContext = {
+  data: unknown;
+  path: string;
+  signal: AbortSignal;
+  ui?: { query?: string };
+  auth?: Record<string, unknown>; // Global auth registry, not AuthConfig
+};
+
+export interface Protocol<Cfg = unknown> {
+  protocol: string; // 'rest_api' | 'table' | 'cookie' | ...
+  resolve(cfg: Cfg, ctx: ProviderContext): Promise<ProviderOutput>;
+}
+
+export interface ProviderBinding {
+  ref: string;
+  protocol: string;
+  config?: unknown;
+  auth?: AuthConfig;
+  cacheTTL?: number;
+  load?: "mount" | "onFocus" | "query";
+}
+
+export type Mapping = {
+  label: string;
+  value: string;
+  meta?: Record<string, string>;
+};
+
+export interface AuthConfig {
+  use?: string; // Reference global auth key
+  apiKey?: string | (() => string); // API key auth
+  bearer?: string | (() => string); // Bearer token auth
+  token?: string | (() => string); // Generic token auth
+  [key: string]: unknown; // Custom auth fields
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+import type { App } from "vue";
+import { cache as globalCache } from "./core/cache";
+import { registry as globalRegistry } from "./core/registry";
+import type { Protocol, AuthConfig } from "./core/types";
+
+export { cache } from "./core/cache";
+export * from "./core/jsonpath";
+export { registry } from "./core/registry";
+export * from "./core/templating";
+// Core exports
+export * from "./core/types";
+
+// Protocol exports
+export { RestApiProtocol } from "./protocols/rest_api";
+
+// Vue exports
+export * as vue from "./vue";
+
+export interface ProviderConfig {
+  protocols?: Protocol[];
+  auth?: AuthConfig;
+}
+
+export default {
+  install(app: App, opts?: ProviderConfig) {
+    const reg = globalRegistry;
+    if (opts?.protocols) {
+      for (const p of opts.protocols) {
+        reg.register(p);
+      }
+    }
+    app.provide("providerRegistry", reg);
+    app.provide("providerCache", globalCache);
+    app.provide("providerAuth", opts?.auth ?? {});
+  },
+};

package/src/protocols/rest_api.ts

@@ -0,0 +1,136 @@
+import { jp } from "../core/jsonpath";
+import { renderObj, renderTpl } from "../core/templating";
+import type {
+  Protocol,
+  ProviderItem,
+  ProviderOutput,
+  AuthConfig,
+} from "../core/types";
+
+export type RestApiCfg = {
+  url: string;
+  method?: "GET" | "POST";
+  headers?: Record<string, string>;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  items: string; // JSONPath to array; e.g. "$.items[*]"
+  map: { label: string; value: string; meta?: Record<string, string> }; // relative to each item
+  paginate?: { cursorPath: string; param: string; maxPages?: number };
+  auth?: AuthConfig;
+};
+
+function buildAuthHeaders(
+  auth?: AuthConfig,
+  globalAuth?: Record<string, unknown>,
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  if (!auth) return headers;
+
+  // Handle "use" reference to global auth
+  if (auth.use && globalAuth?.[auth.use]) {
+    const globalValue = globalAuth[auth.use];
+    const value =
+      typeof globalValue === "function" ? globalValue() : globalValue;
+
+    if (auth.use === "apiKey") {
+      headers["X-API-Key"] = String(value);
+    } else if (auth.use === "bearer") {
+      headers["Authorization"] = `Bearer ${value}`;
+    } else if (auth.use === "token") {
+      headers["Authorization"] = `Token ${value}`;
+    }
+    return headers;
+  }
+
+  // Handle direct auth values
+  if (auth.apiKey) {
+    const value =
+      typeof auth.apiKey === "function" ? auth.apiKey() : auth.apiKey;
+    headers["X-API-Key"] = String(value);
+  }
+
+  if (auth.bearer) {
+    const value =
+      typeof auth.bearer === "function" ? auth.bearer() : auth.bearer;
+    headers["Authorization"] = `Bearer ${value}`;
+  }
+
+  if (auth.token) {
+    const value = typeof auth.token === "function" ? auth.token() : auth.token;
+    headers["Authorization"] = `Token ${value}`;
+  }
+
+  // Handle custom auth fields
+  for (const [key, value] of Object.entries(auth)) {
+    if (
+      !["use", "apiKey", "bearer", "token"].includes(key) &&
+      value !== undefined
+    ) {
+      const authValue = typeof value === "function" ? value() : value;
+      headers[key] = String(authValue);
+    }
+  }
+
+  return headers;
+}
+
+export const RestApiProtocol = (): Protocol<RestApiCfg> => ({
+  protocol: "rest_api",
+  async resolve(cfg, ctx): Promise<ProviderOutput> {
+    const ac = ctx.signal;
+    const out: ProviderItem[] = [];
+    let cursor: unknown = null;
+    let page = 0;
+    do {
+      const url = new URL(renderTpl(cfg.url, { data: ctx.data, ui: ctx.ui }));
+      const q = renderObj(cfg.query ?? {}, {
+        data: ctx.data,
+        ui: ctx.ui,
+      }) as Record<string, unknown>;
+      for (const [k, v] of Object.entries(q))
+        if (v !== undefined && v !== "") url.searchParams.set(k, String(v));
+      if (cursor && cfg.paginate)
+        url.searchParams.set(cfg.paginate.param, String(cursor));
+
+      // Build headers with auth
+      const baseHeaders = renderObj(cfg.headers ?? {}, {
+        data: ctx.data,
+      }) as Record<string, string>;
+      const authHeaders = buildAuthHeaders(cfg.auth, ctx.auth);
+      const headers = { ...baseHeaders, ...authHeaders };
+
+      const method = cfg.method ?? "GET";
+      const requestInit: RequestInit = {
+        method,
+        headers,
+        signal: ac,
+      };
+
+      // Only include body for non-GET requests
+      if (method !== "GET" && cfg.body) {
+        requestInit.body = JSON.stringify(
+          renderObj(cfg.body, { data: ctx.data }),
+        );
+      }
+
+      const res = await fetch(url.toString(), requestInit);
+      if (!res.ok) throw new Error(`REST ${res.status}`);
+      const json = await res.json();
+      const items = jp(json, cfg.items);
+      for (const it of items) {
+        const label = jp(it, cfg.map.label)[0];
+        const value = jp(it, cfg.map.value)[0];
+        const meta = cfg.map.meta
+          ? Object.fromEntries(
+              Object.entries(cfg.map.meta).map(([k, p]) => [k, jp(it, p)[0]]),
+            )
+          : undefined;
+        out.push({ label: String(label ?? ""), value, meta });
+      }
+      cursor = cfg.paginate ? jp(json, cfg.paginate.cursorPath)[0] : null;
+      page += 1;
+    } while (cfg.paginate && cursor && page < (cfg.paginate.maxPages ?? 5));
+    return { items: out, ttl: 300 };
+  },
+});

package/src/vue/components/ProviderAutocomplete.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+import type { ControlElement, JsonSchema } from "@jsonforms/core";
+import { useJsonFormsControl } from "@jsonforms/vue";
+import { computed, ref, watch } from "vue";
+import { useProvider } from "../composables/useProvider";
+
+const props = defineProps<{
+  uischema: ControlElement;
+  schema: JsonSchema;
+  path: string;
+}>();
+const { control, handleChange } = useJsonFormsControl(props);
+
+const binding = computed(() => {
+  const provider = control.value.uischema?.options?.provider;
+  // Ensure load property is set to 'query' by default for autocomplete
+  if (provider && typeof provider === "object" && !provider.load) {
+    return { ...provider, load: "query" };
+  }
+  return provider;
+});
+const query = ref("");
+const { items, loading, error, reload } = useProvider(binding, {
+  data: control.value.data,
+  path: control.value.path,
+  uiQuery: query.value,
+});
+
+watch(query, () => {
+  if (binding.value?.load === "query") reload();
+});
+
+const value = computed({
+  get: () => control.value.data,
+  set: (v) => handleChange(control.value.path, v),
+});
+</script>
+
+<template>
+  <div class="provider-autocomplete">
+    <label>{{ control.schema.title }}</label>
+    <input
+      v-model="query"
+      :placeholder="loading ? 'Loading…' : 'Type to search…'"
+      type="text"
+    />
+    <ul v-if="items.length">
+      <li v-for="it in items" :key="String(it.value)" @click="value = it.value">
+        {{ it.label }}
+      </li>
+    </ul>
+    <small v-if="error" role="alert">Failed: {{ error }}</small>
+  </div>
+</template>

package/src/vue/components/ProviderSelect.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+import type { ControlElement, JsonSchema } from "@jsonforms/core";
+import { useJsonFormsControl } from "@jsonforms/vue";
+import { computed, watch } from "vue";
+import { useProvider } from "../composables/useProvider";
+
+const props = defineProps<{
+  uischema: ControlElement;
+  schema: JsonSchema;
+  path: string;
+}>();
+const { control, handleChange } = useJsonFormsControl(props);
+
+const binding = computed(() => {
+  const provider = control.value.uischema?.options?.provider;
+  // Ensure load property is set to 'mount' by default
+  if (provider && typeof provider === "object" && !provider.load) {
+    return { ...provider, load: "mount" };
+  }
+  return provider;
+});
+
+const deps = computed(
+  () =>
+    ((
+      (control.value.schema as Record<string, unknown>)?.[
+        "x-provider"
+      ] as Record<string, unknown>
+    )?.dependsOn as string[]) ?? [],
+);
+const depValues = computed(() => deps.value.map(() => null)); // you can resolve actual values via control.value.data & pointers
+
+const { items, loading, error, reload } = useProvider(binding, {
+  data: control.value.data,
+  path: control.value.path,
+  dependsOnValues: depValues.value,
+});
+
+watch(
+  () => control.value.data,
+  () => {
+    // if dependsOn changed → reload
+    reload();
+  },
+);
+
+const value = computed({
+  get: () => control.value.data,
+  set: (v) => handleChange(control.value.path, v),
+});
+</script>
+
+<template>
+  <div class="provider-select">
+    <label>{{ control.schema.title }}</label>
+    <select v-model="value">
+      <option value="" disabled>{{ loading ? "Loading…" : "Select…" }}</option>
+      <option v-for="it in items" :key="String(it.value)" :value="it.value">
+        {{ it.label }}
+      </option>
+    </select>
+    <small v-if="error" role="alert">Failed to load: {{ error }}</small>
+  </div>
+</template>
+
+<style scoped>
+.provider-select select {
+  min-width: 16rem;
+}
+</style>

package/src/vue/composables/useProvider.ts

@@ -0,0 +1,111 @@
+import {
+  type ComputedRef,
+  computed,
+  inject,
+  onBeforeUnmount,
+  type Ref,
+  ref,
+  unref,
+  watch,
+} from "vue";
+import { cache as globalCache } from "../../core/cache";
+import { registry as globalRegistry } from "../../core/registry";
+import type {
+  AuthConfig,
+  ProviderBinding,
+  ProviderItem,
+  ProviderOutput,
+} from "../../core/types";
+
+export function useProvider(
+  binding:
+    | ProviderBinding
+    | Ref<ProviderBinding>
+    | ComputedRef<ProviderBinding>,
+  ctxBits: {
+    data: unknown;
+    path: string;
+    dependsOnValues?: unknown[];
+    uiQuery?: string;
+  },
+) {
+  const registry = inject("providerRegistry", globalRegistry);
+  const cache = inject("providerCache", globalCache);
+  const auth = inject("providerAuth", {}) as Record<
+    string,
+    (() => string) | string
+  >;
+
+  const items = ref<ProviderItem[]>([]);
+  const loading = ref(false);
+  const error = ref<string | undefined>(undefined);
+  const ac = new AbortController();
+
+  const cacheKey = computed(() =>
+    JSON.stringify({
+      b: unref(binding),
+      d: ctxBits.dependsOnValues ?? [],
+      q: ctxBits.uiQuery ?? "",
+    }),
+  );
+
+  async function load() {
+    const bindingValue = unref(binding);
+    if (!bindingValue) return;
+    loading.value = true;
+    error.value = undefined;
+    const hit = cache.get(cacheKey.value) as ProviderOutput | undefined;
+    if (hit) {
+      items.value = hit.items;
+      loading.value = false;
+      return;
+    }
+    try {
+      const driver = registry.get(bindingValue.protocol);
+      if (!driver) {
+        throw new Error(
+          `No provider registered for protocol: ${bindingValue.protocol}`,
+        );
+      }
+      const out = await driver.resolve(bindingValue.config ?? {}, {
+        data: ctxBits.data,
+        path: ctxBits.path,
+        ui: { query: ctxBits.uiQuery },
+        signal: ac.signal,
+        auth: resolveAuth(bindingValue.auth, auth),
+      });
+      items.value = out.items;
+      cache.set(cacheKey.value, out, bindingValue.cacheTTL ?? out.ttl ?? 0);
+    } catch (e) {
+      error.value = (e as Error)?.message ?? String(e);
+      items.value = [];
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  onBeforeUnmount(() => ac.abort());
+  watch(
+    [cacheKey],
+    () => {
+      const bindingValue = unref(binding);
+      if (bindingValue?.load === "mount" || bindingValue?.load === "query")
+        load();
+    },
+    { immediate: unref(binding)?.load === "mount" },
+  );
+
+  return { items, loading, error, reload: load };
+}
+
+function resolveAuth(
+  spec: AuthConfig | undefined,
+  authBag: Record<string, (() => string) | string>,
+): AuthConfig {
+  if (!spec) return {};
+  if (spec.use && typeof authBag[spec.use] === "function") {
+    const authFunc = authBag[spec.use] as () => string;
+    return { [spec.use]: authFunc() };
+  }
+  return spec;
+}

package/src/vue/index.ts

@@ -0,0 +1,44 @@
+import type { UISchemaElement } from "@jsonforms/core";
+import {
+  and,
+  isIntegerControl,
+  isNumberControl,
+  isStringControl,
+  or,
+  rankWith,
+} from "@jsonforms/core";
+import ProviderAutocomplete from "./components/ProviderAutocomplete.vue";
+import ProviderSelect from "./components/ProviderSelect.vue";
+
+// Custom tester that checks if provider option exists (as object or boolean)
+const hasProvider = (uischema: UISchemaElement) => {
+  return uischema?.options?.provider !== undefined;
+};
+
+// Create specific testers for each component type
+const providerSelectTester = rankWith(
+  6,
+  and(
+    or(isStringControl, isNumberControl, isIntegerControl),
+    hasProvider,
+    (uischema) => !uischema?.options?.autocomplete,
+  ),
+);
+
+const providerAutocompleteTester = rankWith(
+  7,
+  and(
+    or(isStringControl, isNumberControl, isIntegerControl),
+    hasProvider,
+    (uischema) => uischema?.options?.autocomplete === true,
+  ),
+);
+
+export const providerRenderers = [
+  { tester: providerSelectTester, renderer: ProviderSelect },
+  { tester: providerAutocompleteTester, renderer: ProviderAutocomplete },
+];
+
+export { ProviderAutocomplete, ProviderSelect };
+export { useProvider } from "./composables/useProvider";
+export * from "./testers";

package/src/vue/testers.ts

@@ -0,0 +1,19 @@
+import {
+  and,
+  isIntegerControl,
+  isNumberControl,
+  isStringControl,
+  or,
+  rankWith,
+} from "@jsonforms/core";
+
+// Tester that checks if provider option exists (as object or boolean)
+export const providerTester = rankWith(
+  5,
+  and(
+    or(isStringControl, isNumberControl, isIntegerControl),
+    (uischema: import("@jsonforms/core").UISchemaElement) =>
+      uischema?.options?.provider !== undefined &&
+      uischema?.options?.provider !== null,
+  ),
+);

package/src/vue-shim.d.ts

@@ -0,0 +1,9 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<
+    Record<string, unknown>,
+    Record<string, unknown>,
+    unknown
+  >;
+  export default component;
+}