nuxt-graphql-middleware 5.0.0-alpha.13 → 5.0.0-alpha.16

package/README.md

@@ -1,9 +1,8 @@
 ![nuxt-graphql-middleware banner](docs/banner.png?raw=true 'Nuxt GraphQL Middleware - Expose queries and mutations as fully typed API routes.')
 
-# Nuxt GraphQL Middleware
+# nuxt-graphql-middleware
 
-Keep your GraphQL server private: Expose GraphQL queries and mutations as fully
-typed API routes.
+A GraphQL client for Nuxt 3.
 
 **[Documentation](https://nuxt-graphql-middleware.dulnan.net)** –
 **[npm](https://www.npmjs.com/package/nuxt-graphql-middleware)** –
@@ -13,19 +12,20 @@ typed API routes.
 
 ## Features
 
-- Exposes each query and mutation as an API route
-- GraphQL requests are only done on the server side
-- No GraphQL documents in client bundle
-- Includes composables to perform queries or mutations
-- Modify request headers, responses and handle errors
-- HMR for all GraphQL files
-- Integration with [Nuxt DevTools](https://devtools.nuxtjs.org)
-- Full TypeScript integration for schema, queries, mutations and fragments using
-  [graphql-code-generator](https://github.com/dotansimha/graphql-code-generator)
+- Exposes each query and mutation as an **API route**
+- GraphQL requests are done **only on the server side**
+- Includes **composables** to perform queries or mutations
+- **No GraphQL documents** in client bundle
+- Super fast **TypeScript code generation** using
+  **[graphql-typescript-deluxe](https://github.com/dulnan/graphql-typescript-deluxe)**
+- **HMR** for all GraphQL files
+- Optional **Client side caching** for query operations
+- Modify **request headers**, responses and handle errors
+- Integration with **[Nuxt DevTools](https://devtools.nuxtjs.org)**
 
-# Setup
+## Setup
 
-## Install
+### Install
 
 ```bash
 npx nuxi@latest module add nuxt-graphql-middleware
@@ -42,6 +42,9 @@ export default defineNuxtConfig({
 })
 ```
 
+See
+[all configuration options](https://nuxt-graphql-middleware.dulnan.net/configuration/module)
+
 ## Usage
 
 Write your first query, e.g. in pages/films.query.graphql:
@@ -59,7 +62,7 @@ query films {
 Your query is now available via the useGraphqlQuery() composable:
 
 ```typescript
-const { data } = await useGraphqlQuery('films')
+const { data, errors } = await useGraphqlQuery('films')
 console.log(data.allFilms.films)
 ```
 
@@ -70,12 +73,91 @@ const { data } = await useAsyncGraphqlQuery('films')
 console.log(data.value.allFilms.films)
 ```
 
-Alternatively you can also call
-`http://localhost:3000/api/graphql_middleware/query/films` to get the same
-result.
+Alternatively you can also directly call the API route to get the same result:
+
+```typescript
+const response = await $fetch('/api/graphql_middleware/query/films')
+```
+
+Or using `useFetch`:
+
+```typescript
+const { data } = await useFetch('/api/graphql_middleware/query/films')
+```
 
 ## Nuxt 2
 
 The 3.x releases are only compatible with Nuxt 3. The
 [2.x branch](https://github.com/dulnan/nuxt-graphql-middleware/tree/2.x) and
-releases on npm are compatible with Nuxt 2.
+releases on npm are compatible with Nuxt 2. However this version is not
+maintained anymore.
+
+## Development
+
+The module uses the default Nuxt module authoring setup where the module itself
+is located in `./src`, with a playground located in `./playground/`.
+
+### Setup
+
+#### Install dependencies
+
+Install the dependencies of the module and playground:
+
+```sh
+npm install
+```
+
+#### Prepare Types
+
+This will generate all the types needed to start developing:
+
+```sh
+npm run dev:prepare
+```
+
+#### Start Apollo Server
+
+The playground uses an Apollo server that needs to be built separately.
+
+```sh
+cd apollo
+npm install
+npm run compile
+npm run start
+```
+
+### Start the Playground
+
+```sh
+npm run dev
+```
+
+You can now open http://localhost:3000 to start developing.
+
+### Testing
+
+#### Lint / Code Style
+
+```sh
+npm run lint
+npm run prettier
+```
+
+#### Unit Tests (Vitest)
+
+Unit tests are done using Vitest.
+
+```sh
+npm run test:ci
+```
+
+#### E2E (Cypress)
+
+We use Cypress to run some E2E tests. The tests are executed against the
+playground **build**:
+
+```sh
+npm run dev:build
+npm run dev:start
+npm run cypress
+```

package/dist/client/200.html

@@ -7,5 +7,5 @@
 <link rel="prefetch" as="script" crossorigin href="/__nuxt-graphql-middleware/_nuxt/u9er1db2.js">
 <link rel="prefetch" as="style" crossorigin href="/__nuxt-graphql-middleware/_nuxt/error-500._g0akJim.css">
 <link rel="prefetch" as="script" crossorigin href="/__nuxt-graphql-middleware/_nuxt/AZpplOcD.js">
-<script type="module" src="/__nuxt-graphql-middleware/_nuxt/M311G39J.js" crossorigin></script></head><body><div id="__nuxt"></div><div id="teleports"></div><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1743835674022,false]</script>
-<script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__nuxt-graphql-middleware",buildId:"332611ea-70e0-4678-afde-6ef504a9ef06",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script></body></html>
+<script type="module" src="/__nuxt-graphql-middleware/_nuxt/M311G39J.js" crossorigin></script></head><body><div id="__nuxt"></div><div id="teleports"></div><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1744204373787,false]</script>
+<script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__nuxt-graphql-middleware",buildId:"e1a39e19-d46f-47f9-88fd-317d5fa8bf87",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script></body></html>

package/dist/client/404.html

@@ -7,5 +7,5 @@
 <link rel="prefetch" as="script" crossorigin href="/__nuxt-graphql-middleware/_nuxt/u9er1db2.js">
 <link rel="prefetch" as="style" crossorigin href="/__nuxt-graphql-middleware/_nuxt/error-500._g0akJim.css">
 <link rel="prefetch" as="script" crossorigin href="/__nuxt-graphql-middleware/_nuxt/AZpplOcD.js">
-<script type="module" src="/__nuxt-graphql-middleware/_nuxt/M311G39J.js" crossorigin></script></head><body><div id="__nuxt"></div><div id="teleports"></div><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1743835674022,false]</script>
-<script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__nuxt-graphql-middleware",buildId:"332611ea-70e0-4678-afde-6ef504a9ef06",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script></body></html>
+<script type="module" src="/__nuxt-graphql-middleware/_nuxt/M311G39J.js" crossorigin></script></head><body><div id="__nuxt"></div><div id="teleports"></div><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1744204373788,false]</script>
+<script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__nuxt-graphql-middleware",buildId:"e1a39e19-d46f-47f9-88fd-317d5fa8bf87",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script></body></html>

package/dist/client/_nuxt/builds/latest.json

@@ -1 +1 @@
-{"id":"332611ea-70e0-4678-afde-6ef504a9ef06","timestamp":1743835671841}
+{"id":"e1a39e19-d46f-47f9-88fd-317d5fa8bf87","timestamp":1744204371551}

package/dist/client/_nuxt/builds/meta/e1a39e19-d46f-47f9-88fd-317d5fa8bf87.json

@@ -0,0 +1 @@
+{"id":"e1a39e19-d46f-47f9-88fd-317d5fa8bf87","timestamp":1744204371551,"matcher":{"static":{},"wildcard":{},"dynamic":{}},"prerendered":[]}

package/dist/client/index.html

@@ -7,5 +7,5 @@
 <link rel="prefetch" as="script" crossorigin href="/__nuxt-graphql-middleware/_nuxt/u9er1db2.js">
 <link rel="prefetch" as="style" crossorigin href="/__nuxt-graphql-middleware/_nuxt/error-500._g0akJim.css">
 <link rel="prefetch" as="script" crossorigin href="/__nuxt-graphql-middleware/_nuxt/AZpplOcD.js">
-<script type="module" src="/__nuxt-graphql-middleware/_nuxt/M311G39J.js" crossorigin></script></head><body><div id="__nuxt"></div><div id="teleports"></div><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1743835674022,false]</script>
-<script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__nuxt-graphql-middleware",buildId:"332611ea-70e0-4678-afde-6ef504a9ef06",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script></body></html>
+<script type="module" src="/__nuxt-graphql-middleware/_nuxt/M311G39J.js" crossorigin></script></head><body><div id="__nuxt"></div><div id="teleports"></div><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1744204373788,false]</script>
+<script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__nuxt-graphql-middleware",buildId:"e1a39e19-d46f-47f9-88fd-317d5fa8bf87",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script></body></html>

package/dist/module.d.mts

@@ -1,10 +1,13 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { HookResult } from 'nuxt/schema';
-import { OperationResponseError } from '../dist/runtime/types.js';
-export { GraphqlMiddlewareServerOptions } from '../dist/runtime/types.js';
 import { Types } from '@graphql-codegen/plugin-helpers';
 import { SchemaASTConfig } from '@graphql-codegen/schema-ast';
-import { GeneratorOptions } from 'graphql-typescript-deluxe';
+import { GeneratorOptions, GeneratorOutput } from 'graphql-typescript-deluxe';
+import { GraphQLSchema, GraphQLNamedType } from 'graphql';
+import { Nuxt, ResolvedNuxtTemplate, WatchEvent, HookResult } from 'nuxt/schema';
+import { Resolver } from '@nuxt/kit';
+import { RouterMethod } from 'h3';
+import { OperationResponseError } from '../dist/runtime/types.js';
+export { GraphqlMiddlewareServerOptions } from '../dist/runtime/types.js';
 
 interface ModuleOptions {
     /**
@@ -125,6 +128,8 @@ interface ModuleOptions {
     logOnlyErrors?: boolean;
     /**
      * Options for graphql-typescript-deluxe code generator.
+     *
+     * @see [GeneratorOptions](https://github.com/dulnan/graphql-typescript-deluxe/blob/main/src/types/options.ts#L193)
      */
     codegenConfig?: GeneratorOptions;
     /**
@@ -133,6 +138,8 @@ interface ModuleOptions {
     codegenSchemaConfig?: {
         /**
          * Configure how the schema.graphql file should be generated.
+         *
+         * @see [SchemaASTConfig](https://github.com/dotansimha/graphql-code-generator/blob/master/packages/plugins/other/schema-ast/src/index.ts#L23)
          */
         schemaAstConfig?: SchemaASTConfig;
         /**
@@ -149,6 +156,8 @@ interface ModuleOptions {
          *   }
          * }
          * ```
+         *
+         * @see [Types.UrlSchemaOptions](https://github.com/dotansimha/graphql-code-generator/blob/master/packages/utils/plugins-helpers/src/types.ts#L82)
          */
         urlSchemaOptions?: Types.UrlSchemaOptions;
     };
@@ -171,8 +180,351 @@ interface ModuleOptions {
     };
 }
 
+type RpcItem = {
+    id: string;
+    timestamp?: number;
+    source: string;
+    name: string;
+    identifier: 'fragment' | 'query' | 'mutation';
+    filePath: string;
+};
+
+declare const defaultOptions: ModuleOptions;
+
+declare class ConsolePrompt {
+    private abortController;
+    confirm(message: string): Promise<'yes' | 'no' | 'cancel'>;
+    abort(): void;
+}
+
+type TemplateOptions = {
+    path: string;
+    virtual?: boolean;
+};
+type GeneratorTemplateCallback = (output: GeneratorOutput, helper: ModuleHelper) => string;
+type StaticTemplateCallback = (helper: ModuleHelper) => string;
+type GeneratorTemplate = {
+    type: 'generator';
+    options: TemplateOptions;
+    build: GeneratorTemplateCallback | null;
+    buildTypes: GeneratorTemplateCallback | null;
+    virtual?: boolean;
+};
+type StaticTemplate = {
+    type: 'static';
+    options: TemplateOptions;
+    build: StaticTemplateCallback | null;
+    buildTypes: StaticTemplateCallback | null;
+    virtual?: boolean;
+};
+
+type WithRequired<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};
+type RequiredModuleOptions = WithRequired<ModuleOptions, keyof typeof defaultOptions>;
+type ModuleHelperResolvers = {
+    /**
+     * Resolver for paths relative to the module root.
+     */
+    module: Resolver;
+    /**
+     * Resolve relative to the app's server directory.
+     */
+    server: Resolver;
+    /**
+     * Resolve relative to the Nuxt src folder.
+     */
+    src: Resolver;
+    /**
+     * Resolve relative to the Nuxt app directory.
+     */
+    app: Resolver;
+    /**
+     * Resolve relative to the Nuxt root.
+     *
+     * Should be where nuxt.config.ts is located.
+     */
+    root: Resolver;
+};
+type ModuleHelperPaths = {
+    runtimeTypes: string;
+    root: string;
+    nuxtConfig: string;
+    serverDir: string;
+    schema: string;
+    serverOptions: string | null;
+    clientOptions: string | null;
+    moduleBuildDir: string;
+    moduleTypesDir: string;
+};
+declare class ModuleHelper {
+    private nuxt;
+    readonly resolvers: ModuleHelperResolvers;
+    readonly paths: ModuleHelperPaths;
+    readonly isDev: boolean;
+    readonly options: RequiredModuleOptions;
+    readonly prompt: ConsolePrompt;
+    private nitroExternals;
+    private tsPaths;
+    constructor(nuxt: Nuxt, moduleUrl: string, options: ModuleOptions);
+    /**
+     * Find the path to the graphqlMiddleware.serverOptions.ts file.
+     */
+    private findServerOptions;
+    private findClientOptions;
+    /**
+     * Transform the path relative to the module's build directory.
+     *
+     * @param path - The absolute path.
+     *
+     * @returns The path relative to the module's build directory.
+     */
+    toModuleBuildRelative(path: string): string;
+    /**
+     * Transform the path relative to the Nuxt build directory.
+     *
+     * @param path - The absolute path.
+     *
+     * @returns The path relative to the module's build directory.
+     */
+    toBuildRelative(path: string): string;
+    /**
+     * Get all file paths that match the import patterns.
+     */
+    getImportPatternFiles(): Promise<string[]>;
+    matchesImportPattern(filePath: string): boolean;
+    addAlias(name: string, path: string): void;
+    inlineNitroExternals(arg: ResolvedNuxtTemplate | string): void;
+    transpile(path: string): void;
+    applyBuildConfig(): void;
+    processTemplate(path: string, content: string): string;
+    addTemplate(template: StaticTemplate): void;
+    addPlugin(name: string): void;
+    addServerHandler(name: string, path: string, method: RouterMethod): void;
+    addComposable(name: string): void;
+    addServerUtil(name: string): void;
+}
+
+type CollectorWatchEventResult = {
+    hasChanged: boolean;
+    affectedOperations: string[];
+    error?: {
+        message: string;
+    };
+};
+declare class Collector {
+    private schema;
+    private helper;
+    /**
+     * All collected files.
+     */
+    private files;
+    /**
+     * All documents provided by hooks.
+     */
+    private hookDocuments;
+    /**
+     * All file paths provided by hooks.
+     */
+    private hookFiles;
+    /**
+     * The code generator.
+     */
+    private generator;
+    /**
+     * A map of operation name and timestamp when the operation was last validated.
+     */
+    private operationTimestamps;
+    /**
+     * The generated operations and fragments.
+     */
+    readonly rpcItems: Map<string, RpcItem>;
+    /**
+     * The registered templates.
+     */
+    private templates;
+    /**
+     * The generated template contents.
+     */
+    private templateResult;
+    constructor(schema: GraphQLSchema, helper: ModuleHelper);
+    reset(): Promise<void>;
+    updateSchema(schema: GraphQLSchema): Promise<void>;
+    private filePathToBuildRelative;
+    private filePathToSourceRelative;
+    private operationToLogEntry;
+    private getTemplate;
+    /**
+     * Executes code gen and performs validation for operations.
+     */
+    private buildState;
+    private buildErrorMessage;
+    private logError;
+    /**
+     * Initialise the collector.
+     *
+     * In dev mode, the method will call itself recursively until all documents
+     * are valid.
+     *
+     * If not in dev mode the method will throw an error when documents are not
+     * valid.
+     */
+    init(): Promise<void>;
+    addHookDocument(identifier: string, source: string): void;
+    addHookFile(filePath: string): void;
+    /**
+     * Initialise the collector.
+     */
+    private initDocuments;
+    /**
+     * Add a file.
+     */
+    private addFile;
+    private matchesPatternOrExists;
+    private handleAdd;
+    private handleChange;
+    private handleUnlink;
+    private handleUnlinkDir;
+    /**
+     * Handle the watcher event for the given file path.
+     */
+    handleWatchEvent(event: WatchEvent, filePath: string): Promise<CollectorWatchEventResult>;
+    /**
+     * Adds a virtual template (not written to disk) for both Nuxt and Nitro.
+     *
+     * For some reason a template written to disk works for both Nuxt and Nitro,
+     * but a virtual template requires adding two templates.
+     */
+    private addVirtualTemplate;
+    /**
+     * Adds a template that dependes on Collector state.
+     */
+    addTemplate(template: GeneratorTemplate): void;
+}
+
+/**
+ * Handles downloading, loading and saving the GraphQL schema.
+ */
+declare class SchemaProvider {
+    private helper;
+    /**
+     * The raw schema content.
+     */
+    private schemaContent;
+    /**
+     * The parsed schema object.
+     */
+    private schema;
+    constructor(helper: ModuleHelper);
+    init(): Promise<void>;
+    private loadFromDiskFallback;
+    /**
+     * Loads the schema from disk.
+     *
+     * @returns The schema contents from disk.
+     */
+    private loadSchemaFromDisk;
+    /**
+     * Downloads the schema and saves it to disk.
+     *
+     * @returns The schema contents.
+     */
+    private downloadSchema;
+    /**
+     * Determine if the schema exists on disk.
+     *
+     * @returns True if the schema file exists on disk.
+     */
+    hasSchemaOnDisk(): Promise<boolean>;
+    /**
+     * Load the schema either from disk or by downloading it.
+     *
+     * @param forceDownload - Forces downloading the schema.
+     */
+    loadSchema(opts?: {
+        forceDownload?: boolean;
+        forceDisk?: boolean;
+    }): Promise<void>;
+    /**
+     * Get the schema.
+     *
+     * @returns The parsed GraphQL schema object.
+     */
+    getSchema(): GraphQLSchema;
+}
+
+/**
+ * The public module context class.
+ */
+declare class ModuleContext {
+    private schemaProvider;
+    private collector;
+    constructor(schemaProvider: SchemaProvider, collector: Collector);
+    /**
+     * Return the GraphQL schema.
+     *
+     * Note that the schema may be updated during development, so it can become
+     * stale. Prefer using methods like `schemaHasType()` to query the schema.
+     *
+     * @returns The GraphQL schema.
+     */
+    getSchema(): GraphQLSchema;
+    /**
+     * Check if the given GraphQL type (interface, concrete type, enum, input type)
+     * exists in the schema.
+     *
+     * @param name - The name of the type.
+     *
+     * @returns True if the type exists in the schema.
+     */
+    schemaHasType(name: string): boolean;
+    /**
+     * Get a type from the schema.
+     *
+     * @param name - The name of the type.
+     *
+     * @returns The type.
+     */
+    schemaGetType(name: string): GraphQLNamedType | undefined;
+    /**
+     * Add an additional static document.
+     *
+     * @param identifier - The unique identifier for your document.
+     * @param source - The document source.
+     */
+    addDocument(identifier: string, source: string): ModuleContext;
+    /**
+     * Add an additional GraphQL file to import.
+     *
+     * @param filePath - The absolute path to the file.
+     */
+    addImportFile(filePath: string): ModuleContext;
+}
+
+declare function useGraphqlModuleContext(): ModuleContext;
+declare function useGraphqlModuleContext(options: {
+    nullOnMissing: true;
+}): ModuleContext | null;
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
+declare module '#app' {
+    interface RuntimeNuxtHooks {
+        /**
+         * Emitted when any GraphQL response contains errors.
+         */
+        'nuxt-graphql-middleware:errors': (errors: OperationResponseError) => HookResult;
+    }
+}
+declare module 'vite/types/customEvent.d.ts' {
+    interface CustomEventMap {
+        /**
+         * Emitted when GraphQL operations have been updated.
+         */
+        'nuxt-graphql-middleware:reload': {
+            operations: string[];
+        };
+    }
+}
 declare module '@nuxt/schema' {
     interface AppConfig {
         graphqlMiddleware: {
@@ -186,25 +538,38 @@ declare module '@nuxt/schema' {
             clientCacheMaxSize: number;
         };
     }
-}
-declare module '#app' {
-    interface RuntimeNuxtHooks {
+    interface Nuxt {
         /**
-         * Emitted when any GraphQL response contains errors.
+         * The nuxt-graphql-middleware module context.
          */
-        'nuxt-graphql-middleware:errors': (errors: OperationResponseError) => HookResult;
+        _nuxt_graphql_middleware?: ModuleContext;
     }
-}
-declare module 'vite/types/customEvent.d.ts' {
-    interface CustomEventMap {
+    interface NuxtHooks {
         /**
-         * Emitted when GraphQL operations have been updated.
+         * Called once right before the documents are initialised.
+         *
+         * Use this hook to add any additional documents based on for example the parsed schema.
+         *
+         * @example
+         *
+         * ```typescript`
+         * export default defineNuxtConfig({
+         *   hooks: {
+         *     'nuxt-graphql-middleware:init': (ctx) => {
+         *       if (ctx.schemaHasType('Comment')) {
+         *         ctx.addDocument(
+         *           'queryFromHook',
+         *           `query loadComments { author subject date body }`
+         *         )
+         *       }
+         *     },
+         *   },
+         * })
+         * ```
          */
-        'nuxt-graphql-middleware:reload': {
-            operations: string[];
-        };
+        'nuxt-graphql-middleware:init': (ctx: ModuleContext) => void | Promise<void>;
     }
 }
 
-export { _default as default };
+export { _default as default, useGraphqlModuleContext };
 export type { ModuleOptions };