@stonecrop/nuxt-grafserv 0.7.0

package/README.md

@@ -0,0 +1,180 @@
+# Nuxt Grafserv
+
+[![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]
+
+Pluggable Grafserv GraphQL server as a Nuxt Module. Uses the Grafast execution engine for high-performance GraphQL.
+
+- [✨  Release Notes](/CHANGELOG.md)
+
+## Features
+
+- 🚀  Grafserv Server Integration
+- ⚡️  Grafast Execution Engine (faster than graphql-js)
+- 🔄  Schema Stitching Support
+- 🛠  Middleware Support
+- 📝  TypeScript Support
+- 🔍  GraphiQL Interface
+- ⚡️  Hot Module Reloading
+
+## Quick Setup
+
+1. Add `@stonecrop/nuxt-grafserv` dependency to your project:
+
+```bash
+# Using pnpm
+pnpm add @stonecrop/nuxt-grafserv
+
+# Using yarn
+yarn add @stonecrop/nuxt-grafserv
+
+# Using npm
+npm install @stonecrop/nuxt-grafserv
+```
+
+2. Add `@stonecrop/nuxt-grafserv` to the `modules` section of `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@stonecrop/nuxt-grafserv'],
+  grafserv: {
+    schema: './server/**/*.graphql',
+    resolvers: './server/resolvers.ts',
+    url: '/graphql/',
+  }
+})
+```
+
+## Configuration
+
+Here's a full example of all available options:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@stonecrop/nuxt-grafserv'],
+  grafserv: {
+    // Path to your GraphQL schema files
+    schema: './server/**/*.graphql',
+    
+    // Path to your resolvers
+    resolvers: './server/resolvers.ts',
+    
+    // GraphQL endpoint URL (default: /graphql/)
+    url: '/graphql/',
+    
+    // Enable GraphiQL IDE (default: true in dev, false in prod)
+    graphiql: true,
+    
+    // Middleware functions
+    middleware: [
+      async (ctx, next) => {
+        const start = Date.now()
+        const result = await next()
+        console.log(`Request took ${Date.now() - start}ms`)
+        return result
+      }
+    ],
+    
+    // Grafserv-specific options
+    grafserv: {
+      websockets: false,
+      introspection: true
+    }
+  }
+})
+```
+
+## Basic Usage
+
+1. Create your GraphQL schema (`server/schema.graphql`):
+
+```graphql
+type Query {
+  hello: String!
+  ping: Boolean!
+}
+
+type Mutation {
+  echo(message: String!): String!
+}
+```
+
+2. Create your resolvers (`server/resolvers.ts`):
+
+```typescript
+export default {
+  Query: {
+    hello: () => 'world',
+    ping: () => true
+  },
+  Mutation: {
+    echo: (_: unknown, { message }: { message: string }) => message
+  }
+}
+```
+
+## Middleware
+
+Add middleware functions to process requests:
+
+```ts
+grafserv: {
+  middleware: [
+    // Logging middleware
+    async (ctx, next) => {
+      const start = Date.now()
+      const result = await next()
+      console.log(`Request took ${Date.now() - start}ms`)
+      return result
+    },
+    // Authentication middleware
+    async (ctx, next) => {
+      const token = ctx.req.headers.get('authorization')
+      if (!token) throw new Error('Unauthorized')
+      return next()
+    }
+  ]
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Generate type stubs
+pnpm run dev:prepare
+
+# Develop with the playground
+pnpm run dev
+
+# Build the module
+pnpm run build
+
+# Run ESLint
+pnpm run lint
+
+# Run tests
+pnpm run test
+pnpm run test:watch
+```
+
+## License
+
+[MIT License](./LICENSE)
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/@stonecrop/nuxt-grafserv/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/@stonecrop/nuxt-grafserv
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/@stonecrop/nuxt-grafserv.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/@stonecrop/nuxt-grafserv
+
+[license-src]: https://img.shields.io/npm/l/@stonecrop/nuxt-grafserv.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/@stonecrop/nuxt-grafserv
+
+[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,61 @@
+import { NuxtModule } from '@nuxt/schema';
+import { GraphQLSchema } from 'graphql';
+import { GraphileConfig } from 'graphile-config';
+
+/**
+ * Context provided to GraphQL resolvers
+ */
+type GrafastContext = {
+    req: Request;
+    params: Record<string, string>;
+    [key: string]: unknown;
+};
+/**
+ * Middleware function type for request processing
+ */
+type MiddlewareFunction = (context: GrafastContext, next: () => Promise<GrafastContext>) => Promise<GrafastContext>;
+/**
+ * Schema provider function - returns a GraphQL schema
+ */
+type SchemaProvider = () => GraphQLSchema | Promise<GraphQLSchema>;
+/**
+ * Configuration for the Grafast module
+ */
+interface ModuleOptions {
+    /** Path to schema file(s) or a schema provider function */
+    schema?: string | string[] | SchemaProvider;
+    /** Path to resolvers file (for .graphql schema files) */
+    resolvers?: string;
+    /** GraphQL endpoint URL (default: '/graphql/') */
+    url?: string;
+    /** Whether to enable GraphiQL IDE (default: true in dev, false in prod) */
+    graphiql?: boolean;
+    /**
+     * Path to middleware file that exports an array of middleware functions.
+     * This is the recommended approach as it preserves imports/dependencies.
+     * Example: './server/middleware.ts'
+     */
+    middlewarePath?: string;
+    /**
+     * Middleware functions to process requests (inline).
+     * Note: Inline middleware cannot reference external modules.
+     * For middleware with dependencies, use middlewarePath instead.
+     * @deprecated Use middlewarePath for middleware with external dependencies
+     */
+    middleware?: MiddlewareFunction[];
+    /** Custom Graphile preset to extend (for advanced grafast configuration) */
+    preset?: GraphileConfig.Preset;
+    /** Additional Graphile plugins */
+    plugins?: GraphileConfig.Plugin[];
+    /** Grafserv options */
+    grafserv?: {
+        /** Whether to enable the GraphQL websocket endpoint */
+        websockets?: boolean;
+        /** Whether to enable introspection (default: true in dev) */
+        introspection?: boolean;
+    };
+}
+
+declare const module$1: NuxtModule<ModuleOptions>;
+
+export { module$1 as default };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-grafserv",
+  "configKey": "grafserv",
+  "version": "0.7.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,117 @@
+import { join } from 'node:path';
+import { useLogger, defineNuxtModule, createResolver } from '@nuxt/kit';
+
+const logger = useLogger("nuxt-grafserv");
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-grafserv",
+    configKey: "grafserv"
+  },
+  defaults: (_nuxt) => ({
+    schema: "./server/**/*.graphql",
+    resolvers: "./server/resolvers.ts",
+    url: "/graphql/",
+    graphiql: void 0,
+    // Will default based on dev mode
+    middleware: [],
+    plugins: [],
+    grafserv: {
+      websockets: false,
+      introspection: void 0
+      // Will default based on dev mode
+    }
+  }),
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    nuxt.hook("nitro:config", (config) => {
+      const resolverPath = options.resolvers ? join(nuxt.options.srcDir, options.resolvers) : void 0;
+      config.runtimeConfig = config.runtimeConfig || {};
+      config.runtimeConfig.grafserv = {
+        ...options,
+        // Resolve schema paths
+        schema: typeof options.schema === "string" ? join(nuxt.options.srcDir, options.schema) : Array.isArray(options.schema) ? options.schema.map((s) => join(nuxt.options.srcDir, s)) : options.schema
+        // function passed through
+      };
+      config.virtual = config.virtual || {};
+      if (resolverPath) {
+        config.virtual["#internal/grafserv/resolvers"] = `export { default } from '${resolverPath}'`;
+      }
+      let middlewareCode;
+      if (options.middlewarePath) {
+        const middlewarePath = join(nuxt.options.srcDir, options.middlewarePath);
+        middlewareCode = `export { default } from '${middlewarePath}'`;
+      } else if (options.middleware?.length) {
+        logger.warn("Inline middleware is deprecated. Use middlewarePath for middleware with external dependencies.");
+        middlewareCode = `export default [${options.middleware.map((fn) => fn.toString()).join(",")}]`;
+      } else {
+        middlewareCode = "export default []";
+      }
+      config.virtual["#internal/grafserv/middleware"] = middlewareCode;
+      config.externals = config.externals || {};
+      config.externals.inline = config.externals.inline || [];
+      config.externals.inline.push(
+        "grafast",
+        "grafserv",
+        "grafserv/h3/v1",
+        "graphile-config",
+        "@graphql-tools/schema",
+        "@graphql-tools/load",
+        "@graphql-tools/graphql-file-loader"
+      );
+    });
+    nuxt.hook("nitro:config", (config) => {
+      config.handlers = config.handlers || [];
+      config.handlers.push({
+        route: options.url || "/graphql/",
+        handler: resolve("./runtime/handler")
+      });
+      config.handlers.push({
+        route: "/graphql/cache",
+        handler: resolve("./runtime/cache")
+      });
+      config.handlers.push({
+        route: "/ruru-static/**",
+        handler: resolve("./runtime/handler")
+      });
+    });
+    if (options.url) {
+      nuxt.hook("devtools:customTabs", (tabs) => {
+        tabs.push({
+          name: "nuxt-grafserv",
+          title: "GraphQL (Grafserv)",
+          icon: "simple-icons:graphql",
+          view: {
+            type: "iframe",
+            src: options.url
+          }
+        });
+      });
+    }
+    if (nuxt.options.dev) {
+      let cacheClearing = false;
+      nuxt.hook("builder:watch", async (event, path) => {
+        const isSchemaFile = path.endsWith(".graphql");
+        const isResolverFile = options.resolvers && path.includes(options.resolvers.replace("./", ""));
+        if (isSchemaFile || isResolverFile) {
+          logger.info(`${path} changed`);
+          if (!cacheClearing) {
+            cacheClearing = true;
+            try {
+              logger.info("Clearing Grafserv cache...");
+              const { clearGrafservCache } = await import(resolve("./runtime/handler"));
+              await clearGrafservCache();
+              logger.success("Cache cleared, schema reloaded");
+            } catch (error) {
+              logger.error("Failed to clear cache:", error);
+            } finally {
+              cacheClearing = false;
+            }
+          }
+        }
+      });
+    }
+    logger.success("[@stonecrop/nuxt-grafserv] Module initialized");
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/cache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cache management endpoint for the Grafserv module.
+ *
+ * Actions:
+ * - clear: Clear the Grafserv instance cache
+ * - status: Get cache status information
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+    success: boolean;
+    message: string;
+    data?: undefined;
+    availableActions?: undefined;
+} | {
+    success: boolean;
+    data: {
+        message: string;
+    };
+    message?: undefined;
+    availableActions?: undefined;
+} | {
+    success: boolean;
+    message: string;
+    availableActions: string[];
+    data?: undefined;
+}>>;
+export default _default;

package/dist/runtime/cache.js

@@ -0,0 +1,31 @@
+import { defineEventHandler, getQuery, createError } from "h3";
+import { clearGrafservCache } from "./handler.js";
+export default defineEventHandler(async (event) => {
+  const allowCacheApi = process.env.NODE_ENV === "development";
+  if (!allowCacheApi) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Cache API is disabled in production"
+    });
+  }
+  const query = getQuery(event);
+  const action = query.action;
+  switch (action) {
+    case "clear":
+      await clearGrafservCache();
+      return { success: true, message: "Grafserv cache cleared" };
+    case "status":
+      return {
+        success: true,
+        data: {
+          message: "Grafserv cache status - schema and server instance cached in memory"
+        }
+      };
+    default:
+      return {
+        success: false,
+        message: "Invalid action",
+        availableActions: ["clear", "status"]
+      };
+  }
+});

package/dist/runtime/handler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Clear the cached instances (useful for development hot reload)
+ */
+export declare function clearGrafservCache(): Promise<void>;
+/**
+ * Main H3 event handler for GraphQL requests
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Buffer<ArrayBufferLike> | import("grafserv").JSONValue | undefined>>;
+export default _default;

package/dist/runtime/handler.js

@@ -0,0 +1,133 @@
+import { grafserv } from "grafserv/h3/v1";
+import { makeGrafastSchema } from "grafast";
+import { GraphQLFileLoader } from "@graphql-tools/graphql-file-loader";
+import { loadTypedefs } from "@graphql-tools/load";
+import { defineEventHandler } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+let middlewareFunctions = null;
+async function getMiddleware() {
+  if (middlewareFunctions !== null) {
+    return middlewareFunctions;
+  }
+  try {
+    const mod = await import("#internal/grafserv/middleware");
+    middlewareFunctions = mod.default || [];
+  } catch {
+    middlewareFunctions = [];
+  }
+  return middlewareFunctions;
+}
+let grafservInstance = null;
+let cachedSchema = null;
+async function loadTypeDefsFromFiles(schemaPath) {
+  const paths = Array.isArray(schemaPath) ? schemaPath : [schemaPath];
+  const sources = await loadTypedefs(paths, {
+    loaders: [new GraphQLFileLoader()]
+  });
+  return sources.map((source) => source.document).filter(Boolean);
+}
+async function getSchema(options) {
+  if (cachedSchema) {
+    return cachedSchema;
+  }
+  let schema;
+  if (typeof options.schema === "function") {
+    schema = await options.schema();
+  } else if (options.schema) {
+    const typeDefDocs = await loadTypeDefsFromFiles(options.schema);
+    let plans = {};
+    if (options.resolvers) {
+      try {
+        const resolverModule = await import("#internal/grafserv/resolvers");
+        const resolvers = resolverModule.default || resolverModule;
+        console.log("[@stonecrop/nuxt-grafserv] Resolvers loaded:", Object.keys(resolvers));
+        for (const typeName of Object.keys(resolvers)) {
+          plans[typeName] = {};
+          const typeResolvers = resolvers[typeName];
+          for (const fieldName of Object.keys(typeResolvers)) {
+            const resolver = typeResolvers[fieldName];
+            if (typeof resolver === "function") {
+              plans[typeName][fieldName] = { resolve: resolver };
+            } else {
+              plans[typeName][fieldName] = resolver;
+            }
+          }
+        }
+      } catch (e) {
+        console.warn("[@stonecrop/nuxt-grafserv] Could not load resolvers:", e);
+      }
+    }
+    schema = makeGrafastSchema({
+      typeDefs: typeDefDocs,
+      plans
+    });
+  } else {
+    throw new Error("[@stonecrop/nuxt-grafserv] No schema provided. Configure schema path or provider function.");
+  }
+  cachedSchema = schema;
+  return schema;
+}
+async function getGrafservInstance(options) {
+  if (grafservInstance) {
+    return grafservInstance;
+  }
+  const schema = await getSchema(options);
+  const isDev = process.env.NODE_ENV === "development";
+  grafservInstance = grafserv({
+    schema,
+    graphiql: options.graphiql ?? isDev,
+    websockets: options.grafserv?.websockets ?? false
+  });
+  console.log("[@stonecrop/nuxt-grafserv] Grafserv instance created");
+  return grafservInstance;
+}
+export async function clearGrafservCache() {
+  grafservInstance = null;
+  cachedSchema = null;
+  console.log("[@stonecrop/nuxt-grafserv] Cache cleared");
+}
+async function applyMiddleware(context, middleware) {
+  if (!middleware || middleware.length === 0) {
+    return context;
+  }
+  const applyNext = async (index) => {
+    if (index >= middleware.length) {
+      return context;
+    }
+    return middleware[index](context, () => applyNext(index + 1));
+  };
+  return applyNext(0);
+}
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig();
+  const options = config.grafserv;
+  try {
+    if (event.node.req.url?.includes("/__grafserv_cache_clear") && process.env.NODE_ENV === "development") {
+      await clearGrafservCache();
+      return { success: true, message: "Cache cleared" };
+    }
+    const { req } = event.node;
+    const context = {
+      req: new Request(new URL(req.url || "/", `http://${req.headers.host || "localhost"}`), {
+        method: req.method,
+        headers: req.headers
+      }),
+      params: event.context.params || {}
+    };
+    const middleware = await getMiddleware();
+    await applyMiddleware(context, middleware);
+    const serv = await getGrafservInstance(options);
+    const url = event.node.req.url || "";
+    const method = event.node.req.method || "GET";
+    if (url.includes("/ruru-static/")) {
+      return serv.handleGraphiqlStaticEvent(event);
+    }
+    if (method === "GET" && url.match(/\/graphql\/?(\?.*)?$/)) {
+      return serv.handleGraphiqlEvent(event);
+    }
+    return serv.handleGraphQLEvent(event);
+  } catch (error) {
+    console.error("[@stonecrop/nuxt-grafserv] Error in GraphQL handler:", error);
+    throw error;
+  }
+});

