feat: implement tanstack-query generator plugin (#413)

Author: ymc9

packages/plugins/tanstack-query/.eslintrc.json

@@ -0,0 +1,14 @@
+{
+    "root": true,
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": 6,
+        "sourceType": "module"
+    },
+    "plugins": ["@typescript-eslint"],
+    "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/eslint-recommended",
+        "plugin:@typescript-eslint/recommended"
+    ]
+}

packages/plugins/tanstack-query/LICENSE

@@ -0,0 +1 @@
+../../../LICENSE

packages/plugins/tanstack-query/README.md

@@ -0,0 +1,5 @@
+# ZenStack tanstack-query plugin & runtime
+
+This package contains ZenStack plugin for generating [tanstack-query](https://tanstack.com/query/latest) hooks.
+
+Visit [Homepage](https://zenstack.dev) for more details.

packages/plugins/tanstack-query/jest.config.ts

@@ -0,0 +1,29 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+export default {
+    // Automatically clear mock calls, instances, contexts and results before every test
+    clearMocks: true,
+
+    // Indicates whether the coverage information should be collected while executing the test
+    collectCoverage: true,
+
+    // The directory where Jest should output its coverage files
+    coverageDirectory: 'tests/coverage',
+
+    // An array of regexp pattern strings used to skip coverage collection
+    coveragePathIgnorePatterns: ['/node_modules/', '/tests/'],
+
+    // Indicates which provider should be used to instrument code for coverage
+    coverageProvider: 'v8',
+
+    // A list of reporter names that Jest uses when writing coverage reports
+    coverageReporters: ['json', 'text', 'lcov', 'clover'],
+
+    // A map from regular expressions to paths to transformers
+    transform: { '^.+\\.tsx?$': 'ts-jest' },
+
+    testTimeout: 300000,
+};

packages/plugins/tanstack-query/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@zenstackhq/tanstack-query",
+    "displayName": "ZenStack plugin for generating tanstack-query hooks",
+    "version": "1.0.0-alpha.116",
+    "description": "ZenStack plugin for generating tanstack-query hooks",
+    "main": "index.js",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/zenstackhq/zenstack"
+    },
+    "scripts": {
+        "clean": "rimraf dist",
+        "build": "pnpm lint && pnpm clean && tsc && copyfiles ./package.json ./README.md ./LICENSE 'res/**/*' dist",
+        "watch": "tsc --watch",
+        "lint": "eslint src --ext ts",
+        "prepublishOnly": "pnpm build",
+        "publish-dev": "pnpm publish --tag dev"
+    },
+    "publishConfig": {
+        "directory": "dist",
+        "linkDirectory": true
+    },
+    "keywords": [],
+    "author": "ZenStack Team",
+    "license": "MIT",
+    "dependencies": {
+        "@prisma/generator-helper": "^4.7.1",
+        "@zenstackhq/sdk": "workspace:*",
+        "change-case": "^4.1.2",
+        "decimal.js": "^10.4.2",
+        "lower-case-first": "^2.0.2",
+        "superjson": "^1.11.0",
+        "ts-morph": "^16.0.0",
+        "upper-case-first": "^2.0.2"
+    },
+    "devDependencies": {
+        "@tanstack/react-query": "^4.29.7",
+        "@tanstack/svelte-query": "^4.29.7",
+        "@types/jest": "^29.5.0",
+        "@types/lower-case-first": "^1.0.1",
+        "@types/react": "^18.0.26",
+        "@types/tmp": "^0.2.3",
+        "@types/upper-case-first": "^1.1.2",
+        "@zenstackhq/testtools": "workspace:*",
+        "copyfiles": "^2.4.1",
+        "jest": "^29.5.0",
+        "react": "^17.0.2 || ^18",
+        "react-dom": "^17.0.2 || ^18",
+        "rimraf": "^3.0.2",
+        "swr": "^2.0.3",
+        "ts-jest": "^29.0.5",
+        "typescript": "^4.9.4"
+    }
+}

packages/plugins/tanstack-query/res/react/helper.ts

