@vibeflui/react-query 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeFlui contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @vibeflui/react-query
+
+Optional TanStack Query-compatible provider plugin for VibeFlui / FluiKit.
+
+This package does not make TanStack Query mandatory in `@vibeflui/core`. It accepts a QueryClient-like object and registers a FluiKit provider.
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import { FluiKit, FluiKitProvider } from "@vibeflui/core"
+import { createReactQueryPlugin } from "@vibeflui/react-query"
+
+const queryClient = new QueryClient()
+const reactQueryPlugin = createReactQueryPlugin({ queryClient })
+
+export function UsersPage() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <FluiKitProvider plugins={[reactQueryPlugin]}>
+        <FluiKit schema={usersSchema} />
+      </FluiKitProvider>
+    </QueryClientProvider>
+  )
+}
+```
+
+Use the registered provider from schema:
+
+```ts
+export const usersSchema = {
+  resource: "users",
+  endpoint: "/api/users",
+  provider: {
+    type: "custom",
+    name: "reactQuery"
+  },
+  table: {
+    columns: ["name", "email", "role.name", "status"]
+  },
+  form: {
+    fields: ["name", "email"]
+  }
+}
+```
+
+Default query keys are `["fluikit", resource, operation, ...]`. Mutations invalidate `["fluikit", resource]` by default.

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import type { FluiKitActionExecutionContext, FluiKitDataProvider, FluiKitPlugin } from "@vibeflui/core";
+export type FluiKitQueryKey = readonly unknown[];
+export type FluiKitReactQueryOperation = "list" | "detail" | "create" | "update" | "delete" | "action" | string;
+export type FluiKitFetchQueryOptions = {
+    queryKey: FluiKitQueryKey;
+    queryFn: () => Promise<unknown>;
+    staleTime?: number;
+    gcTime?: number;
+    cacheTime?: number;
+    meta?: Record<string, unknown>;
+};
+export type FluiKitQueryFilters = {
+    queryKey?: FluiKitQueryKey;
+    exact?: boolean;
+    type?: "active" | "inactive" | "all";
+    predicate?: (query: unknown) => boolean;
+    [key: string]: unknown;
+};
+export type FluiKitReactQueryClient = {
+    fetchQuery?: (options: FluiKitFetchQueryOptions) => unknown | Promise<unknown>;
+    ensureQueryData?: (options: FluiKitFetchQueryOptions) => unknown | Promise<unknown>;
+    getQueryData?: (queryKey: FluiKitQueryKey) => unknown;
+    setQueryData?: (queryKey: FluiKitQueryKey, updater: unknown) => unknown;
+    invalidateQueries?: (filters?: FluiKitQueryFilters) => unknown | Promise<unknown>;
+    refetchQueries?: (filters?: FluiKitQueryFilters) => unknown | Promise<unknown>;
+};
+export type FluiKitReactQueryKeyResolver = (context: FluiKitActionExecutionContext, operation: FluiKitReactQueryOperation) => FluiKitQueryKey;
+export type CreateReactQueryPluginOptions = {
+    queryClient?: FluiKitReactQueryClient;
+    providerName?: string;
+    baseProvider?: FluiKitDataProvider;
+    queryKey?: FluiKitReactQueryKeyResolver;
+    invalidateKey?: FluiKitReactQueryKeyResolver;
+    invalidateOnMutation?: boolean;
+    refetchOnMutation?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+    cacheTime?: number;
+    pluginName?: string;
+    version?: string;
+};
+export declare function createReactQueryPlugin(options?: CreateReactQueryPluginOptions): FluiKitPlugin;
+export declare function createReactQueryProvider(options?: CreateReactQueryPluginOptions): FluiKitDataProvider;
+export declare function defaultReactQueryKey(context: FluiKitActionExecutionContext, operation: FluiKitReactQueryOperation): FluiKitQueryKey;
+export declare function defaultReactQueryInvalidationKey(context: FluiKitActionExecutionContext): FluiKitQueryKey;
+export declare const ReactQueryPlugin: typeof createReactQueryPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,109 @@
+import { createEndpointProvider, createFluiKitPlugin } from "@vibeflui/core";
+export function createReactQueryPlugin(options = {}) {
+    const providerName = options.providerName ?? "reactQuery";
+    return createFluiKitPlugin({
+        name: options.pluginName ?? "@vibeflui/react-query",
+        version: options.version ?? "1.0.0",
+        packageName: "@vibeflui/react-query",
+        description: "Optional TanStack Query-compatible provider plugin for FluiKit.",
+        compatibility: {
+            core: ">=1.0.0"
+        },
+        providers: {
+            [providerName]: createReactQueryProvider(options)
+        },
+        messages: {
+            loadError: "Unable to load data.",
+            submitError: "Unable to submit the form."
+        },
+        inspectorPanels: [
+            {
+                key: "react-query",
+                label: "React Query",
+                renderer: "ReactQueryInspectorPanel"
+            }
+        ]
+    });
+}
+export function createReactQueryProvider(options = {}) {
+    const baseProvider = options.baseProvider ?? createEndpointProvider();
+    return {
+        list: (context) => executeRead(context, "list", () => baseProvider.list?.(context) ?? baseProvider.action?.(context), options),
+        detail: (context) => executeRead(context, "detail", () => baseProvider.detail?.(context) ?? baseProvider.action?.(context), options),
+        create: (context) => executeMutation(context, "create", () => baseProvider.create?.(context) ?? baseProvider.action?.(context), options),
+        update: (context) => executeMutation(context, "update", () => baseProvider.update?.(context) ?? baseProvider.action?.(context), options),
+        delete: (context) => executeMutation(context, "delete", () => baseProvider.delete?.(context) ?? baseProvider.action?.(context), options),
+        action: (context) => executeMutation(context, context.operation, () => baseProvider.action?.(context), options)
+    };
+}
+export function defaultReactQueryKey(context, operation) {
+    const resource = context.schema.resource;
+    if (operation === "list") {
+        return ["fluikit", resource, "list", context.query ?? {}];
+    }
+    if (operation === "detail" || operation === "view") {
+        return ["fluikit", resource, "detail", context.params];
+    }
+    return ["fluikit", resource, operation, context.params];
+}
+export function defaultReactQueryInvalidationKey(context) {
+    return ["fluikit", context.schema.resource];
+}
+export const ReactQueryPlugin = createReactQueryPlugin;
+async function executeRead(context, operation, run, options) {
+    const queryClient = options.queryClient;
+    const queryKey = resolveQueryKey(context, operation, options.queryKey);
+    const queryFn = async () => run();
+    if (queryClient?.ensureQueryData) {
+        return queryClient.ensureQueryData({
+            queryKey,
+            queryFn,
+            staleTime: options.staleTime,
+            gcTime: options.gcTime,
+            cacheTime: options.cacheTime,
+            meta: queryMeta(context, operation)
+        });
+    }
+    if (queryClient?.fetchQuery) {
+        return queryClient.fetchQuery({
+            queryKey,
+            queryFn,
+            staleTime: options.staleTime,
+            gcTime: options.gcTime,
+            cacheTime: options.cacheTime,
+            meta: queryMeta(context, operation)
+        });
+    }
+    return queryFn();
+}
+async function executeMutation(context, operation, run, options) {
+    const data = await run();
+    if (options.invalidateOnMutation !== false) {
+        await invalidateReactQuery(context, operation, options);
+    }
+    return data;
+}
+async function invalidateReactQuery(context, operation, options) {
+    const queryClient = options.queryClient;
+    if (!queryClient)
+        return;
+    const filters = {
+        queryKey: resolveQueryKey(context, operation, options.invalidateKey ?? defaultReactQueryInvalidationKey)
+    };
+    if (queryClient.invalidateQueries) {
+        await queryClient.invalidateQueries(filters);
+    }
+    if (options.refetchOnMutation && queryClient.refetchQueries) {
+        await queryClient.refetchQueries(filters);
+    }
+}
+function resolveQueryKey(context, operation, resolver) {
+    return resolver?.(context, operation) ?? defaultReactQueryKey(context, operation);
+}
+function queryMeta(context, operation) {
+    return {
+        resource: context.schema.resource,
+        operation,
+        endpoint: context.endpoint
+    };
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@vibeflui/react-query",
+  "version": "1.0.0",
+  "description": "Optional TanStack Query-compatible provider plugin for VibeFlui / FluiKit.",
+  "license": "MIT",
+  "author": {
+    "name": "heloconia",
+    "url": "https://github.com/heloconia"
+  },
+  "homepage": "https://github.com/heloconia/vibeflui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heloconia/vibeflui.git",
+    "directory": "packages/react-query"
+  },
+  "bugs": {
+    "url": "https://github.com/heloconia/vibeflui/issues"
+  },
+  "funding": [
+    { "type": "ko-fi", "url": "https://ko-fi.com/heloconia" },
+    { "type": "trakteer", "url": "https://trakteer.id/heloconia" },
+    { "type": "saweria", "url": "https://saweria.co/heloconia" }
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "test -f ../core/dist/index.d.ts || npm --prefix ../core run build && npm run build",
+    "typecheck": "tsc -p tsconfig.local.json --noEmit"
+  },
+  "keywords": [
+    "vibeflui",
+    "fluikit",
+    "form generator",
+    "table list generator",
+    "ui generator",
+    "json to ui",
+    "react-query",
+    "tanstack-query",
+    "schema-driven"
+  ],
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "@vibeflui/core": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  }
+}