@jskit-ai/http-web 0.1.1

package/test/requestTransportOptions.test.js

@@ -0,0 +1,457 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
+import { createSSRApp, h } from "vue";
+import { renderToString } from "vue/server-renderer";
+
+import {
+  buildEndpointReadRequestOptions,
+  buildEndpointWriteRequestOptions,
+  useEndpointResource
+} from "../src/client/composables/runtime/useEndpointResource.js";
+import { useCommand } from "../src/client/composables/useCommand.js";
+import {
+  configureHttpWebClient,
+  resetHttpWebClientForTests
+} from "../src/client/lib/httpClient.js";
+import { buildListRequestOptions } from "../src/client/composables/runtime/useListCore.js";
+import {
+  resolveOperationRealtimeOptions
+} from "../src/client/composables/useRealtimeQueryInvalidation.js";
+
+test("endpoint read request options include transport only when provided", () => {
+  assert.deepEqual(
+    buildEndpointReadRequestOptions({
+      method: "get"
+    }),
+    {
+      method: "GET"
+    }
+  );
+
+  assert.deepEqual(
+    buildEndpointReadRequestOptions({
+      method: "get",
+      transport: {
+        kind: "jsonapi-resource",
+        responseType: "user-settings",
+        responseKind: "record"
+      }
+    }),
+    {
+      method: "GET",
+      transport: {
+        kind: "jsonapi-resource",
+        responseType: "user-settings",
+        responseKind: "record"
+      }
+    }
+  );
+});
+
+test("endpoint write request options preserve body/options and append transport", () => {
+  assert.deepEqual(
+    buildEndpointWriteRequestOptions({
+      method: "patch",
+      body: {
+        theme: "dark"
+      },
+      options: {
+        headers: {
+          "x-demo": "1"
+        }
+      },
+      transport: {
+        kind: "jsonapi-resource",
+        requestType: "user-preferences",
+        responseType: "user-settings",
+        responseKind: "record"
+      }
+    }),
+    {
+      method: "PATCH",
+      headers: {
+        "x-demo": "1"
+      },
+      body: {
+        theme: "dark"
+      },
+      transport: {
+        kind: "jsonapi-resource",
+        requestType: "user-preferences",
+        responseType: "user-settings",
+        responseKind: "record"
+      }
+    }
+  );
+});
+
+test("list request options stay GET and carry transport when provided", () => {
+  assert.deepEqual(
+    buildListRequestOptions({
+      requestOptions: {
+        headers: {
+          "x-demo": "1"
+        }
+      },
+      pageParam: "cursor_2",
+      transport: {
+        kind: "jsonapi-resource",
+        responseType: "contacts",
+        responseKind: "collection"
+      }
+    }),
+    {
+      method: "GET",
+      headers: {
+        "x-demo": "1"
+      },
+      query: {
+        limit: 20,
+        cursor: "cursor_2"
+      },
+      transport: {
+        kind: "jsonapi-resource",
+        responseType: "contacts",
+        responseKind: "collection"
+      }
+    }
+  );
+});
+
+test("list request options preserve explicit limit values", () => {
+  assert.deepEqual(
+    buildListRequestOptions({
+      requestOptions: {
+        query: {
+          limit: 50
+        }
+      }
+    }),
+    {
+      method: "GET",
+      query: {
+        limit: 50
+      }
+    }
+  );
+
+  assert.deepEqual(
+    buildListRequestOptions({
+      requestOptions: {
+        query: {
+          "page[limit]": "75"
+        }
+      }
+    }),
+    {
+      method: "GET",
+      query: {
+        "page[limit]": "75"
+      }
+    }
+  );
+});
+
+test("operation realtime options use fallback events unless explicitly overridden", () => {
+  const fallbackRealtime = {
+    events: ["contacts.record.changed"]
+  };
+
+  assert.deepEqual(
+    resolveOperationRealtimeOptions({
+      fallbackRealtime
+    }),
+    {
+      events: ["contacts.record.changed"]
+    }
+  );
+
+  assert.deepEqual(
+    resolveOperationRealtimeOptions({
+      realtime: {
+        enabled: false
+      },
+      fallbackRealtime
+    }),
+    {
+      events: ["contacts.record.changed"],
+      enabled: false
+    }
+  );
+
+  assert.deepEqual(
+    resolveOperationRealtimeOptions({
+      realtime: {
+        event: "contacts.custom.changed"
+      },
+      fallbackRealtime
+    }),
+    {
+      event: "contacts.custom.changed"
+    }
+  );
+
+  assert.equal(
+    resolveOperationRealtimeOptions({
+      realtime: false,
+      fallbackRealtime
+    }),
+    null
+  );
+});
+
+test("endpoint resources invalidate their query key from configured realtime events", async () => {
+  const queryClient = new QueryClient();
+  const invalidations = [];
+  const socketHandlers = new Map();
+  const socket = {
+    on(eventName, handler) {
+      socketHandlers.set(eventName, handler);
+    },
+    off(eventName, handler) {
+      if (socketHandlers.get(eventName) === handler) {
+        socketHandlers.delete(eventName);
+      }
+    }
+  };
+  queryClient.invalidateQueries = async (options = {}) => {
+    invalidations.push(options);
+  };
+  const app = createSSRApp({
+    setup() {
+      useEndpointResource({
+        queryKey: ["today-workout-detail", "/api/today/workouts/2026-05-06"],
+        path: "/api/today/workouts/2026-05-06",
+        client: {
+          async request() {
+            return {};
+          }
+        },
+        realtime: {
+          event: "workout_set_logs.record.changed"
+        }
+      });
+      return () => h("div");
+    }
+  });
+  app.use(VueQueryPlugin, {
+    queryClient
+  });
+  app.provide("jskit.realtime.runtime.client.socket", socket);
+  await renderToString(app);
+
+  const handler = socketHandlers.get("workout_set_logs.record.changed");
+  assert.equal(typeof handler, "function");
+  handler({
+    entityId: "42"
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.deepEqual(invalidations, [
+    {
+      queryKey: ["today-workout-detail", "/api/today/workouts/2026-05-06"]
+    }
+  ]);
+});
+
+test("endpoint resource reads attach request recovery metadata to query options", async () => {
+  const queryClient = new QueryClient();
+  const queryKey = ["project-access", "beepollen"];
+  const app = createSSRApp({
+    setup() {
+      useEndpointResource({
+        queryKey,
+        path: "/api/project-access",
+        client: {
+          async request() {
+            return {};
+          }
+        },
+        requestRecovery: {
+          label: "Project access",
+          source: "project-access.panel",
+          dedupeKey: "project-access"
+        }
+      });
+      return () => h("div");
+    }
+  });
+  app.use(VueQueryPlugin, {
+    queryClient
+  });
+  await renderToString(app);
+
+  const query = queryClient.getQueryCache().find({
+    queryKey
+  });
+  assert.deepEqual(query?.meta?.jskit, {
+    requestRecoveryLabel: "Project access",
+    requestRecoverySource: "project-access.panel",
+    requestRecoveryDedupeKey: "project-access",
+    requestRecoveryMethod: "GET"
+  });
+});
+
+test("endpoint resources use the configured http-web HTTP client by default", async () => {
+  const queryClient = new QueryClient();
+  const calls = [];
+  let resource = null;
+  configureHttpWebClient({
+    csrf: {
+      enabled: false
+    },
+    resolveRequestUrl(url) {
+      return url.replace(/^\/api\//u, "/api/app/beepollen/");
+    },
+    fetchImpl: async (url, options) => {
+      calls.push([url, options]);
+      return {
+        ok: true,
+        status: 200,
+        headers: {
+          get(name) {
+            return String(name || "").toLowerCase() === "content-type"
+              ? "application/json; charset=utf-8"
+              : "";
+          }
+        },
+        async json() {
+          return {
+            ok: true
+          };
+        }
+      };
+    }
+  });
+
+  try {
+    const app = createSSRApp({
+      setup() {
+        resource = useEndpointResource({
+          queryKey: ["vibe64-sessions"],
+          path: "/api/vibe64/sessions"
+        });
+        return () => h("div");
+      }
+    });
+    app.use(VueQueryPlugin, {
+      queryClient
+    });
+    await renderToString(app);
+
+    await resource.reload();
+
+    assert.equal(calls.at(-1)?.[0], "/api/app/beepollen/vibe64/sessions");
+  } finally {
+    resetHttpWebClientForTests();
+  }
+});
+
+test("commands use the configured http-web HTTP client by default", async () => {
+  const queryClient = new QueryClient();
+  const calls = [];
+  let command = null;
+  configureHttpWebClient({
+    csrf: {
+      enabled: false
+    },
+    resolveRequestUrl(url) {
+      return url.replace(/^\/api\//u, "/api/app/beepollen/");
+    },
+    fetchImpl: async (url, options) => {
+      calls.push([url, options]);
+      return {
+        ok: true,
+        status: 200,
+        headers: {
+          get(name) {
+            return String(name || "").toLowerCase() === "content-type"
+              ? "application/json; charset=utf-8"
+              : "";
+          }
+        },
+        async json() {
+          return {
+            ok: true
+          };
+        }
+      };
+    }
+  });
+
+  try {
+    const app = createSSRApp({
+      setup() {
+        command = useCommand({
+          access: "always",
+          apiSuffix: "/vibe64/sessions"
+        });
+        return () => h("div");
+      }
+    });
+    app.use(VueQueryPlugin, {
+      queryClient
+    });
+    await renderToString(app);
+
+    await command.run();
+
+    assert.equal(calls.at(-1)?.[0], "/api/app/beepollen/vibe64/sessions");
+    assert.equal(calls.at(-1)?.[1]?.method, "POST");
+  } finally {
+    resetHttpWebClientForTests();
+  }
+});
+
+test("commands use public CRUD resource access without a CSRF session preflight", async () => {
+  const queryClient = new QueryClient();
+  const calls = [];
+  let command = null;
+  configureHttpWebClient({
+    fetchImpl: async (url, options) => {
+      calls.push([url, options]);
+      return {
+        ok: true,
+        status: 204,
+        headers: {
+          get() {
+            return "";
+          }
+        },
+        async json() {
+          return {};
+        }
+      };
+    }
+  });
+
+  try {
+    const app = createSSRApp({
+      setup() {
+        command = useCommand({
+          access: "always",
+          apiSuffix: "/books/1",
+          writeMethod: "DELETE",
+          resource: {
+            apiAccess: "public"
+          }
+        });
+        return () => h("div");
+      }
+    });
+    app.use(VueQueryPlugin, {
+      queryClient
+    });
+    await renderToString(app);
+
+    await command.run();
+
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0][0], "/api/books/1");
+    assert.equal(calls[0][1].method, "DELETE");
+    assert.equal(Object.hasOwn(calls[0][1], "csrf"), false);
+  } finally {
+    resetHttpWebClientForTests();
+  }
+});

package/test/resourceLoadStateHelpers.test.js

@@ -0,0 +1,189 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ref } from "vue";
+import {
+  buildRequestRecoveryMeta,
+  hasResolvedQueryData,
+  mergeQueryMeta,
+  mergeRequestRecoveryQueryMeta
+} from "../src/client/composables/support/resourceLoadStateHelpers.js";
+
+test("hasResolvedQueryData returns true when the query succeeded", () => {
+  const query = {
+    isSuccess: ref(true)
+  };
+
+  assert.equal(hasResolvedQueryData({
+    query,
+    data: ref(null)
+  }), true);
+});
+
+test("hasResolvedQueryData returns true when data payload is available", () => {
+  const query = {
+    isSuccess: ref(false)
+  };
+
+  assert.equal(hasResolvedQueryData({
+    query,
+    data: ref({
+      id: 2971
+    })
+  }), true);
+});
+
+test("hasResolvedQueryData returns false when query and payload are unresolved", () => {
+  const query = {
+    isSuccess: ref(false)
+  };
+
+  assert.equal(hasResolvedQueryData({
+    query,
+    data: ref(null)
+  }), false);
+});
+
+test("mergeQueryMeta preserves caller metadata while adding JSKIT refresh policy", () => {
+  assert.deepEqual(
+    mergeQueryMeta(
+      {
+        staleTime: 1000,
+        meta: {
+          owner: "contacts",
+          jskit: {
+            feature: "list"
+          }
+        }
+      },
+      {
+        jskit: {
+          refreshOnPull: true
+        }
+      }
+    ),
+    {
+      staleTime: 1000,
+      meta: {
+        owner: "contacts",
+        jskit: {
+          feature: "list",
+          refreshOnPull: true
+        }
+      }
+    }
+  );
+});
+
+test("request recovery query metadata supports labels and disabling recovery", () => {
+  assert.deepEqual(
+    buildRequestRecoveryMeta("Project access"),
+    {
+      jskit: {
+        requestRecoveryLabel: "Project access"
+      }
+    }
+  );
+
+  assert.deepEqual(
+    buildRequestRecoveryMeta(false),
+    {
+      jskit: {
+        requestRecovery: false
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta preserves caller metadata while adding recovery hints", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        staleTime: 5000,
+        meta: {
+          owner: "project-access",
+          jskit: {
+            refreshOnPull: true
+          }
+        }
+      },
+      {
+        label: "Project access",
+        source: "app.project-access",
+        dedupeKey: "project-access",
+        method: "get",
+        dedupeWindowMs: 100
+      }
+    ),
+    {
+      staleTime: 5000,
+      meta: {
+        owner: "project-access",
+        jskit: {
+          refreshOnPull: true,
+          requestRecoveryLabel: "Project access",
+          requestRecoverySource: "app.project-access",
+          requestRecoveryDedupeKey: "project-access",
+          requestRecoveryMethod: "GET",
+          requestRecoveryDedupeWindowMs: 100
+        }
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta does not overwrite explicit query recovery labels with defaults", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        meta: {
+          jskit: {
+            requestRecoveryLabel: "Explicit label",
+            requestRecoveryMethod: "HEAD",
+            requestRecoveryDedupeWindowMs: 0
+          }
+        }
+      },
+      null,
+      {
+        label: "Default label",
+        method: "GET",
+        dedupeWindowMs: 5000
+      }
+    ),
+    {
+      meta: {
+        jskit: {
+          requestRecoveryLabel: "Explicit label",
+          requestRecoveryMethod: "HEAD",
+          requestRecoveryDedupeWindowMs: 0
+        }
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta preserves disabled recovery metadata", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        meta: {
+          jskit: {
+            requestRecovery: false
+          }
+        }
+      },
+      null,
+      {
+        label: "Default label",
+        method: "GET"
+      }
+    ),
+    {
+      meta: {
+        jskit: {
+          requestRecovery: false
+        }
+      }
+    }
+  );
+});