package/dist/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@stonecrop/nuxt-grafserv",
+  "version": "0.7.0",
+  "description": "Pluggable Grafserv GraphQL server as Nuxt Module",
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "Tyler Matteson",
+    "email": "tyler@agritheory.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agritheory/stonecrop",
+    "directory": "nuxt_grafserv"
+  },
+  "bugs": {
+    "url": "https://github.com/agritheory/stonecrop/issues"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/module.mjs",
+      "types": "./dist/types.d.mts"
+    },
+    "./runtime/*": "./dist/runtime/*"
+  },
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@graphql-tools/graphql-file-loader": "^8.1.9",
+    "@graphql-tools/load": "^8.1.8",
+    "@graphql-tools/stitch": "^10.1.8",
+    "@graphql-tools/wrap": "^11.1.4",
+    "grafast": "^1.0.0-rc.3",
+    "grafserv": "^1.0.0-rc.3",
+    "graphile-config": "^1.0.0-rc.2",
+    "graphql": "^16.12.0",
+    "@stonecrop/graphql-middleware": "0.7.0"
+  },
+  "devDependencies": {
+    "@casl/ability": "^6.7.5",
+    "@eslint/js": "^9.39.2",
+    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/eslint-config": "^1.12.1",
+    "@nuxt/kit": "^4.2.2",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.2.2",
+    "@nuxt/test-utils": "^3.23.0",
+    "@vitest/coverage-istanbul": "^4.0.17",
+    "@types/node": "^22.19.5",
+    "zod": "^3.25.76",
+    "h3": "^1.15.4",
+    "nitropack": "^2.13.0",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.39.2",
+    "jsdom": "^27.4.0",
+    "nuxt": "^4.2.2",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17",
+    "vue-tsc": "^3.2.2",
+    "@stonecrop/casl-middleware": "0.7.0",
+    "@stonecrop/rockfoil": "0.7.0"
+  },
+  "peerDependencies": {
+    "@stonecrop/casl-middleware": "0.7.0",
+    "@stonecrop/rockfoil": "0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@stonecrop/casl-middleware": {
+      "optional": true
+    },
+    "@stonecrop/rockfoil": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "_phase:build": "rushx dev:prepare && rushx prepack",
+    "build": "rushx dev:prepare && rushx prepack",
+    "build:module": "rushx dev:prepare && rushx prepack",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:ci": "vitest run --run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  }
+}