next-zero-rpc 0.1.0

package/bin/cli.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
+
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+function log(msg) {
+  console.log(msg);
+}
+
+function success(msg) {
+  console.log(`${GREEN}✓${RESET} ${msg}`);
+}
+
+function warn(msg) {
+  console.log(`${YELLOW}⚠${RESET} ${msg}`);
+}
+
+function error(msg) {
+  console.error(`${RED}✗${RESET} ${msg}`);
+}
+
+const HELP_TEXT = `
+${BOLD}next-zero-rpc${RESET} — Type-safe fetch for Next.js
+
+${BOLD}Usage:${RESET}
+  npx next-zero-rpc               Install files into your Next.js project
+  npx next-zero-rpc --force        Overwrite existing files
+  npx next-zero-rpc --help         Show this help message
+
+${BOLD}What it does:${RESET}
+  Copies 4 files into ${CYAN}lib/next-zero-rpc/${RESET} (or ${CYAN}src/lib/next-zero-rpc/${RESET} if src/ exists):
+    • apiClient.ts         — Type-safe fetch wrapper (1.8 KB runtime)
+    • apiRegistry.ts       — Auto-generated route type registry
+    • responses.ts         — Error/success response helpers
+    • update-api-registry.mjs — Code generator + Next.js plugin
+
+${DIM}Zero dependencies. Zero runtime overhead. Full type safety.${RESET}
+`;
+
+function detectProjectRoot() {
+  const cwd = process.cwd();
+
+  // Check for Next.js indicators
+  const hasPackageJson = fs.existsSync(path.join(cwd, "package.json"));
+  if (!hasPackageJson) {
+    error("No package.json found. Run this from your Next.js project root.");
+    process.exit(1);
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
+  const allDeps = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies,
+  };
+
+  if (!allDeps.next) {
+    error("This doesn't appear to be a Next.js project (no 'next' in dependencies).");
+    process.exit(1);
+  }
+
+  // Detect src directory — works with or without it
+  const hasSrc = fs.existsSync(path.join(cwd, "src"));
+
+  return { root: cwd, hasSrc };
+}
+
+async function init(flags) {
+  const force = flags.includes("--force");
+
+  log("");
+  log(`${BOLD}${CYAN}next-zero-rpc${RESET} ${DIM}v${getVersion()}${RESET}`);
+  log("");
+
+  const { root, hasSrc } = detectProjectRoot();
+  const baseDir = hasSrc ? "src" : ".";
+  const targetDir = path.join(root, baseDir, "lib", "next-zero-rpc");
+  const configImportPrefix = hasSrc ? "./src" : ".";
+
+  log(`${DIM}Detected project layout: ${hasSrc ? "src/" : "root (no src/)"} ${RESET}`);
+  log("");
+
+  // Create target directory
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const files = ["apiClient.ts", "apiRegistry.ts", "responses.ts", "update-api-registry.mjs"];
+
+  let skipped = 0;
+  let written = 0;
+
+  for (const file of files) {
+    const src = path.join(TEMPLATES_DIR, file);
+    const dest = path.join(targetDir, file);
+
+    if (fs.existsSync(dest) && !force) {
+      warn(`${file} already exists ${DIM}(use --force to overwrite)${RESET}`);
+      skipped++;
+      continue;
+    }
+
+    fs.copyFileSync(src, dest);
+    success(`${file}`);
+    written++;
+  }
+
+  // Run update-api-registry once to populate the registry with existing routes
+  try {
+    const registryScript = path.join(targetDir, "update-api-registry.mjs");
+    const { updateApiRegistry } = await import(registryScript);
+    updateApiRegistry();
+    success("API registry updated");
+  } catch (e) {
+    warn(`Could not auto-update registry: ${e.message}`);
+  }
+
+  // Add "infer-api" script to package.json (safely, no overwrite)
+  try {
+    const pkgPath = path.join(root, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    const scriptCmd = `node ${baseDir === "." ? "" : baseDir + "/"}lib/next-zero-rpc/update-api-registry.mjs`;
+
+    if (!pkg.scripts) pkg.scripts = {};
+
+    if (pkg.scripts["infer-api"]) {
+      log(`${DIM}infer-api script already exists in package.json${RESET}`);
+    } else {
+      pkg.scripts["infer-api"] = scriptCmd;
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+      success(`Added ${BOLD}"infer-api"${RESET}${GREEN} script to package.json${RESET}`);
+    }
+  } catch (e) {
+    warn(`Could not update package.json: ${e.message}`);
+  }
+
+  log("");
+
+  if (written === 0 && skipped > 0) {
+    log(`${DIM}All files already exist. Use ${YELLOW}--force${RESET}${DIM} to overwrite.${RESET}`);
+    log("");
+    return;
+  }
+
+  // Print next steps
+  log(`${BOLD}Next steps:${RESET}`);
+  log("");
+  log(`  ${CYAN}1.${RESET} Update your ${BOLD}next.config.ts${RESET}:`);
+  log("");
+  log(
+    `     ${DIM}import { withApiRegistry } from "${configImportPrefix}/lib/next-zero-rpc/update-api-registry.mjs";${RESET}`,
+  );
+  log(`     ${DIM}export default withApiRegistry(nextConfig);${RESET}`);
+  log("");
+  log(`  ${CYAN}2.${RESET} Use ${BOLD}apiFetch${RESET} in your client components:`);
+  log("");
+  log(`     ${DIM}import { apiFetch } from "@/lib/next-zero-rpc/apiClient";${RESET}`);
+  log("");
+  log(
+    `     ${DIM}const [data, err] = await apiFetch("/api/users/123", { method: "GET" });${RESET}`,
+  );
+  log("");
+  log(
+    `  ${CYAN}3.${RESET} Use ${BOLD}createApiSuccess${RESET} / ${BOLD}createApiError${RESET} in your route handlers:`,
+  );
+  log("");
+  log(
+    `     ${DIM}import { createApiSuccess, createApiError } from "@/lib/next-zero-rpc/responses";${RESET}`,
+  );
+  log("");
+  log(`${DIM}The registry auto-updates when you create/delete route.ts files.${RESET}`);
+  log("");
+}
+
+function getVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf-8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// --- CLI Entry ---
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === "--help" || command === "-h") {
+  log(HELP_TEXT);
+  process.exit(0);
+}
+
+// Default: run init (with or without "init" subcommand)
+if (!command || command === "init") {
+  init(args.slice(command === "init" ? 1 : 0));
+} else if (command === "--force") {
+  // Allow: npx next-zero-rpc --force
+  init(args);
+} else {
+  error(`Unknown command: ${command}`);
+  log(`Run ${CYAN}npx next-zero-rpc --help${RESET} for usage.`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "next-zero-rpc",
+  "version": "0.1.0",
+  "description": "Type-safe fetch for Next.js — zero runtime, zero config, zero dependencies.",
+  "keywords": [
+    "nextjs",
+    "typescript",
+    "rpc",
+    "type-safe",
+    "fetch",
+    "api",
+    "codegen"
+  ],
+  "license": "MIT",
+  "author": "caocchinh",
+  "type": "module",
+  "bin": {
+    "next-zero-rpc": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "templates/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/caocchinh/next-zero-rpc"
+  },
+  "homepage": "https://github.com/caocchinh/next-zero-rpc#readme",
+  "bugs": {
+    "url": "https://github.com/caocchinh/next-zero-rpc/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/apiClient.ts

@@ -0,0 +1,114 @@
+import { NextResponse } from "next/server";
+import type { CheckPath, FindMatchingRoute, KnownRoutes } from "./apiRegistry";
+import { ApiErrorPayload, ErrorCode, isApiErrorPayload } from "./responses";
+
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+
+// ─── Type Inference ─────────────────────────────────────────────────────────
+
+/**
+ * Infer the success response type from an API route handler function.
+ * Filters out ApiErrorPayload to only return the success payload.
+ */
+type InferSuccessApiResponse<T, E = never> = T extends (...args: never[]) => infer R
+  ? Extract<Awaited<R>, NextResponse<unknown>> extends NextResponse<infer U>
+    ? Exclude<U, E>
+    : never
+  : never;
+
+type InferErrorApiResponse<T, E = never> = T extends (...args: never[]) => infer R
+  ? Extract<Awaited<R>, NextResponse<unknown>> extends NextResponse<infer U>
+    ? Extract<U, E>
+    : never
+  : never;
+
+type ResolveRoute<Path extends string> =
+  FindMatchingRoute<Path> extends keyof KnownRoutes ? FindMatchingRoute<Path> : never;
+
+type RouteMethods<Path extends string> = Extract<keyof KnownRoutes[ResolveRoute<Path>], HttpMethod>;
+
+type RouteSuccessResult<Path extends string, M extends HttpMethod> = InferSuccessApiResponse<
+  KnownRoutes[ResolveRoute<Path>][M & keyof KnownRoutes[ResolveRoute<Path>]],
+  ApiErrorPayload<ErrorCode>
+>;
+
+type RouteErrorResult<Path extends string, M extends HttpMethod> = InferErrorApiResponse<
+  KnownRoutes[ResolveRoute<Path>][M & keyof KnownRoutes[ResolveRoute<Path>]],
+  ApiErrorPayload<ErrorCode>
+>;
+
+export async function apiFetch<
+  Path extends string,
+  Method extends RouteMethods<Path> = RouteMethods<Path>,
+>(
+  path: Path extends CheckPath<Path> ? Path : CheckPath<Path>,
+  options: RequestInit & { method: Method },
+): Promise<
+  | [RouteSuccessResult<Path, Method>, null]
+  | [null, RouteErrorResult<Path, Method> | ApiErrorPayload<"system:unknown-error">]
+>;
+
+export async function apiFetch(
+  path: string,
+  options: RequestInit & { method: string },
+): Promise<unknown> {
+  try {
+    const res = await fetch(path, options);
+
+    // 1. Read the body as text first to safely handle empty responses.
+    const text = await res.text();
+
+    let payload;
+    // An empty HTTP body resolves to an empty string "" (falsy).
+    // Valid JSON primitives like `0`, `null`, `false`, or `""` serialize to 
+    // length > 0 strings (e.g. `"0"`, `"null"`, `'""'`), which are all truthy.
+    // This perfectly catches empty responses (like 204) while preserving valid JSON.
+    if (!text) {
+      payload = undefined;
+    } else {
+      // 2. Parse the payload safely based on Content-Type
+      const contentType = res.headers.get("content-type");
+      if (contentType && contentType.includes("application/json")) {
+        try {
+          payload = JSON.parse(text);
+        } catch {
+          return [
+            null,
+            {
+              code: "system:unknown-error",
+              message: "Server returned malformed JSON.",
+            },
+          ];
+        }
+      } else {
+        // For non-JSON responses, return the raw text
+        payload = text;
+      }
+    }
+
+    // 3. Strict error validation
+    if (!res.ok) {
+      return [
+        null,
+        isApiErrorPayload(payload)
+          ? payload
+          : {
+              code: "system:unknown-error",
+              message: "An error occurred but the server returned an unrecognized format.",
+            },
+      ];
+    }
+
+    // 4. Return the full response payload directly to the developer
+    return [payload, null];
+  } catch (error) {
+    // Network errors (like offline), CORS errors, etc.
+    return [
+      null,
+      {
+        code: "system:unknown-error",
+        message: error instanceof Error ? error.message : "A network error occurred.",
+      },
+    ];
+  }
+}

package/templates/apiRegistry.ts

@@ -0,0 +1,50 @@
+// --- BEGIN GENERATED API REGISTRY ---
+// This section is auto-generated. Do not edit manually.
+// Run your dev server or `node lib/next-zero-rpc/update-api-registry.mjs` to regenerate.
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type KnownRoutes = {
+  // Routes will be auto-populated here
+};
+// --- END GENERATED API REGISTRY ---
+
+type Split<S extends string> = S extends `${infer Head}/${infer Tail}`
+  ? [Head, ...Split<Tail>]
+  : [S];
+
+type MatchSegment<P extends string, K extends string> = K extends `[${string}]`
+  ? P extends ""
+    ? false
+    : true
+  : K extends P
+    ? true
+    : false;
+
+type MatchSegments<P extends string[], K extends string[]> = K extends []
+  ? P extends []
+    ? true
+    : false
+  : K extends [`[...${string}]`]
+    ? true
+    : [P, K] extends [
+          [infer PH extends string, ...infer PT extends string[]],
+          [infer KH extends string, ...infer KT extends string[]],
+        ]
+      ? MatchSegment<PH, KH> extends true
+        ? MatchSegments<PT, KT>
+        : false
+      : false;
+
+type StripQuery<Path extends string> = Path extends `${infer Base}?${string}` ? Base : Path;
+
+export type FindMatchingRoute<Path extends string> = {
+  [K in keyof KnownRoutes & string]: MatchSegments<Split<StripQuery<Path>>, Split<K>> extends true
+    ? K
+    : never;
+}[keyof KnownRoutes & string];
+
+export type CheckPath<Path extends string> = Path extends ""
+  ? keyof KnownRoutes
+  : FindMatchingRoute<Path> extends never
+    ? keyof KnownRoutes
+    : Path;

package/templates/responses.ts

@@ -0,0 +1,257 @@
+/**
+ * next-zero-rpc — Response helpers for API routes and server actions.
+ * Customize the error codes below to match your application's domain.
+ */
+
+import { NextResponse } from "next/server";
+
+type PrefixedError<T extends string> = `${T}:${string}`;
+
+// ─── Define your error codes here ───────────────────────────────────────────
+// Add, remove, or rename error codes to match your application's domain.
+// Each array must satisfy the PrefixedError<"prefix"> constraint.
+
+export const SYSTEM_ERRORS = [
+  "system:internal-server-error",
+  "system:unknown-error",
+  "system:database-error",
+  "system:timeout",
+  "system:service-unavailable",
+  "system:maintenance-mode",
+  "system:configuration-error",
+] as const satisfies PrefixedError<"system">[];
+
+export const AUTH_ERRORS = [
+  "auth:unauthorized",
+  "auth:forbidden",
+  "auth:not-logged-in",
+  "auth:token-expired",
+  "auth:invalid-token",
+  "auth:session-expired",
+  "auth:insufficient-permissions",
+  "auth:account-locked",
+  "auth:account-disabled",
+  "auth:email-not-verified",
+] as const satisfies PrefixedError<"auth">[];
+
+export const VALIDATION_ERRORS = [
+  "validation:missing-required-fields",
+  "validation:invalid-payload",
+  "validation:rate-limit-exceeded",
+  "validation:invalid-format",
+  "validation:invalid-type",
+  "validation:out-of-range",
+  "validation:too-short",
+  "validation:too-long",
+  "validation:duplicate-entry",
+  "validation:invalid-enum-value",
+] as const satisfies PrefixedError<"validation">[];
+
+export const RESOURCE_ERRORS = [
+  "resource:not-found",
+  "resource:already-exists",
+  "resource:conflict",
+  "resource:gone",
+  "resource:locked",
+  "resource:immutable",
+] as const satisfies PrefixedError<"resource">[];
+
+export const NETWORK_ERRORS = [
+  "network:timeout",
+  "network:external-service-error",
+  "network:dns-resolution-failed",
+  "network:connection-refused",
+] as const satisfies PrefixedError<"network">[];
+
+export const UPLOAD_ERRORS = [
+  "upload:file-too-large",
+  "upload:invalid-file-type",
+  "upload:upload-failed",
+  "upload:quota-exceeded",
+] as const satisfies PrefixedError<"upload">[];
+
+// ─── Combine all error codes ────────────────────────────────────────────────
+// Add your custom error arrays here when you create them.
+
+export const ERROR_CODES = [
+  ...SYSTEM_ERRORS,
+  ...AUTH_ERRORS,
+  ...VALIDATION_ERRORS,
+  ...RESOURCE_ERRORS,
+  ...NETWORK_ERRORS,
+  ...UPLOAD_ERRORS,
+] as const;
+
+const ERROR_CODE_SET: ReadonlySet<string> = new Set(ERROR_CODES);
+
+// ─── HTTP Status Codes ──────────────────────────────────────────────────────
+
+export const HTTP_STATUS_SUCCESS = {
+  OK: 200,
+  CREATED: 201,
+  ACCEPTED: 202,
+  NO_CONTENT: 204,
+} as const;
+
+export const HTTP_STATUS_ERROR = {
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  NOT_ACCEPTABLE: 406,
+  CONFLICT: 409,
+  PAYLOAD_TOO_LARGE: 413,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504,
+} as const;
+
+// ─── Derived Types ──────────────────────────────────────────────────────────
+
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+export type SuccessHttpStatusCode = (typeof HTTP_STATUS_SUCCESS)[keyof typeof HTTP_STATUS_SUCCESS];
+export type ErrorHttpStatusCode = (typeof HTTP_STATUS_ERROR)[keyof typeof HTTP_STATUS_ERROR];
+
+// ─── Payload Types ──────────────────────────────────────────────────────────
+
+export interface ApiErrorPayload<C extends ErrorCode> {
+  code: C;
+  details?: Record<string, string[]>;
+  message?: string;
+}
+
+// ─── API Route Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Create a consistent API error response.
+ *
+ * @example
+ * return createApiError("auth:unauthorized", HTTP_STATUS_ERROR.UNAUTHORIZED);
+ * return createApiError("auth:unauthorized", 401, undefined, "Custom message");
+ */
+export function createApiError<C extends ErrorCode>(
+  code: C,
+  statusCode: ErrorHttpStatusCode,
+  details?: Record<string, string[]>,
+  message?: string,
+): NextResponse<ApiErrorPayload<C>> {
+  return NextResponse.json(
+    {
+      code,
+      details,
+      message,
+    },
+    {
+      status: statusCode,
+    },
+  );
+}
+
+/**
+ * Create a consistent API success response.
+ *
+ * @example
+ * return createApiSuccess({ users: [...] });
+ * return createApiSuccess(undefined, HTTP_STATUS_SUCCESS.NO_CONTENT);
+ */
+export function createApiSuccess<T>(
+  data: T,
+  statusCode?: Exclude<SuccessHttpStatusCode, typeof HTTP_STATUS_SUCCESS.NO_CONTENT>,
+): NextResponse<T>;
+export function createApiSuccess(
+  data?: undefined,
+  statusCode?: typeof HTTP_STATUS_SUCCESS.NO_CONTENT,
+): NextResponse<undefined>;
+export function createApiSuccess<T>(
+  data?: T,
+  statusCode?: SuccessHttpStatusCode,
+): NextResponse<T | undefined> {
+  if (data === undefined || statusCode === HTTP_STATUS_SUCCESS.NO_CONTENT) {
+    return new NextResponse(null, { status: statusCode ?? 204 });
+  }
+
+  return NextResponse.json(data, { status: statusCode ?? 200 });
+}
+
+/**
+ * Type guard to check if an unknown payload is an ApiErrorPayload.
+ */
+export function isApiErrorPayload(payload: unknown): payload is ApiErrorPayload<ErrorCode> {
+  if (!payload || typeof payload !== "object") return false;
+
+  const p = payload as Record<string, unknown>;
+
+  return typeof p.code === "string" && ERROR_CODE_SET.has(p.code);
+}
+
+// ─── Server Action Helpers ──────────────────────────────────────────────────
+
+/**
+ * Error object structure for server actions.
+ */
+export interface ServiceError {
+  message: string;
+  code: ErrorCode;
+  details?: Record<string, string[]>;
+}
+
+/**
+ * Tuple type for server action responses: [data, error]
+ */
+type ServiceResponse<S, E = ServiceError> = [S, null] | [null, E];
+
+/**
+ * Create a consistent server action error response.
+ *
+ * @example
+ * return createServiceError("validation:invalid-payload");
+ * return createServiceError("validation:invalid-payload", undefined, "Custom message");
+ */
+export function createServiceError(
+  code: ErrorCode,
+  details?: Record<string, string[]>,
+  message?: string,
+): ServiceResponse<null, ServiceError> {
+  return [
+    null,
+    {
+      code,
+      details,
+      message: message ?? code,
+    },
+  ];
+}
+
+/**
+ * Create a consistent server action success response.
+ *
+ * @example
+ * return createServiceSuccess({ id: "123", name: "John" });
+ * return createServiceSuccess(); // void success → [undefined, null]
+ */
+export function createServiceSuccess<T>(data?: T): ServiceResponse<T | undefined, null> {
+  return [data, null];
+}
+
+// ─── Exhaustive Check ───────────────────────────────────────────────────────
+
+/**
+ * Compile-time exhaustiveness guard for switch/if-else chains.
+ * Place in the `default` branch — TypeScript will error if any case is unhandled.
+ *
+ * @example
+ * const code = err.code;
+ * switch (code) {
+ *   case "auth:forbidden": …; break;
+ *   case "system:unknown-error": …; break;
+ *   default: assertNever(code);
+ * }
+ */
+export function assertNever(value: never): never {
+  throw new Error(`Unhandled discriminant: ${String(value)}`);
+}