@zachacious/protoc-gen-connect-vue 1.0.5 → 1.0.7

package/README.md

@@ -1,210 +1,175 @@
-# **@zachacious/protoc-gen-connect-vue**
+# **protoc-gen-connect-vue**
 
-A specialized protoc plugin designed to generate a production-grade, reactive TypeScript SDK for **Vue.js**. This plugin serves as an intelligent orchestration layer on top of [ConnectRPC](https://connectrpc.com/) and [TanStack Vue Query](https://tanstack.com/query/latest), automating the tedious aspects of state management, cache synchronization, and pagination.
+protoc-gen-connect-vue is a code generation plugin for [ConnectRPC](https://connectrpc.com/) tailored specifically for Vue.js. It generates a type-safe SDK that combines the power of ConnectRPC with the reactivity of the Vue Composition API and the caching capabilities of TanStack Query (Vue).
 
-## **🏗 Context & Architecture**
+Unlike the official @connectrpc/connect-query which is architected for React, this plugin is built from the ground up for Vue developers, providing first-class support for ref, computed, and manual resource invalidation.
 
-This project is not a replacement for standard tooling but an enhancement of it. It leverages the official [connect-query-es](https://github.com/connectrpc/connect-query-es) plugin to generate underlying query definitions and wraps them in a high-level SDK tailored for Vue 3.
+> Note: this would made for personal and internal projects. If you find it useful, let me know.
 
-### **Core Pillars**
+## **Features**
 
-1. **Reactivity:** Deep integration with Vue's Composition API.
-2. **Smart Invalidation:** Heuristic-based cache clearing. When a mutation (e.g., CreateTicket) succeeds, the SDK automatically invalidates related queries (e.g., ListTickets).
-3. **Deep Pagination Search:** Recursively scans Protobuf messages for pagination fields to automatically switch from standard useQuery to useInfiniteQuery.
-4. **Transport Decoupling:** Global interceptors for Auth and Error handling so your components stay clean.
+- **Reactive Client:** Automatically re-initializes the transport when your base URL or auth tokens change.
+- **TanStack Query Integration:** Generates useQuery, useMutation, and useInfiniteQuery hooks for every RPC.
+- **Manual Wrappers:** Provides standard async wrappers for actions that don't fit the "query" pattern.
+- **Message Initializers:** A createEmpty utility to generate default objects for any Protobuf message type.
+- **Query Key Factory:** Centralized query keys to simplify manual cache invalidation.
 
----
-
-## **🚀 Installation**
-
-### **1. Plugin Installation**
-
-You can install the plugin globally or as a dev dependency.
+## **Installation**
 
-```
-# Recommended for local development
-npm install --save-dev @zachacious/protoc-gen-connect-vue
+```bash
+# install plugin either globally or locally
 
-# For use across non-Node projects (Go/Rust/etc)
 npm install -g @zachacious/protoc-gen-connect-vue
 ```
 
-### **2. Peer Dependencies**
-
-The generated SDK requires these specific packages to be installed in your Vue project:
+```Bash
+# install dependencies
 
-```
-npm install @connectrpc/connect @connectrpc/connect-web @connectrpc/connect-query @tanstack/vue-query @bufbuild/protobuf
+npm install protoc-gen-connect-vue @tanstack/vue-query @connectrpc/connect @connectrpc/connect-web @bufbuild/protobuf
 ```
 
----
+## **Generation**
 
-## **⚙️ Configuration**
+Add the plugin to your buf.gen.yaml:
 
-### **buf.gen.yaml**
-
-The plugin **must** run after protoc-gen-es and protoc-gen-connect-query.
-
-```yaml
-version: v2
-managed:
- enabled: true
+```YAML
 plugins:
- # 1. Base Protobuf TS messages
- - local: es
- out: gen
- opt: target=ts
- # 2. ConnectRPC Query definitions
- - local: connect-query
- out: gen
- opt: target=ts
- # 3. Smart SDK Generator
- - local: protoc-gen-connect-vue
- out: src/api
+# ...
+  - remote: buf.build/bufbuild/es
+    out: web/src/api/gen
+    opt:
+      - target=ts
+
+  # Make sure this plugin goes after protoc-gen-es
+  # It should probably go last
+
+  # npm install -g @zachacious/protoc-gen-connect-vue
+  # https://www.npmjs.com/package/@zachacious/protoc-gen-connect-vue
+  - local: protoc-gen-connect-vue
+    out: web/src/api
+    opt: target=ts
 ```
 
----
-
-**🛠 Integration & Setup**
+## **Setup**
 
-### **1. Global Client Configuration (main.ts)**
+### **1. Configure the Provider**
 
-Configure your environment-specific settings before mounting the app.
+In your main.ts, provide the QueryClient to your Vue application.
 
 ```TypeScript
 
 import { createApp } from 'vue';
-import { VueQueryPlugin } from '@tanstack/vue-query';
-import { setBaseUrl, setAuthResolver, setSDKErrorCallback, globalQueryConfig } from '@/api';
-import { useAuthStore } from '@/stores/auth';
+import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query';
+import { globalQueryConfig } from './api/generated/client';
+import App from './App.vue';
 
 const app = createApp(App);
+const queryClient = new QueryClient(globalQueryConfig);
 
-// 1. Initialize TanStack with SDK defaults (StaleTime, GC, etc.)
-app.use(VueQueryPlugin, { queryClientConfig: globalQueryConfig });
-
-// 2. Configure Endpoint
-setBaseUrl(import.meta.env.VITE_API_URL);
+app.use(VueQueryPlugin, { queryClient });
+app.mount('#app');
+```
 
-// 3. Setup Auth Bridge (Decoupled from SDK logic)
-const auth = useAuthStore();
-setAuthResolver(async () => {
- return auth.token; // Header 'x-api-key' added if exists
-});
+### **2. Runtime Configuration**
 
-// 4. Global Error Handling
-setSDKErrorCallback((err, url) => {
- if (err.code === 16) { // Unauthenticated
- auth.logout();
- window.location.href = '/login';
- }
-});
+Set up your authentication and base URL, typically in an identity store or main entry point.
 
-app.mount('#app');
-```
+```TypeScript
 
-### **2. Transport Provider Setup (App.vue)**
+import { setBaseUrl, setAuthResolver, setSDKErrorCallback } from '@/api/generated';
 
-You must wrap your application (or relevant route views) in the TransportProvider to provide the ConnectRPC context to the hooks.
+setBaseUrl('https://api.example.com');
 
-```html
-<script setup lang="ts">
-  import { TransportProvider } from "@connectrpc/connect-query";
-  import { transport } from "@/api/client";
-</script>
+// Supports async token resolution
+setAuthResolver(async () => {
+ const token = localStorage.getItem('token');
+ return token ? token : null;
+});
 
-<template>
-  <TransportProvider :transport="transport">
-    <router-view />
-  </TransportProvider>
-</template>
+setSDKErrorCallback((err, url) => {
+ console.error(`API Error at ${url}: ${err.message}`);
+});
 ```
 
----
-
-## **📖 Usage Examples**
+## **Usage**
 
-### **Reactive Queries**
+### **Using Hooks and Manual Wrappers**
 
-Unary RPCs that don't start with mutation verbs are generated as standard queries.
+The generated SDK provides both automated hooks and manual async functions.
 
 ```html
 <script setup lang="ts">
-  import { useApi } from "@/api";
-  const api = useApi();
-
-  const { data, isLoading } = api.useGetCustomerById({ id: "123" });
+  import { ref } from "vue";
+  import { useApi } from "@/api/generated";
+
+  const { getUser, useGetUser } = useApi();
+
+  // 1. Reactive Hook (Auto-fetches)
+  const userId = ref("123");
+  const { data, isLoading, error } = useGetUser(userId);
+
+  // 2. Manual Action
+  const handleUpdate = async () => {
+    const { data, error } = await updateUser({ id: "123", name: "New Name" });
+    if (!error) {
+      // Note: The SDK automatically invalidates related queries on success
+      console.log("Update successful");
+    }
+  };
 </script>
 
 <template>
   <div v-if="isLoading">Loading...</div>
-  <div v-else>{{ data.name }}</div>
+  <div v-else-if="error">{{ error }}</div>
+  <div v-else>
+    <h1>{{ data?.name }}</h1>
+    <button @click="handleUpdate">Update Profile</button>
+  </div>
 </template>
 ```
 
-### **Automated Mutations & Invalidation**
-
-The SDK uses resource-name stripping (e.g., UpdateTicket -> Ticket) to invalidate active lists automatically.
+### **Initializing New Data (createEmpty)**
 
-```html
-<script setup lang="ts">
-  const { mutate, isPending } = api.useUpdateTicket({
-    onSuccess: () => console.log("List refreshed by SDK!"),
-  });
+Protobuf messages often require specific default values (e.g., empty strings instead of undefined). The createEmpty utility ensures your local state matches the expected Protobuf structure.
 
-  const save = () => mutate({ id: "123", status: "CLOSED" });
-</script>
-```
-
-### **Infinite Scrolling (Pagination)**
+```TypeScript
 
-If fields like page, offset, or limit are detected, the SDK generates an InfiniteQuery.
+import { useApi } from '@/api/generated';
 
-```html
-<script setup lang="ts">
-  const { data, fetchNextPage, hasNextPage } = api.useListTickets({
-    filter: "open",
-  });
-</script>
+const { createEmpty } = useApi();
 
-<template>
-  <div v-for="page in data?.pages">
-    <div v-for="ticket in page.items">{{ ticket.subject }}</div>
-  </div>
-  <button v-if="hasNextPage" @click="fetchNextPage">Load More</button>
-</template>
+// Create an empty Customer object with all Protobuf defaults
+// Useful when you need to create and empty instance instead of using a nullable object
+const newCustomer = ref(createEmpty.Customer({ name: "Initial Name" }));
 ```
 
----
+### **Manual Cache Invalidation (queryKeys)**
 
-## **🧪 Advanced Features**
+If you need to manually refresh or invalidate a specific query, use the queryKeys factory to ensure the key matches the one used by the generated hooks.
 
-### **Global Loading State**
+```TypeScript
 
-Track the status of _every_ RPC call in your application via a single computed property.
+import { useQueryClient } from '@tanstack/vue-query';
+import { queryKeys } from '@/api/generated';
 
-```html
-<script setup lang="ts">
-  const { isGlobalLoading } = useApi();
-</script>
+const queryClient = useQueryClient();
 
-<template>
-  <ProgressBar v-if="isGlobalLoading" />
-</template>
+const refreshUser = (id: string) => {
+ queryClient.invalidateQueries({
+ queryKey: queryKeys.getUser(id)
+ });
+};
 ```
 
-### **Protobuf Documentation Tags**
+## **Global Loading State**
 
-Fine-tune your SDK directly from your .proto comments:
+The SDK exports a reactive isGlobalLoading computed property that tracks if any RPC (query or mutation) is currently in flight.
 
-| Tag                  | Description                                                      |
-| :------------------- | :--------------------------------------------------------------- |
-| @wrapper:auth        | Marks the endpoint as expecting authentication in documentation. |
-| @sdk:signature=(...) | Overrides the generated TypeScript function signature.           |
-| @sdk:data=res.item   | Overrides the default data extractor for async wrappers.         |
+```TypeScript
 
----
+const { isGlobalLoading } = useApi();
+```
 
-**📝 License**
+---
 
-MIT © [Zachacious](https://www.google.com/search?q=https://github.com/zachacious)
+License MIT

package/dist/generator.js

@@ -336845,14 +336845,28 @@ function processType(typeDesc, serviceFile, wktImports, localImports, externalIm
   externalImports.get(importPath).add(baseName);
   return baseName;
 }
+function collectAllMessages(message, serviceFile, wktImports, localImports, externalImports, seen = new Set) {
+  if (seen.has(message.typeName))
+    return;
+  seen.add(message.typeName);
+  processType(message, serviceFile, wktImports, localImports, externalImports);
+  for (const field of message.fields) {
+    if (field.fieldKind === "message") {
+      collectAllMessages(field.message, serviceFile, wktImports, localImports, externalImports, seen);
+    }
+  }
+}
 function processService(service, protoPbFile, connectQueryFile) {
   const rpcs = [];
   const wktImports = new Set;
   const localImports = new Set;
   const externalImports = new Map;
+  const allSeenMessages = new Set;
   for (const method of service.methods) {
-    const inputBaseName = processType(method.input, service.file, wktImports, localImports, externalImports);
-    const outputBaseName = processType(method.output, service.file, wktImports, localImports, externalImports);
+    collectAllMessages(method.input, service.file, wktImports, localImports, externalImports, allSeenMessages);
+    collectAllMessages(method.output, service.file, wktImports, localImports, externalImports, allSeenMessages);
+    const inputBaseName = method.input.name;
+    const outputBaseName = method.output.name;
     const camelName = method.name.charAt(0).toLowerCase() + method.name.slice(1);
     const mutationVerbs = [
       "Create",
@@ -336884,11 +336898,15 @@ function processService(service, protoPbFile, connectQueryFile) {
       isPaginated: isPaginatedDeep(method.input) && isUnary && !isMutation
     });
   }
+  const messageNames = Array.from(allSeenMessages).map((fullPath) => {
+    return fullPath.split(".").pop();
+  });
   return {
     serviceName: service.name,
     protoPbFile,
     connectQueryFile,
     rpcs,
+    messageNames,
     wktImports: Array.from(wktImports),
     localImports: Array.from(localImports),
     externalImports: Array.from(externalImports.entries()).map(([path2, types2]) => ({
@@ -336899,7 +336917,7 @@ function processService(service, protoPbFile, connectQueryFile) {
 }
 var plugin = createEcmaScriptPlugin({
   name: "protoc-gen-connect-vue",
-  version: "v1.0.2",
+  version: "v1.0.3",
   generateTs: (schema) => {
     let firstService = schema.files.flatMap((f) => f.services)[0];
     if (!firstService)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachacious/protoc-gen-connect-vue",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Smart TanStack Query & ConnectRPC SDK generator for Vue.js",
   "type": "module",
   "license": "MIT",

package/templates/api.ts.mustache

@@ -1,17 +1,28 @@
-import { computed } from "vue";
-import { useQuery, useMutation, useInfiniteQuery, useQueryClient, useIsFetching, useIsMutating } from "@tanstack/vue-query";
+import { computed, unref } from "vue";
+import { 
+  useQuery, 
+  useMutation, 
+  useInfiniteQuery, 
+  useQueryClient, 
+  useIsFetching, 
+  useIsMutating 
+} from "@tanstack/vue-query";
 import { ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
 import { useGrpcClient } from "./client";
 
-import {
-  {{#rpcs}}
-  {{queryDefinitionName}} as {{queryDefinitionName}}Def,
-  {{/rpcs}}
-} from "./gen/{{{connectQueryFile}}}";
+{{#wktImports}}
+import { {{.}}Schema } from "@bufbuild/protobuf";
+import type { {{.}} } from "@bufbuild/protobuf";
+{{/wktImports}}
+
+{{#localImports}}
+import { {{.}}Schema } from "./gen/{{{protoPbFile}}}";
+import type { {{.}} } from "./gen/{{{protoPbFile}}}";
+{{/localImports}}
 
-{{#wktImports}}import type { {{.}} } from "@bufbuild/protobuf";{{/wktImports}}
-{{#localImports}}import type { {{.}} } from "./gen/{{{protoPbFile}}}";{{/localImports}}
 {{#externalImports}}
+import { {{#types}}{{.}}Schema, {{/types}} } from "{{{path}}}";
 import type { {{#types}}{{.}}, {{/types}} } from "{{{path}}}";
 {{/externalImports}}
 
@@ -33,6 +44,25 @@ async function callConnect<ReqT, ResT, DataT>(
   }
 }
 
+/**
+ * Query Keys for manual cache management
+ */
+export const queryKeys = {
+  {{#rpcs}}
+  {{functionName}}: (input?: any) => ["{{resource}}", "{{functionName}}", input] as const,
+  {{/rpcs}}
+};
+
+/**
+ * Utility to create default/empty versions of Protobuf messages 
+ * ensuring all fields (even nested ones) are initialized per schema.
+ */
+export const createEmpty = {
+  {{#messageNames}}
+  {{.}}: (data?: Partial<{{.}}>) => create({{.}}Schema, data),
+  {{/messageNames}}
+};
+
 export const useApi = () => {
   const { client } = useGrpcClient();
   const queryClient = useQueryClient();
@@ -52,5 +82,7 @@ export const useApi = () => {
     {{hookName}},
     {{/rpcs}}
     isGlobalLoading,
+    queryKeys,
+    createEmpty
   };
 };

package/templates/client.ts.mustache

@@ -1,14 +1,25 @@
+import { ref, computed } from "vue";
 import { {{serviceName}} } from './gen/{{{protoPbFile}}}';
 import { createClient, ConnectError, type Interceptor } from "@connectrpc/connect";
 import { createConnectTransport } from "@connectrpc/connect-web"; 
 
-let baseUrl = 'http://localhost:3000';
+// This workaround insures that bigints returned from the backend 
+// can be serialized - otherwise you will run into some hard to pin down bugs
+// dealing with bigint serialization
+if (!(BigInt.prototype as any).toJSON) {
+  (BigInt.prototype as any).toJSON = function () {
+    return this.toString();
+  };
+}
+
+// --- REACTIVE STATE ---
+const baseUrl = ref('http://localhost:3000');
 
 /**
  * Configure the API endpoint at runtime.
  */
 export const setBaseUrl = (url: string) => {
-  baseUrl = url;
+  baseUrl.value = url;
 };
 
 // --- AUTH RESOLVER ---
@@ -35,12 +46,20 @@ const transportInterceptor: Interceptor = (next) => async (req) => {
   }
 };
 
-export const transport = createConnectTransport({
-  baseUrl,
-  interceptors: [transportInterceptor],
-});
+/**
+ * useGrpcClient provides a reactive client.
+ * If baseUrl.value changes, the computed client updates automatically.
+ */
+export const useGrpcClient = () => {
+  const transport = computed(() => createConnectTransport({
+    baseUrl: baseUrl.value,
+    interceptors: [transportInterceptor],
+  }));
+
+  const client = computed(() => createClient({{serviceName}}, transport.value));
 
-export const client = createClient({{serviceName}}, transport);
+  return { client };
+};
 
 export const globalQueryConfig = {
   defaultOptions: {
@@ -52,8 +71,6 @@ export const globalQueryConfig = {
   },
 };
 
-export const useGrpcClient = () => ({ client });
-
 /*
 
 // the following is an example of how to use the hybrid api 

package/templates/rpc.ts.mustache

@@ -1,50 +1,59 @@
 /**
-   * Standard Async: {{functionName}}
-   */
-  const {{functionName}} = async (req: {{inputType}}): Promise<APIResponse<{{outputType}}>> => {
-    const res = await callConnect(client.{{functionName}}, req, (res) => res);
-    if (!res.error) queryClient.invalidateQueries({ queryKey: ["{{resource}}"] });
-    return res;
-  };
+ * Standard Async: {{functionName}}
+ * Used for manual actions. Invalidates the cache for this resource on success.
+ */
+const {{functionName}} = async (req: {{inputType}}): Promise<APIResponse<{{outputType}}>> => {
+  const res = await callConnect(client.value.{{functionName}}.bind(client.value), req, (res) => res);
+  if (!res.error) {
+    queryClient.invalidateQueries({ queryKey: ["{{resource}}"] });
+  }
+  return res;
+};
 
-  /**
-   * TanStack Hook: {{hookName}}
-   */
-  const {{hookName}} = (
-    {{#isQuery}}
-    input: {{inputType}}, 
-    options: any = {}
-    {{/isQuery}}
-    {{^isQuery}}
-    options: any = {}
-    {{/isQuery}}
-  ) => {
-    {{#isPaginated}}
-    return useInfiniteQuery({
-      ...{{queryDefinitionName}}Def,
-      ...options,
-      queryKey: ["{{resource}}", "{{functionName}}", input],
-      initialPageParam: 1,
-      getNextPageParam: options.getNextPageParam || ((lastPage: any) => lastPage.nextPage ?? undefined),
-    });
-    {{/isPaginated}}
-    {{^isPaginated}}
-    {{#isQuery}}
-    return useQuery({
-      ...{{queryDefinitionName}}Def,
-      ...options,
-      queryKey: ["{{resource}}", "{{functionName}}", input],
-    });
-    {{/isQuery}}
-    {{^isQuery}}
-    return useMutation({
-      ...{{queryDefinitionName}}Def,
-      ...options,
-      onSuccess: async (data, variables, context) => {
-        await queryClient.invalidateQueries({ queryKey: ["{{resource}}"] });
-        if (options.onSuccess) return options.onSuccess(data, variables, context);
-      },
-    });
-    {{/isQuery}}
-    {{/isPaginated}}
-  };
+/**
+ * TanStack Hook: {{hookName}}
+ * Provides reactive data binding with caching.
+ */
+const {{hookName}} = (
+  {{#isQuery}}
+  input: any, // Accepts Ref<{{inputType}}> or {{inputType}}
+  options: any = {}
+  {{/isQuery}}
+  {{^isQuery}}
+  options: any = {}
+  {{/isQuery}}
+) => {
+  {{#isPaginated}}
+  return useInfiniteQuery({
+    queryKey: queryKeys.{{functionName}}(input),
+    queryFn: async ({ pageParam }) => {
+      const req = { ...unref(input), page: pageParam }; 
+      return client.value.{{functionName}}(req);
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage: any) => lastPage.nextPage ?? undefined,
+    ...options,
+  });
+  {{/isPaginated}}
+  
+  {{^isPaginated}}
+  {{#isQuery}}
+  return useQuery({
+    queryKey: queryKeys.{{functionName}}(input),
+    queryFn: () => client.value.{{functionName}}(unref(input)),
+    ...options,
+  });
+  {{/isQuery}}
+  
+  {{^isQuery}}
+  return useMutation({
+    mutationFn: (req: {{inputType}}) => client.value.{{functionName}}(req),
+    onSuccess: async (data, variables, context) => {
+      await queryClient.invalidateQueries({ queryKey: ["{{resource}}"] });
+      if (options.onSuccess) return options.onSuccess(data, variables, context);
+    },
+    ...options,
+  });
+  {{/isQuery}}
+  {{/isPaginated}}
+};