@@ -0,0 +1,148 @@
+/* eslint-disable */
+
+import {
+    useMutation,
+    useQuery,
+    useQueryClient,
+    type MutateFunction,
+    type QueryClient,
+    type UseMutationOptions,
+    type UseQueryOptions,
+} from '@tanstack/react-query';
+import { createContext } from 'react';
+
+/**
+ * Context for configuring react hooks.
+ */
+export const RequestHandlerContext = createContext<RequestHandlerContext>({
+    endpoint: DEFAULT_QUERY_ENDPOINT,
+});
+
+/**
+ * Context provider.
+ */
+export const Provider = RequestHandlerContext.Provider;
+
+/**
+ * Creates a react-query query.
+ *
+ * @param model The name of the model under query.
+ * @param url The request URL.
+ * @param args The request args object, which will be superjson-stringified and appended as "?q=" parameter
+ * @param options The react-query options object
+ * @returns useQuery hook
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function query<R>(model: string, url: string, args?: unknown, options?: UseQueryOptions<R>) {
+    const reqUrl = makeUrl(url, args);
+    return useQuery<R>({
+        queryKey: [QUERY_KEY_PREFIX + model, url, args],
+        queryFn: () => fetcher<R>(reqUrl),
+        ...options,
+    });
+}
+
+/**
+ * Creates a POST mutation with react-query.
+ *
+ * @param model The name of the model under mutation.
+ * @param url The request URL.
+ * @param options The react-query options.
+ * @param invalidateQueries Whether to invalidate queries after mutation.
+ * @returns useMutation hooks
+ */
+export function postMutation<T, R = any>(
+    model: string,
+    url: string,
+    options?: Omit<UseMutationOptions<R, unknown, T>, 'mutationFn'>,
+    invalidateQueries = true
+) {
+    const queryClient = useQueryClient();
+    const mutationFn = (data: any) =>
+        fetcher<R>(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body: marshal(data),
+        });
+
+    const finalOptions = mergeOptions<T, R>(model, options, invalidateQueries, mutationFn, queryClient);
+    const mutation = useMutation<R, unknown, T>(finalOptions);
+    return mutation;
+}
+
+/**
+ * Creates a PUT mutation with react-query.
+ *
+ * @param model The name of the model under mutation.
+ * @param url The request URL.
+ * @param options The react-query options.
+ * @param invalidateQueries Whether to invalidate queries after mutation.
+ * @returns useMutation hooks
+ */
+export function putMutation<T, R = any>(
+    model: string,
+    url: string,
+    options?: Omit<UseMutationOptions<R, unknown, T>, 'mutationFn'>,
+    invalidateQueries = true
+) {
+    const queryClient = useQueryClient();
+    const mutationFn = (data: any) =>
+        fetcher<R>(url, {
+            method: 'PUT',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body: marshal(data),
+        });
+
+    const finalOptions = mergeOptions<T, R>(model, options, invalidateQueries, mutationFn, queryClient);
+    const mutation = useMutation<R, unknown, T>(finalOptions);
+    return mutation;
+}
+
+/**
+ * Creates a DELETE mutation with react-query.
+ *
+ * @param model The name of the model under mutation.
+ * @param url The request URL.
+ * @param options The react-query options.
+ * @param invalidateQueries Whether to invalidate queries after mutation.
+ * @returns useMutation hooks
+ */
+export function deleteMutation<T, R = any>(
+    model: string,
+    url: string,
+    options?: Omit<UseMutationOptions<R, unknown, T>, 'mutationFn'>,
+    invalidateQueries = true
+) {
+    const queryClient = useQueryClient();
+    const mutationFn = (data: any) =>
+        fetcher<R>(makeUrl(url, data), {
+            method: 'DELETE',
+        });
+
+    const finalOptions = mergeOptions<T, R>(model, options, invalidateQueries, mutationFn, queryClient);
+    const mutation = useMutation<R, unknown, T>(finalOptions);
+    return mutation;
+}
+
+function mergeOptions<T, R = any>(
+    model: string,
+    options: Omit<UseMutationOptions<R, unknown, T, unknown>, 'mutationFn'> | undefined,
+    invalidateQueries: boolean,
+    mutationFn: MutateFunction<R, unknown, T>,
+    queryClient: QueryClient
+): UseMutationOptions<R, unknown, T, unknown> {
+    const result = { ...options, mutationFn };
+    if (options?.onSuccess || invalidateQueries) {
+        result.onSuccess = (...args) => {
+            if (invalidateQueries) {
+                queryClient.invalidateQueries([QUERY_KEY_PREFIX + model]);
+            }
+            return options?.onSuccess?.(...args);
+        };
+    }
+    return result;
+}

packages/plugins/tanstack-query/res/shared.ts

@@ -0,0 +1,54 @@
+import superjson from 'superjson';
+
+/**
+ * The default query endpoint.
+ */
+export const DEFAULT_QUERY_ENDPOINT = '/api/model';
+
+/**
+ * Prefix for react-query keys.
+ */
+export const QUERY_KEY_PREFIX = 'zenstack:';
+
+/**
+ * Context type for configuring the hooks.
+ */
+export type RequestHandlerContext = {
+    endpoint: string;
+};
+
+/**
+ * Builds a request URL with optional args.
+ */
+export function makeUrl(url: string, args: unknown) {
+    return args ? url + `?q=${encodeURIComponent(marshal(args))}` : url;
+}
+
+async function fetcher<R>(url: string, options?: RequestInit) {
+    const res = await fetch(url, options);
+    if (!res.ok) {
+        const error: Error & { info?: unknown; status?: number } = new Error(
+            'An error occurred while fetching the data.'
+        );
+        error.info = unmarshal(await res.text());
+        error.status = res.status;
+        throw error;
+    }
+
+    const textResult = await res.text();
+    try {
+        return unmarshal(textResult) as R;
+    } catch (err) {
+        console.error(`Unable to deserialize data:`, textResult);
+        throw err;
+    }
+}
+
+export function marshal(value: unknown) {
+    return superjson.stringify(value);
+}
+
+export function unmarshal(value: string) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return superjson.parse<any>(value);
+}