@stonecrop/nuxt-grafserv 0.7.5 → 0.7.6

package/README.md

@@ -63,8 +63,8 @@ export default defineNuxtConfig({
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `schema` | `string \| string[] \| SchemaProvider` | `'server/**/*.graphql'` | Path(s) to GraphQL schema files or schema provider function |
-| `resolvers` | `string` | `'server/resolvers.ts'` | Path to resolvers file |
+| `schema` | `string \| string[] \| SchemaProvider \| PostGraphileInstance` | `'server/**/*.graphql'` | Path(s) to GraphQL schema files, schema provider function, or PostGraphile instance |
+| `resolvers` | `string` | `undefined` | Path to resolvers file (optional - not needed for PostGraphile) |
 | `url` | `string` | `'/graphql/'` | GraphQL endpoint URL (also serves Ruru UI) |
 | `graphiql` | `boolean` | `true` in dev, `false` in prod | Enable GraphiQL IDE |
 | `preset` | `GraphileConfig.Preset` | `undefined` | Custom Graphile preset for advanced configuration |
@@ -238,6 +238,134 @@ export default [loggingPlugin, authPlugin]
 
 ## Advanced Usage
 
+### PostGraphile Integration
+
+This module has first-class support for PostGraphile, enabling instant GraphQL APIs from PostgreSQL databases. PostGraphile generates the complete schema and resolvers, so you don't need to define them manually.
+
+#### Setup with PostGraphile
+
+1. Install PostGraphile:
+
+```bash
+pnpm add postgraphile @graphile/crystal graphile-build-pg
+```
+
+2. Create a PostGraphile schema provider (`server/graphql/schema.ts`):
+
+```typescript
+import { postgraphile } from 'postgraphile'
+import type { GraphQLSchema } from 'graphql'
+
+// Define your PostGraphile preset
+const preset = {
+  pgServices: [
+    {
+      name: 'main',
+      connectionString: process.env.DATABASE_URL || 'postgres://localhost/mydb',
+      schemas: ['public'],
+    },
+  ],
+  grafserv: {
+    websockets: false, // Disable websockets for Nuxt compatibility
+  },
+}
+
+// Create PostGraphile instance
+const pgl = postgraphile(preset)
+
+// Export schema provider function
+export async function createPostGraphileSchema(): Promise<GraphQLSchema> {
+  const { schema } = await pgl.getSchemaResult()
+  return schema
+}
+
+// Export the instance if you need direct access
+export { pgl }
+```
+
+3. Configure Nuxt to use the PostGraphile schema:
+
+```typescript
+// nuxt.config.ts
+import { createPostGraphileSchema } from './server/graphql/schema'
+
+export default defineNuxtConfig({
+  modules: ['@stonecrop/nuxt-grafserv'],
+  grafserv: {
+    // Use PostGraphile schema provider function
+    schema: createPostGraphileSchema,
+    // No resolvers needed - PostGraphile generates everything
+    url: '/graphql',
+    graphiql: true, // Enable Ruru IDE
+  }
+})
+```
+
+#### Direct PostGraphile Instance Usage
+
+You can also pass a PostGraphile instance directly:
+
+```typescript
+// nuxt.config.ts
+import { pgl } from './server/graphql/schema'
+
+export default defineNuxtConfig({
+  grafserv: {
+    schema: pgl, // Pass PostGraphile instance directly
+    url: '/graphql',
+  }
+})
+```
+
+#### PostGraphile with Custom Plugins
+
+Enhance your PostGraphile setup with custom plugins:
+
+```typescript
+// server/graphql/schema.ts
+import { postgraphile } from 'postgraphile'
+import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
+import PgSimplifyInflectorPlugin from '@graphile-contrib/pg-simplify-inflector'
+
+const preset = {
+  extends: [PostGraphileAmberPreset],
+  plugins: [PgSimplifyInflectorPlugin],
+  pgServices: [
+    {
+      name: 'main',
+      connectionString: process.env.DATABASE_URL,
+      schemas: ['public'],
+    },
+  ],
+  grafserv: {
+    websockets: false,
+  },
+  grafast: {
+    explain: process.env.NODE_ENV === 'development', // Enable plan diagrams in dev
+  },
+  schema: {
+    // Add custom behavior overrides
+    defaultBehavior: 'connection', // Enable Relay-style connections by default
+  },
+}
+
+const pgl = postgraphile(preset)
+
+export async function createPostGraphileSchema() {
+  const { schema } = await pgl.getSchemaResult()
+  return schema
+}
+```
+
+#### Benefits of PostGraphile Integration
+
+- **Zero Schema Definition**: Automatically generates GraphQL schema from PostgreSQL
+- **Auto-Generated Resolvers**: All queries and mutations created from database schema
+- **Real-time Subscriptions**: Live query support via PostgreSQL LISTEN/NOTIFY
+- **Row-Level Security**: Leverages PostgreSQL RLS for authorization
+- **High Performance**: Uses Grafast execution engine with intelligent batching
+- **Type Safety**: Full TypeScript support for generated schema
+
 ### Custom Graphile Preset
 
 Leverage the full power of the Graphile ecosystem with custom presets:

package/dist/module.d.mts

@@ -1,4 +1,5 @@
 import { NuxtModule } from '@nuxt/schema';
+import { PromiseOrDirect } from 'grafast';
 import { GraphQLSchema } from 'graphql';
 import { GraphileConfig } from 'graphile-config';
 
@@ -6,13 +7,23 @@ import { GraphileConfig } from 'graphile-config';
  * Schema provider function - returns a GraphQL schema
  */
 type SchemaProvider = () => GraphQLSchema | Promise<GraphQLSchema>;
+/**
+ * PostGraphile instance interface (minimal type for compatibility)
+ */
+interface PostGraphileInstance {
+    getSchema(): PromiseOrDirect<GraphQLSchema>;
+    getSchemaResult(): PromiseOrDirect<{
+        schema: GraphQLSchema;
+        resolvedPreset: GraphileConfig.ResolvedPreset;
+    }>;
+}
 /**
  * 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) */
+    /** Path to schema file(s), a schema provider function, or a PostGraphile instance */
+    schema?: string | string[] | SchemaProvider | PostGraphileInstance;
+    /** Path to resolvers file (optional, only needed for .graphql schema files without PostGraphile) */
     resolvers?: string;
     /** GraphQL endpoint URL (default: '/graphql/') */
     url?: string;

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@stonecrop/nuxt-grafserv",
   "configKey": "grafserv",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -10,7 +10,8 @@ const module$1 = defineNuxtModule({
   },
   defaults: (_nuxt) => ({
     schema: "server/**/*.graphql",
-    resolvers: "server/resolvers.ts",
+    resolvers: void 0,
+    // Optional - not needed for PostGraphile setups
     url: "/graphql/",
     graphiql: void 0,
     // Will default based on dev mode
@@ -44,15 +45,31 @@ const module$1 = defineNuxtModule({
       logger.info(`Nuxt rootDir: ${nuxt.options.rootDir}`);
       logger.info(`Grafserv server alias: ${config.alias["#grafserv-server"]}`);
       const resolverPath = options.resolvers ? resolveForVirtualModule(options.resolvers) : void 0;
-      logger.info(`Resolved resolver path: ${resolverPath}`);
+      if (resolverPath) {
+        logger.info(`Resolved resolver path: ${resolverPath}`);
+      } else {
+        logger.info("No resolvers configured (normal for PostGraphile setups)");
+      }
+      let runtimeSchema;
+      if (typeof options.schema === "function" || options.schema && typeof options.schema === "object" && "getSchema" in options.schema) {
+        runtimeSchema = options.schema;
+        logger.info("Using schema provider function or PostGraphile instance");
+      } else if (typeof options.schema === "string") {
+        runtimeSchema = resolveForSchema(options.schema);
+        logger.info(`Resolved schema path: ${runtimeSchema}`);
+      } else if (Array.isArray(options.schema)) {
+        runtimeSchema = options.schema.map((s) => resolveForSchema(s));
+        logger.info(`Resolved schema paths: ${runtimeSchema.join(", ")}`);
+      } else {
+        runtimeSchema = options.schema;
+      }
       config.runtimeConfig = config.runtimeConfig || {};
       config.runtimeConfig.grafserv = {
         ...options,
         // Pass resolved resolver path for direct import
         resolversPath: resolverPath,
-        // Resolve schema paths from project root
-        schema: typeof options.schema === "string" ? resolveForSchema(options.schema) : Array.isArray(options.schema) ? options.schema.map((s) => resolveForSchema(s)) : options.schema
-        // function passed through
+        // Pass schema (either resolved paths or function/instance)
+        schema: runtimeSchema
       };
       config.virtual = config.virtual || {};
       if (resolverPath) {

package/dist/runtime/handler.js

@@ -13,12 +13,29 @@ async function loadTypeDefsFromFiles(schemaPath) {
   });
   return sources.map((source) => source.document).filter(Boolean);
 }
+function isPostGraphileInstance(value) {
+  return value !== null && typeof value === "object" && "getSchema" in value && typeof value.getSchema === "function";
+}
 async function getSchema(options) {
   if (cachedSchema) {
     return cachedSchema;
   }
   let schema;
-  if (typeof options.schema === "function") {
+  if (isPostGraphileInstance(options.schema)) {
+    console.debug("[@stonecrop/nuxt-grafserv] Using PostGraphile instance for schema");
+    try {
+      if ("getSchemaResult" in options.schema && typeof options.schema.getSchemaResult === "function") {
+        const result = await options.schema.getSchemaResult();
+        schema = result.schema;
+      } else {
+        schema = await options.schema.getSchema();
+      }
+      console.debug("[@stonecrop/nuxt-grafserv] PostGraphile schema loaded successfully");
+    } catch (error) {
+      console.error("[@stonecrop/nuxt-grafserv] Error loading PostGraphile schema:", error);
+      throw error;
+    }
+  } else if (typeof options.schema === "function") {
     schema = await options.schema();
   } else if (options.schema) {
     const typeDefDocs = await loadTypeDefsFromFiles(options.schema);
@@ -38,8 +55,12 @@ async function getSchema(options) {
         }
       } catch (e) {
         console.error("[@stonecrop/nuxt-grafserv] Error loading resolvers:", e);
-        console.warn("[@stonecrop/nuxt-grafserv] Could not load resolvers:", e);
+        console.warn("[@stonecrop/nuxt-grafserv] Continuing without resolvers - this is normal for PostGraphile setups");
       }
+    } else {
+      console.debug(
+        "[@stonecrop/nuxt-grafserv] No resolvers specified - using schema-only mode (normal for PostGraphile)"
+      );
     }
     try {
       schema = makeGrafastSchema({
@@ -52,7 +73,9 @@ async function getSchema(options) {
       throw error;
     }
   } else {
-    throw new Error("[@stonecrop/nuxt-grafserv] No schema provided. Configure schema path or provider function.");
+    throw new Error(
+      "[@stonecrop/nuxt-grafserv] No schema provided. Configure schema path, provider function, or PostGraphile instance."
+    );
   }
   cachedSchema = schema;
   return schema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/nuxt-grafserv",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Pluggable Grafserv GraphQL server as Nuxt Module",
   "license": "MIT",
   "type": "module",
@@ -44,7 +44,7 @@
     "grafserv": "^1.0.0-rc.4",
     "graphile-config": "^1.0.0-rc.3",
     "graphql": "^16.12.0",
-    "@stonecrop/graphql-middleware": "0.7.5"
+    "@stonecrop/graphql-middleware": "0.7.6"
   },
   "devDependencies": {
     "@casl/ability": "^6.8.0",
@@ -63,16 +63,17 @@
     "eslint": "^9.39.2",
     "jsdom": "^27.4.0",
     "nuxt": "^4.2.2",
+    "postgraphile": "^5.0.0-rc.4",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vitest": "^4.0.17",
     "vue-tsc": "^3.2.2",
-    "@stonecrop/casl-middleware": "0.7.5",
-    "@stonecrop/rockfoil": "0.7.5"
+    "@stonecrop/casl-middleware": "0.7.6",
+    "@stonecrop/rockfoil": "0.7.6"
   },
   "peerDependencies": {
-    "@stonecrop/casl-middleware": "0.7.5",
-    "@stonecrop/rockfoil": "0.7.5"
+    "@stonecrop/casl-middleware": "0.7.6",
+    "@stonecrop/rockfoil": "0.7.6"
   },
   "peerDependenciesMeta": {
     "@stonecrop/casl-middleware": {
@@ -94,6 +95,7 @@
     "test": "vitest run",
     "test:ci": "vitest run --run",
     "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run test/e2e",
     "test:watch": "vitest watch",
     "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
   }