tag-rpc 1.0.0

package/dist/chunk-XFEVFUJZ.js

@@ -0,0 +1,100 @@
+// src/scanner.ts
+import fs from "fs";
+import path from "path";
+function runScanner() {
+  const API_DIR = path.resolve("app/api");
+  const OUTPUT_FILE = path.resolve("rpc/api-registry.ts");
+  function extractRouteTypes(fileContent) {
+    const results = {};
+    const regex = /<(\w+)>(.*?)<\1>|<(\w+)>(.*?)<\/\3>/gs;
+    let match;
+    while ((match = regex.exec(fileContent)) !== null) {
+      const tagName = match[1] || match[3];
+      const content = match[2] || match[4];
+      if (tagName && content) {
+        results[tagName] = content.trim();
+      }
+    }
+    return results;
+  }
+  function getRoutes(dir, routeList = []) {
+    if (!fs.existsSync(dir)) return routeList;
+    const files = fs.readdirSync(dir);
+    files.forEach((file) => {
+      const filePath = path.join(dir, file);
+      if (fs.statSync(filePath).isDirectory()) {
+        getRoutes(filePath, routeList);
+      } else if (file === "route.ts") {
+        const content = fs.readFileSync(filePath, "utf8");
+        const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"].filter(
+          (m) => new RegExp(`export\\s+(async\\s+)?(function|const|let|var)\\s+${m}\\b`).test(content)
+        );
+        if (methods.length > 0) {
+          const routePath = dir.replace(path.resolve("app"), "").replace(/\\/g, "/");
+          const pathParamKeys = (routePath.match(/\[(.*?)\]/g) || []).map(
+            (key) => key.replace(/[\[\]]/g, "")
+          );
+          const extractedTypes = extractRouteTypes(content);
+          routeList.push({
+            routePath,
+            methods,
+            pathParamKeys,
+            extractedTypes
+          });
+        }
+      }
+    });
+    return routeList;
+  }
+  const routes = getRoutes(API_DIR);
+  const sdkApiObject = routes.map((r) => {
+    return r.methods.map((m) => {
+      const methodTitle = m.charAt(0).toUpperCase() + m.slice(1).toLowerCase();
+      const customName = r.extractedTypes[`${methodTitle}RouteName`];
+      if (!customName) return null;
+      return `  /** {@link <@/app${r.routePath}/route.ts>} */
+  ${customName}: { path: "${r.routePath}", method: "${m}" }`;
+    }).filter(Boolean).join(",\n");
+  }).filter(Boolean).join(",\n");
+  const registryContent = `/** Generated by TagRPC - Do not edit manually */
+
+export const namedRoutes = {
+${sdkApiObject}
+} as const;
+
+export interface ApiRoutes {
+${routes.map((r) => `  "${r.routePath}": {
+    PathParams: ${r.pathParamKeys.length > 0 ? `{ ${r.pathParamKeys.map((k) => `${k}: string | number`).join("; ")} }` : "never"};
+    Methods: {
+${r.methods.map((m) => {
+    const methodTitle = m.charAt(0).toUpperCase() + m.slice(1).toLowerCase();
+    const body = r.extractedTypes[`${methodTitle}RequestType`] || "any";
+    const resp = r.extractedTypes[`${methodTitle}ResponseType`] || "any";
+    const query = r.extractedTypes[`${methodTitle}QueryType`] || "any";
+    return `      ${m}: {
+        Response: ${resp};
+        Body: ${body};
+        Query: ${query};
+      };`;
+  }).join("\n")}
+    };
+  };`).join("\n")}
+}
+`;
+  let shouldWrite = true;
+  if (fs.existsSync(OUTPUT_FILE)) {
+    const existingContent = fs.readFileSync(OUTPUT_FILE, "utf8");
+    if (existingContent === registryContent) {
+      shouldWrite = false;
+    }
+  }
+  if (shouldWrite) {
+    fs.mkdirSync(path.dirname(OUTPUT_FILE), { recursive: true });
+    fs.writeFileSync(OUTPUT_FILE, registryContent);
+    console.log(`\u2705 [TagRPC] Registry updated at ${OUTPUT_FILE}`);
+  }
+}
+
+export {
+  runScanner
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import {
+  runScanner
+} from "./chunk-XFEVFUJZ.js";
+
+// src/cli.ts
+import chokidar from "chokidar";
+var args = process.argv.slice(2);
+var isWatchMode = args.includes("--watch");
+if (isWatchMode) {
+  console.log("\u{1F440} TagRPC is watching for changes in /app...");
+  const watcher = chokidar.watch("./app", {
+    ignored: /(^|[\/\\])\../,
+    // ignore dotfiles
+    persistent: true
+  });
+  let timeout;
+  watcher.on("change", (path) => {
+    if (path.endsWith("route.ts")) {
+      clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        console.log(`File changed: ${path}. Regenerating...`);
+        runScanner();
+      }, 300);
+    }
+  });
+} else {
+  runScanner();
+}

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Base types that describe the shape of the generated registry.
+ * This allows the package to compile without knowing the exact routes yet.
+ */
+interface BaseApiRoutes {
+    [path: string]: {
+        PathParams: any;
+        Methods: {
+            [method: string]: {
+                Response: any;
+                Body: any;
+                Query: any;
+            };
+        };
+    };
+}
+interface BaseNamedRoutes {
+    [key: string]: {
+        path: string;
+        method: string;
+    };
+}
+/**
+ * Types for the fetcher options, extracted to be reusable.
+ */
+type TagRPCOptions<T extends BaseApiRoutes, TPath extends keyof T, TMethod extends keyof T[TPath]["Methods"]> = Omit<RequestInit, "method" | "body"> & (T[TPath]["PathParams"] extends never ? {
+    pathParams?: never;
+} : {
+    pathParams: T[TPath]["PathParams"];
+}) & (T[TPath]["Methods"][TMethod]["Body"] extends never ? {
+    body?: never;
+} : {
+    body: T[TPath]["Methods"][TMethod]["Body"];
+}) & (T[TPath]["Methods"][TMethod]["Query"] extends never ? {
+    query?: never;
+} : {
+    query?: T[TPath]["Methods"][TMethod]["Query"];
+});
+/**
+ * Custom Error Class for API failures
+ */
+declare class TAG_API_ERROR extends Error {
+    status: number;
+    statusText: string;
+    body: any;
+    url: string;
+    constructor(status: number, statusText: string, body: any, url: string);
+}
+/**
+ * THE MAIN EXPORT: This creates the proxy-based SDK.
+ * Users will call this and pass in their generated types/objects.
+ */
+declare function createTagRPC<T extends BaseApiRoutes, N extends BaseNamedRoutes>(namedRoutes: N): { [K in keyof N]: (options: TagRPCOptions<T, N[K]["path"] & keyof T, N[K]["method"] & keyof T[N[K]["path"] & keyof T]["Methods"]>) => Promise<T[N[K]["path"] & keyof T]["Methods"][N[K]["method"] & keyof T[N[K]["path"] & keyof T]["Methods"]]["Response"]>; } & {
+    fetch: <P extends keyof T, M extends keyof T[P]["Methods"] & string>(path: P, method: M, options: TagRPCOptions<T, P, M>) => Promise<T[P]["Methods"][M]["Response"]>;
+    routes: N;
+};
+
+export { type BaseApiRoutes, type BaseNamedRoutes, TAG_API_ERROR, type TagRPCOptions, createTagRPC };