package/test/routeTemplateHelpers.test.js

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  extractRouteParamNames,
+  resolveScopedRoutePathname,
+  resolveRouteParamNamesInOrder
+} from "../src/client/composables/support/routeTemplateHelpers.js";
+
+test("extractRouteParamNames reads dynamic params from route templates", () => {
+  assert.deepEqual(
+    extractRouteParamNames("/w/:workspaceSlug/admin/contacts/:contactId/addresses/:addressId"),
+    ["workspaceSlug", "contactId", "addressId"]
+  );
+});
+
+test("resolveRouteParamNamesInOrder prefers matched route templates", () => {
+  const route = {
+    matched: [
+      { path: "/w/:workspaceSlug/admin" },
+      { path: "/contacts/:contactId/addresses/:addressId" }
+    ],
+    params: {
+      workspaceSlug: "acme",
+      contactId: "7",
+      addressId: "42"
+    }
+  };
+
+  assert.deepEqual(resolveRouteParamNamesInOrder(route), ["workspaceSlug", "contactId", "addressId"]);
+});
+
+test("resolveScopedRoutePathname supports at/before/after anchors", () => {
+  const currentPathname = "/w/dogandgroom/admin/contacts/541841/pets/715528/edit/advanced";
+  const params = {
+    workspaceSlug: "dogandgroom",
+    contactId: "541841",
+    petId: "715528"
+  };
+  const orderedParamNames = ["workspaceSlug", "contactId", "petId"];
+
+  assert.equal(
+    resolveScopedRoutePathname({
+      currentPathname,
+      params,
+      orderedParamNames,
+      anchorParamName: "contactId",
+      anchorMode: "at"
+    }),
+    "/w/dogandgroom/admin/contacts/541841"
+  );
+  assert.equal(
+    resolveScopedRoutePathname({
+      currentPathname,
+      params,
+      orderedParamNames,
+      anchorParamName: "petId",
+      anchorMode: "before"
+    }),
+    "/w/dogandgroom/admin/contacts/541841/pets"
+  );
+  assert.equal(
+    resolveScopedRoutePathname({
+      currentPathname,
+      params,
+      orderedParamNames,
+      anchorParamName: "petId",
+      anchorMode: "after"
+    }),
+    "/w/dogandgroom/admin/contacts/541841/pets/715528/edit"
+  );
+});
+
+test("resolveScopedRoutePathname falls back to direct value matching", () => {
+  assert.equal(
+    resolveScopedRoutePathname({
+      currentPathname: "/contacts/abc%20123/notes",
+      params: {},
+      orderedParamNames: [],
+      anchorParamName: "contactId",
+      anchorParamValue: "abc 123",
+      anchorMode: "at"
+    }),
+    "/contacts/abc%20123"
+  );
+});