nuxt-procedures 0.1.2

package/README.md

@@ -0,0 +1,203 @@
+# Nuxt Procedures
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Nuxt module to define and easily consume your backend API in a validated and
+type-safe way using procedures and Zod schemas.
+
+- [🏀 Online playground](https://stackblitz.com/github/andresberrios/nuxt-procedures?file=playground%2Fapp.vue)
+
+## Features
+
+- **Type-Safe API Layer:** End-to-end type safety for your API calls.
+- **Zod Validation:** Use Zod schemas to validate inputs and outputs.
+- **Automatic API Client:** An `apiClient` is automatically generated based on your procedures.
+- **`useFetch` Integration:** Seamlessly integrates with Nuxt's `useFetch` for easy data fetching in your components.
+- **`superjson` Support:** Automatically handles serialization of complex data types.
+
+## Installation
+
+### Quick Install (Recommended)
+
+Install and configure the module with a single command:
+
+```bash
+npx nuxi module add nuxt-procedures
+```
+This will add `nuxt-procedures` to your `package.json` and `nuxt.config.ts`.
+
+You also need to install its peer dependency, `zod`:
+```bash
+npm install zod
+```
+
+### Manual Install
+
+1. Install the packages:
+
+```bash
+npm install nuxt-procedures zod
+```
+
+2. Add the module to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['nuxt-procedures'],
+})
+```
+
+## Usage
+
+### 1. Define Procedures
+
+Create `.ts` files in your `server/api` directory. The module will automatically create a corresponding client for each file.
+
+#### Simple Example
+
+For a simple input and output, you can use Zod schemas directly.
+
+`server/api/hello.ts`:
+```typescript
+import { z } from 'zod'
+
+export default defineProcedure({
+  input: z.string(),
+  output: z.string(),
+  handler: async ({ input }) => {
+    return `Hello, ${input}!`
+  },
+})
+```
+
+#### Complex Example
+
+For more complex scenarios, `z.object` is the way to go. This is useful for things like form submissions or creating database entries.
+
+`server/api/users/create.ts`:
+```typescript
+import { z } from 'zod'
+
+export default defineProcedure({
+  input: z.object({
+    name: z.string(),
+    email: z.string().email(),
+    role: z.enum(['admin', 'user']).default('user'),
+  }),
+  output: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string(),
+  }),
+  handler: async ({ input, event }) => {
+    // The event param gives you access to the request context and Nuxt utilities
+    // For example, you can access request headers
+    const headers = getRequestHeaders(event)
+    console.log(headers)
+
+    // In a real app, you would create a user in your database
+    // The following is just an example of how you could get a db client
+    const db = await useDB(event)
+    const newUser = await db.user.create({
+      data: input,
+    })
+    
+    return newUser
+  },
+})
+```
+
+### 2. Use the `apiClient`
+
+The module automatically generates an `apiClient` that you can use in your components or pages. The structure of the `apiClient` mirrors your `server/api` directory.
+
+#### `useCall`
+
+The `useCall` method is a wrapper around Nuxt's `useFetch` and is the recommended way to call procedures from your Vue components.
+
+Calling the simple `hello` procedure:
+```vue
+<script setup lang="ts">
+const { data: greeting, pending } = await apiClient.hello.useCall('World')
+</script>
+
+<template>
+  <p v-if="pending">Loading...</p>
+  <p v-else>{{ greeting }}</p>
+</template>
+```
+
+Calling the complex `users/create` procedure:
+```vue
+<script setup lang="ts">
+const { data: newUser, execute } = apiClient.users.create.useCall({ 
+  name: 'Andres',
+  email: 'andres@example.com',
+})
+
+// `execute` can be called later, e.g. in a form submission handler
+// const submitForm = () => execute()
+</script>
+```
+
+#### `call`
+
+The `call` method makes a direct API call and is useful for calling procedures from server-side code or when you don't need the features of `useFetch`.
+
+```typescript
+// Calling the simple procedure
+const greeting = await apiClient.hello.call('World')
+// greeting is "Hello, World!"
+
+// Calling the complex procedure
+const newUser = await apiClient.users.create.call({
+  name: 'Andres',
+  email: 'andres@example.com',
+})
+// newUser is { id: '...', name: 'Andres', email: 'andres@example.com' }
+```
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
+  
+  ```bash
+  # Install dependencies
+  npm install
+  
+  # Generate type stubs
+  npm run dev:prepare
+  
+  # Develop with the playground
+  npm run dev
+  
+  # Build the playground
+  npm run dev:build
+  
+  # Run ESLint
+  npm run lint
+  
+  # Run Vitest
+  npm run test
+  npm run test:watch
+  
+  # Release new version
+  npm run release
+  ```
+
+</details>
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-procedures/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-procedures
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-procedures.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/nuxt-procedures
+[license-src]: https://img.shields.io/npm/l/nuxt-procedures.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-procedures
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,9 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    enabled: boolean;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-procedures",
+  "configKey": "procedures",
+  "version": "0.1.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,113 @@
+import { join, parse, sep } from 'node:path';
+import { defineNuxtModule, createResolver, addServerImports, addTemplate, updateTemplates, addImports, resolveFiles } from '@nuxt/kit';
+import { camelCase } from 'scule';
+
+const toCode = Symbol("toCode");
+const toList = Symbol("toList");
+class Procedure {
+  constructor(file, url) {
+    this.file = file;
+    this.url = url;
+  }
+  id = "proc" + Math.random().toString(36).slice(2);
+  [toCode]() {
+    return `createCaller<typeof ${this.id}>("${this.url}")`;
+  }
+  [toList]() {
+    return [this];
+  }
+}
+class Router {
+  [toCode]() {
+    return `{
+    ${Object.entries(this).map(([key, value]) => `"${camelCase(key)}": ${value[toCode]()}`).join(",\n")}
+    }`;
+  }
+  [toList]() {
+    return Object.values(this).flatMap((v) => v[toList]());
+  }
+}
+const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-procedures",
+    configKey: "procedures"
+  },
+  // Default configuration options of the Nuxt module
+  defaults: {
+    enabled: true
+  },
+  async setup(options, nuxt) {
+    if (!options.enabled) {
+      return;
+    }
+    const { resolve } = createResolver(import.meta.url);
+    addServerImports([
+      {
+        from: resolve("./runtime/define-procedure.ts"),
+        name: "defineProcedure"
+      }
+    ]);
+    const createCallerPath = resolve("./runtime/create-caller.ts");
+    const generatedClient = addTemplate({
+      filename: "nuxt-procedures/api-client.ts",
+      getContents: () => generateClientCode(nuxt, createCallerPath),
+      write: true
+    });
+    nuxt.hook("builder:watch", async (event, path) => {
+      if (path.includes("api")) {
+        updateTemplates({
+          filter: (t) => t.filename === generatedClient.filename
+        });
+      }
+    });
+    const imports = [{ from: generatedClient.dst, name: "apiClient" }];
+    addImports(imports);
+  }
+});
+async function buildRouterStructure(nuxt) {
+  const procedureDirs = nuxt.options._layers.map(
+    (l) => (
+      // join(l.config.serverDir ?? "server", "procedures")
+      join(l.config.serverDir ?? "server", "api")
+    )
+  );
+  const router = new Router();
+  for (const procDir of procedureDirs) {
+    const files = await resolveFiles(procDir, "**/*.ts");
+    for (const file of files) {
+      const { name, dir } = parse(file);
+      const namespace = dir.slice(procDir.length + 1);
+      const url = namespace === "" ? `/${name}` : `/${namespace}/${name}`;
+      if (namespace === "") {
+        router[name] = new Procedure(file, url);
+      } else {
+        const parts = namespace.split(sep);
+        let subRouter = router;
+        for (const part of parts) {
+          if (!subRouter[part] || subRouter[part] instanceof Procedure) {
+            subRouter[part] = new Router();
+          }
+          subRouter = subRouter[part];
+        }
+        subRouter[name] = new Procedure(file, url);
+      }
+    }
+  }
+  return router;
+}
+function withoutExtension(file) {
+  return file.slice(0, -parse(file).ext.length);
+}
+async function generateClientCode(nuxt, createCallerPath) {
+  const router = await buildRouterStructure(nuxt);
+  const procedures = router[toList]();
+  return `
+    import { createCaller } from "${withoutExtension(createCallerPath)}";
+    
+    ${procedures.map((p) => `import type ${p.id} from "${withoutExtension(p.file)}";`).join("\n")}
+    
+    export const apiClient = ${router[toCode]()};
+  `;
+}
+
+export { module as default };

package/dist/runtime/create-caller.d.ts

@@ -0,0 +1,16 @@
+import type { z } from 'zod';
+import type { Procedure } from './define-procedure.js';
+import { useFetch } from '#imports';
+type InferProcedureInput<P> = P extends Procedure<infer I, any> ? I extends z.ZodUndefined ? unknown : z.infer<I> : never;
+type InferProcedureOutput<P> = P extends Procedure<any, infer O> ? O extends z.ZodTypeAny ? z.infer<O> : unknown : never;
+type Call<P extends Procedure<any, any>> = [unknown] extends [
+    InferProcedureInput<P>
+] ? () => Promise<InferProcedureOutput<P>> : (input: InferProcedureInput<P>) => Promise<InferProcedureOutput<P>>;
+type UseCall<P extends Procedure<any, any>> = [unknown] extends [
+    InferProcedureInput<P>
+] ? () => ReturnType<typeof useFetch<InferProcedureOutput<P>>> : (input: InferProcedureInput<P>) => ReturnType<typeof useFetch<InferProcedureOutput<P>>>;
+export declare function createCaller<P extends Procedure<any, any>>(url: string): {
+    call: Call<P>;
+    useCall: UseCall<P>;
+};
+export {};

package/dist/runtime/create-caller.js

@@ -0,0 +1,23 @@
+import superjson from "superjson";
+import { useFetch, useRequestHeaders } from "#imports";
+export function createCaller(url) {
+  return {
+    call: (input) => {
+      return $fetch("/api" + url, {
+        method: "POST",
+        body: superjson.serialize(input),
+        parseResponse: superjson.parse,
+        headers: useRequestHeaders(["cookie"])
+      });
+    },
+    useCall: (input) => {
+      return useFetch("/api" + url, {
+        key: `${url}: ${JSON.stringify(input)}`,
+        method: "POST",
+        body: superjson.serialize(input),
+        parseResponse: superjson.parse,
+        headers: useRequestHeaders(["cookie"])
+      });
+    }
+  };
+}

package/dist/runtime/define-procedure.d.ts

@@ -0,0 +1,22 @@
+import type { EventHandler, H3Event } from 'h3';
+import z from 'zod';
+export interface Procedure<I extends z.ZodTypeAny = z.ZodUndefined, O extends z.ZodTypeAny = z.ZodVoid> extends EventHandler {
+    __procedureMetadata: {
+        inputSchema: I;
+        outputSchema: O;
+    };
+}
+type Awaitable<T> = T | Promise<T>;
+type HandlerArgs<I> = I extends undefined ? {
+    event: H3Event;
+} : {
+    input: I;
+    event: H3Event;
+};
+type Handler<I extends z.ZodTypeAny = z.ZodUndefined, O extends z.ZodTypeAny = z.ZodVoid> = (args: HandlerArgs<z.infer<I>>) => Awaitable<z.infer<O>>;
+export declare function defineProcedure<I extends z.ZodTypeAny = z.ZodUndefined, O extends z.ZodTypeAny = z.ZodVoid>(args: {
+    input?: I;
+    output?: O;
+    handler: Handler<I, O>;
+}): Procedure<I, O>;
+export {};

package/dist/runtime/define-procedure.js

@@ -0,0 +1,17 @@
+import z from "zod";
+import superjson from "superjson";
+export function defineProcedure({
+  input: inputSchema,
+  output: outputSchema = z.void(),
+  handler
+}) {
+  const h = defineEventHandler(async (event) => {
+    const input = inputSchema ? inputSchema.parse(superjson.deserialize(await readBody(event))) : void 0;
+    const outputRaw = await handler(inputSchema ? { input, event } : { event });
+    const output = outputSchema.parse(outputRaw);
+    return superjson.serialize(output);
+  });
+  const procedure = h;
+  procedure.__procedureMetadata = { inputSchema, outputSchema };
+  return procedure;
+}

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "nuxt-procedures",
+  "version": "0.1.2",
+  "description": "Nuxt module to define and easily consume your backend API in a validated and type-safe way using procedures and Zod schemas.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andresberrios/nuxt-procedures.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.0.1",
+    "scule": "^1.3.0",
+    "superjson": "^2.2.2"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^2.6.2",
+    "@nuxt/eslint-config": "^1.7.1",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.0.1",
+    "@nuxt/test-utils": "^3.19.2",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.32.0",
+    "nuxt": "^4.0.1",
+    "typescript": "~5.8.3",
+    "vitest": "^3.2.4",
+    "vue-tsc": "^3.0.4"
+  }
+}