package/dist/index.js

@@ -0,0 +1,59 @@
+// src/index.ts
+var TAG_API_ERROR = class extends Error {
+  constructor(status, statusText, body, url) {
+    super(`API Error ${status}: ${statusText}`);
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+    this.url = url;
+    this.name = "TagApiError";
+  }
+};
+async function fetchData(path, method, options) {
+  let url = path;
+  if (options.pathParams) {
+    for (const [key, value] of Object.entries(options.pathParams)) {
+      url = url.replace(`[${key}]`, encodeURIComponent(String(value)));
+    }
+  }
+  if (options.query) {
+    const qs = new URLSearchParams(options.query).toString();
+    if (qs) url += `?${qs}`;
+  }
+  const res = await fetch(url, {
+    ...options,
+    method,
+    body: options.body ? JSON.stringify(options.body) : void 0,
+    headers: { "Content-Type": "application/json", ...options.headers }
+  });
+  if (!res.ok) {
+    let errorBody;
+    try {
+      errorBody = await res.json();
+    } catch {
+      errorBody = { message: "Unknown error occurred" };
+    }
+    throw new TAG_API_ERROR(res.status, res.statusText, errorBody, url);
+  }
+  return res.json();
+}
+function createTagRPC(namedRoutes) {
+  const baseFetcher = {
+    fetch: (path, method, options) => fetchData(path, method, options),
+    routes: namedRoutes
+  };
+  return new Proxy(baseFetcher, {
+    get(target, prop) {
+      if (prop in target) return target[prop];
+      const route = namedRoutes[prop];
+      if (route) {
+        return (options) => fetchData(route.path, route.method, options);
+      }
+      return void 0;
+    }
+  });
+}
+export {
+  TAG_API_ERROR,
+  createTagRPC
+};

package/dist/scanner.d.ts

@@ -0,0 +1,3 @@
+declare function runScanner(): void;
+
+export { runScanner as default };

package/dist/scanner.js

@@ -0,0 +1,6 @@
+import {
+  runScanner
+} from "./chunk-XFEVFUJZ.js";
+export {
+  runScanner as default
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "tag-rpc",
+  "version": "1.0.0",
+  "description": "End-to-end type safety for Next.js Route Handlers",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "tag-rpc": "./dist/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsup src/index.ts src/cli.ts src/scanner.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/cli.ts src/scanner.ts --format esm --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [],
+  "author": "Kelvin Mitau",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "chokidar": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}

package/readme.md

@@ -0,0 +1,90 @@
+->TagRPC
+End-to-end type safety for Next.js Route Handlers. TagRPC bridges the gap between your Next.js API routes and your frontend with zero boilerplate and 100% type safety using simple XML-like tags.
+
+->Features
+1.Zero Schemas: No Zod or Valibot required (though you can use them!). Just define your types in your route.ts.
+
+2.Auto-Generation: A watcher that tracks your app/api folder and updates types instantly.
+
+3.Named Routes: Call your APIs by name (e.g., api.getUser()) instead of messy strings like "/api/users/[id]".
+
+4.Ultra-Lightweight: Zero runtime dependencies in your production bundle.
+
+->Installation
+Bash
+npm install tag-rpc
+
+->Setup
+
+1. Tag Your Routes
+   Inside any app/api/\*\*/route.ts file, add tags inside a backtick string to define your route's metadata:
+
+Example:
+// app/api/users/[id]/route.ts
+
+`    <GetRouteName>
+        getUser
+    </GetRouteName>
+    <GetResponseType>
+        id: string,;
+        name: string,
+        email?:string
+    </GetResponseType>
+    <GetRequestType> 
+        id: string,
+        name: string 
+    </GetRequestType>
+    <GetQueryType> 
+        includeemail:string 
+    </GetQueryType>`
+export async function GET(req: Request, { params }: { params: { id: string } }) {
+// ... your logic
+}
+
+2. Run the Scanner
+   Add the scanner to your package.json scripts:
+
+Example:
+
+"scripts": {
+"rpc:watch": "tag-rpc --watch",
+"build": "tag-rpc && next build"
+}
+
+3. Initialize the Client
+   Create a file (e.g., lib/api.ts) to initialize your type-safe client:
+
+Example:
+
+import { createTagRPC } from 'tag-rpc';
+import { ApiRoutes, namedRoutes } from '@/rpc/api-registry'; // Generated file
+
+export const api = createTagRPC<ApiRoutes, typeof namedRoutes>(namedRoutes);
+
+Usage:
+Now, enjoy full autocomplete and type safety in your React components!
+
+TypeScript
+// components/UserCard.tsx
+import { api } from '@/lib/api';
+
+const UserCard = async ({ id }: { id: string }) => {
+// Fully typed: knows path params, query params, and response shape!
+const user = await api.getUser({
+pathParams: { id }
+});
+
+return <div>{user.name}</div>;
+}
+
+->Configuration (Optional)
+Create a tagrpc.config.mjs in your root directory to customize paths:
+
+JavaScript
+export default {
+appDir: 'app', // Where your Next.js app folder is
+outputFile: 'rpc/registry.ts' // Where to save the generated types
+};
+
+->License
+MIT © [Kelvin Mitau]